From 90eb0164efd99511ad61d9a0a996edbf438ae2f4 Mon Sep 17 00:00:00 2001 From: almeidabbm Date: Thu, 14 Aug 2025 11:49:06 +0100 Subject: [PATCH 1/4] chore: add docs for model level parameters --- guides/using-parameters.mdx | 31 +++++++++++++++-- references/tables.mdx | 66 ++++++++++++++++++++++++++++++++++++- 2 files changed, 94 insertions(+), 3 deletions(-) diff --git a/guides/using-parameters.mdx b/guides/using-parameters.mdx index 6853a42..2db900c 100644 --- a/guides/using-parameters.mdx +++ b/guides/using-parameters.mdx @@ -64,7 +64,11 @@ Both syntaxes are equivalent and can be used interchangeably. ## How to define parameters -Parameters are defined in your `lightdash.config.yml` file. Here's an example of how to define parameters: +Parameters can be defined at two different levels in your Lightdash project: + +### Project-level parameters + +Project-level parameters are defined in your `lightdash.config.yml` file and are available across your entire project. Here's an example: ```yaml parameters: @@ -98,7 +102,30 @@ parameters: dimension: "department" ``` -For a complete reference of parameter properties and options, see the [lightdash.config.yml reference](/references/lightdash-config-yml#parameters-configuration). +For a complete reference of project-level parameter properties and options, see the [lightdash.config.yml reference](/references/lightdash-config-yml#parameters-configuration). + +### Model-level parameters + +Model-level parameters are defined within individual model YAML files in your dbt project and are scoped to the model where they are defined. These parameters are defined in the `meta.parameters` section of your model configuration: + +```yaml +models: + - name: orders + meta: + parameters: + date_range: + label: "Date Range" + description: "Filter data by date range" + options: + - "2023-01-01" + - "2022-01-01" + - "2021-01-01" + default: "2023-01-01" +``` + +Model-level parameters offer the same configuration options as project-level parameters but provide better encapsulation and organization by keeping parameters close to where they're used. + +For a complete reference of model-level parameter properties and options, see the [tables reference](/references/tables#parameters-configuration). ## Examples of using parameters diff --git a/references/tables.mdx b/references/tables.mdx index 8a92b58..f4e368b 100644 --- a/references/tables.mdx +++ b/references/tables.mdx @@ -70,7 +70,8 @@ models: | [required_attributes](#required-attributes) | object | Limits access to users with those attributes. [Read about user attributes](/references/user-attributes) | | group_details | object | Describes the groups for dimensions and metrics | | [default_filters](#default-filters) | array | Dimension filters that will be applied when no other filter on those dimension exists. [Read about `default_filters`](#default-filters) | -| [explores](#explores) | object | Allows you to define multiple table explores in Lightdash from a single dbt model. +| [explores](#explores) | object | Allows you to define multiple table explores in Lightdash from a single dbt model. | +| [parameters](#parameters-configuration) | object | Model-level parameters that can be referenced in SQL queries. [Read about parameters](#parameters-configuration) | ### Adding a new dbt model @@ -338,6 +339,69 @@ Using a properly defined primary key helps Lightdash optimize queries and provid | is [boolean] | Is complete is true | is_complete: "true" | | is not [boolean] | Is complete is false or null | is_complete: "\!true" | +## Parameters configuration + +The `parameters` section allows you to define model-level parameters that can be referenced in various parts of your model's SQL queries. These parameters are scoped to the specific model where they're defined. + +```yaml +models: + - name: orders + meta: + 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 model-level parameters + +Model-level parameters can be referenced in your model's SQL using the syntax `${lightdash.parameters.parameter_name}` or the shorter alias `${ld.parameters.parameter_name}`. + +For example, to reference a parameter named `region` in a dimension: + +```yaml +${lightdash.parameters.region} +``` + +Or using the shorter alias: + +```yaml +${ld.parameters.region} +``` + +See the [Parameters guide](/guides/using-parameters) for more examples and information on how to use parameters. + ## Explores You can define multiple table explores from a single table using the `explores` config. This will allow you to list the same dbt model multiple times in the list of Tables in Lightdash. You can use it to show different versions of a table, join different tables to the base table, customize table visibility, etc. From 764e90758dbb6b88cb9babd28dbc5e8b1dc30a5c Mon Sep 17 00:00:00 2001 From: Bruno Almeida Date: Thu, 14 Aug 2025 14:46:16 +0100 Subject: [PATCH 2/4] Apply suggestion from @ZeRego Co-authored-by: Jose Rego --- references/tables.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/references/tables.mdx b/references/tables.mdx index f4e368b..16b7e78 100644 --- a/references/tables.mdx +++ b/references/tables.mdx @@ -71,7 +71,7 @@ models: | group_details | object | Describes the groups for dimensions and metrics | | [default_filters](#default-filters) | array | Dimension filters that will be applied when no other filter on those dimension exists. [Read about `default_filters`](#default-filters) | | [explores](#explores) | object | Allows you to define multiple table explores in Lightdash from a single dbt model. | -| [parameters](#parameters-configuration) | object | Model-level parameters that can be referenced in SQL queries. [Read about parameters](#parameters-configuration) | +| [parameters](#parameters-configuration) | object | Model-level parameters that can be referenced in SQL properties. [Read about parameters](#parameters-configuration) | ### Adding a new dbt model From 4156be27d3a75f9e9fd63e173532dcfbe8df1a2f Mon Sep 17 00:00:00 2001 From: Bruno Almeida Date: Thu, 14 Aug 2025 14:46:21 +0100 Subject: [PATCH 3/4] Apply suggestion from @ZeRego Co-authored-by: Jose Rego --- references/tables.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/references/tables.mdx b/references/tables.mdx index 16b7e78..44bfb68 100644 --- a/references/tables.mdx +++ b/references/tables.mdx @@ -341,7 +341,7 @@ Using a properly defined primary key helps Lightdash optimize queries and provid ## Parameters configuration -The `parameters` section allows you to define model-level parameters that can be referenced in various parts of your model's SQL queries. These parameters are scoped to the specific model where they're defined. +The `parameters` section allows you to define model-level parameters that can be referenced in various parts of your model's SQL properties. These parameters are scoped to the specific model where they're defined. ```yaml models: From a502e6c39f489c3b6b847712979393529213e105 Mon Sep 17 00:00:00 2001 From: almeidabbm Date: Tue, 19 Aug 2025 13:18:32 +0100 Subject: [PATCH 4/4] chore: add parameter examples for joined models --- guides/using-parameters.mdx | 79 +++++++++++++++++++++++++++++++++---- references/tables.mdx | 25 ++++++++++-- 2 files changed, 93 insertions(+), 11 deletions(-) diff --git a/guides/using-parameters.mdx b/guides/using-parameters.mdx index 2db900c..1d89d04 100644 --- a/guides/using-parameters.mdx +++ b/guides/using-parameters.mdx @@ -36,7 +36,9 @@ Parameters can be referenced in many places throughout your Lightdash project: ## How to reference parameters in SQL -To reference parameters in SQL, use the following syntax: +### Project-level parameters + +To reference project-level parameters in SQL, use the following syntax: ```sql ${lightdash.parameters.parameter_name} @@ -48,19 +50,41 @@ For example, to reference a parameter named `region`: ${lightdash.parameters.region} ``` -You can also use the shorter alias: +### Model-level parameters + +To reference model-level parameters in SQL, you need to include the model name: + +```sql +${lightdash.parameters.model_name.parameter_name} +``` + +For example, to reference a parameter named `region` from the `orders` model: + +```sql +${lightdash.parameters.orders.region} +``` + +### Using the shorter alias + +You can also use the shorter alias `ld` instead of `lightdash`: ```sql +# Project parameter ${ld.parameters.parameter_name} + +# Model parameter +${ld.parameters.model_name.parameter_name} ``` For example: ```sql +# Project parameter ${ld.parameters.region} -``` -Both syntaxes are equivalent and can be used interchangeably. +# Model parameter from orders model +${ld.parameters.orders.region} +``` ## How to define parameters @@ -155,7 +179,7 @@ In this example, the `filtered_revenue` dimension will only show revenue for the ### Example 2: Using parameters in table joins -You can use parameters in the SQL_ON clause of a table join: +You can use parameters in the SQL_ON clause of a table join. This includes both project-level parameters and model-level parameters from the joined table: ```yaml models: @@ -168,7 +192,22 @@ models: AND ${customers.region} IN (${lightdash.parameters.region}) ``` -This join will only include customers from the regions selected in the `region` parameter. +This join will only include customers from the regions selected in the project-level `region` parameter. + +You can also reference model-level parameters from joined tables: + +```yaml +models: + - name: orders + meta: + joins: + - join: customers + sql_on: | + ${orders.customer_id} = ${customers.customer_id} + AND ${customers.status} = ${lightdash.parameters.customers.customer_status} +``` + +In this example, the join uses a model-level parameter `customer_status` defined in the `customers` model. This allows you to dynamically filter the joined data based on parameters specific to the joined table. ### Example 3: Using parameters in table calculations @@ -205,7 +244,33 @@ models: This additional dimension will indicate whether an order was placed on or after the date selected in the `date_range` parameter. -## Example 5: Using parameters in SQL Runner +### Example 5: Using model parameters from joined tables in dimensions + +When working with joined tables, you can reference model-level parameters from the joined table in your dimension definitions: + +```yaml +models: + - name: orders + meta: + joins: + - join: customers + sql_on: ${orders.customer_id} = ${customers.id} + columns: + - name: filtered_customer_revenue + meta: + dimension: + type: number + sql: | + CASE + WHEN ${customers.segment} = ${lightdash.parameters.customers.target_segment} + THEN ${TABLE}.revenue + ELSE 0 + END +``` + +In this example, the `filtered_customer_revenue` dimension uses a model-level parameter `target_segment` from the joined `customers` model to conditionally show revenue. + +## Example 6: Using parameters in SQL Runner Parameters can also be used in SQL Runner queries: diff --git a/references/tables.mdx b/references/tables.mdx index 44bfb68..38e4278 100644 --- a/references/tables.mdx +++ b/references/tables.mdx @@ -386,20 +386,37 @@ If using `options_from_dimension`, the object requires the following properties: ### Using model-level parameters -Model-level parameters can be referenced in your model's SQL using the syntax `${lightdash.parameters.parameter_name}` or the shorter alias `${ld.parameters.parameter_name}`. +Model-level parameters are referenced with the model name included in the syntax: `${lightdash.parameters.model_name.parameter_name}` or the shorter alias `${ld.parameters.model_name.parameter_name}`. -For example, to reference a parameter named `region` in a dimension: +For example, to reference a parameter named `region` from the current model: ```yaml -${lightdash.parameters.region} +${lightdash.parameters.orders.region} ``` Or using the shorter alias: ```yaml -${ld.parameters.region} +${ld.parameters.orders.region} ``` +#### Using parameters from joined tables + +You can also reference model-level parameters from joined tables. This is particularly useful when you want to use parameters defined in one model while working in another: + +```yaml +models: + - name: orders + meta: + joins: + - join: customers + sql_on: | + ${orders.customer_id} = ${customers.customer_id} + AND ${customers.status} = ${ld.parameters.customers.customer_status} +``` + +In this example, the join condition references a model-level parameter `customer_status` that is defined in the `customers` model, even though we're configuring the `orders` model. + See the [Parameters guide](/guides/using-parameters) for more examples and information on how to use parameters. ## Explores