Skip to main content
← Back to index page

🎯 Viz-aware AQL: Metrics that automatically adapt to your charts

🔥 Why this feature?​

Ever created the same metric 5 times just because users wanted to view data by month, quarter, AND year? Yeah, we fixed that.

💡 How it works​

  • Context-aware functions: New AQL functions that automatically adapt to visualization settings
  • Dynamic references: Use 'x_axis', 'rows', 'columns' instead of hardcoding dimensions
  • Automatic adaptation: Metrics recalculate correctly when users change chart configurations

Before vs After​

❌ Before (Static AQL)

// Static period comparison - only works for monthly data
metric revenue_vs_prev_month {
  definition: @aql 
    sum(orders.revenue) - 
    sum(orders.revenue) | relative_period(orders.created_at | month(), interval(-1))
  ;;
}

// Separate metric needed for yearly comparison
metric revenue_vs_prev_year {
  definition: @aql 
    sum(orders.revenue) - 
    sum(orders.revenue) | relative_period(orders.created_at | year(), interval(-1 year))
  ;;
}

// Running total hardcoded to specific dimension
metric running_total_by_month {
  definition: @aql 
    window_sum(sum(orders.revenue), order: orders.created_at | month())
  ;;
}

// Percent of total hardcoded to specific dimension
metric pct_of_product_total {
  definition: @aql (sum(orders.revenue) | of_all(products.category)) / sum(orders.revenue) ;;
}

// 😰 Common issues:
// - Need duplicate metrics for each time grain
// - Calculations break when users change visualization settings
// - Running totals don't work when pivoting by different dimensions

✅ After (Viz-aware AQL)

// One metric that adapts to any time grain
metric revenue_vs_previous_period {
  definition: @aql 
    sum(orders.revenue) | relative_period(orders.created_at, -1)
  ;;
}

// Running total that follows visualization
metric revenue_running_total {
  definition: @aql 
    window_sum(sum(orders.revenue), order: 'x_axis')
  ;;
}

// Percentage calculations that adapt to pivot structure
metric pct_of_row_total {
  definition: @aql 
    percent_of_total(sum(orders.revenue), 'row_total')
  ;;
}

// 🎉 Benefits:
// - Single metric works for monthly, quarterly, yearly views
// - Automatically adapts when users change chart settings
// - Drill-downs and pivots work seamlessly
Note

Your existing static AQL definitions continue to work as before - no breaking changes! If you want to make your metrics visualization-aware, you can modify them to use the new context-aware functions.

Functions that support viz-aware features​

Percentage Calculations

  • percent_of_total - Calculate percentages with 'row_total', 'column_total', or 'grand_total'

Time-based Functions

  • relative_period - Compare metrics across time periods that adapt to visualization granularity

Window Functions