LLMs.txt directory

AgentQL

Learn how AgentQL enables Spotter to answer complex analytical questions faster.

AgentQL is ThoughtSpot’s proprietary semantic query dialect that enables Spotter to answer complex analytical questions faster and more accurately by generating structured queries directly on top of your data model, instead of relying on Python-based code execution.

Overview

When you ask Spotter a complex analytical question, Spotter must decide the best way to generate an answer. Previously, Spotter relied on two primary execution paths: TML search tokens for simpler queries, and Python-based code execution for complex multi-step analysis. AgentQL introduces a third, smarter path.

Instead of writing and executing Python code, Spotter generates a structured semantic query — an AgentQL query — that is processed by ThoughtSpot’s Query Generation layer (QGen) and converted into governed SQL executed against your cloud data warehouse (CDW). The result is a significantly faster answer that inherits the full semantic context of your data model, including joins, row-level security (RLS), column-level security (CLS), custom calendars, and column definitions.

AgentQL is not raw SQL. It operates on top of worksheet columns within the TML data model, not directly on database tables.

How it works

When you submit a question to Spotter, Spotter’s agent autonomously evaluates the question and selects the most appropriate execution path:

  • AgentQL — for complex analytical queries requiring multi-step computation, ranking, running totals, or cross-entity measures

  • TML search tokens — for simpler questions that map directly to standard search constructs

  • Python-based code execution — retained for statistical analysis such as forecasting and regression, and for answers that must be stitched from multiple data models

For questions routed through AgentQL, Spotter generates a semantic query during its reasoning step. You can inspect this query in the Show work panel, where a creating_answer_using_AgentQL event is displayed. The query structure is written in readable, analyst-friendly language — you do not need to understand raw database SQL to verify what Spotter has done.

The AgentQL query is then passed to QGen, which translates it into a final, governed SQL statement and executes it on your CDW. The answer is returned as a summary and visualization directly in the Spotter response card.

You can explicitly invoke AgentQL by mentioning Semantic Query in your Spotter prompt. For example: "Use Semantic Query to find the top 10 customers by revenue last quarter." You can also an instructions to use Semantic Query in your Spotter instructions.

Verifying AgentQL answers

Because AgentQL generates a human-readable semantic query rather than opaque Python code, analysts can verify answers without needing to inspect raw SQL. The query structure is visible in the agent’s reasoning block within the Show work panel.

You can copy the AgentQL query directly from the reasoning block and review it in a text editor to understand exactly what data path Spotter took to arrive at the answer.

Because AgentQL is deterministically translated to final SQL by QGen, there is no need to separately verify the generated SQL — the semantic query is the verifiable artifact.

Key benefits

Answers complex questions that tokens could not

TML search tokens struggle with multi-step and nested analytical patterns. AgentQL fills this gap by supporting:

  • Multi-step CTE-based queries (for example, "which publishers have the highest proportion of elite heroes among those with at least 10 good-aligned heroes?")

  • Per-group ranking (Top N per category)

  • Running totals and period-over-period comparisons using LAG, RANK, and DENSE_RANK

  • Cross-entity measures spanning multiple entities in a single data model

Faster answer generation

AgentQL eliminates the overhead of writing Python, executing it in a runtime environment, and retrieving the results. Answers for complex questions that previously took several minutes can now complete in under 60 seconds.

An internal analysis of production Spotter conversations found that approximately 20% of all Spotter conversations include at least one Python code execution step — and approximately 95% of those steps could be replaced by AgentQL.

No row-limit ceiling

Python-based code execution is constrained by a row-count limit on the data Spotter can process. AgentQL pushes computation directly to your CDW, removing this ceiling entirely. You can ask analytical questions across datasets of any size.

Full data governance

AgentQL answers are governed by design. Every AgentQL query respects:

  • Row-Level Security (RLS) and Column-Level Security (CLS)

  • Custom and fiscal calendar configurations using UDFs (for example, YEAR_NUMBER, MONTH_NUMBER)

  • Column aliases, dependencies, and model definitions from the TML worksheet

The same semantic layer that governs all ThoughtSpot answers governs AgentQL answers.

Follow-up questions

Follow-up questions work with AgentQL answers. You can continue a conversation naturally after receiving an AgentQL-generated response.

Answer card and visualization

When AgentQL generates an answer, the Spotter response card includes:

  • A reasoning block showing the semantic query and a table view of intermediate results

  • A summary of the answer in natural language

  • A chart visualization of the result

The chart visualization in the AgentQL answer card is not available in the initial release. This capability is planned for release within the next two to three months after general availability.

Availability

Phase Details

Phase 1 — Beta

Available from ThoughtSpot Cloud 26.5 for select customers.

Phase 1 — GA

Targeted for ThoughtSpot Cloud 26.7, contingent on Phase 1 results.

Phase 2

Visual enhancements to the answer card, pinning AgentQL answers to Liveboards, and parameter support. Targeted for a future release.

AgentQL is enabled via a LaunchDarkly feature flag and will be progressively rolled out starting from ThoughtSpot Cloud 26.8. Contact your ThoughtSpot administrator if you do not see AgentQL on your instance.

Limitations and constraints

  • Chart visualization is not yet available. The answer card currently shows a summary and table. The chart experience is planned for a future update.

  • Pinning to Liveboards is not available in Phase 1. This is targeted for Phase 2.

  • Parameter support is not available in Phase 1. Spotter cannot use or modify parameters via AgentQL until Phase 2 (targeted for a future release).

  • Python code execution is not fully replaced. Code execution is still used for statistical analysis (forecasting, regression) and for answers that must be stitched from multiple data models.

  • AgentQL answers cannot be pinned to a Liveboard in Phase 1. Pinning is scoped to Phase 2.

AgentQL triggers automatically for complex questions. Spotter autonomously decides when to use AgentQL, TML search tokens, or code execution based on the nature of your question.

Frequently asked questions

How does Spotter decide when to use AgentQL?

Spotter’s agent autonomously selects the best execution path based on the complexity of your question. You can also explicitly request AgentQL by mentioning it in your prompt. When AgentQL is active, the Show work panel displays a creating_answer_using_AgentQL event.

Is data governance maintained with AgentQL?

Yes. AgentQL routes through the QGen semantic layer and fully respects RLS, CLS, column dependencies, custom calendar configurations, and all data governance controls defined in the TML model.

Will AgentQL replace Python code execution entirely?

No. Python code execution is still required for statistical analysis such as forecasting and regression, and for answers that stitch together results from multiple data models.

Can I pin AgentQL answers to a Liveboard?

Not in Phase 1. Pinning is targeted for Phase 2.

Additional resources