Grafana Ad-hoc Filters Variable Prompt

You are a senior Grafana dashboard author who uses ad-hoc filters to make dashboards self-service.

I will provide:
- The data source (Prometheus, Loki, Elasticsearch, InfluxDB, SQL)
- The labels/columns users should filter on
- The dashboard's existing variables

Your job:

1. **Explain ad-hoc filters**: a special variable type that applies key/value filters to every query on the dashboard automatically, with no need to edit each panel.
2. **Check datasource support**: ad-hoc filters work with Prometheus, Loki, Elasticsearch, InfluxDB, and some SQL sources; confirm compatibility.
3. **Create the variable**: type `adhoc`, bound to the target datasource; Grafana auto-discovers label keys and values.
4. **Restrict keys (optional)**: pre-populate allowed keys so users only filter on sanctioned labels.
5. **Interaction with queries**: filters are injected into the query at render time (label matchers for Prometheus, WHERE clauses for SQL).
6. **Combine with other variables**: layer ad-hoc filters on top of custom/query variables without conflicts.
7. **Persistence and sharing**: filters survive in the URL so a filtered view is shareable.
8. **Provisioning**: encode the variable in dashboard JSON under `templating.list`.

Mark DESTRUCTIVE: none typically, but a datasource-wide ad-hoc variable can expose high-cardinality labels that slow every panel.

---

Data source: [DESCRIBE]
Labels/columns: [DESCRIBE]
Existing variables: [DESCRIBE]

Why this prompt works

Ad-hoc filters are the highest-leverage, least-understood Grafana variable — one variable makes an entire dashboard self-service, but it silently rewrites every query and can expose high-cardinality labels. This prompt makes the model confirm datasource support, restrict keys, and reason about the cardinality and empty-panel side effects before shipping.

How to use it

1. Name the data source so the assistant confirms ad-hoc support.
2. List the labels/columns users should be allowed to filter on.
3. Ask it to restrict keys if you want a curated filter set.
4. Request the dashboard JSON snippet for the templating list.

Useful commands

# Confirm Prometheus label keys the ad-hoc variable will offer
curl -s "http://prometheus:9090/api/v1/labels" | jq '.data'

# Inspect a dashboard's templating variables via the Grafana API
curl -s -H "Authorization: Bearer $GRAFANA_TOKEN" \
  http://localhost:3000/api/dashboards/uid/mydash \
  | jq '.dashboard.templating.list[] | select(.type=="adhoc")'

Example config

// dashboard JSON: templating.list entry
{
  "templating": {
    "list": [
      {
        "name": "Filters",
        "type": "adhoc",
        "datasource": { "type": "prometheus", "uid": "prom-main" },
        "label": "Ad-hoc filters",
        "filters": [
          { "key": "namespace", "operator": "=", "value": "production" }
        ],
        "defaultKeys": [
          { "text": "namespace", "value": "namespace" },
          { "text": "service", "value": "service" },
          { "text": "pod", "value": "pod" }
        ]
      }
    ]
  }
}

# Effect at render time: the ad-hoc filter is injected as a label matcher
# Author writes:
rate(http_requests_total[$__rate_interval])
# Grafana runs (with namespace="production" applied):
rate(http_requests_total{namespace="production"}[$__rate_interval])

Common findings this catches

• Slow dashboard → high-cardinality label offered as a filter key.
• Empty panels → filter applied to a label some queries lack.
• No effect → datasource does not support ad-hoc filters.
• Unsafe SQL → injected WHERE on a non-indexed/unsafe column.
• Uncurated keys → internal labels exposed to viewers.
• Leaked values → sensitive filter values shared in the URL.
• Unexpected matchers → interaction with multi-value variables.

When to escalate

• Persistent panel slowness from high-cardinality filtering — datasource/capacity review.
• Sensitive label exposure — security review of what keys are filterable.
• Cross-datasource filtering needs — consider a mixed datasource redesign.