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

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

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.

Introduction

Explore and analyze

Build your semantic layer

Workspace and user management

Integrations

Embedding

Self-hosting and deployment

Contact

lightdash.config.yml reference

What is lightdash.config.yml?

Do I need this file?

Getting started

Configuration options

Spotlight configuration

Parameters configuration

Using parameters in your project

​What is lightdash.config.yml?

​Do I need this file?

​Getting started

​Configuration options

​Spotlight configuration

​Parameters configuration

​Using parameters in your project

What is lightdash.config.yml?

Do I need this file?

Getting started

Configuration options

Spotlight configuration

Parameters configuration

Using parameters in your project