Sidequery

Dimensions

Dimensions are fields you group and filter by: categorical, numeric, boolean, and time (with granularity suffixes).

Dimensions are the fields you group and filter by. They define the grain of a query.

Runnable Example (Executed in CI)

Doctest fixture (models/semantic_layer.yml)
models:
  - name: orders
    sql: |
      select * from (values
        (1, 120.00, timestamp '2024-01-15 10:12:00'),
        (2, 80.00,  timestamp '2024-01-20 09:30:00'),
        (3, 50.00,  timestamp '2024-02-05 14:05:00'),
        (4, 200.00, timestamp '2024-02-18 11:00:00')
      ) as t(id, amount, created_at)
    primary_key: id
    dimensions:
      - name: created_at
        type: time
        sql: created_at
        granularity: day
    metrics:
      - name: revenue
        agg: sum
        sql: amount

uvx sidemantic query "SELECT orders.created_at__month, orders.revenue FROM orders ORDER BY orders.created_at__month" --models ./models

created_at__month,revenue
2024-01-01,200.00
2024-02-01,250.00

Dimension Types

  • categorical: text/enum values (region, status)
  • numeric: numbers used as group keys (tier, bucket)
  • boolean: true/false flags
  • time: timestamps/dates with a base granularity

YAML

models:
  - name: orders
    dimensions:
      - name: status
        type: categorical
        sql: status

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

Time Granularity Suffixes

Time dimensions support suffixes like __month in queries:

SELECT orders.created_at__month, orders.revenue
FROM orders

Gotchas