diff --git a/explore-analyze/_snippets/import-discover-query-controls-into-dashboard.md b/explore-analyze/_snippets/import-discover-query-controls-into-dashboard.md index a8ce4dd08b..c604d248f9 100644 --- a/explore-analyze/_snippets/import-discover-query-controls-into-dashboard.md +++ b/explore-analyze/_snippets/import-discover-query-controls-into-dashboard.md @@ -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. diff --git a/explore-analyze/_snippets/multi-value-esql-controls.md b/explore-analyze/_snippets/multi-value-esql-controls.md new file mode 100644 index 0000000000..e0247b0578 --- /dev/null +++ b/explore-analyze/_snippets/multi-value-esql-controls.md @@ -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. diff --git a/explore-analyze/_snippets/variable-control-form.md b/explore-analyze/_snippets/variable-control-form.md deleted file mode 100644 index 5bee780111..0000000000 --- a/explore-analyze/_snippets/variable-control-form.md +++ /dev/null @@ -1,11 +0,0 @@ -* 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. - * {applies_to}`stack: ga 9.1` 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 {{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. - - ![ESQL control settings](/explore-analyze/images/esql-visualization-control-settings.png "title =50%") \ No newline at end of file diff --git a/explore-analyze/_snippets/variable-control-procedure.md b/explore-analyze/_snippets/variable-control-procedure.md new file mode 100644 index 0000000000..d18c9e8532 --- /dev/null +++ b/explore-analyze/_snippets/variable-control-procedure.md @@ -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. \ No newline at end of file diff --git a/explore-analyze/dashboards/add-controls.md b/explore-analyze/dashboards/add-controls.md index d1f7fad5c2..6f6d8da6d9 100644 --- a/explore-analyze/dashboards/add-controls.md +++ b/explore-analyze/dashboards/add-controls.md @@ -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 diff --git a/explore-analyze/discover/try-esql.md b/explore-analyze/discover/try-esql.md index 80aa5e7338..520aa64030 100644 --- a/explore-analyze/discover/try-esql.md +++ b/explore-analyze/discover/try-esql.md @@ -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. diff --git a/explore-analyze/images/esql-visualization-control-suggestion.png b/explore-analyze/images/esql-visualization-control-suggestion.png index 85c3408ba4..14d499225e 100644 Binary files a/explore-analyze/images/esql-visualization-control-suggestion.png and b/explore-analyze/images/esql-visualization-control-suggestion.png differ diff --git a/explore-analyze/query-filter/languages/esql-kibana.md b/explore-analyze/query-filter/languages/esql-kibana.md index af836b2780..44b85bb36c 100644 --- a/explore-analyze/query-filter/languages/esql-kibana.md +++ b/explore-analyze/query-filter/languages/esql-kibana.md @@ -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.