Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 47ede2e

Browse files
authored
Merge pull request #115 from lightdash/docs/parameters
docs: parameters
2 parents 78c0af6 + ee04177 commit 47ede2e

File tree

3 files changed

+358
-0
lines changed

3 files changed

+358
-0
lines changed

‎docs.json

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,7 @@
125125
"references/virtual-views",
126126
"references/dbt-write-back",
127127
"references/dashboards-as-code",
128+
"guides/using-parameters",
128129
"guides/filtering-dashboard-in-url",
129130
"guides/vs-code-yaml-validation",
130131
"guides/renaming-models-and-fields"
@@ -139,6 +140,7 @@
139140
"references/joins",
140141
"references/lightdash-cli",
141142
"references/caching",
143+
"references/lightdash-config-yml",
142144
"references/sql-variables",
143145
"references/feature-maturity-levels"
144146
]

‎guides/using-parameters.mdx

Lines changed: 239 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,239 @@
1+
---
2+
title: "How to use parameters"
3+
---
4+
5+
<Warning>
6+
Parameters are an **experimental** feature. See our [Feature Maturity Levels](/references/feature-maturity-levels) documentation to understand what this means.
7+
</Warning>
8+
9+
<Info>
10+
Parameters are defined in the `lightdash.config.yml` file, which is not supported when your project is connected to dbt Cloud.
11+
</Info>
12+
13+
**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.
14+
15+
Parameters are defined in your `lightdash.config.yml` file and can be referenced in various parts of your Lightdash project.
16+
17+
## What are parameters?
18+
19+
Parameters are variables that you can define once and reference in multiple places throughout your Lightdash project. They allow you to:
20+
21+
- Create dynamic filters that users can change at runtime
22+
- Make your SQL more reusable and maintainable
23+
- Allow non-technical users to customize queries without writing SQL
24+
- Save parameter values at the chart and dashboard level
25+
26+
For example, you might define a `region` parameter that users can set to filter data by different geographic regions, or a `date_range` parameter that allows users to select different time periods for analysis.
27+
28+
## Where can you reference parameters?
29+
30+
Parameters can be referenced in many places throughout your Lightdash project:
31+
32+
1. **Dimension SQL**: Use parameters in the SQL definition of a dimension
33+
2. **Metric SQL**: Use parameters in the SQL definition of a metric
34+
3. **Table SQL**: Use parameters in the SQL definition of a table
35+
4. **Table SQL_ON**: Use parameters in the SQL_ON clause of a table join
36+
5. **Table Join**: Use parameters in join conditions
37+
6. **SQL Runner**: Use parameters in custom SQL queries
38+
7. **Table Calculations**: Use parameters in table calculations
39+
8. **Additional Dimensions**: Use parameters in the SQL definition of an additional dimension
40+
9. **Custom Dimensions**: Use parameters in custom dimension definitions
41+
42+
## How to reference parameters in SQL
43+
44+
To reference parameters in SQL, use the following syntax:
45+
46+
```sql
47+
${lightdash.parameters.parameter_name}
48+
```
49+
50+
For example, to reference a parameter named `region`:
51+
52+
```sql
53+
${lightdash.parameters.region}
54+
```
55+
56+
You can also use the shorter alias:
57+
58+
```sql
59+
${ld.parameters.parameter_name}
60+
```
61+
62+
For example:
63+
64+
```sql
65+
${ld.parameters.region}
66+
```
67+
68+
Both syntaxes are equivalent and can be used interchangeably.
69+
70+
## How to define parameters
71+
72+
Parameters are defined in your `lightdash.config.yml` file. Here's an example of how to define parameters:
73+
74+
```yaml
75+
parameters:
76+
# Parameter with simple options list
77+
date_range:
78+
label: "Date Range"
79+
description: "Filter data by date range"
80+
options:
81+
- "2023年01月01日"
82+
- "2022年01月01日"
83+
- "2021年01月01日"
84+
default: "2023年01月01日"
85+
86+
# Parameter with multiple selection enabled
87+
region:
88+
label: "Region"
89+
description: "Filter data by region"
90+
options:
91+
- "EMEA"
92+
- "AMER"
93+
- "APAC"
94+
default: ["EMEA", "AMER"]
95+
multiple: true
96+
97+
# Parameter with options from a dimension
98+
department:
99+
label: "Department"
100+
description: "Filter data by department"
101+
options_from_dimension:
102+
model: "employees"
103+
dimension: "department"
104+
```
105+
106+
For a complete reference of parameter properties and options, see the [lightdash.config.yml reference](/references/lightdash-config-yml#parameters-configuration).
107+
108+
## Examples of using parameters
109+
110+
Let's look at some examples of how to use parameters in different parts of your Lightdash project.
111+
112+
### Example 1: Using parameters in dimension SQL
113+
114+
You can reference parameters in the SQL definition of a dimension:
115+
116+
```yaml
117+
models:
118+
- name: orders
119+
columns:
120+
- name: filtered_revenue
121+
meta:
122+
dimension:
123+
type: number
124+
sql: |
125+
CASE
126+
WHEN ${TABLE}.region IN (${lightdash.parameters.region})
127+
THEN ${TABLE}.revenue
128+
ELSE 0
129+
END
130+
```
131+
132+
In this example, the `filtered_revenue` dimension will only show revenue for the regions selected in the `region` parameter.
133+
134+
### Example 2: Using parameters in table joins
135+
136+
You can use parameters in the SQL_ON clause of a table join:
137+
138+
```yaml
139+
models:
140+
- name: orders
141+
meta:
142+
joins:
143+
- join: customers
144+
sql_on: |
145+
${orders.customer_id} = ${customers.id}
146+
AND ${customers.region} IN (${lightdash.parameters.region})
147+
```
148+
149+
This join will only include customers from the regions selected in the `region` parameter.
150+
151+
### Example 3: Using parameters in table calculations
152+
153+
You can reference parameters in table calculations:
154+
155+
```sql
156+
-- Table calculation example
157+
CASE
158+
WHEN ${orders.order_date} >= '${lightdash.parameters.date_range}'
159+
THEN ${orders.revenue}
160+
ELSE 0
161+
END
162+
```
163+
164+
This table calculation will only include revenue for orders placed on or after the date selected in the `date_range` parameter.
165+
166+
### Example 4: Using parameters in additional dimensions
167+
168+
You can use parameters in custom dimension definitions:
169+
170+
```yaml
171+
models:
172+
- name: orders
173+
columns:
174+
- name: order_date
175+
meta:
176+
dimension:
177+
type: date
178+
additional_dimensions:
179+
is_after_cutoff_date:
180+
type: boolean
181+
sql: ${order_date} >= '${lightdash.parameters.date_range}'
182+
```
183+
184+
This additional dimension will indicate whether an order was placed on or after the date selected in the `date_range` parameter.
185+
186+
## Example 5: Using parameters in SQL Runner
187+
188+
Parameters can also be used in SQL Runner queries:
189+
190+
```sql
191+
SELECT
192+
order_id,
193+
order_date,
194+
revenue
195+
FROM orders
196+
WHERE region IN (${lightdash.parameters.region})
197+
AND order_date >= '${lightdash.parameters.date_range}'
198+
```
199+
200+
This query will filter orders by the regions selected in the `region` parameter and by the date selected in the `date_range` parameter.
201+
202+
## Saving parameter values at chart and dashboard levels
203+
204+
Parameter values can be saved at both the chart and dashboard levels.
205+
206+
### Saving parameter values in charts
207+
208+
When you create a chart using parameters, you can save the specific parameter values with the chart. This means that when someone views the chart, they'll see the data filtered according to the saved parameter values.
209+
210+
To save parameter values with a chart:
211+
212+
1. Create or edit a chart
213+
2. Set the parameter values as desired
214+
3. Save the chart
215+
216+
The parameter values will be saved with the chart and will be applied whenever the chart is viewed.
217+
218+
### Saving parameter values in dashboards
219+
220+
You can also save parameter values at the dashboard level, which allows you to create dashboards with consistent parameter values across all charts.
221+
222+
To save parameter values in a dashboard:
223+
224+
1. Create or edit a dashboard
225+
2. Add charts to the dashboard
226+
3. Set the parameter values as desired
227+
4. Save the dashboard
228+
229+
The parameter values will be saved with the dashboard and will be applied to all charts on the dashboard that have parameterized fields.
230+
231+
## Best practices for using parameters
232+
233+
Here are some best practices to follow when using parameters:
234+
235+
1. **Use descriptive names**: Choose parameter names that clearly indicate their purpose
236+
2. **Provide default values**: Set default values for parameters to ensure queries work even if users don't set parameter values
237+
3. **Add descriptions**: Include clear descriptions for parameters to help users understand their purpose
238+
4. **Consider using options_from_dimension**: For parameters that should match values in your data, use `options_from_dimension` to dynamically populate options
239+
5. **Consider performance**: Be mindful of how parameters affect query performance, especially with large datasets

‎references/lightdash-config-yml.mdx

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
---
2+
title: "lightdash.config.yml reference"
3+
description: 'The lightdash.config.yml file allows you to configure project-wide settings for your Lightdash project, including spotlight and parameters.'
4+
sidebarTitle: "lightdash.config.yml"
5+
---
6+
7+
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.
8+
9+
<Info>
10+
The `lightdash.config.yml` file is not supported when your project is connected to dbt Cloud.
11+
</Info>
12+
13+
## Configuration options
14+
15+
The `lightdash.config.yml` file supports the following top-level configuration options:
16+
17+
```yaml
18+
# Configuration for project-wide spotlight settings
19+
spotlight:
20+
# ...
21+
22+
# Configuration for project-wide parameters
23+
parameters:
24+
# ...
25+
```
26+
27+
## Spotlight configuration
28+
29+
The `spotlight` section allows you to configure project-wide spotlight settings. This section is required in the lightdash.config.yml file.
30+
31+
```yaml
32+
spotlight:
33+
default_visibility: "show"
34+
categories:
35+
finance:
36+
label: "Finance"
37+
color: "green"
38+
user_engagement:
39+
label: "User Engagement"
40+
color: "blue"
41+
```
42+
43+
| Property | Required | Value | Description |
44+
| :------- | :------- | :---- | :---------- |
45+
| default_visibility | No | string enum: "show" or "hide" | The default visibility of spotlight metrics. Defaults to `"show"`. |
46+
| categories | No | Object | Define the categories that can be used in Spotlight on your model yml files. |
47+
48+
Each category in the `categories` object requires the following properties:
49+
50+
| Property | Required | Value | Description |
51+
| :------- | :------- | :---- | :---------- |
52+
| label | Yes | string | The label of the category as it will be displayed in Spotlight. |
53+
| 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". |
54+
55+
## Parameters configuration
56+
57+
<Warning>
58+
Parameters are an **experimental** feature. See our [Feature Maturity Levels](/references/feature-maturity-levels) documentation to understand what this means.
59+
</Warning>
60+
61+
The `parameters` section allows you to define project-wide parameters that can be referenced in various parts of your Lightdash project.
62+
63+
```yaml
64+
parameters:
65+
region:
66+
label: "Region"
67+
description: "Filter data by region"
68+
options:
69+
- "EMEA"
70+
- "AMER"
71+
- "APAC"
72+
default: ["EMEA", "AMER"]
73+
multiple: true
74+
department:
75+
label: "Department"
76+
description: "Filter data by department"
77+
options_from_dimension:
78+
model: "employees"
79+
dimension: "department"
80+
```
81+
82+
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:
83+
84+
| Property | Required | Value | Description |
85+
| :------- | :------- | :---- | :---------- |
86+
| label | Yes | string | A user-friendly label for the parameter as it will be displayed in the UI. |
87+
| description | No | string | A description of the parameter. |
88+
| options | No | Array of strings | A list of possible values for the parameter. |
89+
| default | No | string or Array of strings | The default value(s) for the parameter. |
90+
| multiple | No | boolean | Whether the parameter input will be a multi-select. |
91+
| allow_custom_values | No | boolean | Whether users can input custom values beyond predefined options. |
92+
| options_from_dimension | No | Object | Get parameter options from a dimension in a model. |
93+
94+
If using `options_from_dimension`, the object requires the following properties:
95+
96+
| Property | Required | Value | Description |
97+
| :------- | :------- | :---- | :---------- |
98+
| model | Yes | string | The model containing the dimension. |
99+
| dimension | Yes | string | The dimension to get options from. |
100+
101+
### Using parameters in your project
102+
103+
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}`.
104+
105+
For example, to reference a parameter named `region`:
106+
107+
```sql
108+
${lightdash.parameters.region}
109+
```
110+
111+
Or using the shorter alias:
112+
113+
```sql
114+
${ld.parameters.region}
115+
```
116+
117+
See the [Parameters guide](/guides/using-parameters) for more information on how to use parameters.

0 commit comments

Comments
(0)

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