Semantic YAML reference

Every field the Flax semantic layer supports, from model and column metadata to the flax extension

This is the reference for the Flax semantic-layer YAML: the dbt-compatible file shape and the flax: extension that adds dimensions, measures, joins, and row-level security. It is grounded in packages/semantic-spec. Use it to look up field names, types, and constraints.

#File shape

A Flax model file is a dbt schema file. The top level is version: 2 and a models: list. Each model has dbt-native name, description, and columns, plus a Flax-specific flax: block.

version: 2

models:
  - name: orders
    description: One row per order placed in the store.
    columns:
      - name: order_id
        description: Primary key for the order.
      - name: amount
        description: Gross order amount.
    flax:
      primary_key: order_id
      dimensions: [ ... ]
      measures: [ ... ]
      joins: [ ... ]
      access_filters: [ ... ]

Because everything Flax-specific is namespaced under flax:, the same file remains valid to dbt. See dbt projects for connecting an existing project.

#The flax: extension

Field Type Description
primary_key string Column uniquely identifying a base row. Enables correct (symmetric) counts and sums over fan-out joins.
dimensions list Attributes to group and filter by.
measures list Aggregations.
joins list Relationships to other models.
access_filters list Mandatory row-level-security predicates.

#Dimensions

Fields for each item in dimensions. Required: name, type, sql.

Field Type Description
name string Field identifier.
label string Display name in the UI.
description string Documentation for the field.
type enum One of string, number, boolean, time.
sql string SQL expression. ${column} is a column on this model; ${model.column} a joined model's column.
time_grains list For time dimensions: any of day, week, month, quarter, year.
hidden boolean Hide from the explore picker (default false). 
dimensions:
  - name: order_date
    label: Order date
    type: time
    time_grains: [day, week, month, quarter, year]
    sql: ${created_at}

#Measures

Fields for each item in measures. Required: name, type.

Field Type Description
name string Field identifier.
label string Display name in the UI.
description string Documentation for the field.
type enum count, count_distinct, sum, average, min, max, median, percentile, number.
percentile number Fraction 0–1 for type: percentile (e.g. 0.25 for Q1).
sql string Expression to aggregate. Use "*" with type: count for a row count.
filters list of strings SQL boolean expressions AND-ed into the aggregation.
hidden boolean Hide from the explore picker (default false). 
measures:
  - name: completed_revenue
    label: Completed revenue
    type: sum
    sql: ${amount}
    filters:
      - ${status} = 'complete'
  - name: p90_amount
    type: percentile
    percentile: 0.9
    sql: ${amount}

#Joins

Fields for each item in joins. Required: name, sql_on.

Field Type Description
name string Name of the model to join.
type enum left (default), inner, full, right.
relationship enum one_to_one, many_to_one, one_to_many, many_to_many.
sql_on string Join predicate, e.g. ${orders.customer_id} = ${customers.customer_id}.

#Access filters

Fields for each item in access_filters. Required: sql, attribute. See Row-access filters.

Field Type Description
sql string Org-authored SQL expression (e.g. ${region}) compared as text to the caller's attribute values.
attribute string Principal attribute key the allowed values come from (e.g. region). 
access_filters:
  - sql: ${region}
    attribute: region

Note

The flax: block rejects unknown keys — the JSON Schema sets additionalProperties: false on every object. A typo in a field name is a validation error, not a silent no-op.