Skip to content

docs: getting started with lightdash.config.yml #122

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Aug 11, 2025
Merged

docs: getting started with lightdash.config.yml #122

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a85512c
docs: getting started with lightdash.config.yml
ZeRego Aug 11, 2025
58bc10c
docs: notes and warnings
ZeRego Aug 11, 2025
1d8af3c
small cleanup changes
jpetey75 Aug 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion guides/metrics-catalog.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,10 @@ All through your Lightdash `.yml` files.

You can control the visibility of metrics in the catalog by creating a new file called `lightdash.config.yml` in the root of your dbt project.

<Info>
If you're new to lightdash.config.yml, check out our [getting started guide](/references/lightdash-config-yml#getting-started-with-lightdashconfigyml) to learn how to create and set up this file.
</Info>

See this video for an example on how to set this up:

<div
Expand Down Expand Up @@ -292,7 +296,8 @@ models:
default_time_dimension:
field: event_date
interval: DAY
columns:...
columns:
# ... your column definitions here
```

3. [Compile your project](/references/dbt-projects.mdx)
Expand Down
12 changes: 4 additions & 8 deletions guides/using-parameters.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,18 +2,14 @@
title: "How to use parameters"
---

<Warning>
Parameters are an **experimental** feature. See our [Feature Maturity Levels](/references/feature-maturity-levels) documentation to understand what this means.
</Warning>

<Info>
Parameters are defined in the `lightdash.config.yml` file, which is not supported when your project is connected to dbt Cloud.
</Info>

**Parameters** are variables that allow you to create **dynamic, reusable queries** in Lightdash. They enable users to interact with and customize queries without needing to write SQL.

Parameters are defined in your `lightdash.config.yml` file and can be referenced in various parts of your Lightdash project.

<Info>
If you're new to lightdash.config.yml, check out our [getting started guide](/references/lightdash-config-yml#getting-started-with-lightdashconfigyml) to learn how to create and set up this file.
</Info>

## What are parameters?

Parameters are variables that you can define once and reference in multiple places throughout your Lightdash project. They allow you to:
Expand Down
128 changes: 97 additions & 31 deletions references/lightdash-config-yml.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,78 @@ description: 'The lightdash.config.yml file allows you to configure project-wide
sidebarTitle: "lightdash.config.yml"
---

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.

<Info>
The `lightdash.config.yml` file is not supported when your project is connected to dbt Cloud.
</Info>
## 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.

<Warning>
`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).
</Warning>


## 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](/guides/metrics-catalog)** 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](/get-started/setup-lightdash/intro))
2. ✅ A local dbt project (not connected to dbt Cloud)
3. ✅ The [Lightdash CLI](/get-started/setup-lightdash/get-project-lightdash-ready#step-1-install-the-lightdash-cli-tool) installed and configured


<Steps>
<Step title="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.

```bash
# Navigate to your dbt project directory
cd /path/to/your/dbt/project

# Create the config file
touch lightdash.config.yml
```
</Step>
<Step title="Add your first configuration">
Start with a simple configuration. Here's a basic example that sets up Spotlight categories:

```yaml
# Basic lightdash.config.yml example
spotlight:
default_visibility: "show"
categories:
finance:
label: "Finance"
color: "green"
marketing:
label: "Marketing"
color: "blue"
```
</Step>
<Step title="Deploy your changes">
After creating or updating your `lightdash.config.yml` file, deploy the changes to your Lightdash project:

```bash
lightdash deploy
```

That's it! Your configuration is now active in your Lightdash project.
</Step>
</Steps>




## Configuration options

Expand All @@ -24,6 +91,7 @@ parameters:
# ...
```


## Spotlight configuration

The `spotlight` section allows you to configure project-wide spotlight settings. This section is required in the lightdash.config.yml file.
Expand All @@ -40,23 +108,20 @@ spotlight:
color: "blue"
```

| Property | Required | Value | Description |
| :------- | :------- | :---- | :---------- |
| default_visibility | No | string enum: "show" or "hide" | The default visibility of spotlight metrics. Defaults to `"show"`. |
| categories | No | Object | Define the categories that can be used in Spotlight on your model yml files. |
| 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". |
| 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

<Warning>
Parameters are an **experimental** feature. See our [Feature Maturity Levels](/references/feature-maturity-levels) documentation to understand what this means.
</Warning>
## Parameters configuration

The `parameters` section allows you to define project-wide parameters that can be referenced in various parts of your Lightdash project.

Expand All @@ -81,36 +146,37 @@ parameters:

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

```sql
```yaml
${lightdash.parameters.region}
```

Or using the shorter alias:

```sql
```yaml
${ld.parameters.region}
```

Expand Down