Answers
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
DateisYYYY-MM-DD. ADateTimereading 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
| Key | Says |
|---|---|
domain | the domain that answered, {id, name, display_name} |
as_of | the model revision the answer was computed at |
timezone | the reporting zone, {zone, source}, where source is request, domain or default (UTC) |
served_from | cache or warehouse, for the whole statement |
freshness | how current the answer is. For a cube: its refresh state, and how far it reaches when the window runs past its last refresh. |
cache | on a warehouse answer, why the cache could not serve it, reason by reason |
window | each window as used, per select and time axis: {axis, grain, from, to, snapped, default} |
warnings | anything you must know to read the answer correctly (below) |
drafts | on a preview, which metrics were unsaved drafts (below) |
data_versions | the 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
| Warning | Means |
|---|---|
RENAMED | you 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_APPLIED | the default window bounded the other metrics, but this one has no time axis, so it is all-time |
MATCHED_BY_NAME | a 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 sentwarehouse.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.sqlandcache.cubes: when a cube answered, the statement over the cubes and each cube readwarehouse.usage: what the statement cost, in the warehouse's own units (bytes billed, milliseconds)context.metrics: each metric's definition as computed, such assum of amount over orders, with its filtersreference_id: the request's trace id. It is also on the warehouse statement (Snowflake'sQUERY_TAG, BigQuery'ssl_tracelabel), 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.
Consent
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
operandnames a field rather than an expression, and a derivedexpruses only metric names, numbers, arithmetic and a few functions (ABS,ROUND,COALESCE,NULLIF,CASE…). It carries nocacheand noserving. - 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.