Practitioner Evidence Dossier: Reliable, Governed AI-Assisted Analytics from Natural-Language Questions
Research snapshot: October 3, 2026
Operational question: How should an AI analytical system be designed, evaluated, and operated so that natural-language questions produce traceable, governed, and sufficiently reliable answers from company data?
The central finding is straightforward:
Do not design the system as “a language model that writes SQL.” Design it as a governed analytical compiler and execution system in which the model is allowed to perform only selected probabilistic steps.
An answer is not reliable merely because its SQL parses or executes. Production reliability requires five separate things to be sufficiently correct: the business meaning, the state and suitability of the data, the computation, the returned result, and the interpretation presented to the user. Enterprise text-to-SQL evidence strongly supports this distinction: Spider 2.0 contains schemas averaging hundreds of columns, often more than 1,000, and realistic tasks requiring metadata search, documentation, multiple queries, and project context; its reported agent performance was dramatically below traditional text-to-SQL benchmarks. 1
The recommended operating principle is therefore:
LLM for interpretation and bounded planning; governed artifacts for meaning; deterministic software for permissions, validation and execution; independent checks for results; constrained generation for narrative.
Production architecture and governing contract
Production reference architecture
The target architecture should look conceptually like this:
text
┌──────────────────────────────┐<br> │ User + identity + question │<br> └──────────────┬───────────────┘<br> │<br> ▼<br> ┌──────────────────────────────┐<br> │ Question classifier │<br> │ risk + analytical task │<br> └──────────────┬───────────────┘<br> │<br> ▼<br> ┌──────────────────────────────┐<br> │ Analytical contract builder │<br> │ terms, metric, time, grain │<br> │ entity, filters, output │<br> └──────────────┬───────────────┘<br> │<br> unresolved ambiguity?<br> ┌──────┴──────┐<br> yes│ │no<br> ▼ ▼<br> clarification semantic resolver<br> │<br> ┌───────────────────────────┼──────────────────────────┐<br> ▼ ▼ ▼<br> governed metrics schema / joins verified queries<br> glossary / contracts descriptions examples<br> └───────────────────────────┬──────────────────────────┘<br> ▼<br> scoped analytical plan<br> │<br> ▼<br> deterministic policy / contract gate<br> │<br> ▼<br> SQL compiler / generator<br> │<br> ▼<br> AST + join + grain + cost validation<br> │<br> ▼<br> read-only execution gateway<br> │<br> ▼<br> result + DQ + freshness validation<br> │<br> ▼<br> deterministic result object<br> ┌──────────┴─────────┐<br> ▼ ▼<br> visualization narrative layer<br> observed /<br> inferred /<br> hypothesized<br> └──────────┬─────────┘<br> ▼<br> answer + evidence panel<br><br> Every stage → structured trace / versions / audit events<br>
This is deliberately different from a typical agent loop. Permissions, metric semantics, valid join relationships, cost limits and validation rules must not depend on the model deciding to follow instructions. Current production products already reflect pieces of this architecture: Databricks Genie restricts an agent to explicitly attached sources and evaluates data access against each end user’s Unity Catalog permissions; Snowflake separates question categorization from SQL-generation instructions; dbt MetricFlow compiles governed metric definitions; Looker uses modeled join cardinalities and primary keys to protect aggregations. 2
A useful acceptance equation is:
[
R_{\text{answer}} =
R_{\text{meaning}}
\land R_{\text{data}}
\land R_{\text{query}}
\land R_{\text{result}}
\land R_{\text{interpretation}}
\land R_{\text{authorization}}
]
This is a conjunctive, not averaging, model. A perfect SQL query implementing the wrong definition of “active customer” still fails. A correct calculation over an incomplete load still fails. Correct numbers accompanied by a fabricated root-cause explanation still fail.
Analytical contract / question model
Before generating SQL, turn the user’s prose into a typed analytical contract. The LLM may propose this representation, but the system—not the LLM—should determine whether enough required fields have been resolved.
A practical contract is:
| Contract field |
Production representation |
Required before SQL? |
| Original question |
immutable user text + conversation reference |
Always |
| User / authorization context |
principal, groups, tenant, applicable data policy |
Always |
| Task class |
lookup, slice, trend, comparison, exploratory, diagnostic, forecast, causal, unsupported |
Always |
| Business terms |
canonical concept IDs + matched aliases |
Whenever relevant |
| Metric |
governed metric ID, version, definition reference |
Required for metric questions |
| Dimensions |
canonical dimension IDs |
When grouping/slicing |
| Filters |
explicit filters plus governed defaults |
When material |
| Timeframe |
start/end or relative-period expression |
Normally |
| Time semantics |
event date / booking date / ingestion date etc. |
When multiple candidates exist |
| Calendar |
Gregorian, fiscal, ISO week, custom periods |
When relevant |
| Timezone |
canonical timezone |
Whenever boundary-sensitive |
| Grain |
intended output grain |
Always for tabular analytical results |
| Entity |
order, account, user, subscription, session etc. |
When entity counting/aggregation occurs |
| Population |
inclusion/exclusion/cohort conditions |
Whenever materially affects result |
| Units |
currency, percentage basis, quantity unit |
When relevant |
| Source scope |
permitted logical data products / semantic models |
Always |
| Join path |
governed relationship edges |
For multi-source queries |
| Expected output |
scalar/table/time series; schema; sorting; cardinality |
Always |
| Validation plan |
applicable invariants/reconciliations |
Before execution |
| Unresolved assumptions |
explicit structured list |
Must be empty or approved defaults |
| Semantic versions |
metric/model/contract versions |
Always |
| Freshness requirement |
maximum acceptable age / SLA class |
Whenever answer is freshness-sensitive |
This approach has production precedent. Semantic systems model metrics, dimensions and relationships explicitly rather than asking the model to rediscover those semantics for every question; dbt’s semantic layer validates semantic models and compiles metric queries, while Databricks recommends structured SQL expressions and metric views over plain-text instructions for business semantics. 3
What must be explicit before SQL generation?
For routine analytical questions, at minimum:
metric or measure meaning + population/entity + timeframe/date semantics + output grain + dimensions + material filters + permitted source domain.
Add currency, timezone, fiscal calendar, cohort semantics and comparison baseline whenever they can change the answer.
The wrong design is to let SQL generation double as semantic disambiguation. Once SQL exists, both machines and reviewers become anchored on an implementation that may answer the wrong question.
Mandatory clarification policy
Clarification should be mandatory when two plausible interpretations can materially alter the result and there is no governed default.
Examples include:
-
“Revenue” matches gross revenue and recognized net revenue.
-
“Customers” could mean accounts or end users.
-
“Last quarter” is ambiguous between calendar and fiscal quarters.
-
“Conversion rate” has competing denominators.
-
The requested comparison does not identify the baseline.
-
A cohort definition is missing.
-
The intended currency or exchange-rate policy is unclear.
-
More than one legitimate date field could define the period.
-
A requested metric has no governed definition.
-
The join needed to answer the question has no governed relationship.
-
The user requests a causal conclusion from a workflow that supports only descriptive analytics.
This is not merely theoretical. Snowflake’s Cortex Analyst exposes a separate question_categorization mechanism that can classify a request as unclear, ask for missing details, or reject prohibited topics. Databricks likewise recommends explicit trigger conditions describing exactly which missing parameters require clarification—for example time range, sales channel or KPI selection. 4
A governed default can avoid clarification, but it should be represented as policy, not guessed by the model:
“Using the corporate fiscal quarter and EUR reporting currency, per Finance Analytics policy v12.”
Silent defaults are semantic debt.
Question-classification strategy
Classification should happen before analytical planning, because “give me revenue last month,” “why did revenue drop?” and “what will revenue be next month?” are fundamentally different analytical operations.
| Question class |
Allowed workflow |
Key constraint |
| Known metric lookup |
governed metric → bounded query → validation |
No free-form metric invention |
| Slice/filter |
metric + governed dimensions/filters |
Validate dimensional compatibility |
| Trend |
metric + time dimension + calendar |
Explicit period/grain |
| Comparison |
two governed populations/periods → deterministic difference |
Comparable populations and units |
| Exploratory analysis |
multi-step bounded exploration |
State, budget and stopping criteria |
| Diagnostic analysis |
hypothesis → multiple validated queries |
Output association/evidence, not automatic causation |
| Forecasting |
route to approved forecasting workflow |
Backtesting, horizon, intervals, model provenance |
| Causal question |
causal-analysis gate |
No causal claim from ordinary descriptive SQL |
| Unsupported/out of scope |
refusal or capability explanation |
Do not fabricate an answer |
Snowflake’s explicit separation between question categorization and SQL generation provides production evidence for this architectural split. 4
Recommendation: make classification deterministic where possible. Rules can reliably detect certain classes—forecasting language, explicitly causal questions, prohibited domains, known metric IDs—and use the model only for residual classification. Treat the output as another auditable artifact.
Semantic context, verified knowledge and schema grounding
Semantic-context strategy
The system needs multiple sources of semantics, but it should not treat them as interchangeable.
A useful hierarchy is:
| Semantic source |
Typical reliability |
Maintenance burden |
Appropriate role |
| Versioned metric/semantic layer |
High |
Medium–high upfront |
Canonical computation |
| Data contract / governed data product |
High |
Medium |
Grain, keys, guarantees, ownership |
| Governed glossary |
High if owned/versioned |
Medium |
Business terminology |
| Curated relationship graph |
High |
Medium |
Valid join paths/cardinalities |
| Verified query |
High for its exact question/version |
Medium–high |
Demonstrated implementation/example |
| dbt/model documentation |
Medium–high |
Medium |
Table/column meaning and lineage |
| Table/column descriptions |
Medium |
Medium |
Schema grounding |
| Analyst-authored instructions |
Medium |
Medium |
Exceptional policies/workflow guidance |
| Example questions/SQL |
Medium |
Medium–high at scale |
Pattern guidance |
| Unowned natural-language metadata |
Low–medium |
Apparently low, often hidden drift |
Retrieval hint only |
Databricks’ current guidance is unusually explicit: use SQL expressions for reusable business semantics, example SQL for complex patterns and text instructions only where structured methods do not apply; it also warns against conflicting instructions. 5
Precedence must be governance-based, not prompt-order-based. I recommend this conflict order:
-
Authorization, privacy and security policy.
-
Versioned canonical metric/semantic definition.
-
Data contract, grain and relationship constraints.
-
Domain-governed analytical policy.
-
Verified query compatible with the current versions.
-
Governed catalog/glossary metadata.
-
Examples and analyst instructions.
-
Ungoverned descriptions.
When two artifacts of equal authority disagree, stop rather than merge them probabilistically. Record the conflict and request clarification or owner resolution.
A verified query must not silently override a newer canonical metric definition merely because it has historically worked.
Verified-query patterns
Verified queries are valuable, but they solve a narrower problem than sometimes advertised.
Snowflake’s Verified Query Repository stores natural-language questions with corresponding SQL and retrieves relevant verified queries when answering similar questions; entries can record verifier and verification time. Databricks similarly allows reviewed SQL examples to become agent instructions and uses SQL answers as benchmark ground truths. 6
Use them differently according to match confidence:
| Pattern |
Reliability contribution |
Recommended use |
| Exact semantic match |
Very high if still version-compatible |
Execute stored parameterized query deterministically |
| Template match |
High |
Bind validated parameters into approved template |
| Similar-query retrieval |
Moderate–high |
Provide pattern/context to planner |
| Few-shot example |
Moderate |
Steering only; generated query still requires full validation |
| Query repair example |
Moderate |
Teach known dialect/business patterns |
| Regression gold item |
High |
Compare result against known answer |
| User suggestion / landing-page example |
Low as correctness evidence |
Discoverability only |
A key distinction:
A retrieved verified query should be evidence, not automatically truth.
Before reuse, verify:
-
semantic-model version compatibility;
-
metric version;
-
relevant schema versions;
-
applicable date/filter policy;
-
authorization scope;
-
parameter ranges;
-
whether it was intended as an example or an authoritative template.
Snowflake itself warns operationally that VQR entries are used to influence answers to similar questions, which makes a bad or obsolete verified query a reusable error amplifier. 6
Overfitting risk. Verified-query repositories disproportionately improve questions close to what analysts anticipated. They cannot establish reliability for novel metric combinations, unseen join paths or new semantics. That conclusion follows directly from the similarity-based retrieval mechanism documented by Snowflake and should therefore be treated as an architectural inference rather than an independently measured universal effect. 6
Schema grounding and join control
Large enterprise schemas are hostile to “dump the whole schema into the prompt.”
Spider 2.0’s enterprise-oriented tasks involve databases averaging roughly 744–812 columns depending on benchmark variant, with large schemas, nested structures and multiple SQL dialects; successful tasks often require searching metadata and documentation rather than merely seeing table names. 1
Current production guidance converges on domain scoping. Databricks recommends starting a Genie Agent with five or fewer relevant tables where possible, despite supporting a larger technical limit, and recommends prejoined views or metric views for more complex domains. 5
The grounding pipeline should therefore be hierarchical:
text
business domain<br> ↓<br>candidate governed data products<br> ↓<br>semantic entities / metrics<br> ↓<br>candidate tables or views<br> ↓<br>relevant columns<br> ↓<br>valid relationship subgraph<br> ↓<br>candidate literals / values<br>
Do not perform a single embedding search over every table and then let the model invent the rest.
Useful schema-grounding metadata includes:
-
row grain;
-
canonical entity;
-
primary/unique keys;
-
foreign-key/relationship information;
-
dimension and measure type;
-
synonyms;
-
value examples where safe;
-
descriptions;
-
lineage;
-
ownership;
-
data classification;
-
freshness;
-
applicable metrics;
-
prohibited joins.
Descriptions improve grounding, but they are not equivalent to executable governance. Databricks states that clear table/column descriptions and synonyms improve agent interpretation while also recommending human review of AI-generated descriptions. 5
Join control
Dynamic join choice is one of the highest-risk freedoms to give an analytical model.
Looker’s documentation demonstrates why. Joining an order-level measure onto an order-item table can turn a correct total of 124.84 into 223.44 through duplicated facts. Looker protects such calculations using modeled primary keys, declared relationship cardinalities and symmetric aggregates; its documentation explicitly states that these protections depend on the unique primary key and relationship being correctly modeled. 7
Recommended precedence for joins:
governed semantic relationship → curated/prejoined dataset → approved analyst join rule → explicitly permitted AI-selected edge
—not arbitrary AI-generated JOIN ... ON.
Prevent the agent from dynamically inventing a join when:
-
two fact tables are being joined at incompatible grains;
-
an undeclared many-to-many relationship is required;
-
the join key is non-unique and no bridge semantics exist;
-
temporal validity/SCD logic is required but unmodeled;
-
the requested metric is non-additive across the proposed path;
-
different identity namespaces are involved;
-
the relationship crosses a sensitive data boundary;
-
no owner-approved join exists.
Looker explicitly models one_to_one, many_to_one, one_to_many, and many_to_many relationships because correct relationship declarations are necessary for accurate measures. 8
My recommended production stance: for high-value company metrics, an AI agent should be allowed to select among governed join paths, not invent relationship semantics.
Grain, metrics, query generation and deterministic verification
Grain and metric controls
Grain should be represented as a type, not documentation trivia.
Every analytical data object should expose:
text
row_grain<br>entity_key<br>uniqueness_constraint<br>time_grain_if_applicable<br>allowed_join_relationships<br>
Every governed metric should additionally expose:
text
metric_id<br>metric_version<br>measure_expression<br>native_entity<br>native_grain<br>aggregation_type<br>additivity<br>allowed_dimensions<br>required_filters<br>excluded_populations<br>denominator_definition<br>time_dimension<br>calendar<br>currency / unit policy<br>attribution policy<br>cohort policy<br>
dbt’s semantic abstractions encode metrics, dimensions and identifiers and validate semantic-model consistency; dbt’s generic data tests can enforce uniqueness, not-null constraints, accepted values and relationship integrity. 3
Practical grain checks should include:
Before a join
-
uniqueness test of declared primary/entity keys;
-
relationship/cardinality assertion;
-
compatibility between metric and requested dimension;
-
declared fact grain versus intended result grain.
During/after a join
-
fact-row count comparison where appropriate;
-
distinct fact-key count comparison;
-
measure reconciliation before and after dimension enrichment;
-
many-to-many key detection;
-
uniqueness of expected result keys.
Before returning the answer
-
group-by columns correspond to the analytical contract;
-
result cardinality is plausible;
-
no implicit aggregation has altered the entity definition.
Do not accept DISTINCT as a generic fix for a fanout problem. It can hide duplicates while changing legitimate counts.
Metrics
For AI consumption, I would rank metric representations this way:
| Representation |
Production role |
Main weakness |
| Metric API backed by versioned semantic model |
Preferred computational interface |
Requires semantic infrastructure |
| Versioned semantic/metric layer |
Preferred canonical definition |
Governance/maintenance investment |
| Approved parameterized stored query |
Excellent for bounded known question |
Brittle outside its intended shape |
| Reviewed raw SQL definition |
Usable implementation artifact |
Easy to duplicate/diverge |
| Natural-language definition |
Human explanation and retrieval |
Not sufficient computational specification |
MetricFlow’s purpose is precisely to compile semantic metric definitions into reusable SQL, including more complex metric and join behavior, instead of requiring each consumer to recreate the formula. 9
The dangerous metric errors are often not syntax errors at all:
-
numerator or denominator changed;
-
“active” filter missing;
-
cancellation/refund exclusion omitted;
-
Gregorian versus fiscal calendar;
-
gross versus net currency conversion;
-
attribution window differs;
-
customer versus account cohort;
-
metric definition changed without pinning the version.
Databricks’ troubleshooting examples explicitly include fiscal-calendar misinterpretation, and its current guidance prefers structured expressions for metrics/filters rather than plain-text instruction. 10
Non-negotiable rule: when no governed definition exists for a business metric, the system must not silently synthesize one. It can propose a provisional definition for user approval, but that is a different operation from answering the analytical question.
Query generation and execution
The default production path should be:
plan → validate contract → retrieve governed context → compile or generate → parse → policy-check → dry-run/explain → execute → validate result
rather than:
question → SQL → run.
One-shot SQL is reasonable only for low-complexity questions where the contract and semantic path are already unambiguous.
Planning becomes increasingly valuable for multi-table and multi-step enterprise work. Spider 2.0 shows that realistic enterprise problems can involve project code, metadata searches, dialect-specific functions and multiple SQL statements, with substantially poorer success rates than conventional benchmark tasks. 1
Execution feedback is useful for:
-
missing columns;
-
dialect errors;
-
type mismatches;
-
invalid SQL;
-
timeout/cost feedback.
It is not evidence that the business semantics became correct. An agent can iteratively repair an executable query while preserving the original wrong interpretation.
Database trust must be independent of model trust
Even a “well-aligned” agent should operate through an execution gateway enforcing:
-
read-only or narrowly scoped credentials;
-
permitted statement classes;
-
DDL/DML prohibition for analytical agents;
-
dataset/table allowlists;
-
row and result-byte limits;
-
statement timeout;
-
scan/cost limits;
-
concurrency limits;
-
query cancellation;
-
sandbox routing for experimental workflows.
For example, BigQuery exposes query validation/dry runs that validate query structure and estimate bytes processed before execution; Snowflake supports a warehouse/session statement timeout that causes long-running SQL to be cancelled. 11
Those are database controls. An instruction saying “never run expensive SQL” is not equivalent.
Deterministic validation
A substantial portion of the analytical pipeline can and should be checked without an LLM.
| Validation |
Deterministic? |
Typical method |
| SQL parses in intended dialect |
Yes |
parser/compiler |
| Statement is read-only |
Yes |
AST policy |
| Only allowed objects referenced |
Yes |
AST + catalog |
| Required metric selected |
Yes if canonical metric ID exists |
contract comparison |
| Mandatory filter present |
Yes |
normalized predicate AST |
| Date range valid |
Yes |
typed date validation |
| Maximum period respected |
Yes |
policy |
| Join edge allowed |
Yes |
relationship graph |
| Cardinality declared |
Yes |
semantic model |
| Estimated scan/cost acceptable |
Usually |
warehouse dry-run/explain |
| Expected columns/types returned |
Yes |
result contract |
| Maximum rows respected |
Yes |
execution/result gate |
| Declared result grain unique |
Often |
uniqueness assertion |
| Obvious fanout occurred |
Often |
pre/post invariant |
| Known totals reconcile |
Yes when reference exists |
reconciliation |
| Data meets freshness threshold |
Yes |
DQ/freshness metadata |
| Correct interpretation of “good customers” |
No, unless governed |
semantic resolution |
| Correct causal explanation |
No |
separate analytical methodology |
| “Best” recommendation justified |
Generally no |
human/decision workflow |
The boundary matters: static validators establish rule conformance, not analytical truth.
Result validation
The result layer needs independent checking because plausible-but-wrong output is the failure users are least likely to notice.
Use multiple mechanisms:
Trusted computation comparison. For covered questions, compare with a verified query or canonical metric API rather than comparing SQL text. Databricks’ benchmark facility compares generated query results against an analyst-provided SQL answer and treats semantically equivalent result sets as correct even when SQL differs. 10
Reconciliation. Compare the same metric/version/time/filter context with a trusted dashboard or certified report.
Invariants. Examples:
-
region totals should reconcile to overall total;
-
component counts cannot exceed population counts unless definition permits;
-
percentage components should reconcile to the expected whole;
-
inventory cannot be negative where the domain forbids it;
-
detailed-result aggregation should equal separately computed aggregate result.
Cross-query checks. Compute important numbers through an independent query shape.
Sampling and drill-through. Validate a small number of underlying entities against source records.
Statistical sanity checks. Compare ranges, distribution, day-over-day movements and missingness against historical behavior.
None proves business correctness individually. A strong system layers them.
Data state, provenance and generated interpretation
Data-quality and freshness integration
The answer must carry the state of its inputs with it.
At minimum preserve:
-
latest successful upstream load;
-
effective source-data timestamp;
-
freshness threshold and status;
-
missing/incomplete partitions;
-
relevant failing tests;
-
known incident or outage;
-
cache timestamp and cache age;
-
metric-definition version;
-
semantic-model/deployment version.
dbt explicitly supports source-freshness thresholds and can be configured so stale data fails a pipeline step and prevents later steps from running. Its guidance ties check frequency to the applicable freshness SLA. 12
A user-facing answer should therefore distinguish:
Query executed: 2026-10-03 14:06 UTC
Data current through: 2026-10-03 11:00 UTC
Freshness SLA: 2 hours
Status: within SLA
rather than displaying only “generated just now.”
Refuse versus qualify
Recommended policy:
| Data condition |
Behavior |
| Critical upstream freshness error |
Refuse current answer or explicitly offer last known trusted snapshot |
| Critical test indicates materially incorrect data |
Refuse |
| Source outage with certified cache |
Answer only if cache timestamp is conspicuous |
| Noncritical warning known not to affect requested lineage |
Answer with qualification |
| Freshness slightly beyond soft SLA |
Warning, depending on use-case risk |
| Unknown data state |
Treat as degraded confidence, not “healthy” |
Lineage allows degradation to be scoped rather than globally disabling analytics. OpenLineage’s standard explicitly associates metadata with datasets, jobs and runs to help identify root causes and downstream impact. 13
Provenance model
Persist the entire structured decision chain:
text
question<br>→ authenticated principal<br>→ task classification<br>→ interpreted analytical contract<br>→ resolved business-term IDs<br>→ metric ID + version<br>→ dimensions / filters / timeframe / grain<br>→ retrieved semantic artifacts + versions<br>→ selected data sources<br>→ selected relationship path<br>→ analytical plan<br>→ generated SQL<br>→ validated SQL<br>→ executed SQL<br>→ warehouse query ID<br>→ input freshness / DQ state<br>→ raw result metadata / result hash<br>→ validation results<br>→ deterministic derived statistics<br>→ visualization specification<br>→ narrative input<br>→ narrative output<br>→ model/version<br>→ human-review outcome<br>
This should be a structured trace, not a requirement to retain private free-form chain-of-thought. What operators need is reconstructable decisions, artifacts and tool actions.
OpenLineage provides a useful standard for the data side—datasets, jobs and runs—while OpenTelemetry provides standard tracing infrastructure; an analytical AI system still needs analytics-specific fields layered on top. 13
What users should see
Expose a compact evidence panel:
-
interpreted metric;
-
timeframe/calendar;
-
dimensions and filters;
-
grain;
-
source/certified dataset;
-
“data through” timestamp;
-
warnings;
-
metric version;
-
optionally expandable SQL.
What operators should additionally retain
-
retrieved candidate context and selected artifact IDs;
-
policy decisions;
-
full executed SQL;
-
query ID;
-
validation checks/results;
-
prompt/configuration/model identifiers;
-
semantic deployment version;
-
result hash/statistics;
-
cost and latency;
-
security decisions;
-
review/feedback.
Avoid unnecessarily copying sensitive result data into observability systems. Store identifiers, hashes and bounded diagnostic samples where possible.
Narrative and visualization controls
The deterministic analytical result and its prose explanation should be separate artifacts.
Use a narrative contract with three categories:
Observed
Revenue was €4.21M in September, down 7.2% from August.
Numbers come directly from validated calculations.
Inferred
The decline is concentrated in the DACH segment, which accounts for €210k of the €327k month-over-month decrease.
This is derived by a defined decomposition and should preserve method/provenance.
Hypothesized
Possible explanations include lower acquisition volume or increased churn; these data do not establish the cause.
The model must not quietly promote a hypothesis into an observed finding.
Specific deterministic controls should calculate rather than language-generate:
Ban or gate words such as “caused,” “significant,” “driven by,” “explains,” and “therefore we should” unless the corresponding analytical evidence exists.
A “why did revenue fall?” question should not make the system a causal inference engine by linguistic accident.
Visualization
The chart should be generated from the validated result schema, not independently regenerated from the original natural-language request.
Automatically check:
-
every plotted series maps to a returned field;
-
chart aggregation equals query aggregation;
-
units and labels match metric metadata;
-
date dimension matches the requested time grain;
-
categorical comparisons use comparable populations;
-
chart does not silently omit categories;
-
percentage axis and numeric formatting match semantics;
-
uncertainty intervals are displayed when material and supplied;
-
result cardinality is suitable for the selected chart type;
-
bar-chart baseline policy is obeyed;
-
no secondary-axis comparison is introduced without explicit rules.
The system can mechanically reject many misleading charts. Selecting the most insightful visualization remains a softer semantic task.
Multi-step / agentic analysis
Autonomy is most justified for exploratory and diagnostic questions, not routine metric retrieval.
Each agentic step should have explicit state:
text
step ID<br>hypothesis / sub-question<br>analytical contract<br>sources<br>SQL<br>query ID<br>result hash<br>validation outcomes<br>new evidence<br>remaining uncertainty<br>cumulative cost<br>
Only validated intermediate results should become premises for later steps.
Stopping criteria should include:
Spider 2.0 confirms that realistic enterprise analytical workflows often require multi-query interaction and planning, while simultaneously demonstrating that this is much harder than ordinary text-to-SQL. 1
Prefer predefined analytical workflows over unconstrained agents for repeatable tasks such as:
Let the model choose parameters and branches inside the workflow rather than reinvent the methodology.
Human-review patterns
Reviewing every SQL statement is not a viable end state. The highest-leverage review point depends on the type of risk.
My recommended hierarchy is:
| Review target |
Errors caught well |
Errors it misses |
| Analytical intent/contract |
wrong question, missing dimensions/time/population |
SQL implementation errors |
| Metric definition |
semantic disagreement |
query implementation |
| SQL |
wrong joins, predicates, formulas |
subtle wrong business premise |
| Result |
obvious anomalies/reconciliation errors |
plausible systematic errors |
| Narrative |
causal overreach, misleading framing |
upstream numerical errors |
| Recommendation |
unjustified business action |
underlying technical issues |
For materially important questions, the highest-leverage early review is usually the analytical contract/metric definition, not the generated SQL. That is a synthesis recommendation: once the system has misunderstood the requested business object, reviewing syntactically competent SQL may simply validate the wrong implementation.
Use risk tiers:
-
Low-risk known lookup: automated.
-
Novel multi-table calculation: contract + automated validation, possibly analyst review.
-
Executive/KPI publication: metric/result review.
-
Causal, forecasting or consequential recommendation: methodology/final-output review.
-
New semantic definition: domain-owner approval before reusable deployment.
Databricks’ production workflow similarly supports requesting manual review, inspecting generated SQL, correcting it and turning corrected queries into future examples. 10
The countervailing risk is review economics: if human review becomes mandatory for every query, the product becomes a slower dashboard request queue. Governance must therefore remove recurring reasons for review by turning corrections into metrics, contracts, tests and verified patterns.
Evaluation, regression, observability and security
Organizational evaluation suite
Do not evaluate with random easy questions. Build a deliberately adversarial suite that tests every reliability layer.
| Test case |
Test construction |
Expected system behavior |
| Basic metric retrieval |
Unambiguous governed metric and period |
Resolve canonical metric, execute, validate, answer |
| Ambiguous metric |
“What was revenue?” with multiple revenue definitions |
Clarify before SQL |
| Ambiguous date range |
“recent customer growth” without governed “recent” default |
Clarify, or apply and explicitly disclose approved default |
| Multi-table join |
Valid fact→dimension relationship |
Use only governed join path; verify cardinality |
| Wrong-grain trap |
Account metric requested by user/session field |
Detect incompatible grain; refuse/repair |
| Fanout trap |
Order measure joined through order_items |
Block or use governed fanout-safe computation |
| Hidden filter |
Metric requires excluding test/internal accounts |
Apply governed filter and preserve provenance |
| Stale-data case |
Source exceeds freshness SLA |
Qualify or refuse according to policy |
| Conflicting definitions |
Glossary/query says A; canonical metric says B |
Do not blend; prefer governed authority or escalate |
| Unauthorized data request |
User asks for salary/PII outside permission |
Deny before execution; reveal no protected values |
| Impossible question |
Required event/attribute never collected |
State insufficient data; do not invent proxy silently |
| Causal question |
“Did campaign X cause retention to improve?” |
Route to causal workflow or explicitly decline causal conclusion |
| Forecasting request |
“What will next quarter’s ARR be?” |
Route to forecasting workflow, with provenance/backtest/interval |
| Source outage |
Canonical source unavailable |
Explicit failure or clearly labeled certified cached snapshot |
| Malformed schema metadata |
Invalid key/cardinality/description conflict |
Quarantine/fail semantic validation; do not improvise around it |
Every case should have:
-
several paraphrases;
-
entity aliases;
-
innocuous and adversarial variants;
-
expected task classification;
-
expected contract;
-
expected clarification/refusal;
-
allowed sources;
-
expected metric/version;
-
validation assertions;
-
final expected result or behavior.
Databricks recommends testing realistic questions, adding multiple phrasings of the same question, and comparing generated results against SQL ground truth. It also explicitly notes LLM non-determinism, making repeated trials important. 10
Its documented benchmark implementation provides another useful lesson: result comparisons can have operational edge cases such as row-count truncation and ordering, so the evaluator itself needs testing. 10
Never report one aggregate “accuracy” number alone. Report performance by task class and severity. NIST’s agent-security evaluations demonstrate the same general evaluation principle: aggregate success rates can hide drastically different performance and consequences for individual task types. 14
Recommended scorecard:
| Layer |
Example metric |
| Intent |
exact contract-field accuracy |
| Clarification |
required-clarification recall / unnecessary-clarification rate |
| Metric |
canonical metric resolution accuracy |
| Schema |
source/table/column recall and precision |
| Join |
valid relationship-path rate |
| SQL |
execution/result equivalence |
| Grain |
grain-trap detection rate |
| Result |
reconciliation pass rate |
| Freshness |
stale-data detection rate |
| Security |
unauthorized-query prevention rate |
| Narrative |
unsupported-claim rate |
| Cost |
p50/p95 warehouse + model cost |
| Latency |
p50/p95 end-to-end |
| Human burden |
reviews per 100 questions / analyst minutes |
Regression strategy
Treat the analytical agent exactly like changing software.
Run regression when any of these changes:
Maintain two complementary suites:
Frozen regression suite. Stable data snapshot and expected outputs. This gives reproducibility.
Live canary suite. Runs against current production semantics/data. This catches freshness, schema and integration problems that snapshots cannot.
Regression gates should cover:
-
contract interpretation;
-
mandatory clarification/refusal;
-
semantic retrieval;
-
metric selection;
-
join/grain validation;
-
SQL parsing/execution;
-
result equivalence;
-
DQ/freshness propagation;
-
security/adversarial tests;
-
narrative unsupported-claim checks;
-
latency/cost.
Schema/semantic systems already apply similar software-engineering concepts. dbt semantic validations catch invalid semantic configurations, while BI systems such as Looker provide content validation to detect downstream references broken by model changes. 3
Verified question/SQL pairs are especially valuable as regression gold items—but compare canonical result semantics rather than requiring textual SQL equality unless query shape itself is a policy requirement. Databricks’ benchmark mechanism likewise accepts equivalent result sets, not only identical SQL. 10
Observability model
Each answer should produce one trace spanning the entire pipeline.
Minimum events/attributes:
| Area |
Capture |
| Request |
trace ID, session, user/role, question |
| Classification |
task class, risk tier, confidence |
| Interpretation |
normalized analytical contract |
| Retrieval |
candidates, scores, selected artifact IDs |
| Semantics |
metric IDs/versions, semantic deployment |
| Schema |
selected sources, fields, relationship path |
| Generation |
model, model configuration, prompt/config hash |
| Query |
proposed SQL, final SQL, AST validation |
| Execution |
query ID, warehouse, execution state |
| Result |
schema, row count, bounded statistics, result hash |
| Data state |
freshness, test failures, incidents |
| Validation |
each validator and pass/fail/reason |
| Narrative |
claims/result references, model/version |
| User outcome |
feedback, correction, review request |
| Human review |
reviewer, outcome, correction |
| Performance |
stage latency |
| Cost |
tokens/model spend, warehouse scan/compute estimate |
| Failure |
structured error/refusal code |
OpenLineage already provides interoperable concepts for runs, jobs and datasets, making it useful for joining AI traces to upstream data lineage. 13
The operator must be able to answer:
“Why did Radek receive €4.21M as the September result yesterday?”
with an evidence chain—not “the model probably saw the schema and decided that was right.”
Security controls
The model should be considered a potentially confused principal operating in an adversarial input environment.
Relevant attack surfaces include:
-
user question;
-
table descriptions;
-
column descriptions;
-
glossary entries;
-
retrieved documents;
-
analyst examples;
-
data values themselves;
-
uploaded files;
-
tool responses.
Google Cloud explicitly warns that agents can interpret data as instructions and gives examples of malicious instructions embedded in resources including BigQuery; its mitigations include constrained execution environments and resource/network boundaries. 15
NIST’s agent-hijacking work similarly evaluates indirect prompt injection through externally controlled content and warns that security testing must be adaptive and task-specific. 14
Therefore:
Treat metadata as data, not as trusted instructions.
Deterministic security boundaries should include:
-
authenticated user identity propagated to data access;
-
RBAC/ABAC;
-
row-level security;
-
column masking;
-
source allowlists;
-
statement allowlists;
-
read-only credentials;
-
network/egress boundaries;
-
secret isolation;
-
tool capability restrictions;
-
maximum result/export size;
-
sensitive aggregation policy;
-
query auditing;
-
tenant isolation.
Databricks provides a concrete production example of separating compute access from data authorization: the agent may use embedded compute credentials while underlying data access is still evaluated using the end user’s Unity Catalog permissions, including row filters and column masks. 2
Do not rely on:
“You must never reveal salary data.”
as the primary salary-data security control.
Also test inference leakage, not just direct row access. A user who cannot see individual compensation may still infer it through repeated small-group aggregates. Aggregation minimums, suppression, differential privacy or query-budget controls may be required depending on sensitivity.
Failure-mode catalogue and practitioner disagreements
Failure-mode catalogue
Evidence strength below means:
-
Strong: direct benchmark, documented mechanism or multiple authoritative sources.
-
Moderate: well-supported engineering inference from production mechanisms.
-
Interpretive: recommended control derived from system reasoning; requires organization-specific validation.
| Failure |
Symptom |
Likely mechanism |
Detection |
Containment |
Recovery |
Preventive control |
Evidence |
| Correct SQL, wrong question |
Plausible answer disagrees with user’s intent |
Ambiguous term/time/population resolved silently |
Contract review; semantic gold test |
Stop before execution on unresolved material field |
Clarify and rebuild contract |
Mandatory analytical contract |
Strong — clarification mechanisms in Snowflake/Databricks 4 |
| Executable but wrong SQL |
Query succeeds with wrong result |
Wrong predicate/formula/table/dialect assumption |
Gold-result comparison, invariants, review |
Block result on failed validation |
Regenerate from validated plan |
Parser + semantic + result checks |
Strong — enterprise benchmark difficulty and production review workflows 1 |
| Hallucinated metric definition |
Convincing but unofficial KPI |
No governed metric; model improvises formula |
Metric-ID lookup fails |
Refuse calculation |
Request/approve provisional definition |
Metrics must resolve to governed IDs |
Moderate/strong — structured semantics preferred by dbt/Databricks 16 |
| Fanout |
Total increases after joining dimensions |
One-to-many/many-to-many duplication |
Pre/post fact-key and total reconciliation |
Reject join |
Use governed join/preaggregation |
Relationship cardinality + keys |
Strong — explicit documented Looker example 7 |
| Wrong grain |
Counts/averages subtly incorrect |
Entity or metric aggregated at incompatible level |
Uniqueness/grain assertions |
Block incompatible grouping |
Replan aggregation |
Explicit row + metric grain |
Strong/moderate 7 |
| Hidden filter omission |
Dashboard and AI differ |
Certified metric contains exclusions agent omitted |
Compare metric predicates/reconciliation |
Do not publish mismatch |
Recompile canonical metric |
Central metric definition |
Moderate 5 |
| Wrong fiscal/calendar logic |
Period totals displaced |
Model assumes calendar periods |
Contract calendar/version check |
Block ambiguous period |
Rerun with explicit calendar |
Governed time dimension/calendar |
Strong/moderate — production troubleshooting specifically identifies this class 10 |
| Hidden stale data |
Answer looks current because query just ran |
Query timestamp confused with source freshness |
Freshness metadata/SLA |
Qualify/refuse |
Last trusted snapshot or wait for healthy load |
Freshness gate |
Strong 12 |
| Source outage silently becomes stale cache |
Old result presented as current |
Cache fallback has no provenance |
Compare cache/source timestamp |
Label or refuse |
Restore source / explicitly select snapshot |
Cache provenance + policy |
Moderate |
| Dashboard disagreement |
Two authoritative-looking numbers |
Different metric versions, filters, grains or freshness |
Contract-to-contract comparison |
Suppress “single truth” claim |
Explain divergence, resolve owner |
Versioned semantic definitions |
Moderate |
| False root-cause narrative |
“Revenue fell because X” without causal evidence |
LLM converts correlation/decomposition into causation |
Claim-type validator/human review |
Downgrade to observed/inferred/hypothesized |
Rewrite narrative |
Narrative contract + causal routing |
Interpretive, high importance |
| Percentage misreading |
5%→6% described as “1% increase” or “20 percentage points” |
Free-form arithmetic/language |
Deterministic computed deltas |
Reject generated numeric claim |
Regenerate from derived statistics |
Narrative only references computed stats |
Moderate |
| Verified-query staleness |
Previously correct pattern returns obsolete logic |
Metric/schema policy evolved |
Version-compatibility checks |
Remove from retrieval |
Reverify/update query |
Verification timestamp + dependency versions |
Moderate inference from VQR behavior 6 |
| Verified-query overfit |
Familiar prompts work; novel combinations fail |
Repository covers historical patterns, not semantic space |
Stratify evaluation by novelty |
Fall back to semantic workflow |
Add semantics, not merely examples |
Treat VQR as accelerator, not semantic layer |
Moderate inference 6 |
| Prompt injection via metadata |
Agent follows instructions embedded in catalog/data |
Retrieved content treated as higher-priority instruction |
Adversarial tests/tool-policy violation |
Hard tool/egress boundaries |
Quarantine malicious metadata |
Untrusted-context separation |
Strong 15 |
| Permission leakage |
User receives restricted values |
Agent credentials exceed user authorization |
Security audit / negative permission tests |
Block before query/result |
Incident response; revoke capability |
Data-layer user authorization |
Strong 2 |
| Sensitive inference |
Restricted fact inferred via aggregates |
Repeated low-cardinality queries |
Query-pattern/privacy rules |
Suppress risky result |
Tighten aggregation policy |
Minimum groups/privacy budgets |
Moderate |
| Runaway query |
High warehouse spend/latency |
Model generates broad scan/join |
dry-run/explain/bytes estimate |
Cancel/reject |
Rewrite/scoped query |
Cost, scan, timeout limits |
Strong 11 |
| Autonomous compounding error |
Later conclusions rest on first wrong step |
Agent treats unvalidated intermediate output as fact |
Per-step validation/provenance |
Halt chain |
Restart from last validated state |
Typed state + step budget |
Moderate, supported by complexity evidence 1 |
| Evaluation blind spot |
Great overall score, catastrophic failure class |
Easy/common cases dominate metric |
Per-class/per-risk reporting |
Prevent release despite average score |
Expand/red-team set |
Stratified evaluation |
Strong — NIST shows aggregate metrics can hide task-level risk 14 |
| Evaluation gold error |
Model penalized/rewarded incorrectly |
Wrong expected query/result/evaluator truncation |
Gold review, evaluator red-team |
Quarantine test |
Correct and re-run history |
Gold ownership + evaluator tests |
Strong — Spider 2.0 required repeated annotation QC; Databricks documents result-comparison edge cases 1 |
| Review burden exceeds value |
Analytics team becomes approval bottleneck |
Every query treated high risk |
Reviews/query; analyst minutes; abandonment |
Narrow review scope |
Convert recurring review findings into rules |
Risk-based review |
Interpretive |
No community anecdote is used as a load-bearing justification in this catalogue.
Practitioner disagreements
“Modern LLMs are good enough to reason directly over the warehouse schema.”
I would reject this as a default production architecture. Spider 2.0’s large-schema results and Databricks’ recommendation to keep analytical agents tightly scoped both point toward smaller governed analytical surfaces. 1
“Verified queries solve accuracy.”
Partly. They are excellent for known and neighboring patterns, and both Snowflake and Databricks operationalize them. But they are not a substitute for canonical semantics because similarity retrieval cannot guarantee correct behavior outside repository coverage. 6
“Give the LLM all joins and let it choose.”
I would not for enterprise KPIs. Relationship cardinality is computational semantics. Looker’s fanout example demonstrates that a syntactically valid join can silently change a measure by almost 80% in a tiny example. 7
“One general data agent is better UX than many domain agents.”
Potentially better discovery UX, worse control surface. My preferred compromise is one user-facing router over several bounded analytical domains. Databricks’ own guidance recommends purpose-specific agents with focused tables rather than general cross-domain agents. 5
“Self-correction solves bad SQL.”
It helps syntax and execution errors. It does not solve semantic misunderstanding because execution feedback can positively reinforce a query answering the wrong question. Spider 2.0’s interactive environment still exhibits major performance gaps despite execution interaction. 1
“Show users all SQL for trust.”
Useful for analysts, insufficient for business users. SQL says little about whether “ARR,” “customer” or “Q3” was resolved correctly. Show the interpreted analytical contract and provenance first, with SQL available as evidence.
“Always answer, but add a confidence score.”
I disagree. Some states have categorical semantics: unauthorized, undefined metric, invalid join, broken source, irreducibly ambiguous period. A numerical confidence score should never turn those into permissible execution.
“Fail closed whenever anything is imperfect.”
Also too extreme. Warning-level freshness or nonmaterial DQ issues can support a useful qualified answer. The policy should distinguish hard invalidity from uncertainty.
“A single benchmark accuracy score is enough to compare releases.”
No. The same average can hide materially different failures. Both NIST’s task-specific security evaluation findings and Databricks’ benchmark mechanics argue for case-level and class-level analysis. 14
Evidence map and remaining firsthand work
Claim-to-source table
The dossier prioritizes primary technical material: official documentation and first-party benchmark/research artifacts. Vendor documentation is evidence that a production control or architecture exists; it is not independent evidence that the vendor’s complete system achieves a particular real-world accuracy level.
| Important claim |
Source |
Source classification |
Evidence interpretation |
| Enterprise text-to-SQL is much harder than older benchmarks |
Spider 2.0 |
Benchmark; empirical research |
Strong direct benchmark evidence; not an organization’s proprietary workload |
| Enterprise tasks involve huge schemas, metadata and multi-step work |
Spider 2.0 |
Benchmark; empirical research |
Strong |
| Semantic metrics can be compiled rather than regenerated from scratch |
dbt MetricFlow |
Official documentation; production evidence |
Strong evidence of implementable pattern, not comparative accuracy proof |
| Semantic-model validation can enforce structural rules |
dbt Semantic Layer |
Official documentation |
Strong |
| Unique/relationship tests support data-grain validation |
dbt data tests |
Official documentation |
Strong for those deterministic checks |
| Narrow, curated analytical domains are recommended for NL analytics |
Databricks Genie best practices |
Official documentation; production evidence |
Strong product-engineering guidance; “five tables” itself is vendor-specific |
| Structured SQL expressions are preferred over plain text for business semantics |
Databricks Genie |
Official documentation; engineering report/production guidance |
Strong evidence of current practitioner design |
| Clarification can be explicit workflow behavior |
Snowflake + Databricks |
Official documentation; production evidence |
Strong |
| Verified question/SQL pairs can steer similar queries |
Snowflake VQR |
Official documentation; production evidence |
Strong |
| Verified SQL can become benchmark ground truth |
Databricks benchmarks |
Official documentation; production evidence |
Strong |
| LLM analytical responses remain non-deterministic |
Databricks Genie documentation |
Official documentation; production evidence |
Direct vendor acknowledgement for that system |
| Join cardinality affects measure correctness |
Looker relationship docs |
Official documentation |
Strong |
| Fanout can produce plausible, materially wrong aggregates |
Looker symmetric aggregates |
Official documentation; engineering report |
Strong direct worked mechanism |
| Freshness can be a pipeline gate |
dbt source freshness |
Official documentation; production evidence |
Strong |
| Dry runs can validate structure and estimate scan size |
BigQuery |
Official documentation |
Strong |
| SQL runtime can be bounded independently of model behavior |
Snowflake timeout parameter |
Official documentation |
Strong |
| Dataset/job/run lineage can be standardized |
OpenLineage |
Official documentation |
Strong implementation foundation |
| Metadata/data can carry indirect prompt injection |
Google Cloud |
Official documentation; engineering report |
Strong |
| Agent security evaluations should be adaptive and task-specific |
NIST |
Empirical research; engineering report |
Strong |
| Aggregate evaluation scores can conceal high-risk failure classes |
NIST |
Empirical research |
Strong |
| Contract-first review is generally higher leverage than reviewing every SQL statement |
This dossier synthesis |
Interpretation |
Requires firsthand validation in organizational workflow |
| VQRs can become stale or overfit covered question families |
This dossier synthesis, based on similarity-based retrieval/version dynamics |
Interpretation |
Strongly plausible; magnitude requires firsthand testing |
| Observed/inferred/hypothesized narrative separation reduces overclaiming |
This dossier design recommendation |
Interpretation |
Needs organization-specific evaluation |
| Risk-tiered human review is preferable to universal review |
This dossier design recommendation |
Interpretation |
Needs operating-cost measurement |
Relevant primary evidence includes the current Snowflake VQR and categorization documentation, Databricks’ September 2026 Genie guidance and benchmark documentation, dbt freshness and semantic-model documentation, Google/Looker join guidance, BigQuery execution controls, OpenLineage, Google Cloud security guidance, NIST agent-hijacking evaluation work and Spider 2.0. 6
Practitioner-experience and community-discussion sources were not used as primary support for material architecture decisions. That is intentional: such sources can be valuable for discovering edge cases, but claims in this dossier are anchored where possible in executable product mechanisms, official engineering documentation and benchmark evidence.
Recommended minimum production standard
A system should not be described internally as a reliable analytical agent unless, for the question classes it claims to support, it can demonstrate all of the following:
| Capability |
Minimum bar |
| Analytical meaning |
Canonical terms/metrics/time/grain represented before execution |
| Ambiguity |
Material unresolved ambiguity triggers clarification |
| Semantics |
Governed sources have explicit precedence |
| Schema |
Retrieval is domain-scoped and testable |
| Joins |
Relationship graph/cardinality constrain generated SQL |
| Grain |
Source and result grain are explicit and validated |
| Metrics |
No silent metric invention |
| Execution |
Database-enforced permissions, time and cost limits |
| Query validation |
AST/static/policy checks before execution |
| Result validation |
At least one independent check for important results |
| DQ |
Relevant upstream health affects answer status |
| Freshness |
“Data as of” is available and SLA-aware |
| Provenance |
Question→result→narrative can be reconstructed |
| Narrative |
Generated statements are traceable to validated outputs |
| Agentic analysis |
Intermediate state and stopping criteria are explicit |
| Review |
Risk-tiered human escalation exists |
| Evaluation |
Includes ambiguity, fanout, grain, security and failure cases—not merely easy SQL |
| Regression |
Model/prompt/schema/semantic changes trigger tests |
| Observability |
Operators can reconstruct failed and successful answers |
| Security |
Enforcement occurs outside model instructions |
That bar is intentionally much higher than “execution accuracy.”
Things that still require firsthand testing
Public benchmarks and vendor documentation cannot answer the most important operational question: how well this design works against your organization’s semantics, schemas and users.
The following therefore require direct organizational tests.
Contract extraction. Measure how often real questions omit a materially required field, how often the system detects it, and how annoying its clarification behavior becomes. A theoretically correct system that interrogates the user five times per question will not be adopted.
Metric-resolution precision. Test real internal synonyms, overloaded terms, old KPI names, abbreviations and department-specific definitions. “Revenue” in Finance, Growth and Sales may not be the same object.
Verified-query coverage. Measure the share of actual traffic that is exact-match, near-match and genuinely novel—and how quickly verified queries become stale after semantic-model changes.
Schema retrieval. Test table and column retrieval over the actual warehouse/catalog, especially domains with hundreds of similarly named objects, cloned tables, legacy datasets and incomplete descriptions. Spider 2.0 establishes that large-schema grounding is difficult, but it does not predict your retrieval accuracy. 1
Join and grain validators. Measure false negatives on known fanout incidents and false positives on legitimate bridge/many-to-many models. A “block all M:N joins” policy may be safe but unusable.
Semantic-layer coverage. Determine what fraction of user questions can be answered entirely from canonical metrics and dimensions versus requiring bespoke analysis.
Result reconciliation. Run AI outputs against existing certified dashboards and investigate every disagreement. Do not assume the dashboard is automatically correct; compare contracts, filters, versions and freshness.
Data-quality propagation. Inject stale sources, missing partitions, broken uniqueness, delayed dimensions and partial loads. Confirm that the right answers become warnings/refusals and unrelated answers remain available.
Model-change regressions. Run the same suite repeatedly across candidate models because both classification and generated SQL can change despite unchanged semantic context. Databricks explicitly documents nondeterministic behavior in its own agent workflow. 10
Repeated trials. Do not execute each benchmark once. Measure success distributions on probabilistic stages.
Narrative fidelity. Have analysts label unsupported causes, false significance claims, denominator mistakes, percentage/percentage-point mistakes and ungrounded recommendations.
Forecast routing. Test whether forecasting questions are reliably separated from descriptive questions and whether users understand that forecast output is model-dependent rather than a retrieved fact.
Causal routing. Test subtle causal formulations—not just sentences containing “cause.” Examples include “What drove churn?”, “What impact did the campaign have?”, and “Which feature increased conversion?”
Prompt-injection resistance. Put adversarial instructions in descriptions, glossary documents, retrieved text, data values and user files. Test actual tool/data exfiltration rather than merely whether the model repeats malicious text. Google and NIST evidence makes this a mandatory production exercise. 15
Authorization. Test positive and negative cases across row-level security, column masking, role changes, shared conversations and caches. Verify the enforcement identity at the warehouse, not just in application code.
Sensitive aggregation attacks. Test whether repeated filters or small groups allow inference of hidden individual values.
Cost controls. Generate pathological joins, cross-products, huge date ranges and high-cardinality groupings and confirm that dry-run/cost gates prevent expensive execution. 11
Source outage behavior. Simulate warehouse, semantic-service, catalog and DQ-service outages independently. The system needs explicit degraded modes, not a single generic retry loop.
Trace reconstruction. Select a random historical answer and require an operator unfamiliar with it to reconstruct the question interpretation, metric definition, source, join, SQL, result, freshness and narrative from logs alone.
Human-review economics. Measure analyst minutes per 100 questions, reasons for escalation, corrections per reviewer and user wait/abandonment. This determines whether a theoretically safe workflow is economically viable.
Provenance UX. Test what users actually inspect. Many business users will not read SQL; determine whether metric/filter/time/freshness summaries improve their ability to detect misunderstandings.
Real incident replay. The strongest evaluation set will eventually be your own historical failures: dashboard disagreements, fanout bugs, stale loads, bad metric migrations, permission incidents and misunderstood business questions. Every material production incident should become a permanent regression case.
The practical endpoint is not an agent that “usually writes good SQL.” It is a system in which a probabilistic model operates inside a deterministic analytical control plane: business meaning is resolved before computation; metrics and relationships come from governed artifacts; unsafe queries cannot execute merely because the model produced them; grain, freshness and data health travel with the result; generated prose cannot outrank the evidence; and every consequential answer can be reconstructed after the fact.
That is the production boundary between a useful analytics copilot and a fluent source of plausible numbers.