The Semantic View

The semantic view is what makes Cortex Analyst accurate. It is the evidence the agent reasons over. Get it right and answers hold up under cross-examination. Get it wrong and no amount of agent tuning saves you.

Why it leads the exhibits: most agent accuracy is won or lost here, before the agent spec is ever written. The three sections below are the highest-leverage moves.

Start with Practices and work through the tabs in order. When you are done here, head to Exhibit B: The Agent.

Exhibit A · Section 1 of 3

High-Leverage Practices

The semantic view is where Cortex Analyst gets its accuracy. These six moves deliver the most accuracy per unit of effort.

Business names + curated synonyms

Name objects the way users speak ("Revenue", not AMT_TOT). Add a few real alternate phrasings, but avoid auto-generated synonym spam.

Comments that teach

At view, table, and column level, state business meaning, grain, and any exclusions or caveats.

Model KPIs as metrics

Put canonical calculations in METRICS (net_sales, avg_order_value). Use FACTS for reusable row-level expressions, DIMENSIONS for grouping/filtering.

Sample values + enums

Add SAMPLE_VALUES so the model maps phrasing to real filter values. Add IS_ENUM only when the listed values are the complete set (and it must come after SAMPLE_VALUES).

Verified queries

AI_VERIFIED_QUERIES for common and failure-prone questions, phrased how users actually ask, one of the strongest accuracy levers.

Explicit keys & relationships

Declare PRIMARY KEY / UNIQUE and named RELATIONSHIPS. Prefer a clean star shape; disambiguate multi-path metrics with USING (relationship_name).

Keep scope tight. Start with ~3–5 tables and roughly 50–100 columns total. Smaller, focused views outperform "do-it-all" models, because Cortex Analyst has a limited context window. Split by domain when needed.

Exhibit A · Section 2 of 3

The AI_* Clauses: Additive and Independent

Two optional, completely independent modules. Use neither, one, or both. Start with what you know is wrong today; add rules as you find gaps during testing. Over-prompting degrades accuracy and raises token cost.

Clause	Fires	Good candidates
`AI_SQL_GENERATION` how the agent writes SQL	During SQL generation	Default time filters ("no date → last 30 days"); fiscal calendar offsets; rounding/formatting; domain classification ("stock CRITICAL <10, LOW 10–24, OK 25+"); enum casing quirks
`AI_QUESTION_CATEGORIZATION` what to do with a question	Before SQL is attempted	Reject out-of-scope topics ("employee data → contact HR"); table routing when unrelated tables share a view; ask for clarification on ambiguous questions; encoding guardrails (doubled single quotes for apostrophes)

Keep SQL-generation rules here, not in the agent. Rounding, metric synonyms ("sales" = net_sales), and default filters belong in AI_SQL_GENERATION, not in agent instructions. One source of truth.

Exhibit A · Section 3 of 3

Clause Order Is Enforced

Author the DDL in exactly this sequence. COMMENT must come before the AI_* clauses, and AI_VERIFIED_QUERIES comes last.

TABLES→ RELATIONSHIPS→ FACTS→ DIMENSIONS→ METRICS→ COMMENT→ AI_SQL_GENERATION→ AI_QUESTION_CATEGORIZATION→ AI_VERIFIED_QUERIES

Gotcha: placing COMMENT after the AI_* clauses raises unexpected 'COMMENT'. Order is not a suggestion.

Annotated skeleton

{{ config(materialized='semantic_view') }}

CREATE OR REPLACE SEMANTIC VIEW sv_sales
  TABLES (
    orders PRIMARY KEY (order_id) -- one row per order
  )
  RELATIONSHIPS ( -- FK joins between tables (clean star)  )
  FACTS      ( orders.line_total AS quantity * unit_price )
  DIMENSIONS ( orders.region WITH SAMPLE_VALUES ('WEST','EAST') )
  METRICS    ( orders.net_sales AS SUM(line_total) )
  COMMENT = 'Order-grain sales. Excludes cancelled orders.'
  WITH AI_SQL_GENERATION   -- how to write SQL (defaults, rounding)
  WITH AI_QUESTION_CATEGORIZATION -- routing / reject / clarify
  WITH AI_VERIFIED_QUERIES  -- confirmed Q&A pairs (last) ;

Materialize it with dbt build --select sv_<name>, then confirm a sample SELECT ... FROM SEMANTIC_VIEW(sv_<name> ...) returns rows. Built into {DBT_DATABASE}.{DBT_SCHEMA} automatically, since it inherits the dbt target.

Visual

Drop a screenshot of the Semantic View editor in Snowsight, or a before/after of a question answered correctly once verified queries were added.