Fields
Source: docs/guide/02-fields.md at origin/main (3688d236), synced 2026-11-05. Do not edit this page here; change the source and run yarn sync:semantic.
A field is a named scalar expression over its dataset's source. Fields are what a query groups and filters by, and what a metric aggregates.
name: order_size
expression: "CASE WHEN amount >= 100 THEN 'large' ELSE 'small' END"
datatype: String
display_name: Order size
Expression
expression is SQL in the dialect of the dataset's warehouse, evaluated once per row. It may
use any function that warehouse has, such as TRY_STRPTIME and :: casts on DuckDB or IFF on
Snowflake, because a field only ever runs there. model_inspect and GET /datasets/{id} say which
dialect that is.
A bare column name is quoted for you. An expression that is exactly one column name, such as
stateId, is that column's exact name, and the layer quotes it so the warehouse cannot fold its
case. Any other expression is used as written, so its quoting is yours: on Postgres, write
lower("stateId").
Datatype
datatype is one of String, Integer, Decimal, Float, Boolean, Date, Time,
DateTime, DateTimeTz or Opaque. It decides which filter operators and values a field
accepts (Filters), and it labels the column in answers. Each write checks the
declared type against what the warehouse actually returns, without reading any rows: a mismatch on
a time axis refuses the write, and anywhere else it warns.
The three temporal types differ in what they hold:
datatype | Holds | Example |
|---|---|---|
DateTimeTz | a moment, the same instant everywhere | 2026-01-01T09:00:00+05:30 |
DateTime | a clock reading with no time zone | 2026-01-01 09:00:00 |
Date | a calendar date | 2026-01-01 |
A field that is a time axis must be DateTimeTz or Date (Datasets).
If your column is a naive timestamp in UTC, convert it in the expression (for example
timezone('UTC', col) on DuckDB) and declare DateTimeTz.
resolution narrows a DateTimeTz axis that is coarser than its type. A column loaded once a
night changes once a day, so resolution: day stops queries bucketing it by hour, and a window
bound in the middle of a day widens to whole days. It is allowed only on DateTimeTz.
Trying a field before saving it
A field write with mode=validate (over MCP, model_change without mode="apply") saves nothing.
It shows what the expression gives on up to 50 rows from the last 7 days, or from your
preview_from to preview_to: each input column beside the output, plus two counts.
nullcounts the rows whose output is null.failedcounts the rows whose inputs are all present but whose output is null. That usually means text in a format the expression does not parse.
On a metered warehouse (Snowflake, BigQuery) the preview is priced first and reads nothing until
you consent. A price over the byte cap is refused, and consent does not lift that. An expression
the warehouse refuses is VALIDATION_FAILED with the warehouse's own message, and nothing is
stored.
Metadata
display_name,descriptionandai_contextdescribe the field to people and agents.formatandunitsay what the value is (Metrics). They never rescale it.valueslists known example values, which help people and agents write filters.sensitive: truekeepsvaluesout of describe output and keeps the field out of warehouse sampling.- A field's
namenever changes.
Referring to a field
A reference takes one of three shapes:
| Shape | Spelling | Means |
|---|---|---|
| bare | amount | a field of the dataset you are writing from (a metric's anchor) |
| shorthand | customers.segment | the field of customers, reached by the one shortest route from the anchor |
| path | shipments.second_carrier.carrier_name | the field reached by exactly the links you name |
A query has no dataset of its own, so in a query every field is qualified: orders.region, never
region. A metric's definition may use a bare name for a field of its anchor.
A path is needed when the shorthand cannot say which route you mean: a dataset linked to the same dataset twice, or a dataset linked to itself. Relationships explains routes, and Fields and paths in SQL shows them in queries.