SQL query

The SQL query capability allows an agent to answer natural-language questions using data from a connected relational database or a processed spreadsheet. The agent identifies a relevant data source and tables, generates a query for the source’s SQL dialect, and returns the results as a Dataset that can be viewed as an interactive table.

The capability is only available to agents with the SQL query permission. It can use only database connections and documents that the current user is authorised to access.

How queries are handled

Stage	What DataQI does
Data source selection	Identifies a relevant connected database or processed spreadsheet and the tables needed to answer the question.
Query generation	Instructs the language model to generate one read-only `SELECT` query using only the supplied table and column schemas.
Static validation	Parses the generated SQL for the database dialect and rejects queries that cannot be shown to be a single read-only query, including known unsafe statements, locking operations and functions.
Execution	Applies a timeout and row limit. Database queries run through the configured read-only connection controls; spreadsheet queries run in a confined pod-local worker over staged Parquet tables.
Results	Stores the point-in-time results as a Dataset for display and further analysis, and are available as a CSV export.

If a generated query is rejected or fails, the agent can attempt one correction. A query that remains invalid is not executed again.

Spreadsheet-derived tables

When spreadsheet ingestion has produced queryable tables, those tables participate in the same source-selection and Dataset workflow as connected databases. A query can filter, order, aggregate, and join tables from the same document. It cannot join a spreadsheet table to a different document or database in one query.

The API streams only the selected authorised table files into temporary pod-local storage. A separate DuckDB worker executes the query, then the API publishes the bounded result to the normal Dataset store. Temporary query files are removed after the operation and are not needed to view, page, or export the resulting Dataset.

The SQL-generation prompt, static validator and automatic transaction rollback are defence-in-depth precautions. They reduce risk, but they cannot guarantee that every accepted query is harmless.

A sufficiently knowledgeable user may still be able to influence or construct a dangerous query that passes these application-level checks. Static validation cannot reliably establish the behaviour of every database function, stored procedure, view, extension or provider-specific feature. Transaction rollback also cannot reverse every possible database, session or external side effect.

The database administrator must treat the credentials configured for the connection as the primary security boundary:

Use a dedicated, least-privileged database account.
Grant read access only to the schemas, tables and views that DataQI needs.
Do not grant data modification, schema modification, ownership, administrative or superuser permissions.
Restrict access to functions and stored procedures that can change state or cause external effects.
Enforce database-native read-only controls where the provider supports them.

Never use DataQI’s prompt instructions, validator or transaction rollback as a substitute for database-level authorisation.