diff --git a/explore-analyze/dashboards/add-controls.md b/explore-analyze/dashboards/add-controls.md index cf078236f6..2cf3b1fa55 100644 --- a/explore-analyze/dashboards/add-controls.md +++ b/explore-analyze/dashboards/add-controls.md @@ -116,6 +116,64 @@ Change the settings for the Options list and Range slider controls. 1. Hover over the control you want to edit, then click ![The Edit control icon that opens the Edit control flyout](../../images/kibana-dashboard_controlsEditControl_8.3.0.png ""). 2. On the **Edit control** flyout, change the options, then click **Save and close**. +## Add controls from your ES|QL visualization's query [add-esql-control] +```{applies_to} +stack: preview +serverless: preview +``` + +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. This enables controls that only +apply to a specific panel, and exposes visualization configuration such as date histogram interval controls to dashboard users. + +:::{note} +Currently, only **Options lists** with static values are supported for ES|QL-based controls. +::: + +1. While editing your ES|QL visualization's query, the autocomplete menu suggests adding a control. + + ![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: + + * The name of the control. That is the name that will appear in your ES|QL query, prefixed with a `?` symbol. + * Values available to select for users with this control. You can add multiple values from suggested fields, or type in custom values. + * 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%") + +3. Save the control. The panel closes and the control's name is inserted into your query. + + +**Examples** + +* Integrate filtering into your ES|QL 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 + ``` + +![Editing ES|QL controls from a dashboard](https://images.contentstack.io/v3/assets/bltefdd0b53724fa2ce/blte42dfaa404bfc2d6/67d2e31e2e4dc59da190d78f/dashboard-esql-controls.gif) + ## Remove controls [remove-controls] diff --git a/explore-analyze/discover/discover-get-started.md b/explore-analyze/discover/discover-get-started.md index d655654f6e..3442617ab4 100644 --- a/explore-analyze/discover/discover-get-started.md +++ b/explore-analyze/discover/discover-get-started.md @@ -251,6 +251,10 @@ You can use **Discover** with the Elasticsearch Query Language, ES|QL. When usin You can switch to the ES|QL mode of Discover from the application menu bar. +:::{tip} +If you've entered a KQL or Lucene query in the default mode of Discover, it automatically converts to ES|QL. +::: + Note that in ES|QL mode, the **Documents** tab is named **Results**. Learn more about how to use ES|QL queries in [Using ES|QL](try-esql.md). diff --git a/explore-analyze/discover/try-esql.md b/explore-analyze/discover/try-esql.md index 6774946a13..c7299e41bb 100644 --- a/explore-analyze/discover/try-esql.md +++ b/explore-analyze/discover/try-esql.md @@ -10,7 +10,7 @@ mapped_pages: The Elasticsearch Query Language, {{esql}}, makes it easier to explore your data without leaving Discover. -In this tutorial we’ll use the {{kib}} sample web logs in Discover and Lens to explore the data and create visualizations. +The examples on this page use the {{kib}} sample web logs in Discover and Lens to explore the data and create visualizations. You can also install it by following [Add sample data](../index.md#gs-get-data-into-kibana). ::::{tip} For the complete {{esql}} documentation, refer to the [{{esql}} documentation](../query-filter/languages/esql.md). For a more detailed overview of {{esql}} in {{kib}}, refer to [Use {{esql}} in Kibana](../query-filter/languages/esql-kibana.md). @@ -28,14 +28,17 @@ To view the {{esql}} option in **Discover**, the `enableESQL` setting must be en To load the sample data: -1. [Install the web logs sample data](../index.md#gs-get-data-into-kibana). -2. Go to **Discover**. -3. Select **Try {{esql}}** from the application menu bar. +1. Go to **Discover**. +2. Select **Try {{esql}}** from the application menu bar. -Let’s say we want to find out what operating system users have and how much RAM is on their machine. + :::{tip} + If you've entered a KQL or Lucene query in the default mode of Discover, it automatically converts to ES|QL. + ::: -1. Set the time range to **Last 7 days**. -2. Copy the query below: + Let’s say we want to find out what operating system users have and how much RAM is on their machine. + +3. Set the time range to **Last 7 days**. +4. Copy the query below: ```esql FROM kibana_sample_data_logs <1> @@ -49,7 +52,7 @@ Let’s say we want to find out what operating system users have and how much RA Put each processing command on a new line for better readability. :::: -3. Click **▶Run**. +5. Click **▶Run**. ![An image of the query result](/explore-analyze/images/kibana-esql-machine-os-ram.png "") ::::{note} {{esql}} keywords are not case sensitive. @@ -70,7 +73,7 @@ Let’s add `geo.dest` to our query, to find out the geographical destination of ::::{note} When you don’t specify any specific fields to retain using `KEEP`, the visualization isn’t broken down automatically. Instead, an additional option appears above the visualization and lets you select a field manually. :::: - ![An image of the extended query result](/explore-analyze/images/kibana-esql-limit.png "") + ![An image of the extended query result](../../images/kibana-esql-limit.png "") We will now take it a step further to sort the data by machine ram and filter out the `GB` destination. @@ -87,7 +90,7 @@ We will now take it a step further to sort the data by machine ram and filter ou 2. Click **▶Run** again. The table and visualization no longer show results for which the `geo.dest` field value is "GB", and the results are now sorted in descending order in the table based on the `machine.ram` field. - ![An image of the full query result](/explore-analyze/images/kibana-esql-full-query.png "") + ![An image of the full query result](../../images/kibana-esql-full-query.png "") 3. Click **Save** to save the query and visualization to a dashboard. @@ -114,7 +117,7 @@ FROM kibana_sample_data_ecommerce | KEEP customer_first_name, email, products._id.keyword ``` -:::{image} /explore-analyze/images/kibana-esql-no-time-series.png +:::{image} ../../images/kibana-esql-no-time-series.png :alt: ESQL query without time series capabilities enabled ::: @@ -125,6 +128,14 @@ FROM kibana_sample_data_ecommerce | WHERE order_date >= ?_tstart and order_date <= ?_tend ``` -:::{image} /explore-analyze/images/kibana-esql-custom-time-series.png +:::{image} ../../images/kibana-esql-custom-time-series.png :alt: ESQL query with a custom time field enabled ::: + + +### ES|QL and LOOKUP JOINs + +The ES|QL editor supports [`LOOKUP JOIN`](elasticsearch://reference/query-languages/esql/esql-commands.md#esql-lookup-join) commands and suggests lookup mode indices and join condition fields. + +![Using the LOOKUP JOIN command to autocomplete an ES|QL query](https://images.contentstack.io/v3/assets/bltefdd0b53724fa2ce/blte43a30a93241d650/67c23670045f5839e5bfd1e4/lookup-join-demo.gif) + diff --git a/explore-analyze/images/esql-visualization-control-settings.png b/explore-analyze/images/esql-visualization-control-settings.png new file mode 100644 index 0000000000..92be940a53 Binary files /dev/null and b/explore-analyze/images/esql-visualization-control-settings.png differ diff --git a/explore-analyze/images/esql-visualization-control-suggestion.png b/explore-analyze/images/esql-visualization-control-suggestion.png new file mode 100644 index 0000000000..83884b70bd Binary files /dev/null and b/explore-analyze/images/esql-visualization-control-suggestion.png differ diff --git a/explore-analyze/images/esql-visualization-customization-options.png b/explore-analyze/images/esql-visualization-customization-options.png new file mode 100644 index 0000000000..9dd9bc732b Binary files /dev/null and b/explore-analyze/images/esql-visualization-customization-options.png differ diff --git a/explore-analyze/images/esql-visualization-customize-axis.png b/explore-analyze/images/esql-visualization-customize-axis.png new file mode 100644 index 0000000000..abf932f37e Binary files /dev/null and b/explore-analyze/images/esql-visualization-customize-axis.png differ diff --git a/explore-analyze/query-filter/languages/esql-kibana.md b/explore-analyze/query-filter/languages/esql-kibana.md index 347eee1a8d..8e2deb95f0 100644 --- a/explore-analyze/query-filter/languages/esql-kibana.md +++ b/explore-analyze/query-filter/languages/esql-kibana.md @@ -33,7 +33,7 @@ To get started with {{esql}}, go to **Discover**. Next, select **Try ES|QL** fro ### The query bar [esql-kibana-query-bar] -After switching to {{esql}} mode, the query bar shows a sample query. For example: +After switching to {{esql}} mode, the query bar shows your previous KQL or Lucene query converted into {{esql}}. If the query was empty, it shows a sample query. For example: ```esql from kibana_sample_data_logs | limit 10 @@ -78,6 +78,7 @@ You can do that using the **Add line breaks on pipes** button from the query edi :::{image} /explore-analyze/images/esql-line-breakdown.gif :alt: Automatic line breaks for ES|QL queries +:width: 50% ::: You can adjust the editor’s height by dragging its bottom border to your liking. @@ -235,22 +236,22 @@ You can save the visualization to a new or existing dashboard by clicking the sa You can use {{esql}} queries to create panels on your dashboards. To add a panel to a dashboard, under **Dashboards**, click the **Add panel** button and select {{esql}}. -:::{image} /explore-analyze/images/elasticsearch-reference-esql-dashboard-panel.png -:alt: esql dashboard panel -::: - Check the {{esql}} query by clicking the Panel filters button (![Panel filters button on panel header](/explore-analyze/images/elasticsearch-reference-dashboard_panel_filter_button.png "")): :::{image} /explore-analyze/images/elasticsearch-reference-esql-dashboard-panel-query.png :alt: esql dashboard panel query +:width: 50% ::: You can also edit the {{esql}} visualization from here. Click the options button in the top-right (![esql icon options](/explore-analyze/images/elasticsearch-reference-esql-icon-options.svg "")) and select **Edit ESQL visualization** to open the in-line editor. :::{image} /explore-analyze/images/elasticsearch-reference-esql-dashboard-panel-edit-visualization.png :alt: esql dashboard panel edit visualization +:width: 50% ::: +You can also [Add dashboard controls from your ES|QL visualization's query](/explore-analyze/dashboards/add-controls.md#add-esql-control) + ## Create an enrich policy [esql-kibana-enrich] @@ -258,18 +259,21 @@ The {{esql}} [`ENRICH`](elasticsearch://reference/query-languages/esql/esql-comm :::{image} /explore-analyze/images/elasticsearch-reference-esql-kibana-enrich-autocomplete.png :alt: esql kibana enrich autocomplete +:width: 50% ::: Next, you can enter a policy name, the policy type, source indices, and optionally a query: :::{image} /explore-analyze/images/elasticsearch-reference-esql-kibana-enrich-step-1.png :alt: esql kibana enrich step 1 +:width: 50% ::: Click **Next** to select the match field and enrich fields: :::{image} /explore-analyze/images/elasticsearch-reference-esql-kibana-enrich-step-2.png :alt: esql kibana enrich step 2 +:width: 50% ::: Finally, click **Create and execute**. @@ -291,6 +295,7 @@ You can use {{esql}} queries to create alerts. From Discover, click **Alerts** a :::{image} /explore-analyze/images/elasticsearch-reference-esql-kibana-create-rule.png :alt: esql kibana create rule +:width: 50% ::: diff --git a/explore-analyze/visualize/esorql.md b/explore-analyze/visualize/esorql.md index 3447c698a2..d5f0c01e64 100644 --- a/explore-analyze/visualize/esorql.md +++ b/explore-analyze/visualize/esorql.md @@ -31,4 +31,20 @@ You can then **Save** and add it to an existing or a new dashboard using the sav ![Previewing an ESQL visualization](https://images.contentstack.io/v3/assets/bltefdd0b53724fa2ce/blt69dcceb4f1e12bc1/66c752d6aff77d384dc44209/edit-esql-visualization.gif "") -4. Select **Apply and close** to save the visualization to the dashboard. +4. You can bind controls to your ES|QL visualizations in dashboards by creating [ES|QL controls](../dashboards/add-controls.md#add-esql-control). +5. Select **Apply and close** to save the visualization to the dashboard. + + +## Customize the appearance of your {{esql}} visualization + +When editing an {{esql}} visualization, you can customize the appearance of the chart. To do that: + +1. Click one of the fields representing an axis of the chart to open its details. + + ![Click on the axis field to open its details](/explore-analyze/images/esql-visualization-customize-axis.png) + +2. Define the appearance of your choice from the available options. + + ![Appearance customization options for ESQL charts](/explore-analyze/images/esql-visualization-customization-options.png) + +3. Return to the previous menu, then **Apply and close** the configuration to save your changes.