lightdash.config.yml reference

What is lightdash.config.yml?

The lightdash.config.yml file is an optional configuration file that allows you to define project-wide settings for your Lightdash project. Think of it as a way to customize and enhance your Lightdash experience beyond the basic setup.

lightdash.config.yml is not supported when your project is connected directly to dbt Cloud.This file only works with projects that use direct git connections or deploy with the CLI (either from local dbt projects and/or continuous deployment).

Do I need this file?

You don’t need lightdash.config.yml to get started with Lightdash! This file is for users who want to:

Organize metrics in the Metrics Catalog with custom categories and visibility settings
Create parameters that users can change to modify data across multiple charts and dashboards

If you’re just getting started with Lightdash, you can skip this file and come back to it later when you want these advanced features.

Getting started

Before creating a lightdash.config.yml file, make sure you have:

✅ A working Lightdash project (completed the getting started guide)
✅ A local dbt project (not connected to dbt Cloud)
✅ The Lightdash CLI installed and configured

Create the file

Create a new file called lightdash.config.yml in the root directory of your dbt project - this is the same folder where your dbt_project.yml file is located.

# Navigate to your dbt project directory
cd /path/to/your/dbt/project

# Create the config file
touch lightdash.config.yml

Add your first configuration

Start with a simple configuration. Here’s a basic example that sets up Metrics Catalog categories:

# Basic lightdash.config.yml example
spotlight:
  default_visibility: "show"
  categories:
    finance:
      label: "Finance"
      color: "green"
    marketing:
      label: "Marketing" 
      color: "blue"

Deploy your changes

After creating or updating your lightdash.config.yml file, deploy the changes to your Lightdash project:

lightdash deploy

That’s it! Your configuration is now active in your Lightdash project.

Configuration options

The lightdash.config.yml file supports the following top-level configuration options:

# Configuration for project-wide spotlight settings
spotlight:
  # ...

# Configuration for project-wide parameters
parameters:
  # ...

# Configuration for project-wide defaults
defaults:
  # ...

# Configuration for custom date granularities
custom_granularities:
  # ...

# Configuration for table groups in the sidebar
table_groups:
  # ...

Metrics Catalog configuration

The spotlight section allows you to configure project-wide Metrics Catalog settings. spotlight is the YAML namespace that covers everything about how your metrics show up across the Metrics experience — here you set the project-wide defaults, and you can override them per model or metric in your model .yml files. This section is required in the lightdash.config.yml file.

spotlight:
  default_visibility: "show"
  categories:
    finance:
      label: "Finance"
      color: "green"
    user_engagement:
      label: "User Engagement"
      color: "blue"

Property	Required	Value	Description
`default_visibility`	No	string enum	The default visibility of Metrics Catalog metrics. Defaults to `show`, can also be set to `hide`.
`categories`	No	Object	Define the categories that can be used in the Metrics Catalog on your model yml files.

Each category in the categories object requires the following properties:

Property	Required	Value	Description
`label`	Yes	string	The label of the category as it will be displayed in the Metrics Catalog.
`color`	No	string enum	The color of the category. If not provided, it will be set to gray. Allowed values: `gray`, `violet`, `red`, `orange`, `green`, `blue`, `indigo`, `pink`, `yellow`.

Parameters configuration

The parameters section allows you to define project-wide parameters that can be referenced in various parts of your Lightdash project.

parameters:
  region:
    label: "Region"
    description: "Filter data by region"
    options:
      - "EMEA"
      - "AMER"
      - "APAC"
    default: ["EMEA", "AMER"]
    multiple: true
  min_revenue:
    label: "Minimum Revenue"
    description: "Filter for minimum revenue threshold"
    type: "number"
    options:
      - 1000
      - 5000
      - 10000
    default: 5000
  custom_date_range_start:
    label: "Custom date range - start"
    description: "The start date for a custom date range filter"
    type: "date"
custom_date_range_end:
    label: "Custom date range - end"
    description: "The end date for a custom date range filter"
    type: "date"
department:
    label: "Department"
    description: "Filter data by department"
    options_from_dimension:
      model: "employees"
      dimension: "department"

Each parameter is defined as a key-value pair where the key is the parameter name (must be alphanumeric with underscores or hyphens) and the value is an object with the following properties:

