The lightdash.config.yml file is a configuration file that allows you to define project-wide settings for your Lightdash project. This file should be placed in the root of your dbt project.
The lightdash.config.yml file is not supported when your project is connected to dbt Cloud.

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 enum: “show” or “hide”The default visibility of spotlight metrics. Defaults to "show".
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

Parameters are an experimental feature. See our Feature Maturity Levels documentation to understand what this means.
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.
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.