Semantic Model Query Tool

The Semantic Model Query tool is an Agent tool leveraging a Semantic Model to translate natural language queries into SQL queries, and providing answers based on the execution of the SQL queries.

Configuration

Once you’ve instantiated a Semantic Model Query tool, you need to configure the following parameters:

  • Which Semantic Model to use

  • The LLM to use for the agent reasoning and SQL generation

  • Optionally, an embedding LLM for semantic value matching

  • Semantic Model Selection: Select the project containing the semantic model to query, the semantic model and its version.

  • 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, recommended for large semantic models. Disable to use the faster linear SQL generation pipeline.

  • SQL Generation Parameters: By default uses the parameters defined in your semantic models. If configure parameters is selected, set limits on the number of rows returned and the maximum agent 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.

Internal details

When using the agent mode, the Semantic Model Query tool is itself an agent, that uses multiple tools under the hood, in order to:

  • Explore the schema of datasets (get the list of entities, their attributes, the relationships)

  • Resolve values (i.e. to match user query terms with resolvable attributes 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 (i.e. all the context in the semantic model isn’t provided in bulk to generate SQL queries, only the minimum context is fetched), making the tool scalable with datasets with a high number of attributes or big semantic models.

The Semantic Model Query Tool follows this general workflow:

  1. Planning & Metadata Retrieval: The tool starts by exploring the entities, their attributes and relationships to identify information relevant to the user’s query and ensure entities are joined correctly.

  2. Value Resolution & Term Extraction: Maps terms in the user query to the semantic model, to fix typos, ensure values match the database exactly, use business metrics and clarify jargon/acronyms.

  3. SQL Generation: Generates SQL candidates based on the metadata gathered, relationships 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 (up to five times). Synthesizes the data results back into a concise natural language response for the user.