Property	Required	Value	Description
`label`	Yes	string	A user-friendly label for the parameter as it will be displayed in the UI.
`description`	No	string	A description of the parameter.
`type`	No	”string”, “number”, or “date”	The type of the parameter. Defaults to “string” if not specified.
`options`	No	Array of strings, numbers, or `{ label, value }` objects	A list of possible values for the parameter.
`default`	No	string, number, or Array of strings/numbers	The default value(s) for the parameter. When using labeled options, the default must match a `value`, not a `label`.
`multiple`	No	boolean	Whether the parameter input will be a multi-select.
`allow_custom_values`	No	boolean	Whether users can input custom values beyond predefined options.
`options_from_dimension`	No	Object	Get parameter options from a dimension in a model. Requires `model` and `dimension` arguments (see below).

If using options_from_dimension, the object requires the following properties:

Property	Required	Value	Description
`model`	Yes	string	The model containing the dimension.
`dimension`	Yes	string	The dimension to get options from.

Labeled options

Static options can be authored as either plain values or { label, value } objects.

parameters:
  status:
    label: "Status"
    description: "Filter data by status"
    options:
      - label: "Active"
        value: "active_id_1"
      - label: "Inactive"
        value: "inactive_id_2"
    default: "active_id_1"

Plain string/number arrays continue to work and remain the simplest form when the label and value are the same.

Using parameters in your project

Parameters defined in the lightdash.config.yml file can be referenced in various parts of your Lightdash project using the syntax ${lightdash.parameters.parameter_name} or the shorter alias ${ld.parameters.parameter_name}. For example, to reference a parameter named region:

${lightdash.parameters.region}

Or using the shorter alias:

${ld.parameters.region}

See the Parameters guide for more information on how to use parameters.

Reserved parameter names

A small set of parameter names are reserved by Lightdash and resolve automatically from the query context — you don’t need to declare them in lightdash.config.yml or in a model.

Reserved name	Resolves to
`date_zoom`	The currently selected date zoom granularity, lowercased (e.g. `day`, `week`, `month`). Empty string when no date zoom is selected.

If you define a user parameter with one of these names, your user parameter shadows the reserved one. See Reserved parameters for usage details.

Defaults configuration

The defaults section allows you to set project-wide default settings that apply across all explores and dimensions. These defaults can be overridden at the explore or dimension level.

defaults:
  case_sensitive: false
  column_totals: false
  additional_time_intervals:
    date: ['fiscal_quarter']
    timestamp: ['HOUR']
  granularity_labels:
    week: "Week starting Monday"

Property	Required	Value	Description
`case_sensitive`	No	boolean	Default case sensitivity for string filters across the project. When `false`, all string filters will be case insensitive by default. Defaults to `true`.
`column_totals`	No	boolean	Default behavior for column totals in the explorer results table. When `false`, Lightdash skips the extra warehouse query that calculates column totals for new queries. Charts that explicitly enable “Show column totals” still calculate them. Defaults to `true`.
`additional_time_intervals`	No	Object	Extra time intervals appended to the built-in defaults for `date` and `timestamp` dimensions that don’t declare their own `time_intervals`. See Additional time intervals below.
`granularity_labels`	No	Object (string → string)	Override the display label of standard granularities (e.g. `week`, `month`) project-wide. Applied to dimension labels in the Explorer, the Explorer sidebar tree, the date zoom dropdown, and chart axis labels. See Granularity label overrides below.

Disabling column totals by default

Every time you run a query in the explorer, Lightdash runs an additional warehouse query to calculate column totals for the results table footer. For cost-conscious users, setting column_totals: false skips this extra query by default, which can reduce warehouse spend on busy projects.

defaults:
  column_totals: false

This is a default, not a kill switch — charts that explicitly enable “Show column totals” still calculate totals as expected. You can also toggle this default via the API:

PUT /api/v2/projects/{projectUuid}/defaults
{ "column_totals": false }

Case sensitivity hierarchy

The case_sensitive setting follows a hierarchy where more specific settings override broader ones:

Dimension-level (highest priority) - Set on individual dimensions
Explore/table-level - Set on the explore or table
Project-level - Set in lightdash.config.yml defaults
Default behavior - Case sensitive (true) if nothing is specified

This allows you to set organization-wide defaults while maintaining the flexibility to override them for specific explores or dimensions as needed. Example: Set case insensitivity as the project default, but override for a specific table:

# lightdash.config.yml
defaults:
  case_sensitive: false  # Project-wide default

# In your model yml file - override for a specific table
models:
  - name: case_sensitive_table
    meta:
      case_sensitive: true  # Override: this table uses case sensitive filters

See Tables reference for explore-level configuration and Dimensions reference for dimension-level configuration.

Additional time intervals

