lightdash.config.yml reference

The lightdash.config.yml file allows you to configure project-wide settings for your Lightdash project, including spotlight, parameters, and defaults.

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 Spotlight 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:

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

1. 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
   
2. Add your first configuration

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

   # Basic lightdash.config.yml example
   spotlight:
     default_visibility: "show"
     categories:
       finance:
         label: "Finance"
         color: "green"
       marketing:
         label: "Marketing" 
         color: "blue"
   
3. 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:
  # ...

Spotlight configuration

The spotlight section allows you to configure project-wide spotlight settings. 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 spotlight metrics. Defaults to show, can also be set to hide.
categories	No	Object	Define the categories that can be used in Spotlight 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 Spotlight.
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.

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

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.

Case sensitivity hierarchy

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

1. Dimension-level (highest priority) - Set on individual dimensions
2. Explore/table-level - Set on the explore or table
3. Project-level - Set in lightdash.config.yml defaults
4. 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 an Early Access 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.

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.