[ESQL in Kibana] 8.18 updates (#857)

^^

Includes: 

- ES|QL dashboard controls
- Support for LOOKUP JOIN with autocomplete suggestions
- KQL/Lucene query carried over when switching to ES|QL mode
- ES|QL viz customization options

Rel: elastic/platform-docs-team#614

Author: florent-leborgne

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]
 

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

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)
+

explore-analyze/images/esql-visualization-control-settings.png

@@ -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,41 +236,44 @@ 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]
 
 The {{esql}} [`ENRICH`](elasticsearch://reference/query-languages/esql/esql-commands.md#esql-enrich) command enables you to [enrich](elasticsearch://reference/query-languages/esql/esql-enrich-data.md) your query dataset with fields from another dataset. Before you can use `ENRICH`, you need to [create and execute an enrich policy](elasticsearch://reference/query-languages/esql/esql-enrich-data.md#esql-set-up-enrich-policy). If a policy exists, it will be suggested by auto-complete. If not, click **Click to create** to create one.
 
 :::{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%
 :::
 
 

explore-analyze/images/esql-visualization-control-suggestion.png

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