Skip to main content
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 to learn how to create and set up this file.
Watch this video to see Parameters in action! You can also try it out in our live demo.

​
What are parameters?

Parameters are variables that you can define once and reference in multiple places throughout your Lightdash project. They allow you to:
  • Create dynamic filters that users can change at runtime
  • Make your SQL more reusable and maintainable
  • Allow non-technical users to customize queries without writing SQL
  • Save parameter values at the chart and dashboard level
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.

​
Where can you use parameters?

Parameters can be referenced in many places throughout your Lightdash project:
  1. Dimension SQL: Use parameters in the SQL definition of a dimension
  2. Metric SQL: Use parameters in the SQL definition of a metric
  3. Table SQL: Use parameters in sql_from and sql_filter definitions
  4. Table Joins: Use parameters in join conditions
  5. SQL Runner: Use parameters in the SQL Runner query
  6. Table Calculations: Use parameters in table calculations
  7. Additional Dimensions: Use parameters in the SQL definition of an additional dimension
  8. Custom Dimensions: Use parameters in custom dimension 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.

​
Supported parameter types

Lightdash officially supports the following parameter types:
  • String (default): Text values
  • Number: Numeric values (integers and decimals)

​
Type conversion workarounds

While not officially supported yet, you can work around for other data types via SQL type casting. To convert a parameter to a specific type, use the :: syntax followed by the type name: 
${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: 
-- 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

As a workaround, you can use ::boolean to convert string values like “true”/“false” to boolean: 
-- Convert to boolean (workaround)
WHERE ${TABLE}.is_active = ${lightdash.parameters.active_only}::boolean

​
Other type conversions

You can use any SQL type conversion that your database supports: 
-- Convert to specific database types
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

To reference project-level parameters in SQL, use the following syntax: 
${lightdash.parameters.parameter_name}
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: 
${lightdash.parameters.model_name.parameter_name}
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: 
# Project parameter
${ld.parameters.parameter_name}

# Model parameter
${ld.parameters.model_name.parameter_name}
For example: 
# Project parameter
${ld.parameters.region}

# Model parameter from orders model
${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: 
parameters:
  # Parameter with simple options list
  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"
  
  # Parameter with multiple selection enabled
  region:
    label: "Region"
    description: "Filter data by region"
    options:
      - "EMEA"
      - "AMER"
      - "APAC"
    default: ["EMEA", "AMER"]
    multiple: true
  
  # Parameter with number type
  min_revenue:
    label: "Minimum Revenue"
    description: "Filter for minimum revenue threshold"
    type: "number"
    options:
      - 1000
      - 5000
      - 10000
    default: 5000
  
  # Parameter with options from a dimension
  department:
    label: "Department"
    description: "Filter data by department"
    options_from_dimension:
      model: "employees"
      dimension: "department"
For a complete reference of project-level parameter properties and options, see the lightdash.config.yml reference.

​
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: 
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.

​
Examples of using parameters

Let’s look at some examples of how to use parameters in different parts of your Lightdash project.

​
In dimension SQL

You can reference parameters in the SQL definition of a dimension: 
models:
  - name: orders
    columns:
      - name: filtered_revenue
        meta:
          dimension:
            type: number
            sql: |
              CASE 
                WHEN ${TABLE}.region IN (${lightdash.parameters.region}) 
                THEN ${TABLE}.revenue 
                ELSE 0 
              END
In this example, the filtered_revenue dimension will only show revenue for the regions selected in the region parameter.

​
In numeric dimension SQL

You can reference numeric parameters directly without casting: 
models:
  - name: orders
    columns:
      - name: high_value_orders
        meta:
          dimension:
            type: boolean
            sql: ${TABLE}.revenue >= ${lightdash.parameters.min_revenue}
In this example, the high_value_orders dimension will be true for orders with revenue greater than or equal to the numeric min_revenue parameter value.

​
In metric SQL

You can reference parameters in the SQL definition of a metric: 
models:
  - name: races
    meta:
      metrics:
        avg_distance_unit_param:
          type: average
          sql: |
            case
              when ${lightdash.parameters.unit} = 'Miles' 
                then ${TABLE}.distance_miles
              when ${lightdash.parameters.unit} = 'Kilometers'
                then ${TABLE}.distance_km
            end
In this example, the avg_distance_unit_param metric will return an average of the race distance in miles when the unit parameter is set to Miles and Kilometers when it gets set to Kilometers.

​
In table joins

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: 
models:
  - name: orders
    meta:
      joins:
        - join: customers
          sql_on: |
            ${orders.customer_id} = ${customers.id} 
            AND ${customers.region} IN (${lightdash.parameters.region})
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: 
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.

​
In table calculations

You can reference parameters in table calculations: 
-- Table calculation example
CASE 
  WHEN ${orders.order_date} >= ${lightdash.parameters.date_range}
  THEN ${orders.revenue}
  ELSE 0
END
This table calculation will only include revenue for orders placed on or after the date selected in the date_range parameter.

​
In additional dimensions

You can use parameters in custom dimension definitions: 
models:
  - name: orders
    columns:
      - name: order_date
        meta:
          dimension:
            type: date
          additional_dimensions:
            is_after_cutoff_date:
              type: boolean
              sql: ${order_date} >= ${lightdash.parameters.date_range}
This additional dimension will indicate whether an order was placed on or after the date selected in the date_range parameter.

​
In SQL Runner

Parameters can also be used in SQL Runner queries: 
SELECT
  order_id,
  order_date,
  revenue
FROM orders
WHERE region IN (${lightdash.parameters.region})
  AND order_date >= ${lightdash.parameters.date_range}
  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: 
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.

​
Saving parameter values

Parameter values can be saved at both the chart and dashboard levels.

​
Saving values in charts

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. To save parameter values with a chart:
  1. Create or edit a chart
  2. Set the parameter values as desired
  3. Save the chart
The parameter values will be saved with the chart and will be applied whenever the chart is viewed.

​
Saving values in dashboards

You can also save parameter values at the dashboard level, which allows you to create dashboards with consistent parameter values across all charts. To save parameter values in a dashboard:
  1. Create or edit a dashboard
  2. Add charts to the dashboard
  3. Set the parameter values as desired
  4. Save the dashboard
The parameter values will be saved with the dashboard and will be applied to all charts on the dashboard that have parameterized fields.

​
Best practices for using parameters

Here are some best practices to follow when using parameters:
  1. Use descriptive names: Choose parameter names that clearly indicate their purpose
  2. Provide default values: Set default values for parameters to ensure queries work even if users don’t set parameter values
  3. Add descriptions: Include clear descriptions for parameters to help users understand their purpose
  4. Consider using options_from_dimension: For parameters that should match values in your data, use options_from_dimension to dynamically populate options
  5. Consider performance: Be mindful of how parameters affect query performance, especially with large datasets
⌘I