Querying

#Database Query Flow

For SQLite and PostgreSQL, the model uses one dialect-specific tool:

• data_query_sqlite
• data_query_postgresql

Each call includes source_id, sql, and optional positional parameters. The runtime then:

1. confirms the tool was projected for the active source and read scope;
2. validates arguments against the declared schema;
3. parses and normalizes exactly one SQL statement;
4. resolves tables, columns, and relationships against the current catalog;
5. rejects unsafe syntax, functions, or source scope;
6. revalidates live facts at the connector boundary;
7. executes once through a read-only connection or transaction; and
8. returns a bounded schema-validated result.

#Read Contract

SQLite uses a connector-level authorizer. PostgreSQL uses a deliberately bounded function set because server functions can perform external I/O even in a read-only transaction.

Arbitrary SQL mutation is unsupported. The only database mutation is the separate data_preview_postgresql_update → data_update_postgresql path for exact tables and assignment columns that an operator explicitly enabled. It accepts structured filters and assignments, not model-authored SQL. See PostgreSQL Updates.

#Catalog and Permission Scope

A database query must reference at least one current readable resource in the selected source. Unknown tables, columns, or resources outside the exact read scope are rejected before source I/O. Results retain source and resource revisions so their structural provenance remains inspectable.

#Result Bounds

Database query results include:

• canonical SQL and an SQL fingerprint;
• source and resource IDs and revisions;
• columns and JSON-safe rows;
• row and byte limits;
• returned and total row counts when available;
• explicit truncation status and reasons; and
• trust classification and sensitivity provenance.

Truncation is explicit. A model should not present a truncated result as a complete population. When the requested output is a file, use data_export_sqlite or data_export_postgresql to create an exact bounded CSV or XLSX artifact.

#Parameters

Model-proposed values should use parameters when possible rather than SQL interpolation. Connector adapters preserve normalized JSON-safe values and reject unsupported shapes.

#Workspace Data

Local CSV, TSV, JSON-records/NDJSON, and Parquet data use file_query, not a catalog source tool. Daita expands one workspace-relative pattern, revision-binds the exact file manifest, and exposes only the relation data to a private DuckDB worker.

Text discovery and reading use file_search and file_read. There is no data_read_file tool and no attached CSV/JSON directory source in the current framework.

#Failure and Repair

Parser, catalog, permission, freshness, containment, and connector failures become bounded model-visible tool results. The direct loop may let the model correct a bad selector or SQL query on the next step, but it does not start a separate repair workflow or verifier pass.