​
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"
PropertyRequiredValueDescription
default_visibilityNostring enumThe default visibility of spotlight metrics. Defaults to show, can also be set to hide.
categoriesNoObjectDefine the categories that can be used in Spotlight on your model yml files.
Each category in the categories object requires the following properties:
PropertyRequiredValueDescription
labelYesstringThe label of the category as it will be displayed in Spotlight.
colorNostring enumThe 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:
PropertyRequiredValueDescription
labelYesstringA user-friendly label for the parameter as it will be displayed in the UI.
descriptionNostringA description of the parameter.
optionsNoArray of stringsA list of possible values for the parameter.
defaultNostring or Array of stringsThe default value(s) for the parameter.
multipleNobooleanWhether the parameter input will be a multi-select.
allow_custom_valuesNobooleanWhether users can input custom values beyond predefined options.
options_from_dimensionNoObjectGet 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:
PropertyRequiredValueDescription
modelYesstringThe model containing the dimension.
dimensionYesstringThe 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.