PostgreSQL query variable creation steps
To create a query variable in PostgreSQL: Navigate to the dashboard and click Edit. Click the Add new element icon (blue plus sign). Click Variable. Select Query as the variable type. Enter a Name for the variable (for example, 'host'). Select an option in the Display drop-down list to control where on the dashboard the variable is displayed. Click Open variable editor to open the Query Variable dialog box. Select your PostgreSQL data source. Write a SQL query in the editor; macros like $__timeFilter are supported. Optionally set Value Field and Text Field to control which columns map to the variable value and display label.
PostgreSQL query variable basic example
A query variable can return values from a single column. For example, the query 'SELECT hostname FROM host' returns all values from the hostname column for use in a drop-down select box.
PostgreSQL query variable with multiple columns
A query can return multiple columns, and Grafana automatically generates a list using the values from those columns. For example, the query 'SELECT host.hostname, other_host.hostname2 FROM host JOIN other_host ON host.city = other_host.city' returns values from both the hostname and hostname2 columns, which are included in the variable's drop-down list.
PostgreSQL time range dependent macro requires refresh mode configuration
To use time range dependent macros like $__timeFilter(column) in a query variable, you must set the template variable's refresh mode to On Time Range Change.
PostgreSQL time range macro example
The query 'SELECT event_name FROM event_log WHERE $__timeFilter(time_column)' demonstrates using the $__timeFilter macro with a time column.
PostgreSQL key/value variable with Value field and Text field
You can create a key/value variable so the drop-down shows a user-friendly label while panel queries use a different value. Use the variable editor's Value field and Text field at the bottom of the query section to specify which query columns supply the value and the label. Your query can use any column names; you do not need __value or __text in the SQL. Example: run a query 'SELECT hostname, id FROM host', then set Text field to 'hostname' and Value field to 'id'.
PostgreSQL key/value variable legacy approach with __text and __value
Alternatively, you can use the legacy approach: return columns named __text and __value in your query (for example, 'SELECT hostname AS __text, id AS __value FROM host'). Note that the values in the text column should be unique. If there are duplicates, Grafana uses only the first matching entry.
PostgreSQL nested variables with IN operator
You can create nested variables, where one variable depends on the value of another. For example, if you have a variable named region, you can configure a hosts variable to only show hosts from the selected region. If region is a multi-value variable, use the IN operator instead of = to match against multiple selected values. Example: 'SELECT hostname FROM host WHERE region IN($region)'.
PostgreSQL multi-value variable with Include All and Hidden display issue
When using a multi-value PostgreSQL query variable with Include All option enabled and Display set to Hidden, the variable defaults to the first returned value, not All. This is because Grafana persists the active selection at dashboard save time, and a hidden variable has no UI for users to change it. To default a hidden variable to All, temporarily show the variable, select All in the drop-down, save the dashboard, then hide the variable and save again.
PostgreSQL __searchFilter macro for real-time filtering
Using __searchFilter in the query field filters the query results based on user input in the drop-down selection box. If nothing is entered, the default value for __searchFilter is %. You must enclose the __searchFilter expression in quotes because Grafana doesn't add them automatically. Example: 'SELECT hostname FROM host WHERE hostname LIKE '$__searchFilter''.
PostgreSQL __searchFilter with LIMIT for large tables
For tables with a large number of rows, combine __searchFilter with LIMIT to keep the drop-down responsive. Example: 'SELECT DISTINCT hostname FROM host WHERE hostname LIKE '$__searchFilter' ORDER BY hostname LIMIT 100'.
PostgreSQL regex variable for filtering and transforming
You can use a Regex type variable to filter or transform values from another variable. For example, if you have a variable named server that returns values like web-prod-01, web-staging-01, and db-prod-01, you can create a regular expression variable to extract only the environment. Create a new variable with Type: Query, set the query to return the raw values, and in the Regex field, enter a pattern to extract or filter (for example, '/^web-(.+)-\d+$/' extracts 'prod' and 'staging' from web server names). You can also use regular expression to filter a variable's options (for example, setting the Regex field to '/prod/' limits the drop-down to only production servers).
PostgreSQL multi-property variables overview
The PostgreSQL data source supports multi-property variables. Use them when the same logical concept has different identifiers in different contexts (for example, an environment called dev in one system and development in another). Instead of maintaining several variables in sync, you can map all of those values to one variable and reference the property you need in each panel or query.
PostgreSQL multi-property variable with Type: Custom
You can create a multi-property variable with Type: Custom. In Custom options > JSON, paste your own JSON array with the mapping. Each object in the array can have any number of properties; use 'text' and 'value' for the label and value shown in the drop-down, and add additional properties as needed.
PostgreSQL multi-property variable with Type: Query example
You can create a multi-property variable with Type: Query. Write a SQL query that returns multiple columns. In the variable editor, set Value field and Text field to the columns that supply the value and the label for the drop-down. Add one column per property you want to reference; each column name becomes a property name. In panels and queries, reference a property with ${varName.columnName}. Example: a variable named 'env' that lists environments with different identifiers per cloud. Set Text field to 'name' and Value field to 'id'. Query: 'SELECT name, id, aws_identifier AS env_aws, azure_identifier AS env_azure FROM environments'. In a panel query use '$env.env_aws' for AWS-related queries and '$env.env_azure' for Azure-related queries.
PostgreSQL template variable quoting behavior
Grafana automatically quotes template variable values only when the template variable is a multi-value variable. When using a multi-value variable, use the IN comparison operator instead of = to match against multiple values.
PostgreSQL variable syntax $varname and [[varname]]
Grafana supports two syntaxes for using variables in queries: $<varname> syntax and [[varname]] syntax. Both are equivalent. Example with $varname syntax: 'SELECT atimestamp AS time, aint AS value FROM table WHERE $__timeFilter(atimestamp) AND hostname IN($hostname) ORDER BY atimestamp ASC'. Example with [[varname]] syntax: 'SELECT atimestamp AS time, aint AS value FROM table WHERE $__timeFilter(atimestamp) AND hostname IN([[hostname]]) ORDER BY atimestamp ASC'.
PostgreSQL multi-value variable automatic quoting with IN clause
When a variable has Multi-value enabled, Grafana automatically adds quotes around each selected value. For example, if the user selects web01 and web02, $hostname expands to 'web01','web02'. Use the IN operator to match. Example: 'SELECT $__timeGroupAlias("created_at", '5m'), count(*) AS requests FROM access_log WHERE $__timeFilter("created_at") AND hostname IN($hostname) GROUP BY time ORDER BY time'. If only a single value is selected, the IN clause still works correctly—IN('web01') is equivalent to = 'web01'.
PostgreSQL multi-value numeric variable with csv format option
For numeric columns (such as IDs), disable quoting with the csv format option so values aren't wrapped in quotes. Example: 'SELECT name FROM host WHERE id IN(${host_id:csv})'. If host_id has values 1, 2, and 3 selected, this expands to IN(1,2,3) instead of IN('1','2','3').
PostgreSQL multi-value variable disable quoting with csv format
By default, Grafana formats multi-value variables as a quoted, comma-separated string. For example, if server01 and server02 are selected, the result is 'server01','server02'. To disable quoting, use the csv formatting option: ${servers:csv}. This outputs the values as an unquoted comma-separated list.
URL variables query parameter prefix
Grafana interprets query string parameters prefixed with 'var-' as variables in the given dashboard. For example, the query parameter 'var-example=value' represents the dashboard variable 'example' with a value of 'value'.
Multiple values for a dashboard URL variable
To pass multiple values for a single variable in a dashboard URL, repeat the variable parameter once for each value. For example: 'https://${your-domain}/path/to/your/dashboard?var-example=value1&var-example=value2' passes the variable 'example' with two values: 'value1' and 'value2'.
Filter as query parameter in dashboard URL
To pass a filter as a query parameter, use the variable syntax with the filter key, operator, and value as a pipe-separated list. For example: 'https://${your-domain}/path/to/your/dashboard?var-filter=example_key|=|example_value'. When sharing URLs with filters, pipes must be encoded as '%7C' and the equality operator '=' as '%3D'.
Dashboard links can include current dashboard variables
When creating dashboard links in dashboard settings, you can select an option to have current dashboard variables automatically included in the link.
Filter and Group by feature overview
The Filter and Group by feature is a dashboard control that automatically queries your data source for available dimensions and lets users add or remove filters and group by dimensions dynamically. It allows you to quickly apply filters dashboard-wide without creating individual variables for each dimension. In the dashboard schema, it is still referred to as 'kind: AdhocVariable' under the variables schema property.
Group by function for aggregation queries
The group by function allows you to group data by keys and split aggregated results. This function is typically used with aggregation queries such as sum(your_metric_here) to split aggregated results by selected dimensions, and you can then use filters within panels to filter data in or out.
Data sources supporting filters and group by
The following data sources support filters: Prometheus (supports group by), Loki (supports group by), InfluxDB, Elasticsearch, OpenSearch, and Special Dashboard data source. Data sources marked with an asterisk also support the group by function.
Steps to add Filter and Group by controls
To add filters and group by controls: (1) Navigate to the dashboard and click Edit; (2) Click the Add new element icon (blue plus sign); (3) Click Filter and Group by; (4) Enter a Name for the filter; (5) Optionally enter a Label for the display name in the drop-down list (if not entered, the drop-down label is the filter name); (6) Optionally enter a Description (supports Markdown-style links and bare URLs for http/https protocols); (7) Choose a Display option; (8) Set Filter options including Data source, Default filters, Enable group by, Default group by, Use static key dimensions, and Allow custom values; (9) Click Save; (10) Enter an optional description and click Save; (11) Click Exit edit.
Filter and Group by display options
Display options for filters are: Above dashboard (displays above the dashboard with Name or Label; default), Above dashboard, label hidden (displays above without the filter name), Controls menu (displays in the dashboard controls menu as a button), and Hidden (no filter drop-down displayed).
Filter options configuration table
Filter options configuration:
| Option | Description |
| Data source | Select a target data source in the drop-down list. Click Open advanced data source picker to see more options including adding a data source (Admins only). |
| Default filters | Set a default key/value pair (optional). Default values are indicated with an information icon in the dashboard filter control. |
| Enable group by | Only appears if Prometheus or Loki data source is selected. Toggle to enable data grouping. |
| Default group by | Set a default key for the dashboard (optional). Default values are indicated with an information icon in the dashboard filter control. |
| Use static key dimensions | Toggle to provide filter dimensions as comma-separated values (CSV) instead of querying the data source (optional). |
| Allow custom values | Toggle to allow dashboard users to add custom values to the filter and group by lists (optional). |
Panel-level group by control
When the Group by switch is toggled on, you can set a group by dimension from a panel by hovering the cursor over any panel using the data source of the filter to show the Group by selector. The panel-level Group by control only includes keys available in the panel's query, in contrast with the dashboard-level control that includes all available keys for the dashboard. Your selection applies to all panels in the dashboard with the same data source.
Filter on time series panel values
After setting your group by dimension and splitting data, you can click on a series in a time series panel and click 'Filter on this value' or 'Filter out this value'. This filters by the labels found on that series, which are related to the already set group by dimensions. To enable this functionality, you need to add one or more overrides for the panel that add a regular expression so that all fields are filterable and enable the Filterable switch. You can also do this programmatically by returning the data frame with the appropriate filterable property on the desired fields.
Filters overview feature
To see all active filters and group by dimensions across the dashboard at once, click the Filters overview icon (filter) in the toolbar to open an overview. The overview lets you search for specific keys and adjust them without scrolling through the dashboard controls. You can add an operator and value for a key to add it as a filter or select the Group by checkbox to set a group by dimension.
Filter any data using Dashboard data source
For data sources that don't support filters, you can use the special Dashboard data source to reference that data and then filter it in a new panel. To use filters on unsupported data sources: (1) Navigate to the dashboard with the panel containing the data to filter; (2) Click Edit; (3) Add a new panel; (4) Click Configure visualization; (5) In the Queries tab, enter 'Dashboard' in the Data source field and select '-- Dashboard --'; (6) In the query configuration, select Source panel (the panel with source data), Data (choose All Data for all data including annotations), and toggle on Filters to make the data from the referenced panel filterable; (7) Configure other options and save; (8) Click Back to dashboard and Exit edit.
Dashboard drilldown with filters from table and bar chart
In table and bar chart visualizations, you can apply filters directly from the visualization. Hover your cursor over a table cell with the value you want to filter, or hover over a bar in a bar chart. Click the add filter icon. The variable pair (e.g., alertname = ConfigMap Updated) is added to the filter and all panels using the same data source that include that variable value are filtered by that value. If a panel doesn't include that variable value, it won't return any data.
Panel-to-panel filtering with data links
You can use data links to link back to the dashboard you are currently on, enabling panel-to-panel filtering where clicking a data point in one panel updates the dashboard variables and filters the rest of the dashboard. To preserve the context of the current dashboard: (1) Explicitly include the current time range in the link; (2) Enable 'Include all variables' to preserve existing selections; (3) Ensure that 'Include all variables' is placed before the specific variable you are defining in the link. Filters on the current dashboard are automatically preserved.
Edit variables in the Variables section
In the Variables section of the dashboard sidebar, you can click Select on a variable control to open it in the sidebar and make updates.
Duplicate a variable
Duplicate a variable by clicking the clone icon in the sidebar header. This creates a copy of the variable with the name of the original variable prefixed with 'copy' and the number of the copy; for example, 'copy1'.
Delete a variable
Delete a variable by clicking the trash icon in the sidebar header.
Reorder variables
Reorder variables by dragging and dropping controls in the Variables section.
Change variable display location
Drag and drop variable controls between sub-sections to update the control display option: Above dashboard, Controls menu, or Hidden. Links cannot be hidden.
Inspect variable dependencies
In the Variables section, click 'Show dependencies' at the bottom of the list to open a dependencies diagram that shows relationships between dashboard variables.