Lightdash Dimension Configuration in dbt YAML

Every column declared in a dbt model’s YAML automatically becomes a dimension in Lightdash. There is no separate import step, no mapping table, no ETL between your dbt project and your BI layer. Lightdash reads your repo, compiles the project, and the Explore view populates. That tight coupling is the whole point of building a BI tool on top of dbt — your transformation layer and your analytics layer share one source of truth.

The meta: block under each column is where you configure how Lightdash presents that dimension. On dbt v1.9 and earlier, meta: sits directly under the column. On v1.10+ (and Fusion), it wraps inside a config: block. The examples here use the v1.9 syntax, which is still the norm in production projects.

Dimension Types

Lightdash supports five types: string, number, date, timestamp, and boolean. Types are auto-detected from your warehouse schema but can be overridden in the YAML if the inference is wrong or if you want to control how a column is presented:

models:
  - name: mrt__sales__orders
    columns:
      - name: order__created_at
        description: "Timestamp when the order was placed"
        meta:
          dimension:
            type: timestamp
      - name: order__status
        description: "Current order status"
        meta:
          dimension:
            type: string
      - name: order__revenue
        description: "Order total in EUR, after discounts"
        meta:
          dimension:
            type: number

Type matters because it controls which operations Lightdash offers in the UI. Number dimensions get aggregate options (sum, average, count). Timestamp dimensions get time granularity selectors. String dimensions get filter operators like “contains” and “starts with.”

Key Properties

label

Overrides the display name. Defaults to a humanized version of the column name (order__revenue becomes “Order Revenue”). Use label when the humanized default is wrong, awkward, or missing important context:

meta:
  dimension:
    type: number
    label: "Revenue (EUR, post-discount)"

Labels only affect what users see in the Explore view. The column name stays as the identifier in YAML references.

description

Shows on hover in the Explore view and inherits from the dbt column description if no dimension-level description is set. This is the mechanism by which your dbt documentation flows into the BI layer without duplication. Write the description at the column level, not inside meta.dimension, and Lightdash picks it up automatically.

format

Accepts spreadsheet-style number formatting patterns:

meta:
  dimension:
    type: number
    format: '[$€]#,##0.00'   # €1,234.56

Common patterns:

• '[$€]#,##0.00' — euro with two decimal places
• '$#,##0' — dollar, no cents
• '0.0%' — percentage with one decimal
• '#,##0.0K' — abbreviated thousands

The format applies in the Explore view and in chart axis labels. It does not affect the underlying data — the raw value is always accessible for metric calculations.

hidden

The hidden: true flag keeps a dimension out of the Explore sidebar while still making it available for metric calculations. This is the standard pattern for raw revenue columns you want to aggregate but not expose directly:

- name: order__revenue
  meta:
    dimension:
      type: number
      format: '[$€]#,##0.00'
      hidden: true  # available for metrics, invisible to users
    metrics:
      total_revenue:
        type: sum
        format: '[$€]#,##0.00'

Users see total_revenue in the sidebar. They do not see order__revenue as a standalone dimension. This prevents the confusion of having both a raw column and its aggregate visible at the same time.

time_intervals

Controls which granularities appear for date and timestamp fields. The default set is reasonable for most use cases, but you can customize:

meta:
  dimension:
    type: timestamp
    time_intervals: ['DAY', 'WEEK', 'MONTH', 'QUARTER', 'YEAR']

Set time_intervals: 'OFF' to disable the automatic date dimension expansion entirely. Useful for date fields that represent categories (fiscal period codes, cohort dates) rather than time series data.

groups

Assigns the dimension to a named sidebar section. Groups collapse and expand, which is the practical solution to a sidebar with 30+ fields. Covered in detail in Organizing Lightdash Metrics at Scale.

Additional Dimensions

Some computed values don’t map to physical columns. additional_dimensions under the model’s meta: block handles these:

models:
  - name: mrt__sales__orders
    meta:
      additional_dimensions:
        order__revenue_thousands:
          type: number
          sql: "${TABLE}.order__revenue / 1000"
          format: '[$€]#,##0.0K'
          label: "Revenue (thousands)"
        is_high_value:
          type: boolean
          sql: "${TABLE}.order__revenue > 500"
          label: "High-Value Order"

The sql field uses ${TABLE} as a reference to the model’s underlying table. You can also reference other dimensions using ${dimension_name}.

additional_dimensions are useful for:

• Unit conversions (revenue in different currencies, time in different units)
• Derived categorizations that don’t need their own SQL column
• Boolean flags computed from thresholds
• Display-friendly transformations that you don’t want to materialize in dbt

The tradeoff is that they live in the YAML rather than in SQL, which means they can’t be indexed or optimized by the warehouse. For heavy computations or frequently filtered derived columns, materializing them in an intermediate dbt model is the better call.

The Flow from Column to Dimension

Every column in your dbt model’s YAML is a potential dimension. The meta.dimension block is optional — if you omit it, Lightdash still creates a dimension from the column with auto-detected type. The meta.dimension block is where you override defaults, add formatting, hide raw columns, and control time granularities.

The column’s description from dbt flows through automatically. Documentation written at the column level surfaces in Lightdash without duplication.

For how to define the metrics that sit on top of these dimensions, see Lightdash Metric Types and Definition Syntax.