Add variable controls to Discover queries

Variable controls help you make your queries more dynamic instead of having to maintain several versions of almost identical queries. Viewers change the value from the control. The query stays one query.

Before you begin

You need an ES|QL query in Discover. If you are new to that editor, start with Get started with ES|QL in Discover.

Add variable controls to your Discover queries

You can add them from your Discover ES|QL query.

Variable control in Discover

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.

×
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 to populate the list of options. Use this option to dynamically retrieve control values or to set up chained controls.
    
    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, use custom time parameters instead.
- The name of the control. You use this name to reference the control in ES|QL queries.
  - Start the name with ? for options that are static values.
  - Start the name with ?? for options that are fields or functions.
- 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.
- Whether the control allows a single selection or multiple selections. Multiple selections require using the MV_CONTAINS or MV_INTERSECTS functions in your query.
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.

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
		
```

Result: The control appears for the query, and its variable is inserted where you created it.

Allow multi-value selections for ES|QL-based variable controls

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

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. Use MV_INTERSECTS instead if matching any subset value is enough.
When defining the control, select the Allow multiple selections option.
Save the control.

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

Edit a variable control

Once a control is active for your query, you can still edit it by hovering over it and by selecting the Edit option that appears.

You can edit all the options described in Add variable controls to Discover queries > Add variable controls to your Discover queries.

When you save your edits, the control is updated for your query.

Import a Discover query along with its controls into a dashboard

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.

Save the ES|QL query containing the variable control into a Discover session. If your Discover session contains several tabs:
- You can choose which tab the panel displays after adding the session to a dashboard.
- Only the first tab is imported to the dashboard.
Go to Dashboards and open or create one.
Select Add, then From library.
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.

Importing Discover session with controls into a dashboard

Method 2: Adding the Discover visualization

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

Next to the Discover visualization, select Save visualization to dashboard (or Save visualization in earlier versions).

×
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.