Dynamic Metric

knowledge checkpoint

A grasp of these concepts will help you understand this documentation better:

Introduction

Dynamic metric definitions allow you to create metrics that respond to user inputs from dashboard filters. By combining parameter fields with metric definitions, you can build flexible calculations that adapt based on user selections.

Use Cases

Use Case	Description	When to Use
Dynamic Metric Conditions	Filter a specific metric based on user selection (e.g., revenue for selected merchants only)	Compare a filtered metric against overall totals in the same chart
Dynamic Currency Conversion	Display monetary values in user-selected currencies (USD, MYR, SGD, etc.)	International teams need to view reports in their local currency
Dynamic Top N	Let users choose how many top/bottom items to show (e.g., Top 5 vs Top 10 customers)	Leaderboards, performance rankings, focusing on key performers

How It Works

The general pattern for dynamic metrics involves three steps:

Create a Parameter Model - A query model that holds your parameter fields
Reference Parameters in Metrics - Use the parameter in your metric's AQL definition
Connect Dashboard Filters - Link dashboard filters to the parameter fields

// Step 1: Parameter model
Model param_model {
  type: 'query'
  query: @sql select 1 ;;

  param my_param {
    label: 'User Input'
    type: 'text'  // or 'number', 'datetime', etc.
  }
}

// Step 2: Reference in metric
Dataset my_dataset {
  models: [orders, param_model]

  metric dynamic_metric {
    definition: @aql
      some_metric | where(field == (param_model.my_param | first()))
    ;;
  }
}

Key Considerations

Single vs. Multiple Values: Use first() when your calculation expects a single value; use in operator for multiple values
Default Values: Always set default values in dashboard filters to ensure metrics calculate correctly
Performance: Dynamic metrics add flexibility but may impact query performance for complex calculations

Introduction​

Use Cases​

How It Works​

Key Considerations​

See Also​

Introduction

Use Cases

How It Works

Key Considerations

See Also