Field-by-field reference for Sidemantic YAML definitions.

This page documents the YAML contract. For editor validation and full machine-readable structure, see JSON Schema.

Top-Level

models: []
metrics: []     # graph-level metrics (optional)

Model

models:
  - name: orders
    table: raw_orders            # or: sql: "select ..."
    primary_key: id
    description: Optional text
    dimensions: []
    metrics: []
    segments: []
    relationships: []
    pre_aggregations: []

Model Fields

• name (required)
• table (required unless sql is provided)
• sql (optional; derived model query)
• primary_key (required for joins and correctness)
• dimensions (optional)
• metrics (optional; model-level metrics)
• segments (optional)
• relationships (optional)
• pre_aggregations (optional)

Dimension

dimensions:
  - name: created_at
    type: time
    sql: created_at
    granularity: day

Common fields:

• name (required)
• type (required)
• sql (required)
• granularity (time only)

Metric (Model-Level)

metrics:
  - name: revenue
    agg: sum
    sql: amount
    filters: ["status = 'completed'"]

Fields:

• name (required)
• agg (required)
• sql (optional; defaults depend on agg)
• filters (optional list of SQL filter strings)

Metric (Graph-Level)

metrics:
  - name: total_revenue
    sql: orders.revenue

Graph-level metrics can also be typed forms like ratio, derived, cumulative, and time_comparison (see Metrics).

Relationship

relationships:
  - name: customers
    type: many_to_one
    foreign_key: customer_id

See Relationships for details and best practices.