Skip to main content

Natural Language Queries

ASK translates a question into SQL using the selected schema as context, validates the generated statement, and executes it through the query engine. Use it for exploration, then inspect the SQL and results before adopting a query in a report or application. Syntactic validation does not prove that an interpretation answers the intended question.

Quick Start​

After preparing the natural-language tutorial:

ASK 'What is the top-selling product by total revenue across all orders? Use all dates.'
    WITH SCOPE tutorial.sales;

The tutorial provides known source rows so you can compare the answer with an ordinary SQL aggregation. Be explicit about dates, metric definitions, ties, and whether returns or cancellations should be excluded.

Syntax​

ASK 'your question' WITH SCOPE catalog_name.schema_name;

An explicit scope avoids dependence on the editor's current selection. A named conversation can supply its stored scope; otherwise the request/session context must supply it.

Explain the context​

EXPLAIN ASK 'top selling product by revenue'
    WITH SCOPE tutorial.sales;

EXPLAIN ASK describes scope and retrieval context. It does not provide a completed model answer or prove generated SQL correctness.

Configuration​

ASK and SUGGEST QUERIES use Gnok's AI provider; you don't supply a provider API key. They are off for each organization until an organization administrator, in Studio under Operations → AI Governance, saves a monthly token budget as Available and enables a rollout policy. The policy must allow the provider (anthropic) and model (claude-haiku-4-5-20251001), with egress and retention approved. EXPLAIN ASK makes no provider call. See AI Governance.

How It Works​

  1. Resolve the authenticated tenant, catalog/schema scope, and optional conversation.
  2. Gather schema context and relevant tables.
  3. Send the question and selected schema context to Gnok's AI provider.
  4. Validate the generated SQL and retry within the configured budget when appropriate.
  5. Execute an accepted query through the regular query path.

Schema context and retrieval​

Schema context includes table and column metadata. Multi-hop retrieval narrows large inventories to relevant tables and related join neighbors when the schema-embedding infrastructure is available. Multi-hop retrieval is service-managed and can fall back when it cannot narrow the schema.

The service-managed schema-size gate limits the tables sent after retrieval. A table limit can omit relevant context, so use a focused scope and inspect the generated SQL when a required table appears to be missing.

SQL validation​

Generated SQL must be a single read-only query; modifying statements and multiple statements are rejected. This limits the allowed operation but does not establish business correctness. Check join keys, filters, units, date boundaries, and aggregate definitions against the data.

Multi-turn conversations​

Conversation history is explicit. Begin a conversation and use the returned session ID for subsequent questions:

BEGIN CONVERSATION WITH SCOPE tutorial.sales;

Copy the returned ID in place of the placeholder:

ASK 'Revenue by product across all dates' IN '<returned-session-id>';
ASK 'Now break that down by region' IN '<returned-session-id>';
END CONVERSATION '<returned-session-id>';

Repeating unrelated one-shot ASK statements does not automatically join them into a durable conversation. Scope and successful prior turns are restored through the catalog; an invalid or ended conversation is an error rather than a silent new conversation.

SUGGEST QUERIES​

SUGGEST QUERIES
    ABOUT 'revenue trends and product mix'
    LIMIT 5
    WITH SCOPE tutorial.sales;

Suggestions contain rank, title, description, and sql. ABOUT is optional; LIMIT defaults to 5 with a cap of 20. Returned SQL is checked before inclusion. The requested limit is an upper bound: provider output limits or rejected suggestions can produce fewer rows.

Suggestions use the same provider and AI Governance as ASK. Inspect and run the chosen SQL; receiving a suggestion does not execute it or validate its business interpretation.

Cost and data handling​

Questions, selected schema context, and conversation context can be sent to Gnok's AI provider. Use only authorized inputs and treat schema names and questions as potentially sensitive. Retries increase token use. Reuse inspected SQL for scheduled reports and application hot paths instead of regenerating it on each request.

The AI scalar functions are a separate surface for text completion, extraction, and classification. AI_SQL produces SQL text without the same schema-grounded ASK workflow.

Limitations​

Ambiguous questions, incomplete schema context, and model errors can all produce a syntactically valid but incorrect answer. Neither temperature zero nor successful parsing guarantees reproducibility or accuracy. Compare important answers with source rows or an independently written query.

Natural-language tutorial · AI scalar functions · Configuration

Last updated on