Skip to main content

Answers

Synced from semantic-layer

Source: docs/guide/12-answers.md at origin/main (3688d236), synced 2026-11-05. Do not edit this page here; change the source and run yarn sync:semantic.

An executed statement returns a table, columns and rows, plus what you need to trust it: where it came from, the window and time zone it used, what each column is, and the exact SQL that ran. A plan returns the same account without rows.

The table​

columns are the outer query's output names, in order, and each row is an array in that order. A field or measure keeps its name (region, revenue), an alias wins, and an unnamed expression is column_<n>.

  • A moment is written in the reporting time zone with its offset: 2026-01-01T09:00:00+05:30.
  • A Date is YYYY-MM-DD. A DateTime reading stays as it was.
  • An empty metric cell is a group the metric had no rows for. A count reads 0 there, and a sum reads null.
  • A time bucket with no rows for any metric is not a row at all: an hourly series can have 17 rows for 24 hours (Time).

semantics​

KeySays
domainthe domain that answered, {id, name, display_name}
as_ofthe model revision the answer was computed at
timezonethe reporting zone, {zone, source}, where source is request, domain or default (UTC)
served_fromcache or warehouse, for the whole statement
freshnesshow current the answer is. For a cube: its refresh state, and how far it reaches when the window runs past its last refresh.
cacheon a warehouse answer, why the cache could not serve it, reason by reason
windoweach window as used, per select and time axis: {axis, grain, from, to, snapped, default}
warningsanything you must know to read the answer correctly (below)
draftson a preview, which metrics were unsaved drafts (below)
data_versionsthe lake snapshot read, when the statement read the tenant's lake

column_semantics says what each column that passes a field or a measure through is: its source field or metric, title, type, format and unit, and for a metric its rollup and bounds. A computed column, such as a growth rate, has no entry.

bases[] has one entry per semantic select, with the query it lowered to, how each metric was routed, and that select's own warnings.

Warnings​

WarningMeans
RENAMEDyou spelled a domain or metric by a former name. The answer is the same resource, and the column keeps the name you wrote.
WINDOW_NOT_APPLIEDthe default window bounded the other metrics, but this one has no time axis, so it is all-time
MATCHED_BY_NAMEa derived metric's component was grouped by a same-named field of its own anchor

No warning ever covers a choice between two routes. A reference two routes reach is refused, never answered along one of them.

execution: the SQL that ran​

Every answer, and every plan, carries execution, so the number can be checked rather than taken on trust:

  • question: your SQL and parameters as sent
  • warehouse.sql: the exact warehouse statement, byte for byte, with its dialect and the connection it ran on. On a cache answer it is what would compute the same thing live (equivalent_only: true).
  • cache.sql and cache.cubes: when a cube answered, the statement over the cubes and each cube read
  • warehouse.usage: what the statement cost, in the warehouse's own units (bytes billed, milliseconds)
  • context.metrics: each metric's definition as computed, such as sum of amount over orders, with its filters
  • reference_id: the request's trace id. It is also on the warehouse statement (Snowflake's QUERY_TAG, BigQuery's sl_trace label), so you can find the statement in the warehouse's own history.

Plans​

A plan (mode: plan, query_compile) checks, routes and prices a statement and runs nothing. It returns valid: true with the outer columns, served_from, an estimate (a cost class, a row bound, and the warehouse's dry-run price when it gives one), each metric's routing, and the execution an execute would send. Or it returns valid: false with errors, each a code, a message that says what to write instead, and details such as did_you_mean.

A plan does not ask for consent. Instead, its routing says consent_required: true where executing would ask.

On a metered warehouse a statement that the cache cannot serve stops and answers 409, with the plan and its price, under CACHE_MISS_CONSENT_REQUIRED or, for a stale cube under on_stale: ask, STALE_CACHE_CONSENT_REQUIRED. Send the same statement again with consent: {warehouse: true}, or {stale: true} to accept the stale cube (Caching).

Previewing a metric before saving it​

draft_metrics sends 1 to 10 unsaved metric documents with a query. For that one request they are part of the model, and nothing is stored:

{
"sql": "SELECT orders.region, MEASURE(big_order_revenue) FROM commerce WHERE time >= '2026-09-01' AND time < '2026-10-01' GROUP BY ALL",
"draft_metrics": [
{"name": "big_order_revenue", "anchor": "orders", "agg": "sum", "operand": "amount",
"filters": [{"field": "amount", "op": "gte", "value": 100}]}
]
}
  • A draft is checked like a saved metric and refused with the same errors, naming its path (draft_metrics[0].operand).
  • It must be structured. An operand names a field rather than an expression, and a derived expr uses only metric names, numbers, arithmetic and a few functions (ABS, ROUND, COALESCE, NULLIF, CASE…). It carries no cache and no serving.
  • It may only read fields the domain exposes.
  • A draft with a saved metric's name replaces it for the request, which previews an edit. Saved metrics composed over it then answer with the draft.
  • The answer lists the drafts, and every saved metric they affected, in semantics.drafts, so a number from an unsaved definition is never mistaken for a governed one.