Dimensions

Dimension fields represent categorical attributes used for grouping and filtering.

Overview

Dimensions are the categorical fields in your semantic model. They represent attributes of your data that can be used for grouping, filtering, and analysis.

Characteristics

  • Used in GROUP BY - Dimensions group query results
  • Can be filtered - Specs filter by dimension values
  • Lower cardinality - Typically fewer unique values than measures
  • Examples: Customer Name, Product Category, Order Date, Region

Basic Definition

- type: dimension
  name: Customer Name
  description: Name of the customer
  data_type: string
  expression:
    sql: customer_name

Dimension Properties

name

The name a spec uses to reference the dimension (case-insensitive), and the name your client sees.

name: Customer Name

description

Optional description explaining what the dimension represents.

description: Full name of the customer

data_type

The data type of the dimension. See data types.

data_type: string

For date and date_time dimensions, including grains and filtering patterns, see Date and DateTime dimensions.

expression

How to query this dimension from the database.

expression:
  sql: customer_name

Learn about expressions →

Optional Properties

hidden

Hide the dimension from discovery (the fields endpoint omits it by default, explore never suggests it) while keeping it resolvable in a spec and usable in complex dimensions and calculations.

hidden: true

display_type

Tell your client what kind of value this is. Stored as metadata; nothing in SQL generation uses it.

display_type: url  # default, html, url, email, phone_number, image

format

Presentation hint for your client (shortcut string or mapping). Validated and stored at deploy; nothing in SQL generation uses it.

format: currency:2  # or hash: { type: currency, precision: 2 }

Learn about field format →

synonyms

Alternative names for this dimension. A field reference in a spec resolves by uid, name or synonym, and GET .../fields?q= matches on them, so callers using different terminology land on the same field.

synonyms:
  - client name
  - buyer name
  - account name

extended_blend_group

For dimensions that should blend across tables in queries, set the same extended_blend_group on each. See Extended blending groups.

Primary Keys

Mark dimensions as primary keys for query optimization:

- type: dimension
  name: Order ID
  data_type: integer
  expression:
    primary_key: true
    sql: order_id

Benefits:

  • Helps planner optimize joins
  • Ensures uniqueness
  • Improves query performance

Complex Dimensions

Complex dimensions are dimensions whose expressions are defined in terms of other dimensions instead of directly referencing a physical column.

Rules:

  • Complex dimensions may reference only dimensions, not measures.
  • All referenced dimensions must be reachable in the same universe as the complex dimension (so they can be grouped together).
  • Evaluation happens at query time, similar to compound measures.

Example: Derived status label

- type: dimension
  name: Customer Status Code
  data_type: string
  expression:
    sql: status_code

- type: dimension
  name: Customer Status
  data_type: string
  expression:
    sql: |
      CASE
        WHEN [Customer Status Code] = 'A' THEN 'Active'
        WHEN [Customer Status Code] = 'I' THEN 'Inactive'
        ELSE 'Unknown'
      END

Example: Custom date bucket

- type: dimension
  name: Order Date
  data_type: date
  expression:
    sql: order_date

- type: dimension
  name: Order Month Label
  data_type: string
  expression:
    sql: to_char([Order Date], 'YYYY-MM')

Use complex dimensions when you want to:

  • Reuse existing dimensions in multiple derived attributes,
  • Keep business-friendly labels and buckets out of raw SQL in every query, and
  • Ensure that all logic for a concept (like “status” or “month”) lives in one place in the semantic model.

Common Patterns

Simple Dimension

- type: dimension
  name: Product Category
  data_type: string
  expression:
    sql: category_name

Formatted Dimension

- type: dimension
  name: Product Image
  data_type: string
  display_type: image
  expression:
    sql: image_url

Primary Key Dimension

- type: dimension
  name: Order ID
  data_type: integer
  expression:
    primary_key: true
    sql: order_id

Best Practices

  1. Use descriptive names - Business-friendly dimension names
  2. Add descriptions - They come back from the fields endpoint, so callers know what a dimension means
  3. Set grains for date/datetime - See Date and DateTime dimensions
  4. Mark primary keys - Improve query optimization
  5. Use appropriate data types - Match database column types

Next Steps