Skip to main content
When a filter is selected, you may see a connection error, syntax error, or unexpected results. If the same metric works fine without a filter (or with a hardcoded value), the problem is almost always filter substitution or value shape, not credentials or network.

​
Common Issues and Fixes

Cause: The final SQL query still contains unresolved {{variable}} placeholders when it runs. This happens when:
  1. The variable name in the SQL doesn’t exactly match the filter’s variable name (case-sensitive)
  2. The filter has no value and no default, so nothing gets substituted
  3. The SQL references a variable that no filter provides
Fix: Make the {{name}} in your SQL exactly match the filter’s variable name, and give the filter a default value so the metric can run before a user makes a selection.
-- Works once the filter named global_region has a value or default
SELECT * FROM sales WHERE region = {{global_region}}
Keep filter variables in the WHERE clause. There is no built-in way to display or “inspect” the current filter value in a metric, so a variable in SELECT has no supported use — do not use SELECT {{var}} to debug.
Cause: A multi-select filter is being used with single-value syntax (= {{var}}). When the product substitutes an array of selected values, the resulting SQL can be invalid.Fix: For multi-select filters, use IN syntax instead of =. The runtime substitutes the variable as a parenthesized list of quoted values (e.g. ( 'US' , 'CA' )), so do not add your own parentheses:
-- Wrong: multi-select with equality
WHERE region = {{global_region}}

-- Wrong: double-wrapped parentheses produce invalid SQL
WHERE region IN ({{global_region}})

-- Correct: multi-select with IN, no extra parentheses
WHERE region IN {{global_region}}
See Dashboard Filter Variable Apply On for single-select vs. multi-select details.
Cause: The filter value shape (array vs. scalar) doesn’t match what the SQL expects. Hardcoding the same value works because it’s always a scalar.Fix: Check whether the filter is configured as single-select or multi-select, and adjust your SQL accordingly. For multi-select, use IN {{var}} (no extra parentheses).
Cause: The selected filter value may contain special characters (e.g., apostrophes, quotes) that break the generated SQL.Fix:
  • If you control the filter options (e.g., Manual filter), use values that don’t contain apostrophes or special SQL characters.
  • For custom SQL filters, ensure your LHS/RHS or Apply on logic handles escaping.
Cause: The variable may be substituted as empty or NULL, producing invalid SQL (e.g., WHERE col = with nothing after =).Fix: In your WHERE clause, handle the “no filter” case explicitly if your use case requires optional filtering:
WHERE ('{{global_region}}' = '' OR region = {{global_region}})
Check the dashboard filter docs for recommended optional-filter patterns.
Cause: The variable name in your metric’s SQL does not match the name configured for the filter.Fix:
  • Use the exact variable name shown when you set up the filter (Apply on > Variable Filter). Copy it from the product UI if possible.
  • Variable names are case-sensitive.
  • In Python console or embed context, metric_filters is only populated when: (1) the metric’s SQL actually uses that filter variable, (2) the metric runs in a dashboard context with the filter applied, and (3) the variable name matches exactly.

​
Quick Checklist

CheckAction
”Filter or Client variables detected”?An unresolved {{…}} remains — check name match and default value.
Multi-select filter?Use IN {{var}} (no extra parentheses), not = {{var}}.
Special characters in values?Avoid or escape; use safe values in Manual filter.
Empty filter value?Handle “no selection” in WHERE if needed.
Variable name mismatch?Must match filter config exactly (case-sensitive).
metric_filters empty?Ensure SQL uses the variable, name matches, and context is a dashboard with the filter applied.

Dashboard Filter Variable Apply On

How variable naming works, single-select vs. multi-select, and WHERE clause usage.

Create/Modify Dashboard Filter

Full guide to creating and configuring dashboard filters.

LHS/RHS Custom SQL

Custom SQL transformations in dashboard filters.