Authoring Reference

Before any syntax, set the frame. Measures and metrics are two distinct surfaces in the catalog with two distinct purposes.

Implications:

• Not every measure needs a corresponding metric. Measures are queryable as primitives.
• The catalog lists measures and metrics as distinct surfaces.
• Measures do not auto-publish to metrics. Author the metric explicitly when an access pattern deserves a stable contract.

The v1 contract is terse because the loader fills in identifiers and traversal deterministically. Author the business meaning; the loader handles:

• Key-derived IDs. Every object's id and name come from package.namespace + key. Override with as: only to preserve a public reference.
• Auto-created key dimensions. From graph.entities.<x>.key: for every model that exposes the entity.
• Inferred relationships. Any pair of entities co-declared in model.entities: produces a default RelationshipConfig. Author overrides in graph.relationships: only when needed.
• Primary entity auto-detect. The entity whose canonical key matches model.grain:. No marker needed.
• Backing time dimensions. Auto-created from each times: entry's column:.
• Default aggregations. Accumulation class drives the allowed set; subtract with disallowed_aggregations:.

The full table is in auto-derivations summary.

A package has seven concrete components plus the expression AST. Each one auto-derives most identifiers when package.namespace is set.

Declares the schema version, identity, warehouse target, seed inputs (DuckDB) or connection (every other warehouse), declared environments, the schema_strict flag, and defaults inherited by dimensions, temporal roles, and measures.

Top-level fields

Example

For remote warehouses (Snowflake, Postgres, BigQuery, Databricks, and the rest), swap seed for connection — see connection-mode decision.

schema_version: 1

package:
  id: shop
  namespace: shop
  warehouse: duckdb
  default_db: data/shop.duckdb
  seed: { kind: sql_script, source: data/seed.sql }
  schema_strict: true

defaults:
  dimension: { groupable: true, filterable: true }
  time:
    timezone: UTC
    supported_grains: [day, week, month, quarter, year]

The canonical entity registry. Each entry declares one business object the package exposes (customer, order, product, …), its key column, and any non-default relationships to other entities.

graph.entities:

graph.relationships:

Most relationships are inferred from FK references in model.entities: blocks. Author an explicit graph.relationships: entry only when you need a non-default rule: per-direction rollup safety, SCD2 temporal_validity:, custom cardinality:, or allowed_directions: restriction.

Relationships are bidirectional. The entities: field is an unordered pair; cardinality and rollup safety are expressed relative to that pair.

Example

graph:
  entities:
    customer:
      label: Customer
      key: customer_id
      synonyms: [buyer, account]
      disallowed_names: [cust_id, custid, customerid]
    order:
      label: Order
      key: order_id
      disallowed_names: [ord_id, orderid]
    order_item:
      label: Order item
      key: order_item_id
    product:
      label: Product
      key: product_id
    customer_history:
      label: Customer history
      key: [customer_id, valid_from]
      allowed_as_root: false

  relationships:
    customer_history_x_customer:
      entities: [customer_history, customer]
      cardinality: many_to_one
      safety: requires_rewrite
      temporal_validity:
        valid_from: effective_from
        valid_to: effective_to
      rollup_safe:
        forward: [sum, count]
        reverse: []

