lightdash.config.yml reference

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

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:
  # ...

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
  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.
options	No	Array of strings	A list of possible values for the parameter.
default	No	string or Array of strings	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.