Semantic Fields

Fields are the building blocks of your semantic model: dimensions, measures, data types, and field format.

Overview

  • Dimensions: Categorical attributes for grouping and filtering
  • Measures: Aggregatable quantities (sum, count, avg, etc.)
  • Data Types: string, integer, decimal, date, date_time, boolean, and more
  • Field format: currency, percent and date formats, stored as metadata for your client

One field on several tables

A field named on several tables is one field, with one description, one set of synonyms and one type. The tables only say where it is mapped: Order Date on the orders fact and on the returns fact is the same dimension, resolvable once and groupable across both.

So describe it on the table it belongs to and leave the others bare:

# models/sales/tbl.orders.yml — where the field belongs
  - type: dimension
    name: Order Date
    description: Date the order was placed, in warehouse local time.
    synonyms: [booked date, order day]
    data_type: date
    expression:
      sql: order_date

# models/sales/tbl.returns.yml — the same field, just mapped
  - type: dimension
    name: Order Date
    expression:
      sql: original_order_date

A later file fills in only what an earlier one left out. A bare mapping does not erase a description written beside the dimension, so the order the files load in cannot quietly blank the metadata. Everything that changes the plan stays last-definition-wins, so a bare mapping can still clear a rule deliberately.

Two files that both describe it, differently, leave the answer to whichever loads last — and zsql check warns, naming both:

warning: models/tbl.contact.yml: field Call Center ID: description is 'Call center that handled the contact.'
here and 'Call center identifier (e.g. CC01).' in models/tbl.call_center.yml; the last file loaded wins,
so say it in one place

zsql generate follows the same rule when it drafts: one description, written once, and one type per field name across the whole run.

Quick Reference

Field typeUse in GROUP BYAggregationExample
DimensionYesNoCustomer Name, Region, Order Date
MeasureNoYes (required)Total Revenue, Order Count

Next Steps