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 f9da232..cf1d313 100644 --- a/references/lightdash-config-yml.mdx +++ b/references/lightdash-config-yml.mdx @@ -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. - -The `lightdash.config.yml` file is not supported when your project is connected to dbt Cloud. - +## 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](/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 + + + + + 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 + ``` + + + 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" + ``` + + + 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 @@ -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. @@ -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 - -Parameters are an **experimental** feature. See our [Feature Maturity Levels](/references/feature-maturity-levels) documentation to understand what this means. - +## Parameters configuration The `parameters` section allows you to define project-wide parameters that can be referenced in various parts of your Lightdash project. @@ -81,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 @@ -104,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 によって変換されたページ (->オリジナル) /