Dataset SQL Query Tool

The Dataset SQL Query tool is an Agent tool that translates natural language queries into SQL queries, and provides answers based on the execution of the SQL queries on the underlying datasets.

Configuration

Once you’ve instantiated a Dataset SQL Query tool, you need to configure the following:

  • Dataset Selection: Select the project containing the dataset to query and the SQL dataset.

  • LLM Configuration:

    • LLM:Select the LLM to use for the agent reasoning and SQL generation.

    • Embedding LLM (optional): Select the embedding LLM for semantic value matching.

    • Agent mode: Enable to use the multi-step agentic workflow. Disable to use the faster linear SQL generation pipeline.

  • Query Limits:

    • Max Rows per Query: Determines the maximum number of rows the LLM will have access to from the output of the SQL query

    • Max rows in Artifacts: Determines the maximum amount of rows generated in the artifacts

    • Max rows in Sources: Determines the maximum amount of rows in the sources

    • Agent recursion limit: Maximum LangGraph loop iterations

  • Security: Define whether the tool should be executed as user calling the tool or the end-user (only relevant if these two are distinct).

  • Description for LLM (optional): General instructions for usage of this tool (e.g. a description of the dataset, its attributes, associated metrics…)

Input and output

The tool takes a natural language query as input, and returns a synthesized answer, artifacts of the SQL record(s) retrieved and the associated SQL query generated and executed.

How it works

The tool supports two modes, selected with the Agent mode setting.

When the tool is first instantiated, it reads the target dataset to generate a “semantic model spec” (a structured representation of the dataset’s schema, columns, and metadata) and detects the specific SQL dialect of the underlying database. Both modes use this spec to generate SQL.

Agent mode

When the agent mode is enabled, the Dataset SQL Query tool is itself an agent, that uses multiple tools under the hood, in order to:

  • Explore the schema of the dataset (its columns and their metadata)

  • Resolve values (i.e. to match user query terms with column values to correct typos and find exact values in the data.)

  • Perform SQL operations (generate, validate and execute SQL). Importantly, it validates that SQL queries only read data (no INSERT/UPDATE/DELETE).

This means that the tool can fetch context dynamically (only the minimum context is fetched to generate SQL queries), making the tool scalable with datasets with a high number of columns.

In agent mode, the tool follows this general workflow:

  1. Planning & Metadata Retrieval: The tool starts by exploring the columns and their metadata to identify information relevant to the user’s query.

  2. Value Resolution & Term Extraction: Maps terms in the user query to the dataset, to fix typos and ensure values match the database exactly.

  3. SQL Generation: Generates SQL candidates based on the metadata gathered and resolved values.

  4. Validation & Execution: SQL queries are checked for syntax and security (read-only) before being executed. If the query execution fails, analyzes the error logs and loops back to refine the SQL. Synthesizes the data results back into a concise natural language response for the user.

Linear mode

When the agent mode is disabled, the tool processes user queries in a straight-through pipeline:

  • Security Context Resolution: It determines who is executing the query to ensure the query runs with the appropriate data access permissions.

  • Semantic Value Matching (Optional): If an Embedding LLM was configured, the tool maps terms in the user’s question to the exact categorical values stored in the database (e.g., matching the word “NYC” in the prompt to “New York City” in the dataset).

  • SQL Generation: The LLM uses the natural language question, the semantic model spec, and the identified SQL dialect to generate a SQL query.

  • Validation & Execution: The generated SQL query is validated and executed, and the results are synthesized into a natural language answer.