Create query-based variables

Query-based variables dynamically populate filter options by querying your data sources, which ensures that variable options always reflect your current infrastructure and data. Unlike static variable lists that require manual updates, query-based variables leverage your data to generate filter options.

This approach eliminates manual maintenance when entities change, because the variable automatically discovers new values through queries. With query-based variables, your dashboard filters stay synchronized with reality every time you add a new server, deploy to a new region, or introduce new services.

To create a query-based variable, complete the following steps:

1. Open a dashboard that uses a Prometheus or metrics data source.

2. Click Edit in the top-right corner.

3. In the right sidebar, click Dashboard options (gear icon).

4. In the Variables section of the pane, click Add variable.

5. Click Query to choose the query variable type.

6. In the Name field, enter the variable name you’ll use in queries.

   For example, enter environment.

7. Under Query options, click Open variable editor.

8. In the Query Variable editor, select your Grafana Cloud Prometheus data source.

9. In the Query field, enter a query that returns the list of values.

   For example, select Classic query and enter label_values(up, environment) to retrieve unique environment labels.

10. Under Refresh, select when variable values should update.

    For example, select On dashboard load.

11. Click Preview to review the list of values.

12. Click Close to finish configuring the query.

13. Click Save to save the dashboard with your new variable.

14. The dashboard displays the query variable at the top as an interactive drop-down list.

In the next milestone, you learn how to create custom variables with manually defined options.