Advanced Variables¶

When your dashboard needs dynamic behavior beyond simple filters, this advanced variables guide shows how to:

wire dependent variables (country → state, metric selectors, etc.),
conditionally emit filters using helper macros,
show or hide charts/boards based on the current values.

Dependent Variables¶

Dependent filters arise whenever one variable drives another (pick a country, then the state dropdown updates). To keep the UI and SQL in sync:

Source the dependent dropdown from a query that references the parent variable.
Guard the filtering logic with the filter macro so the dependent filter only applies when both variables have values.

variables:
  country:
    column: locations.country
    input: select

  state:
    query: |
      SELECT DISTINCT state
      FROM locations
      WHERE {{ filter('country', '=', country) }}
      ORDER BY state
    input: select

queries:
  customers:
    sql: |
      SELECT *
      FROM customers
      WHERE {{ filter('country_name', '=', country) }}
        AND {{ filter('state_name', '=', state, country and state) }}
    profile: my_postgres

The state list refreshes whenever country changes, and its filter only runs when both country and state are defined. This keeps the dropdown options clean and the SQL lean.

Conditional Filters¶

Use the filter macro (and filter_date_range for ranges) to keep your SQL compact while still handling undefined or null gracefully. You can rely on the default behavior (value is defined), or pass an explicit condition to control when the filter fires.

queries:
  sales:
    sql: |
      SELECT *
      FROM revenue
      WHERE {{ filter('region', '=', region) }}
        AND {{ filter_date_range('order_date', date_range) }}
        AND {{ filter('total_revenue', '>=', min_revenue) }}
    profile: my_postgres

If you need customized fallback values or formatting, use Jinja inside the arguments (e.g., region or 'North').

Conditional Layouts¶

Variables can drive which charts or boards appear on the dashboard. Every board and chart supports an optional include property which by default is true.

The include property accepts a boolean value or a boolean expression string. Unlike other Jinja templates, you do not need to wrap these expressions in {{ }} braces (though using them is also supported).

If the expression evaluates to true (the default), the component is rendered. If false, it is completely omitted from the layout.

Conditionally Including a Board¶

By applying variables the include field you can control the visibility of a chart or board (and its children).

variables:
  show_details:
    input: checkbox
    default: false

rows:
  - title: "Main KPIs"
    cols: ...

  - title: "Regional Details"
    include: show_details  # Only included if this variable is true
    rows:
      - region_map
      - region_table

Conditionally Including a Chart¶

Charts also support the include property, making it easy to toggle specific visualizations.

variables:
  show_forecast:
    input: checkbox
    default: false

cols:
  - title: "Forecast"
    type: line
    query: queries.forecast
    include: show_forecast  # Toggle this chart

Swapping Content¶

You can swap between two different views by listing both in the same layout but giving them mutually exclusive include conditions.

For example, to toggle between a "Summary" view and a "Detailed" view:

variables:
  mood:
    input: select
    options: ['happy', 'sad']
    default: 'happy'

rows:
  - include: mood == 'happy'
    style:
      background: "#FFF9C4" # Yellow
    content: |
      # :smile:
      Everything is awesome!

  - include: mood == 'sad'
    style:
      background: "#37474F" # Dark Blue Grey
      color: white
    content: |
      # :cry:
      Everything is terrible.

This approach keeps your layout definitions declarative and easy to read.