add date params to docs (#264)

Author: jpetey75

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). 
+   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:
+
+<Accordion title="Custom date range parameter configuration">
+``` 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
+```
+</Accordion>
+
+
+<Accordion title="Custom date range additional dimension code">
+``` 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
+```
+</Accordion>
+
+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:
+
+<Frame>
+  <img src="/images/guides/custom_range_pop.png" alt=""/>
+</Frame>

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.
 
 <Info>
   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.
 
 <Info>
-  **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.
 </Info>
 
 
@@ -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.
 </Note>
 
-#### 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,25 +147,27 @@ ${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:
 
 ```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:

images/guides/custom_range_pop.png

@@ -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. |