By default, Lightdash exposes a fixed set of time intervals on date and timestamp dimensions:

Date dimensions: DAY, WEEK, MONTH, QUARTER, YEAR
Timestamp dimensions: RAW, DAY, WEEK, MONTH, QUARTER, YEAR

The additional_time_intervals setting lets you append extra intervals (standard granularities or custom granularity keys) to those built-in defaults project-wide, so you don’t have to repeat time_intervals on every column.

defaults:
  additional_time_intervals:
    date:
      - fiscal_quarter      # custom_granularities key
    timestamp:
      - HOUR                # standard granularity
      - fiscal_quarter      # custom_granularities key

Property	Required	Value	Description
`date`	No	Array of strings	Extra intervals appended to the date defaults. Values may be standard granularities or custom granularity keys.
`timestamp`	No	Array of strings	Extra intervals appended to the timestamp defaults. Values may be standard granularities or custom granularity keys.

How it works:

Additive only — the built-in defaults are always included; values listed here are appended after them and de-duplicated.
Fallback-only — if a dimension declares its own time_intervals in its model .yml, the per-column list wins and additional_time_intervals is ignored for that dimension.
Validation — values are validated once at project compile time. Standard granularities are accepted case-insensitively. Sub-day grains (RAW, MILLISECOND, SECOND, MINUTE, HOUR) are not valid under date and are dropped with a warning. Unknown names that don’t match a standard grain or a defined custom_granularities key are also dropped with a warning.

Example: Add HOUR to every timestamp dimension and a fiscal_quarter custom granularity to both:

# lightdash.config.yml
custom_granularities:
  fiscal_quarter:
    label: "Fiscal Quarter"
    sql: "DATE_TRUNC('quarter', ${COLUMN} + INTERVAL '1 month')"
    type: date

defaults:
  additional_time_intervals:
    date: ['fiscal_quarter']
    timestamp: ['HOUR', 'fiscal_quarter']

A column that overrides this default still works as before:

# In your model yml file - this column ignores the project default
columns:
  - name: created_at
    meta:
      dimension:
        type: timestamp
        time_intervals: ['DAY', 'WEEK']  # explicit list wins

See Dimensions reference for per-dimension configuration and the Custom granularities section below for defining custom granularity keys.

Granularity label overrides

The granularity_labels setting lets you replace how standard granularities are displayed across the project. This is useful when your business uses a non-default convention — for example, a week that starts on Monday — and you want the UI to reflect that everywhere a granularity is shown.

defaults:
  granularity_labels:
    week: "Week starting Monday"
    month: "Calendar month"

Property	Required	Value	Description
`<granularity>` (e.g. `week`)	No	string	The full replacement label used for this grain wherever the grain name is shown. The configured string is used verbatim, not appended to the built-in name.

Supported keys are the standard Lightdash TimeFrames values, written in lowercase or uppercase, for example week, month, or hour. Unknown keys are ignored with a warning at project compile time. Where the override is applied:

Explorer dimension labels — the configured string replaces the built-in grain segment of the auto-generated dimension label. For example, with week: "Week starting Monday", the Order date Week dimension becomes Order date Week starting Monday.
Explorer sidebar tree — the same relabeling is shown in the dimension tree.
Date zoom dropdown — the configured string is used verbatim as the option label (e.g. Week starting Monday instead of Week).
Chart axis labels — axis labels that reflect the active grain pick up the override automatically.

How it works:

Full replacement — the configured string replaces the grain label outright. Provide the complete label you want users to see (e.g. "Week starting Monday"), not just a suffix.
Standard granularities only — to relabel non-standard time periods (e.g. fiscal quarters), define a custom granularity instead.
Project-wide — applies to every date and timestamp dimension in the project; there is no per-dimension override.

Example: Make every weekly grain advertise its week-start convention:

# lightdash.config.yml
defaults:
  granularity_labels:
    week: "Week starting Monday"

With this config, a created_at timestamp dimension exposes Created at Week starting Monday in the Explorer, sidebar tree, and chart axis labels, and Week starting Monday appears in the date zoom dropdown.

Custom granularities configuration

Availability: Custom granularities are a Beta feature.

The custom_granularities section allows you to define reusable custom time granularities that appear in the date zoom dropdown alongside standard options (Day, Week, Month, Quarter, Year). This is useful for business-specific time periods like fiscal quarters, Monday-to-Sunday weeks, or other custom date groupings.

