Add variable controls with ES|QL

Variable controls let you bind interactive controls to variables in your ES|QL visualization queries. Unlike 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.

• 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

You can bind controls to your ES|QL visualizations in dashboards. When creating an ES|QL visualization, the autocomplete suggestions prompt control insertion for field values, field names, function configuration, and function names. ES|QL controls act as variables in your ES|QL visualization queries.

When you add a variable control from an ES|QL panel, for example, by choosing Create control from the autocomplete menu, you can place it beside the panel so the control appears directly next to the visualization that uses it. This enables controls that only apply to specific panels in your dashboards, and exposes visualization configuration such as date histogram interval controls to dashboard users.

Only Options lists are supported for ES|QL-based controls. Options can be:

• values or fields that can be static or defined by a query
• functions

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 menu opens to let you configure the control. This is where you can specify:

   • The type of the control.
     • For controls with Static values, enter available controls manually or select them from the dropdown list.
     • For controls with Values from a query, write an ES|QL query to populate the list of options. This option is useful for dynamically retrieving control values or perform advanced actions such as defining chaining controls.
       Tip - Only display values available for the selected time range

       By linking the control to the global time range, the control only shows values that exist within the time range selected in the dashboard or Discover session. You can do that by specifying WHERE @timestamp <= ?_tend AND @timestamp > ?_tstart in the control's query, or custom time parameters if your indices don't have a @timestamp field.

   • The name of the control. You use this name to reference the control in ES|QL queries.
     • Start the name with ? if you want the options to be simple static values.
     • Start the name with ?? if you want the options to be fields or functions.
   • The values users can select for this control. You can add multiple values from suggested fields, or type in custom values. If you selected Values from a query, you must instead write an ES|QL query at this step.
   • The label of the control. This is the label displayed in Discover or in the dashboard.
   • Whether the control should allow selecting a single value or multiple values. This requires using the MV_CONTAINS function in your query.

3. Save the control.

The variable is inserted into your query, and the control appears.

If you added it by starting from a query, the control is directly inserted in that query and you can continue editing it. You can then insert it in any other ES|QL visualization queries by typing the control's name.

Examples

• Integrate filtering into your ES|QL experience

  | WHERE field == ?value
  		

• Fields in controls for dynamic group by

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

• Variable time ranges? Bind function configuration settings to a control

  | BUCKET(@timestamp, ?interval),
  		

• Make the function itself dynamic

  | 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, and create a variable as one of its parameters. For example:

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

   Note

   Multi-selection is only available for ?values variables. It is not available for ??fields and ??functions variables.

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.

You can set up variable controls in such a way that the selection of one control determines the options available for another control.

This allows you to narrow down control selections dynamically without affecting the entire dashboard, which is especially useful when working with data from multiple indices or when you need hierarchical filtering.

To chain variable controls, you 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 toolbar, 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, only the first tab will be 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.

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.

   

2. Select the dashboard to add the visualization to. You can choose 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.