A model declares one warehouse table or mart, the entities it exposes, and the dimensions, temporal roles, and measures attached to its grain. The loader merges every YAML file under models/** into the package config.

Top-level model fields

model.entities:

Required on every model. Declares which entities the model exposes. Each entry binds by default to the entity's canonical column from graph.entities.<x>.key:; override per entity with expr: when the model's column name differs.

The primary entity is auto-detected: whichever entity's canonical key column matches model.grain:. For compound-grain models, all entities whose keys are in the grain are co-primary.

Examples

# Default binding — columns auto-resolved from graph
model:
  id: orders
  relation: shop_order
  # grain derived from primary entity's key (graph's order.key)
  entities:
    order: {}                      # primary; column = graph's order_id
    customer: {}                   # FK reference; column = graph's customer_id
    product: {}

# Column rename via expr:
model:
  id: order_renamed_columns
  relation: shop_order
  entities:
    order: { expr: ord_id }        # primary, column renamed
    customer: { expr: cust_id }    # FK, column renamed

# Junction table — not used as a join path. Compound grain comes from
# the bridge's two primary entity keys, not an authored `grain:` field.
model:
  id: customer_segment_membership
  relation: shop_customer_segment
  entities:
    bridge: false
    customer: {}
    segment: {}

times: (temporal roles)

The times: block key IS the temporal role. The backing date/timestamp dimension is auto-created from column:. default: true picks the implicit time axis when a query omits time.temporal_role.

dimensions:

Behavioral attributes attached to the model's grain. The dimension's kind drives type coercion in SQL lowering and the filter-operator menu surfaced through build-options.

Key dimensions auto-create from graph.entities.<x>.key. Backing date/timestamp dimensions auto-create from times:. You only author behavioral dimensions here.

measures:

Each measure declares the explicit triple (kind, accumulation, value_type) plus the aggregation expression. expr: and default_agg: live directly on the measure — no expression: wrapper.

Measures do not auto-publish to metrics. To expose a measure as a governed metric, write the metric explicitly under metrics.

Core fields

model.variants: physical rollups

Use model.variants: when one semantic model has multiple physical tables at different time grains: transaction, daily, weekly, monthly, or another exact rollup. The model keeps one definition for entities, dimensions, times, and measures. Each variant declares only the physical differences.

The loader turns eligible non-transaction variants into aggregate relations. During compile, the planner can route compatible measure leaves to the rollup relation while preserving the same public measure and dimension IDs.

model:
  id: orders
  relation: order_fact
  default_variant: tx
  grain: [order_id]
  entities:
    order: {}
    customer: {}
    store: {}
  times:
    ordered_at:
      column: ordered_at
      kind: timestamp
      class: event_time
      default: true
  dimensions:
    store_id: { kind: categorical }
    customer_id: { kind: categorical }
  measures:
    revenue_usd:
      kind: aggregate
      expr: order_total_cents / 100.0
      default_agg: sum
      rollup: additive
      accumulation: { kind: flow }
      value_type: currency

  variants:
    tx:
      relation: order_fact
      grain: { time: transaction, entities: [order] }
      covers: inherit_all

    monthly:
      relation: order_monthly
      grain: { time: month, entities: [store] }
      time: { role: ordered_at, column: month_start }
      excludes:
        dimensions: [customer_id]
      columns:
        store_id: store_id
        revenue_usd: revenue_usd
      eligible_time_grains: [month, quarter, year]
      selection: { priority: 50 }
      equivalence: { kind: exact }
      source: default

Full model example

model:
  id: orders
  label: Orders
  relation: shop_order
  # grain derived from primary entity's key — do NOT author alongside entities:
  entities:
    order: {}                      # primary
    customer: {}                   # FK reference
    product: {}                    # FK reference
  times:
    ordered_at:
      column: ordered_at
      kind: timestamp
      class: event_time
      default: true
  dimensions:
    status: { kind: categorical }
  measures:
    revenue_usd:
      label: Revenue (USD)
      kind: aggregate
      expr: order_total_cents / 100.0
      default_agg: sum
      accumulation: { kind: flow }
      value_type: currency
      disallowed_aggregations: [median]
    order_count:
      kind: entity_count
      entity_key: order
      accumulation: { kind: event }
      value_type: count

Metrics codify governed access patterns. Each metric carries a kind: that determines the required fields. Common kinds use direct named fields; kind: derived and kind: conversion use the full expression AST.

References to other measures/metrics use package-relative keys (revenue_usd), not fully qualified IDs (metric.shop.revenue_usd). The loader resolves keys.

Top-level fields (any kind)

Required fields per kind

Aggregate, ratio, and time-series examples

These kinds use direct named fields (no expression AST). Anchors: aggregate, ratio, cumulative, rolling, prior_period, period_to_date.

metrics:
  # kind: aggregate — publish a measure
  revenue_usd:
    label: Revenue (USD)
    kind: aggregate
    measure: revenue_usd
    value_type: currency

  # kind: ratio — direct numerator/denominator
  aov_usd:
    label: Average order value (USD)
    kind: ratio
    numerator: revenue_usd
    denominator: order_count
    null_behavior: null_if_zero
    value_type: currency
    time: ordered_at

  # time-series kinds: same shape, different window/period field
  cumulative_revenue_usd:
    kind: cumulative
    measure: revenue_usd
    value_type: currency

  revenue_28d:
    kind: rolling
    measure: revenue_usd
    window: { unit: day, value: 28 }
    value_type: currency

  revenue_prior_month:
    kind: prior_period
    measure: revenue_usd
    period: month
    value_type: currency

  revenue_mtd:
    kind: period_to_date
    measure: revenue_usd
    period: month
    value_type: currency

derived metric (AST escape hatch)

Use kind: derived for arbitrary formulas over multiple metrics. The full expression AST is authored under expression:. References to other metrics use bare keys; the loader resolves them to qualified IDs.

metrics:
  margin_pct:
    label: Gross Margin (%)
    description: (revenue − cogs) / revenue
    kind: derived
    value_type: percent
    expression:
      kind: arithmetic
      op: divide
      left:
        kind: arithmetic
        op: subtract
        left:  { kind: metric, metric: revenue_usd }
        right: { kind: metric, metric: cogs_usd }
      right: { kind: metric, metric: revenue_usd }

conversion metric

Counts entities where a base event is followed by a converted event within a bounded window. Authored as the AST.

metrics:
  signup_to_first_order_7d:
    label: Signup → first order (7d)
    kind: conversion
    value_type: count
    expression:
      kind: conversion
      base:      { metric: signup_count }
      converted: { metric: order_count }
      entity: customer
      window: { unit: day, value: 7 }
      matching_mode: first_converted_after_base
      constant_properties: [region]

Reusable membership filters anchored on an entity plus a basis metric. Previewed by POST /api/v1/segment-preview, validated by /segment-validate, and explained by /segment-explain.

Example

segments:
  high_value_customers:
    entity: customer
    basis_metric: revenue_usd
    preview_dimensions: [region]
    membership:
      metric_filters:
       - expression:
            metric: lifetime_revenue_usd
          op: ">="
          value: 1000
       - expression:
            kind: metric_predicate
            input: { metric: order_count }
            entity: customer
            op: ">="
            value: 3
            scope_mode: entity_only
            window: { unit: day, value: 90 }
          op: "is_true"

Optional. Policies live in a single top-level file under semantic_policies:. Four kinds are recognized by the runtime: package_release, object_visibility, object_access, protected_object.

Every expression:, expr:, and metric-filter body is a small AST. The kind: field selects the node shape; the runtime rejects unknown kinds with INVALID_EXPRESSION_AST.

Authors may write {measure: …} as shorthand for {kind: measure, measure: …}, and {metric: …} as shorthand for {kind: metric, metric: …}; both expand identically.

metric_predicate alignment matrix

metric_predicate is the most field-heavy AST node; this matrix shows which combinations of scope_mode and time_alignment are legal. Other combinations raise INVALID_METRIC_PREDICATE.

The planner enforces context-specific subsets. Putting a metric AST in where: is the most common authoring trap; where: only accepts dimension-level predicates.

Every rule below fires only when the field is missing or empty — explicit values are preserved unchanged. package.namespace (default package.id) is the master switch.

When package.schema_strict: true is set, the loader rejects every legacy authoring form. This is the recommended setting for new packages.

Removed boilerplate (use auto-derivation instead)

• id: on semantic objects — auto-derived from namespace + key; use as: only to preserve a public reference.
• name: on objects — auto-derived from key.
• kind: id dimensions — key dimensions auto-create from graph.entities.<x>.key.
• Duplicate date/timestamp dimension when times: covers the same column — the times: entry creates the backing dimension.
• Authored model.grain: separate from primary — derived from primary entity key.
• Top-level temporal_role.<id>: separate registration — the times: block key IS the role.
• Model-level entity: (singular) + keys.foreign: + joins: blocks — use model.entities:; overrides in graph.relationships:.
• Per-model parent_entity: block — rollup safety lives on graph.relationships.<name>.rollup_safe.
• entity.key_roles (authored) — auto-derived from key role pairs.

Renames

• agg_function: → default_agg: on measures.
• accumulation: stock + sibling snapshot_policy: → nested accumulation: { kind: stock, snapshot: end_of_period }.
• expression: wrapper around expr: / default_agg: on kind: aggregate measures → un-nest. Write expr: and default_agg: directly.
• Buried expression: AST on metric kinds with direct named fields (aggregate, ratio, cumulative, rolling, prior_period, period_to_date, semi_additive) → use direct fields. AST authoring is reserved for kind: derived and kind: conversion.

Required additions

• accumulation always object form; kind must be in {flow, stock, event, population}.
• Every authored metric must declare value_type: explicitly. The metric output type may differ from the underlying measure.
• At most one times: entry per model may have default: true.
• No name on a model (column, dimension, measure, entity binding) may appear in any graph entity's disallowed_names:.

Dropped (no replacement)

• auto_publish: on measures — auto-publish is gone. Author explicit metrics.
• package.default_account_id — vestigial, no consumer.
• dimension.preferred_filter_ops — metadata-only, no planner gating.
• measure.clock_variants, comparison_peers, preferred_companion_metrics — metadata-only on measures. comparison_family and comparison_mode stay (load-bearing). preferred_companion_metrics is allowed on metrics as advisory governance metadata; companion-metric relationships are too volatile to lock in at the measure layer.
• topics: on any object — no validation, no scaling pattern.
• policy.kind: plan_constraint — runtime no-op. The four real kinds are package_release, object_visibility, object_access, protected_object.

Warnings (advisory, not blocking): as: used where the resulting ID matches the auto-computed one (use is unnecessary).

Every package must declare schema_version: 1 at the top of package.yml. Any other value raises INVALID_CONFIG at load time.

schema_version is a stamp, not a feature toggle. The number bumps on a breaking authoring change — not on additive features. The runtime no longer has a version-dispatch path; 1 is the only contract.

Every warehouse except duckdb declares a package.connection block whose kind selects the connector. For warehouse: snowflake, kind selects between two paths.

Both kinds require name. snowflake_cli reads it as the CLI profile name; snowflake_native reads it as a logical label surfaced in explain and operational metadata.

Native connection options

• account_env · user_env · password_env — env var names holding the credential. Literal credentials are rejected.
• password_file_env — env var holding a file path; the file's content is the password.
• warehouse · role · database · schema — per-session defaults applied at connection time.
• query_tag — attached to every query; surfaces in Snowflake query history.

Other warehouses

The remaining warehouses each expose a single native kind: postgres_native, bigquery_native, databricks_native, motherduck_native, ducklake_native, athena_native, clickhouse_native. The same secrets convention applies everywhere: credentials are never literals: they arrive through env-var indirection (*_env names) or file paths (*_file), while non-secret locators like host or database may be literal or env-indirected.

package:
  warehouse: postgres
  connection:
    kind: postgres_native
    host_env: SR_POSTGRES_HOST
    port: 5432
    database: sr_jaffle
    schema: public
    user_env: SR_POSTGRES_USER
    password_env: SR_POSTGRES_PASSWORD

The full option list for each warehouse lives in the per-warehouse *_CONNECTION_OPTIONS tuples in semantic_rails/dialects.py, with canonical env-var names in .env.example at the repo root. Redshift is coming next; until then see docs/ADDING_A_DIALECT.md.

Every error code raised at load or plan time maps to a small number of authoring fields. Use this table when an error appears in validate-config, compile, or explain. The full inventory and request / response shapes live in the API reference.

One entity, one model with one dimension / time / measure, no metrics, no segment, no policy. Extend section-by-section by referring back to the relevant component above.

# package.yml
schema_version: 1
package:
  id: shop_min
  namespace: shop_min
  warehouse: duckdb
  default_db: data/shop_min.duckdb
  seed: { kind: sql_script, source: data/seed.sql }
  schema_strict: true

# graph.yml
graph:
  entities:
    order:
      label: Order
      key: [order_id]                 # list form is required
      model: orders                   # which model declares this entity as primary

# models/orders.yml
model:
  id: orders                          # required; the mapping key alone is not enough
  label: Orders
  relation: shop_min_order
  # grain: is derived from the primary entity's key — do NOT author it
  # alongside `entities:` (strict mode rejects the combination).
  entities:
    order: {}                         # primary; grain comes from graph's order.key
  times:
    ordered_at:
      column: ordered_at
      kind: timestamp
      class: event_time
      default: true
  dimensions:
    status: { kind: categorical }
  measures:
    order_count:
      kind: entity_count
      entity_key: order
      accumulation: { kind: event }
      value_type: count

# metrics/order_count.yml — at least one metric recipe is required
metrics:
  order_count:
    label: Order Count
    description: Count of orders. Codified for stable reference.
    kind: aggregate
    measure: order_count
    value_type: count

uv run semantic-rails parse-config --path /path/to/shop_min returns ok: true; the catalog exposes measure.shop_min.order_count and metric.shop_min.order_count. A package must declare at least one metric recipe to load — the metrics/ file above is not optional.

Next: pair this reference with the narrative Package Authoring guide, Query Planner for how authored objects flow into plans, or the API Reference for the wire shape on every route.