Add variable controls to dashboards

Variable controls bind interactive controls to variables in your ES|QL visualization queries. Unlike the standard dashboard controls that filter using data view fields, variable controls work directly with ES|QL queries to enable dynamic filtering, grouping, and function selection.

Serverless Preview Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Preview This functionality is in technical preview and is ready for evaluation. Use with caution in production; it is not recommended for mission-critical workloads. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. Specific Support terms apply. Serverless interfaces and procedures might differ from classic Elastic Stack deployments. Stack Planned The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Planned We plan to add this functionality in a future Elastic Stack update. Subject to changes. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. To make a Vega visualization react to a variable control, refer to Apply dashboard variable controls to ES|QL data sources.

To add variable controls to a dashboard, you need:

• All privilege for the Dashboard feature in Kibana
• An existing dashboard open in Edit mode
• An ES|QL visualization on your dashboard, or the intent to create one

Serverless Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Generally available This functionality is generally available and ready for production usage. Serverless interfaces and procedures might differ from classic Elastic Stack deployments. Stack 9.4+ The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 9.4 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. A dashboard can hold up to 1,000 top-level items (panels, unpinned controls, and sections) and, separately, up to 100 controls pinned to the top of the dashboard. For the exact limits, refer to Panel limits.

Variable controls act as variables in your ES|QL visualization queries. On the dashboard, they appear as options lists. A control's options can be:

• Values or fields, either static or defined by a query.
• Serverless Preview Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Preview This functionality is in technical preview and is ready for evaluation. Use with caution in production; it is not recommended for mission-critical workloads. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. Specific Support terms apply. Serverless interfaces and procedures might differ from classic Elastic Stack deployments. Stack Preview 9.1+ The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Preview since 9.1 This functionality is in technical preview and is ready for evaluation. Use with caution in production; it is not recommended for mission-critical workloads. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. Specific Support terms apply. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. Functions.

You create a variable control while writing an ES|QL query: the autocomplete suggests adding a control for field values, field names, function configuration, or function names.

On a dashboard, you can also add a variable control directly by selecting Add → Controls → Variable control.

1. While you edit your ES|QL query, the autocomplete menu suggests adding a control when relevant or when you type ? in the query. Select Create control.

2. A flyout opens to let you configure the control. Specify:

   • The type of the control:

     • For controls with Static values, enter available values manually or select them from the dropdown list.

     • For controls with Values from a query, write an ES|QL query that returns a single column to populate the list of options. Use this option to dynamically retrieve control values or to set up chained controls. This type is available only for controls that replace values, such as a host name or a number. Controls that replace field names, function names, or time intervals use Static values.

       Tip - Only display values available for the selected time range

       To restrict the options to values that exist within the selected time range, add WHERE @timestamp <= ?_tend AND @timestamp > ?_tstart to the control's query. If your indices don't have a @timestamp field, replace @timestamp with your time field, as described in custom time parameters.

   • The name of the control. You use this name to reference the control in ES|QL queries. You can't change the name after you save the control, so the prefix is also fixed. The prefix tells ES|QL what the control inserts into the query:

     • Start the name with ? when the options are values, such as a host name, a number, or a time interval. The control inserts the value you select.
     • Serverless Preview Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Preview This functionality is in technical preview and is ready for evaluation. Use with caution in production; it is not recommended for mission-critical workloads. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. Specific Support terms apply. Serverless interfaces and procedures might differ from classic Elastic Stack deployments. Stack Preview 9.1+ The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Preview since 9.1 This functionality is in technical preview and is ready for evaluation. Use with caution in production; it is not recommended for mission-critical workloads. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. Specific Support terms apply. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. Start the name with ?? when the options are field names or function names. The control inserts the name you select.

   • The values users can select. You can add multiple values from suggested fields or type in custom values. If you selected Values from a query, write an ES|QL query instead.

   • The label of the control. This is the label displayed in Discover or in the dashboard.

   • Serverless Preview Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Preview This functionality is in technical preview and is ready for evaluation. Use with caution in production; it is not recommended for mission-critical workloads. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. Specific Support terms apply. Serverless interfaces and procedures might differ from classic Elastic Stack deployments. Stack Preview 9.3+ The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Preview since 9.3 This functionality is in technical preview and is ready for evaluation. Use with caution in production; it is not recommended for mission-critical workloads. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. Specific Support terms apply. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. Whether the control allows a single selection or multiple selections. Multiple selections require using the MV_CONTAINS function in your query.

     • Serverless Preview Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Preview This functionality is in technical preview and is ready for evaluation. Use with caution in production; it is not recommended for mission-critical workloads. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. Specific Support terms apply. Serverless interfaces and procedures might differ from classic Elastic Stack deployments. Stack Preview 9.4+ The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Preview since 9.4 This functionality is in technical preview and is ready for evaluation. Use with caution in production; it is not recommended for mission-critical workloads. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. Specific Support terms apply. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. To match any selected value instead of all of them, use MV_INTERSECTS instead of MV_CONTAINS.

3. Save the control.

The control is created. If you created it while editing a query, its variable is inserted into that query, which you can keep editing.

With an ES|QL query, you can shape the values offered in the control more precisely.

For example, use WHERE to limit the values the control offers, instead of surfacing every value in the field. The following query offers only the operating systems seen in requests for CSS files from the sample web logs, instead of every operating system in the data:

FROM kibana_sample_data_logs
| WHERE extension.keyword == "css"
| STATS BY machine.os.keyword

You can reference the control in your ES|QL visualization queries by typing its name.