custom_granularities:
  fiscal_quarter:
    label: "Fiscal Quarter"
    sql: "DATE_TRUNC('quarter', ${COLUMN} + INTERVAL '1 month')"
    type: date
  week_monday:
    label: "Week (Mon-Sun)"
    sql: "DATE_TRUNC('week', ${COLUMN})"
    type: date
  fiscal_year:
    label: "Fiscal Year"
    sql: "EXTRACT(YEAR FROM ${COLUMN} + INTERVAL '1 month')"
    type: string

Each custom granularity is defined as a key-value pair where the key is the granularity name (must be alphanumeric with underscores) and the value is an object with the following properties:

Property	Required	Value	Description
`label`	Yes	string	A user-friendly label for the granularity as it will be displayed in the date zoom dropdown.
`sql`	Yes	string	SQL expression that defines how to truncate/transform the date. Use `${COLUMN}` as a placeholder for the actual date column - it will be replaced with the column’s SQL at runtime.
`type`	No	`date`, `timestamp`, or `string`	The output type of the SQL expression. Use `date` for truncated dates, `timestamp` for truncated timestamps, or `string` for formatted text output (e.g., fiscal year labels). Defaults to `date` if not specified.

How custom granularities work

Custom granularities are defined at the project level in lightdash.config.yml and become available on date dimensions through the time_intervals property. The ${COLUMN} template in the SQL expression is automatically replaced with the actual column SQL when generating queries. Example: Define a fiscal quarter granularity and use it on a dimension:

# lightdash.config.yml
custom_granularities:
  fiscal_quarter:
    label: "Fiscal Quarter"
    sql: "DATE_TRUNC('quarter', ${COLUMN} + INTERVAL '1 month')"
    type: date

# In your model yml file
columns:
  - name: order_date
    meta:
      dimension:
        type: date
        time_intervals: ['DAY', 'WEEK', 'MONTH', 'fiscal_quarter', 'YEAR']

The custom granularity fiscal_quarter will now appear in the date zoom dropdown for order_date, alongside the standard intervals.

Custom granularities inherit requiredAttributes and anyAttributes from the parent dimension, so access controls are automatically applied.

See the Date zoom guide for information on configuring which granularities appear in the dropdown and setting defaults.

Use cases

Fiscal calendars: Define fiscal quarters or years that don’t align with calendar quarters
Week start customization: Create weeks that start on Monday or any other day
Custom periods: Define business-specific time periods like “retail weeks” or “academic terms”

See Dimensions reference for more information on configuring time intervals on dimensions, including how to reference custom granularities.

Table groups configuration

The table_groups section defines display labels and descriptions for the group keys referenced by your models in their meta.groups array. These groups are used to render nested table groups in the Explore sidebar (up to 3 levels of nesting).

table_groups:
  mobile:
    label: 'Mobile App'
    description: 'Tables related to the mobile app'
  engagement:
    label: 'Engagement'
  finance:
    label: 'Finance'
    description: 'Revenue, billing, and accounting tables'

Each entry in table_groups is keyed by the group identifier you reference from a model’s meta.groups, and supports the following properties:

Property	Required	Value	Description
`label`	Yes	string	Display label shown in the sidebar for this table group.
`description`	No	string	Optional description of this table group.

Group keys must match the pattern ^[a-zA-Z0-9_-]+$. If a key referenced from a model’s meta.groups is not defined in table_groups, the key itself is used as the label.

When you run lightdash deploy or lightdash preview, the CLI only syncs table groups if the table_groups key is present in your config. To clear all previously deployed table groups, set table_groups: {} explicitly — omitting the key leaves the server-side groups unchanged.

To assign a table to a group, use the groups property on the model’s meta:

models:
  - name: users
    meta:
      groups: ['mobile', 'engagement']

See Tables reference for more information on grouping tables in the sidebar.

​What is lightdash.config.yml?

​Do I need this file?

​Getting started

​Configuration options

​Metrics Catalog configuration

​Parameters configuration

​Labeled options

​Using parameters in your project

​Reserved parameter names

​Defaults configuration

​Disabling column totals by default

​Case sensitivity hierarchy

​Additional time intervals

​Granularity label overrides

​Custom granularities configuration

​How custom granularities work

​Use cases

​Table groups configuration

What is lightdash.config.yml?

Do I need this file?

Getting started

Configuration options

Metrics Catalog configuration

Parameters configuration

Labeled options

Using parameters in your project

Reserved parameter names

Defaults configuration

Disabling column totals by default

Case sensitivity hierarchy

Additional time intervals

Granularity label overrides

Custom granularities configuration

How custom granularities work

Use cases

Table groups configuration