diff --git a/explore-analyze/_snippets/import-discover-query-controls-into-dashboard.md b/explore-analyze/_snippets/import-discover-query-controls-into-dashboard.md new file mode 100644 index 0000000000..a8ce4dd08b --- /dev/null +++ b/explore-analyze/_snippets/import-discover-query-controls-into-dashboard.md @@ -0,0 +1,17 @@ +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: + +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. + +1. Go to **Dashboards** and open or create one. + +1. Select **Add**, then **From library**. + +1. 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 controls into a dashboard](/explore-analyze/images/import-discover-control-dashboard.png " =40%") + +:::{note} +When you add a visualization to a dashboard using the {icon}`save` **Save visualization** option, controls are not added to the dashboard. +::: \ No newline at end of file diff --git a/explore-analyze/_snippets/variable-control-examples.md b/explore-analyze/_snippets/variable-control-examples.md new file mode 100644 index 0000000000..0e46bef222 --- /dev/null +++ b/explore-analyze/_snippets/variable-control-examples.md @@ -0,0 +1,25 @@ +**Examples** + +* Integrate filtering into your {{esql}} experience + + ```esql + | WHERE field == ?value + ``` + +* Fields in controls for dynamic group by + + ```esql + | STATS count=COUNT(*) BY ??field + ``` + +* Variable time ranges? Bind function configuration settings to a control + + ```esql + | BUCKET(@timestamp, ?interval), + ``` + +* Make the function itself dynamic + + ```esql + | STATS metric = ??function + ``` \ No newline at end of file diff --git a/explore-analyze/_snippets/variable-control-form.md b/explore-analyze/_snippets/variable-control-form.md new file mode 100644 index 0000000000..5bee780111 --- /dev/null +++ b/explore-analyze/_snippets/variable-control-form.md @@ -0,0 +1,11 @@ +* 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/dashboards/add-controls.md b/explore-analyze/dashboards/add-controls.md index c3ab46bef9..d1f7fad5c2 100644 --- a/explore-analyze/dashboards/add-controls.md +++ b/explore-analyze/dashboards/add-controls.md @@ -90,6 +90,10 @@ You can add one interactive time slider control to a dashboard. ## Add variable controls [add-variable-control] +```{applies_to} +stack: preview 9.0 +serverless: preview +``` :::{note} In versions `9.0` and `9.1`, variable controls are called {{esql}} controls. @@ -113,17 +117,8 @@ Only **Options lists** are supported for {{esql}}-based controls. Options can be 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**, select the options available in the controls by entering them manually or by using a dropdown listing available values. - * 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 of the control 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 for users viewing the dashboard for that control. - * The width of the control. - - ![ESQL control settings](/explore-analyze/images/esql-visualization-control-settings.png "title =50%") + :::{include} ../_snippets/variable-control-form.md + ::: 3. Save the control. @@ -132,34 +127,19 @@ If you added it by starting from a query, the control is directly inserted in th You can then insert it in any other {{esql}} visualization queries by typing the control's name. +:::{include} ../_snippets/variable-control-examples.md +::: -**Examples** - -* Integrate filtering into your {{esql}} experience - - ```esql - | WHERE field == ?value - ``` - -* Fields in controls for dynamic group by - - ```esql - | STATS count=COUNT(*) BY ?field - ``` - -* Variable time ranges? Bind function configuration settings to a control - - ```esql - | BUCKET(@timestamp, ?interval), - ``` - -* Make the function itself dynamic +![Editing {{esql}} controls from a dashboard](https://images.contentstack.io/v3/assets/bltefdd0b53724fa2ce/blte42dfaa404bfc2d6/67d2e31e2e4dc59da190d78f/dashboard-esql-controls.gif) - ```esql - | STATS metric = ?function - ``` +### Import a Discover query along with its controls into a dashboard +```{applies_to} +stack: preview 9.2 +serverless: preview +``` -![Editing {{esql}} controls from a dashboard](https://images.contentstack.io/v3/assets/bltefdd0b53724fa2ce/blte42dfaa404bfc2d6/67d2e31e2e4dc59da190d78f/dashboard-esql-controls.gif) +:::{include} ../_snippets/import-discover-query-controls-into-dashboard.md +::: ## Configure the controls settings [configure-controls-settings] diff --git a/explore-analyze/discover/try-esql.md b/explore-analyze/discover/try-esql.md index f5aff2ee09..80aa5e7338 100644 --- a/explore-analyze/discover/try-esql.md +++ b/explore-analyze/discover/try-esql.md @@ -188,4 +188,43 @@ To view or edit an index: Editing a lookup index affects all {{esql}} queries that reference it. Make sure that your changes are compatible with existing queries that use this index. ::: -4. If you made changes, select **Save** before closing the flyout. \ No newline at end of file +4. If you made changes, select **Save** before closing the flyout. + +### Add variable controls to your Discover queries [add-variable-control-discover] +```{applies_to} +stack: preview 9.2 +serverless: preview +``` + +Variable controls help you make your queries more dynamic instead of having to maintain several versions of almost identical queries. + +![Variable control in Discover](/explore-analyze/images/variable-control-discover.png " =75%") + +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 + ::: + +3. Save the control. + +The variable is inserted into your query, and the control appears in the query editor. + +:::{include} ../_snippets/variable-control-examples.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). + +When you save your edits, the control is updated for your query. + +#### Import a Discover query along with its controls into a dashboard + +:::{include} ../_snippets/import-discover-query-controls-into-dashboard.md +::: diff --git a/explore-analyze/images/import-discover-control-dashboard.png b/explore-analyze/images/import-discover-control-dashboard.png new file mode 100644 index 0000000000..d494294dc5 Binary files /dev/null and b/explore-analyze/images/import-discover-control-dashboard.png differ diff --git a/explore-analyze/images/variable-control-discover.png b/explore-analyze/images/variable-control-discover.png new file mode 100644 index 0000000000..786be9712d Binary files /dev/null and b/explore-analyze/images/variable-control-discover.png differ