Skip to main content

Fields

Synced from semantic-layer

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:

datatypeHoldsExample
DateTimeTza moment, the same instant everywhere2026-01-01T09:00:00+05:30
DateTimea clock reading with no time zone2026-01-01 09:00:00
Datea calendar date2026-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.

  • null counts the rows whose output is null.
  • failed counts 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, description and ai_context describe the field to people and agents.
  • format and unit say what the value is (Metrics). They never rescale it.
  • values lists known example values, which help people and agents write filters.
  • sensitive: true keeps values out of describe output and keeps the field out of warehouse sampling.
  • A field's name never changes.

Referring to a field​

A reference takes one of three shapes:

ShapeSpellingMeans
bareamounta field of the dataset you are writing from (a metric's anchor)
shorthandcustomers.segmentthe field of customers, reached by the one shortest route from the anchor
pathshipments.second_carrier.carrier_namethe 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.