You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
@@ -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 DownExpand 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)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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:
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
@@ -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. |
| `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". |
| `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. |
| `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
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.