Where you place a variable control affects which panels it filters. For details, refer to How controls affect the dashboard.

Examples

• Filter by a selected value:

  | WHERE field == ?value
  

• Group by a selected field:

  | STATS count = COUNT(*) BY ??field
  

• Adjust a function setting, such as a date histogram interval:

  | STATS count = COUNT(*) BY BUCKET(@timestamp, ?interval)
  

• Switch the aggregation function:

  | STATS metric = ??function
  

You can create controls that let users select multiple values. To do that:

1. Add the MV_CONTAINS function to your query, with the field as the first parameter (superset) and a variable as the second parameter (subset). For example:

   FROM logs-* | WHERE MV_CONTAINS(field, ?values)
   

   Note

   Multi-selection is only available for ?values variables, not for ??fields or ??functions variables.

   MV_CONTAINS checks that all subset values are present.

   Serverless Preview Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Preview This functionality is in technical preview and is ready for evaluation. Use with caution in production; it is not recommended for mission-critical workloads. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. Specific Support terms apply. Serverless interfaces and procedures might differ from classic Elastic Stack deployments. Stack Preview 9.4+ The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Preview since 9.4 This functionality is in technical preview and is ready for evaluation. Use with caution in production; it is not recommended for mission-critical workloads. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. Specific Support terms apply. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. If matching any subset value is enough, use MV_INTERSECTS instead.

2. When defining the control, select the Allow multiple selections option.

3. Save the control.

The newly configured control becomes available and allows users to select multiple values.

Chain variable controls so that the selection in one control determines the options available in another. This is useful when you work with data from multiple indices or need hierarchical filtering, because it narrows control selections dynamically without filtering the entire dashboard.

To chain variable controls, reference one control's variable in another control's ES|QL query using the ?variable_name syntax.

Example: You create a dashboard that analyzes web traffic by region and IP address. Next, you want to see only the IP addresses that are active in a selected region, and then analyze traffic patterns for a specific IP, all without filtering the entire dashboard by region.

1. Create the first control that will be referenced in other controls.

   Tip

   Create the controls that will be referenced in other controls first. This allows the ES|QL editor to provide proper autocomplete suggestions.

   In Edit mode, select Add → Controls → Variable control in the application menu, then define the control:

   • Type: Values from a query
   • Query:

     FROM kibana_sample_data_logs | WHERE @timestamp <= ?_tend AND @timestamp > ?_tstart | STATS BY geo.dest
     

   • Variable name: ?region
   • Label: Region

   This control extracts all unique destination regions from your logs.

2. Create the second control that depends on the first control.

   Add another variable control:

   • Type: Values from a query
   • Query:

     FROM kibana_sample_data_logs
     | WHERE @timestamp <= ?_tend AND @timestamp > ?_tstart AND geo.dest == ?region
     | STATS BY ip
     

   • Variable name: ?ip
   • Label: IP address

   This control references the ?region variable and the built-in time range variables (?_tstart and ?_tend). The available IP addresses will be only those associated with the selected region.

3. Test the chained controls. Both controls are now visible on your dashboard. Select different values in the Region control and observe how the available IP addresses in the IP address control change to show only IPs from that region.

4. Create an ES|QL visualization that uses the ?ip control to filter data. For example:

   FROM kibana_sample_data_logs
   | WHERE ip == ?ip
   | STATS count = COUNT(*) BY day = DATE_TRUNC(1 day, @timestamp)
   | SORT day
   

   This visualization filters data based on the selected IP address, while the IP address options themselves are filtered by the selected region.

To add the results of your Discover explorations to a dashboard in a way that preserves the controls created from Discover and also adds them to the dashboard, you have two methods:

Method 1: Adding the Discover session's results

This method allows you to add the result table of your Discover ES|QL query to any dashboard.

1. Save the ES|QL query containing the variable control into a Discover session. If your Discover session contains several tabs:

   • Serverless Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Generally available This functionality is generally available and ready for production usage. Serverless interfaces and procedures might differ from classic Elastic Stack deployments. Stack 9.4+ The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 9.4 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. You can select which tab the panel displays after adding the session to a dashboard.
   • Stack 9.2-9.3 The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available from 9.2 to 9.3 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. Only the first tab is imported to the dashboard.

2. Go to Dashboards and open or create one.

3. Select Add, then From library.

4. Find and select the Discover session you saved earlier.

A new panel appears on the dashboard with the results of the query along with any attached controls.

Serverless Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Generally available This functionality is generally available and ready for production usage. Serverless interfaces and procedures might differ from classic Elastic Stack deployments. Stack 9.3+ The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 9.3 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. Method 2: Adding the Discover visualization

This method allows you to add the visualization of your Discover ES|QL query to any dashboard.

1. Next to the Discover visualization, select Save visualization to dashboard. In 9.3, the button is Save visualization.

   
   

2. Select the dashboard to add the visualization to. You can select an existing dashboard or create one.

The selected dashboard opens. It now includes a new panel that shows the visualization imported from Discover. Existing controls from the initial query in Discover are also added. You can find them at the top of the dashboard.

After a variable control is on your dashboard, you can edit it, adjust its display, move it, or delete it. How you access these actions depends on whether the control is pinned:

• When pinned, hover over the control to reveal its action icons.
• Serverless Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Generally available This functionality is generally available and ready for production usage. Serverless interfaces and procedures might differ from classic Elastic Stack deployments. Stack 9.4+ The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 9.4 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. When unpinned, hover over the control to reveal its action icons, or open its panel menu, which adds standard panel actions such as Duplicate and Copy to dashboard.