diff --git a/guides/period-over-period.mdx b/guides/period-over-period.mdx index 732cc3c..9d501ce 100644 --- a/guides/period-over-period.mdx +++ b/guides/period-over-period.mdx @@ -340,4 +340,84 @@ To do this, you: You can then add this chart to a dashboard. Users can select an option from the `Date Range` parameter and the charts will automatically update to display the selected period. - Take a look at our example dashboard in our demo site [here](https://demo.lightdash.com/projects/2014e038-ff4b-4761-ae6f-fbf551e7b468/dashboards/8813b2bf-3983-48b0-aff7-088b59490cfa/view). \ No newline at end of file + Take a look at our example dashboard in our demo site [here](https://demo.lightdash.com/projects/2014e038-ff4b-4761-ae6f-fbf551e7b468/dashboards/8813b2bf-3983-48b0-aff7-088b59490cfa/view). + + +### Custom date range example + +Similar to above, you can also set up a custom date range parameter that allows users to select specific start and end dates for their analysis. + +Below is the code needed for the parameter and the additional dimension to categorize the date periods for a custom date range: + + +``` yaml +parameters: + custom_range_start: + label: "Start of custom date range" + description: "The start of the custom date range" + type: date + custom_range_end: + label: "End of custom date range" + description: "The end of the custom date range" + type: date +``` + + + + +``` yaml +- name: order_date + description: 'Date of order placement by user.' + meta: + dimension: + type: date + additional_dimensions: + order_date_custom_period: + description: Date period bucket based on custom Start date and End date parameters + type: string + sql: | + case + --invalid date range + when ${lightdash.parameters.dbt_orders.custom_range_start} is null + or ${lightdash.parameters.dbt_orders.custom_range_end} is null + or ${lightdash.parameters.dbt_orders.custom_range_start} > ${lightdash.parameters.dbt_orders.custom_range_end} + then 'invalid date range' + + --current period + when ${order_date_day} >= ${lightdash.parameters.dbt_orders.custom_range_start} + and ${order_date_day} <= ${lightdash.parameters.dbt_orders.custom_range_end} + then 'current period' + + --previous period + when ${order_date_day} between date_sub( + ${lightdash.parameters.dbt_orders.custom_range_start}, + interval (date_diff( + ${lightdash.parameters.dbt_orders.custom_range_end}, + ${lightdash.parameters.dbt_orders.custom_range_start}, + day + ) + 1) day + ) and date_sub( + ${lightdash.parameters.dbt_orders.custom_range_end}, + interval (date_diff( + ${lightdash.parameters.dbt_orders.custom_range_end}, + ${lightdash.parameters.dbt_orders.custom_range_start}, + day + ) + 1) day + ) + then 'previous period' + + --previous year + when date(${order_date_day}) between date_sub(${lightdash.parameters.dbt_orders.custom_range_start}, interval 1 year) + and date_sub(${lightdash.parameters.dbt_orders.custom_range_end}, interval 1 year) + then 'previous year' + + else 'out of range' + end +``` + + +The code examples above will give you the following parameter options in the Lightdash UI that will output the custom period labels shown in the chart: + + + + diff --git a/guides/using-parameters.mdx b/guides/using-parameters.mdx index b6c43f5..962182d 100644 --- a/guides/using-parameters.mdx +++ b/guides/using-parameters.mdx @@ -5,7 +5,7 @@ sidebarTitle: Parameters **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. +Parameters are defined in your `lightdash.config.yml` file or in a `schema.yml` file for a specific model, 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. @@ -28,7 +28,7 @@ Parameters are variables that you can define once and reference in multiple plac For example, you might define a `region` parameter that users can set to filter data by different geographic regions, a `date_range` parameter that allows users to select different time periods for analysis, or a `min_revenue` parameter with numeric values that allows users to set revenue thresholds for analysis. - **Parameter Types**: Parameters support both string and number values. You can use strings (like `"EMEA"` or `"2023-01-01"`) or numbers (like `1000` or `5000`) as parameter options. + **Parameter Types**: Parameters support string, date, and number values. You can use strings (like `"EMEA"`) or numbers (like `1000`) or dates (date parameters will show a calendar picker) as parameter options. @@ -45,6 +45,7 @@ Parameters can be referenced in many places throughout your Lightdash project: 7. **Additional Dimensions**: Use parameters in the SQL definition of an [additional dimension](/references/dimensions#additional-dimensions) 8. **Custom Dimensions**: Use parameters in [custom dimension](/references/custom-fields#custom-sql) definitions + ## Parameter types Parameters in Lightdash support different data types to help you work with various kinds of data. By default, all parameters are treated as strings, but you can convert them to other types as needed. @@ -55,6 +56,8 @@ Lightdash officially supports the following parameter types: - **String** (default): Text values - **Number**: Numeric values (integers and decimals) +- **Date**: Date values (date selector is shown in the UI) + ### Type conversion workarounds @@ -69,17 +72,6 @@ ${lightdash.parameters.parameter_name}::type The type conversion happens at the SQL level, so the available types depend on your database system (PostgreSQL, BigQuery, Snowflake, etc.). Common types like `integer`, `numeric`, `date`, `timestamp`, and `boolean` are supported across most databases. -#### Date conversion - -As a workaround, you can use `::date` for dates or `::timestamp` for datetime values: - -```sql --- Convert to date (workaround) -WHERE ${TABLE}.order_date >= ${lightdash.parameters.start_date}::date - --- Convert to timestamp (workaround) -WHERE ${TABLE}.created_at >= ${lightdash.parameters.start_datetime}::timestamp -``` #### Boolean conversion @@ -100,6 +92,7 @@ WHERE ${TABLE}.category_id = ${lightdash.parameters.category}::uuid WHERE ${TABLE}.amount = ${lightdash.parameters.amount}::decimal(10,2) ``` + ## How to reference parameters in SQL ### Project-level parameters @@ -116,6 +109,7 @@ For example, to reference a parameter named `region`: ${lightdash.parameters.region} ``` + ### Model-level parameters To reference model-level parameters in SQL, you need to include the model name: @@ -130,6 +124,7 @@ For example, to reference a parameter named `region` from the `orders` model: ${lightdash.parameters.orders.region} ``` + ### Using the shorter alias You can also use the shorter alias `ld` instead of `lightdash`: @@ -152,10 +147,12 @@ ${ld.parameters.region} ${ld.parameters.orders.region} ``` + ## 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: @@ -163,14 +160,14 @@ Project-level parameters are defined in your `lightdash.config.yml` file and are ```yaml parameters: # Parameter with simple options list - date_range: - label: "Date Range" - description: "Filter data by date range" + team: + label: "Team" + description: "Filter data by team" options: - - "2023-01-01" - - "2022-01-01" - - "2021-01-01" - default: "2023-01-01" + - "Sales" + - "Marketing" + - "Finance" + default: "Sales" # Parameter with multiple selection enabled region: @@ -193,7 +190,13 @@ parameters: - 5000 - 10000 default: 5000 - + + # Parameter with date type + min_date: + label: "Minimum date" + description: "Filter to only show data after this date" + type: "date" + # Parameter with options from a dimension department: label: "Department" @@ -205,6 +208,7 @@ parameters: 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: @@ -214,14 +218,14 @@ 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" + date_range_start: + label: "Date Range Start" + description: "Start date for filtering orders in custom time period metrics" + type: "date" + date_range_end: + label: "Date Range End" + description: "End date for filtering orders in custom time period metrics" + type: "date" ``` 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. @@ -337,7 +341,7 @@ You can reference parameters in table calculations: ```sql -- Table calculation example CASE - WHEN ${orders.order_date} >= ${lightdash.parameters.date_range} + WHEN ${orders.order_date} >= ${lightdash.parameters.date_range_start} THEN ${orders.revenue} ELSE 0 END @@ -361,7 +365,7 @@ models: additional_dimensions: is_after_cutoff_date: type: boolean - sql: ${order_date} >= ${lightdash.parameters.date_range} + sql: ${order_date} >= ${lightdash.parameters.date_range_start} ``` This additional dimension will indicate whether an order was placed on or after the date selected in the `date_range` parameter. @@ -378,12 +382,13 @@ SELECT revenue FROM orders WHERE region IN (${lightdash.parameters.region}) - AND order_date >= ${lightdash.parameters.date_range} + AND order_date >= ${lightdash.parameters.date_range_start} AND revenue >= ${lightdash.parameters.min_revenue} ``` This query will filter orders by the regions selected in the `region` parameter, by the date selected in the `date_range` parameter, and by orders with revenue greater than or equal to the numeric `min_revenue` parameter. + ### 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: diff --git a/images/guides/custom_range_pop.png b/images/guides/custom_range_pop.png new file mode 100644 index 0000000..4453cf8 Binary files /dev/null and b/images/guides/custom_range_pop.png differ diff --git a/references/lightdash-config-yml.mdx b/references/lightdash-config-yml.mdx index aa13924..76d8c3e 100644 --- a/references/lightdash-config-yml.mdx +++ b/references/lightdash-config-yml.mdx @@ -145,7 +145,15 @@ parameters: - 5000 - 10000 default: 5000 - department: + custom_date_range_start: + label: "Custom date range - start" + description: "The start date for a custom date range filter" + type: "date" +custom_date_range_end: + label: "Custom date range - end" + description: "The end date for a custom date range filter" + type: "date" +department: label: "Department" description: "Filter data by department" options_from_dimension: @@ -159,7 +167,7 @@ Each parameter is defined as a key-value pair where the key is the parameter nam | :----------------------- | :------- | :------------------------- | :---------- | | `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. | -| `type` | No | "string" or "number" | The type of the parameter. Defaults to "string" if not specified. | +| `type` | No | "string", "number", or "date" | The type of the parameter. Defaults to "string" if not specified. | | `options` | No | Array of strings or numbers | A list of possible values for the parameter. | | `default` | No | string, number, or Array of strings/numbers | The default value(s) for the parameter. | | `multiple` | No | boolean | Whether the parameter input will be a multi-select. |