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 or numbers	A list of possible values for the parameter.
`default`	No	string, number, or Array of strings/numbers	The default value(s) for the parameter.
`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.

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

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`.

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.

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.

Introduction

Explore and analyze

Build with AI

Build your semantic layer

Workspace and user management

Integrations

Lightdash SDK

Embedding

Self-hosting and deployment

Contact

lightdash.config.yml reference

What is lightdash.config.yml?

Do I need this file?

Getting started

Configuration options

Metrics Catalog configuration

Parameters configuration

Using parameters in your project

Reserved parameter names

Defaults configuration

Disabling column totals by default

Case sensitivity hierarchy

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

​Using parameters in your project

​Reserved parameter names

​Defaults configuration

​Disabling column totals by default

​Case sensitivity hierarchy

​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

Using parameters in your project

Reserved parameter names

Defaults configuration

Disabling column totals by default

Case sensitivity hierarchy

Custom granularities configuration

How custom granularities work

Use cases

Table groups configuration