elastic · florent-leborgne · Oct 17, 2025 · Oct 17, 2025 · Oct 17, 2025 · Oct 17, 2025
@@ -1,4 +1,4 @@
-To add a Discover query to a dashboard in a way that preserves the [controls created from Discover](/explore-analyze/discover/try-esql.md#add-variable-control-discover) and also adds them to the dashboard, do as follows:
+To add a Discover query to a dashboard in a way that preserves the [controls created from Discover](/explore-analyze/discover/try-esql.md#add-variable-control) and also adds them to the dashboard, do as follows:
 
 1. Save the {{esql}} 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.
 

@@ -0,0 +1,17 @@
+You can create controls that let users select multiple values. To do that:
+
+1. Add the [`MV_CONTAINS`](elasticsearch://reference/query-languages/esql/functions-operators/mv-functions.md#esql-mv_contains) function to your query, and [create a variable](#add-variable-control) as one of its parameters. For example:
+
+    ```esql
+    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.
@@ -0,0 +1,22 @@
+1. While you edit your {{esql}} query, the autocomplete menu suggests adding a control when relevant or when you type `?` in the query. Select **Create control**.
+
+   ![ESQL query prompting to add a control](/explore-analyze/images/esql-visualization-control-suggestion.png " =40%")
+
+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 {{esql}} query to populate the list of options.
+    * The name of the control. This name is used to reference the control in {{esql}} 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. {applies_to}`stack: ga 9.1`
+    * 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 {{esql}} query at this step.
+    * The label of the control. This is the label displayed in **Discover** or in the dashboard.
+    * The width of the control.
+    * Whether the control should allow selecting a single value or multiple values. This [requires using the `MV_CONTAINS` function in your query](#esql-multi-values-controls). {applies_to}`stack: preview 9.3` {applies_to}`serverless: preview`
+
+    ![ESQL control settings](/explore-analyze/images/esql-visualization-control-settings.png "title =40%")
+
+3. Save the control.
+
+The variable is inserted into your query, and the control appears.
@@ -109,29 +109,30 @@ Only **Options lists** are supported for {{esql}}-based controls. Options can be
 - functions {applies_to}`stack: ga 9.1`
 :::
 
-1. Use one of the following options to start creating a variable control:
-   - In **Edit** mode, select **Add** > **Controls** > **Variable control** in the toolbar. 
-   - On the **Create variable control** flyout, while editing your {{esql}} visualization's query, the autocomplete menu suggests adding a control when relevant or when typing `?` in the query.
-
-   ![ESQL query prompting to add a control](/explore-analyze/images/esql-visualization-control-suggestion.png)
-
-2. A menu opens to let you configure the control. This is where you can specify:
-
-   :::{include} ../_snippets/variable-control-form.md
-   :::
-
-3. Save the control. 
+:::{include} ../_snippets/variable-control-procedure.md
+:::
 
-The panel closes and the control is added to the dashboard.
 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 {{esql}} visualization queries by typing the control's name.
 
-:::{include} ../_snippets/variable-control-examples.md
+:::{tip}
+You can also create variable controls to add later to any query by selecting **Add** > **Controls** > **Variable control** in the dashboard's toolbar. 
 :::
 
 ![Editing {{esql}} controls from a dashboard](https://images.contentstack.io/v3/assets/bltefdd0b53724fa2ce/blte42dfaa404bfc2d6/67d2e31e2e4dc59da190d78f/dashboard-esql-controls.gif)
 
+:::{include} ../_snippets/variable-control-examples.md
+:::
+
+### Allow multi-value selections for {{esql}}-based variable controls [esql-multi-values-controls]
+```{applies_to}
+stack: preview 9.3
+serverless: preview
+```
+
+:::{include} ../_snippets/multi-value-esql-controls.md
+:::
+
 ### Import a Discover query along with its controls into a dashboard
 ```{applies_to}
 stack: preview 9.2

@@ -190,7 +190,7 @@ To view or edit an index:
 
 4. If you made changes, select **Save** before closing the flyout.
 
-### Add variable controls to your Discover queries [add-variable-control-discover]
+### Add variable controls to your Discover queries [add-variable-control]
 ```{applies_to}
 stack: preview 9.2
 serverless: preview
@@ -202,25 +202,26 @@ Variable controls help you make your queries more dynamic instead of having to m
 
 You can add them from your Discover {{esql}} query.
 
-1. While editing your {{esql}} query, the autocomplete menu suggests adding a control when relevant or when typing `?` in the query. Select **Create control**.
-
-2. A menu opens to let you configure the control. This is where you can specify:
-
-   :::{include} ../_snippets/variable-control-form.md
-   :::
+:::{include} ../_snippets/variable-control-procedure.md
+:::
 
-3. Save the control.
+:::{include} ../_snippets/variable-control-examples.md
+:::
 
-The variable is inserted into your query, and the control appears in the query editor.
+#### Allow multi-value selections for {{esql}}-based variable controls [esql-multi-values-controls]
+```{applies_to}
+stack: preview 9.3
+serverless: preview
+```
 
-:::{include} ../_snippets/variable-control-examples.md
+:::{include} ../_snippets/multi-value-esql-controls.md
 :::
 
 #### 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 {icon}`pencil` **Edit** option that appears.
 
-You can edit all of the options described in [](#add-variable-control-discover).
+You can edit all of the options described in [](#add-variable-control).
 
 When you save your edits, the control is updated for your query.
 

@@ -190,9 +190,6 @@ FROM kibana_sample_data_logs
 
 To display data within a specified time range, you can use the standard time filter, custom time parameters, or a WHERE command.
 
-% DO NOT REMOVE - Link from the product, will become a real section link shortly
-$$$esql-multi-values-controls$$$
-
 
 #### Standard time filter [_standard_time_filter]
 
@@ -227,6 +224,32 @@ FROM kibana_sample_data_logs
 | WHERE timestamp > NOW() - 15minutes
 ```
 
+
+### Create controls with {{esql}} variables [add-variable-control]
+
+{{esql}} variables help you add interactive controls to your queries and make them more dynamic.
+
+They're available for:
+* [Discover queries](/explore-analyze/discover/try-esql.md#add-variable-control) {applies_to}`stack: ga 9.2`
+* [{{esql}} visualizations in dashboards](/explore-analyze/dashboards/add-controls.md#add-variable-control)
+
+:::{include} ../../_snippets/variable-control-procedure.md
+:::
+
+:::{include} ../../_snippets/variable-control-examples.md
+:::
+
+% Link from the product
+#### Allow multi-value selections for {{esql}}-based variable controls [esql-multi-values-controls]
+```{applies_to}
+stack: preview 9.3
+serverless: preview
+```
+
+:::{include} ../../_snippets/multi-value-esql-controls.md
+:::
+
+
 ### LOOKUP JOINs
 
 The ES|QL editor supports [`LOOKUP JOIN`](elasticsearch://reference/query-languages/esql/commands/processing-commands.md#esql-lookup-join) commands and suggests lookup mode indices and join condition fields.