Skip to main content

Dimensions

Dimensions are the columns in your table. They are the "attributes" of your data. For example, user_id in your users table is a dimension.

Adding dimensions to your project​

For a dimension to appear in Lightdash, you just need to declare it in your dbt model's YAML file.

version: 2

models:
  - name: my_model
    columns:
      - name: user_id # will be "User id" in LightDash
        description: 'Unique identifier for a user."

Column descriptions in your YAML file are automatically pulled into Lightdash and you can spot them if you hover over the dimension name 👀

screenshot-column-descriptions

Dimension configuration​

To customize the dimension, you can do it in your dbt model's YAML file.

version: 2

models:
  - name: my_model
    columns:
      - name: revenue_gbp_total_est
        description: "Total estimated revenue in GBP based on forecasting done by the finance team."
        meta:
          dimension:
            label: 'Total revenue' # this is the label you'll see in Lightdash
            description: 'My custom description'
            sql: "IF(${revenue_gbp_total_est} = NULL, 0, ${registered_user_email})"
            hidden: false
            round: 2
            format: 'gbp'

All the properties you can customize:

PropertyRequiredValueDescription
labelNostringCustom label. If you set this property, this is what you'll see in Lightdash instead of the dimension name.
typeNoDimension typeThe dimension type is automatically pulled from your table schemas in Lightdash but you can override the type using this property.
descriptionNostringDescription of the dimension in Lightdash. You can use this to override the description you have for the dimension in dbt.
sqlNostringCustom SQL applied to the column used to define the dimension.
time_intervalsNo'default' or OFF or string[]'default' will be converted into ['DAY', 'WEEK', 'MONTH', 'YEAR'] for dates and ['RAW', 'DAY', 'WEEK', 'MONTH', 'YEAR'] for timestamps, as will not setting anything; if you want no time intervals set 'OFF'
hiddenNobooleanIf set to true, the dimension is hidden from Lightdash. By default, this is set to false if you don't include this property.
roundNonumberRounds a number to a specified number of digits
formatNostringThis option will format the output value on the result table and CSV export. Currently supports one of the following: ['km', 'mi', 'usd', 'gbp', 'percent']

Dimension types​

Dimension types are automatically pulled from your tables schemas in Lightdash. We currently support these dimension types:

Dimension Types
string
number
timestamp
date
boolean

Time intervals​

Lightdash automatically adds intervals for dimensions that are timestamps or dates, so you don't have to!

For example, here we have the timestamp dimension created defined in our dbt project:

      - name: created
        description: 'Timestamp when the user was created.'

Lightdash breaks this out into the default intervals automatically. So, this is how created appears in our Lightdash project:

screenshot-default-intervals

By default, the time intervals we use are:​

Date: ['DAY', 'WEEK', 'MONTH', 'YEAR'] Timestamp: ['RAW', 'DAY', 'WEEK', 'MONTH', 'YEAR']

To change the time intervals used for a dimension, specify your custom intervals using time_intervals​

If you want to change the time intervals shown for a dimension, you can specify the custom time intervals you'd like you include using the time_intervals property for a dimension. You can use any values supported by your warehouse.

In this example, I've only included the day, month, and quarter time intervals for the created dimension in Lightdash.

      - name: created
        description: 'Timestamp when the user was created.'
        meta:
          dimension:
            time_intervals:
              - DAY
              - MONTH
              - QUARTER

screenshot-custom-intervals

To turn off time intervals for a dimension, set time_intervals: OFF​

If you want to turn off time intervals for a dimension, you can simply set the time_intervals property to OFF.

In this example, created would now appear as a single, timestamp dimension without a drop-down list of time intervals in Lightdash:

      - name: created
        description: 'Timestamp when the user was created.'
        meta:
          dimension:
            time_intervals: OFF

screenshot-intervals-off