Parameter Fields

Introduction

Parameter fields (aka param fields) are special type of fields defined at the model. Param field act as variables to carry user inputs from dashboard controls to the model's query definitions, thus in turn change the chart results.

Unlike dimensions & measures which contain actual data, parameter fields act as variables that:

Accept user inputs through dashboard filters or visualization conditions
Pass these values into your model's query definitions (SQL or AQL)
Create dynamic content (charts) based on user's selection

How it works

To use param fields, we:

Define param fields in model (can be table model or query model)
Reference to param fields in model's query, dimension or measure's definitions
Bind dashboard's filter to model's param fields

Define Param Field

Add a parameter field to your model using this syntax:

Model my_model {

  dimension xxx { ... }
  measure yyy { ... }

  param my_param {
    label: 'Parameter Label'     // How it appears in the UI
    type: 'text'                             // Data type (text, number, datetime)
    description: 'What this parameter does'   // Helps other users understand the purpose
    allowed_values: ['value1', 'value2']    // Optional: restrict to specific values
  }
}

Available parameter types:

text: For string values
number: For numeric inputs
datetime: For date and time values
date: For date values
truefalse: For true/false options

Reference Param Fields in Model

You can reference param fields in your model's query or dimension formulas.

Inject param fields to query model
Model my_model {
  type: 'query'

  param my_param { ... }

  query: @sql
    SELECT *
    FROM your_table
    WHERE category = {% filter(my_param) %} category {% end %}
  ;;
}

Inject param fields in field's definitions
Model users {
  dimension age_group { ... }
  dimension gender { ... }

  param dim_selector {
    type: 'text'
    description: 'Select Dimension'
    allowed_values: ['age_group', 'gender']
  }

  dimension dynamic_field {
    type: 'text'
    definition: @aql case(
      when: 'age_group' in my_model.dim_selector, then: my_model.age_group,
      when: 'gender' in my_model.dim_selector, then: my_model.gender
    );

  }
}

Apply Param Fields at Dashboard

In a dashboard, create a filter and bind it to the model's param field.

Dashboard sales {
 
  block f1: FilterBlock {
    label: 'Select Dimension'
    type: 'field'
    source: FieldFilterSource {
      dataset: my_dataset
      field: ref('users', 'dim_selector')
    }
    default {
      operator: 'is'
      value: ['value1']
    }
  }

  block f2: VizBlock {

  }
}

Key Use Cases

1. Dynamic Query Models

Parameter fields can pass user input values directly into the SQL definition of a Query Model. This allows for:

Dynamic column selection: Let users choose which columns to include in a query
Performance optimization: Apply filters at the SQL level rather than after data retrieval
Customizable calculations: Allow users to input values for calculations (e.g., exchange rates)

For detailed implementation of this use case, see Dynamic Query Model.

2. Dynamic Dimension Selection

Parameter fields enable users to change which dimension is used in a report through dashboard filters. This allows for:

Flexible grouping: Switch between different grouping dimensions (e.g., by product, by region, by time period)
User-controlled analysis: Let users decide how to slice the data without creating multiple reports
Simplified dashboards: Reduce the number of visualizations needed by making existing ones adaptable

For detailed implementation, see Dynamic Dimensions.

3. Dynamic Measures Selection

Similar to dimensions, parameter fields can control which metrics are displayed in a report:

Comparative analysis: Switch between different metrics for comparison
Contextual reporting: Show metrics relevant to specific business contexts
User preference: Allow users to focus on metrics they care about

For detailed implementation, see Dynamic Measures.

4. Dynamic Explore Conditions

Parameter fields can control the filtering conditions applied to your data:

Adaptive security filters: Apply different data access rules based on user roles
Flexible time windows: Dynamically adjust date ranges based on user selection
Contextual filtering: Apply different business rules based on selected parameters

For detailed implementation, see Dynamic Explore Conditions.

Best Practices

Provide clear labels and descriptions for parameters so users understand their purpose
Set appropriate default values to ensure reports work even before user input
Consider performance implications when using parameters in complex queries
Test thoroughly with different parameter values to ensure correct behavior
Document parameter usage for other analysts who might use your models

Parameter Fields

Introduction​

How it works​

Define Param Field​

Reference Param Fields in Model​

Apply Param Fields at Dashboard​

Key Use Cases​

1. Dynamic Query Models​

2. Dynamic Dimension Selection​

3. Dynamic Measures Selection​

4. Dynamic Explore Conditions​

Best Practices​

Related Documentation​