Domains
Source: docs/guide/07-domains.md at origin/main (3688d236), synced 2026-11-05. Do not edit this page here; change the source and run yarn sync:semantic.
A domain is one use case, such as commerce or logistics. It is what a query names in FROM. It
chooses which datasets, fields and links its users can see, owns the metrics they ask for, and sets
the time zone and defaults their questions are read in.
name: commerce
display_name: Commerce analytics
description: Orders, traffic, and conversion
timezone: America/New_York
defaults:
time_window: last_28d
row_limit: 5000
select:
orders: "*"
customers:
fields: [segment]
sessions:
fields: [started_at]
A domain's name is unique in the tenant, so FROM commerce finds it with nothing else. Its
datasets may live on different connections, but one statement reads one connection
(Semantic SQL).
What a domain selects
select is keyed by dataset name.
"*"exposes every field of the dataset, now and later, and every link from it whose target the domain also selects.- An explicit entry lists
fields,relationships, or both. In the example,customersexposes onlysegment, so a query cannot readcustomers.email.
A link to a dataset the domain does not select is not exposed, so a query through it is
FIELD_NOT_REACHABLE until the domain selects the target.
The selection must hold everything its metrics need: each metric's anchor, and every dataset its
operand or filters reach. Otherwise the write is refused (SELECTION_NOT_CLOSED). A metric's own
definition may read a field the domain does not expose. A query cannot.
A hidden field looks like a missing one. A field the domain does not expose is not in describe
or field search, and a query naming it is UNKNOWN_FIELD. The dataset may still have it. In the
example, customers.email exists but commerce does not expose it. Say "this domain does not
expose it", not "it does not exist". Exposing it is a change to the domain's select.
Every metric the domain owns can be asked for by name. Metrics are not listed in select.
Deleting a domain deletes its metrics.
Time zone
timezone is the zone the domain's questions are read and bucketed in, unless the request names
its own. It decides whose midnight starts a day, whose Monday starts a week, and what a bare
'2026-01-01' means (Time). Without one it is UTC.
It must name a place, as the IANA time zone database does: UTC, Asia/Kolkata,
America/New_York. An abbreviation (IST), an offset (+05:30) or a legacy name (EST, which
never observes daylight saving) is refused, with the fix.
Only a UTC domain's metrics can be cached today (Caching).
Defaults
time_windowis the window a query gets when it writes none:last_<n><unit>, the unitm,h,dorw. It means the lastnwhole periods of the domain's calendar, today included so far. At 14:37,last_7druns from midnight six days ago to now. Every answer says which window it used and that it was the default.row_limitcaps how many rows an answer may have, under the platform cap of 50,000 (Semantic SQL).
Describe
Describe (query_describe_model over MCP) prints a domain's surface: each selected dataset with
its exposed fields and links, and each metric's card. A card lists reachable_dimensions, every
field the metric can be broken down by, spelled exactly as a query writes it. That includes the
paths, for a dataset reached two ways or through a self link:
shipments.shipped_at
shipments.first_carrier.carrier_name
shipments.second_carrier.carrier_name
shipments.first_carrier.carrier_category.category_name
…
A metric whose stored definition no longer works, usually because something it read was deleted,
is listed under broken with the reason. Every other metric still answers.