From a85512c9b67806a3e0f8e0a1da0271e87473fc16 Mon Sep 17 00:00:00 2001 From: Jose Rego Date: 2025年8月11日 10:40:09 +0100 Subject: [PATCH 1/3] docs: getting started with lightdash.config.yml --- references/lightdash-config-yml.mdx | 69 +++++++++++++++++++++++++++-- 1 file changed, 65 insertions(+), 4 deletions(-) diff --git a/references/lightdash-config-yml.mdx b/references/lightdash-config-yml.mdx index f9da232..91cc569 100644 --- a/references/lightdash-config-yml.mdx +++ b/references/lightdash-config-yml.mdx @@ -4,11 +4,72 @@ 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. +## What is lightdash.config.yml? - -The `lightdash.config.yml` file is not supported when your project is connected to dbt Cloud. - +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. + + +The `lightdash.config.yml` file is **not supported** when your project is connected to dbt Cloud. This file only works with projects that use dbt Core (local dbt projects). + + +## 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** with custom categories and visibility settings (Spotlight feature) +- **Create dynamic parameters** that users can change to modify data across multiple charts and dashboards +- **Customize project-wide settings** beyond the default Lightdash behavior + +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 with lightdash.config.yml + +### Prerequisites + +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 + +### Step 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. + +```bash +# Navigate to your dbt project directory +cd /path/to/your/dbt/project + +# Create the config file +touch lightdash.config.yml +``` + +### Step 2: 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 3: 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. ## Configuration options From 58bc10cb763e5b9f8382d1302e36f9d58c29db24 Mon Sep 17 00:00:00 2001 From: Jose Rego Date: 2025年8月11日 10:48:45 +0100 Subject: [PATCH 2/3] docs: notes and warnings --- guides/metrics-catalog.mdx | 7 ++++++- guides/using-parameters.mdx | 12 ++++-------- references/lightdash-config-yml.mdx | 4 ---- 3 files changed, 10 insertions(+), 13 deletions(-) diff --git a/guides/metrics-catalog.mdx b/guides/metrics-catalog.mdx index 9ff3de8..e9030e7 100644 --- a/guides/metrics-catalog.mdx +++ b/guides/metrics-catalog.mdx @@ -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. + + 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. + + See this video for an example on how to set this up:
- Parameters are an **experimental** feature. See our [Feature Maturity Levels](/references/feature-maturity-levels) documentation to understand what this means. - - - - Parameters are defined in the `lightdash.config.yml` file, which is not supported when your project is connected to dbt Cloud. - - **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. + + 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. + + ## What are parameters? Parameters are variables that you can define once and reference in multiple places throughout your Lightdash project. They allow you to: diff --git a/references/lightdash-config-yml.mdx b/references/lightdash-config-yml.mdx index 91cc569..e7b95a3 100644 --- a/references/lightdash-config-yml.mdx +++ b/references/lightdash-config-yml.mdx @@ -115,10 +115,6 @@ Each category in the `categories` object requires the following properties: ## Parameters configuration - -Parameters are an **experimental** feature. See our [Feature Maturity Levels](/references/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. ```yaml From 1d8af3cfd48a20664dd40b08feccf6334b3102a5 Mon Sep 17 00:00:00 2001 From: Jake Peterson Date: 2025年8月11日 14:39:03 -0500 Subject: [PATCH 3/3] small cleanup changes --- references/lightdash-config-yml.mdx | 125 +++++++++++++++------------- 1 file changed, 67 insertions(+), 58 deletions(-) diff --git a/references/lightdash-config-yml.mdx b/references/lightdash-config-yml.mdx index e7b95a3..cf1d313 100644 --- a/references/lightdash-config-yml.mdx +++ b/references/lightdash-config-yml.mdx @@ -4,27 +4,29 @@ description: 'The lightdash.config.yml file allows you to configure project-wide sidebarTitle: "lightdash.config.yml" --- + ## 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. -The `lightdash.config.yml` file is **not supported** when your project is connected to dbt Cloud. This file only works with projects that use dbt Core (local dbt projects). + `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** with custom categories and visibility settings (Spotlight feature) -- **Create dynamic parameters** that users can change to modify data across multiple charts and dashboards -- **Customize project-wide settings** beyond the default Lightdash behavior +- **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 with lightdash.config.yml -### Prerequisites +## Getting started Before creating a `lightdash.config.yml` file, make sure you have: @@ -32,44 +34,48 @@ Before creating a `lightdash.config.yml` file, make sure you have: 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 -### Step 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. + + + 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 + ```bash + # Navigate to your dbt project directory + cd /path/to/your/dbt/project -# Create the config file -touch lightdash.config.yml -``` + # Create the config file + touch lightdash.config.yml + ``` + + + Start with a simple configuration. Here's a basic example that sets up Spotlight categories: -### Step 2: Add your first configuration + ```yaml + # Basic lightdash.config.yml example + spotlight: + default_visibility: "show" + categories: + finance: + label: "Finance" + color: "green" + marketing: + label: "Marketing" + color: "blue" + ``` + + + After creating or updating your `lightdash.config.yml` file, deploy the changes to your Lightdash project: -Start with a simple configuration. Here's a basic example that sets up Spotlight categories: + ```bash + lightdash deploy + ``` -```yaml -# Basic lightdash.config.yml example -spotlight: - default_visibility: "show" - categories: - finance: - label: "Finance" - color: "green" - marketing: - label: "Marketing" - color: "blue" -``` + That's it! Your configuration is now active in your Lightdash project. + + -### Step 3: 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. ## Configuration options @@ -85,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. @@ -101,17 +108,18 @@ 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 @@ -138,22 +146,23 @@ 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 @@ -161,13 +170,13 @@ Parameters defined in the `lightdash.config.yml` file can be referenced in vario For example, to reference a parameter named `region`: -```sql +```yaml ${lightdash.parameters.region} ``` Or using the shorter alias: -```sql +```yaml ${ld.parameters.region} ```

AltStyle によって変換されたページ (->オリジナル) /