[8.x] [Docs] Update Kibana ESQL docs (elastic#199371) (elastic#199430)

# Backport

This will backport the following commits from `main` to `8.x`:
- [[Docs] Update Kibana ESQL docs
(elastic#199371)](elastic#199371)

<!--- Backport version: 9.4.3 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sqren/backport)

<!--BACKPORT
[{"author":{"name":"florent-leborgne","email":"[email protected]"},"sourceCommit":{"committedDate":"2024-11-08T09:35:25Z","message":"[Docs]
Update Kibana ESQL docs (elastic#199371)\n\nThis PR updates ESQL docs currently
in the Kibana guide. I'll do another\r\nPR to the Elasticsearch docs to
update the docs there as well.\r\n\r\nRel:
https://github.com/elastic/platform-docs-team/issues/552","sha":"cd7447db36613dc71d361ded1d1dec25ea4ed3bc","branchLabelMapping":{"^v9.0.0$":"main","^v8.17.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["Team:Docs","release_note:skip","v9.0.0","v8.16.0","backport:version","v8.17.0"],"title":"[Docs]
Update Kibana ESQL
docs","number":199371,"url":"https://github.com/elastic/kibana/pull/199371","mergeCommit":{"message":"[Docs]
Update Kibana ESQL docs (elastic#199371)\n\nThis PR updates ESQL docs currently
in the Kibana guide. I'll do another\r\nPR to the Elasticsearch docs to
update the docs there as well.\r\n\r\nRel:
https://github.com/elastic/platform-docs-team/issues/552","sha":"cd7447db36613dc71d361ded1d1dec25ea4ed3bc"}},"sourceBranch":"main","suggestedTargetBranches":["8.16","8.x"],"targetPullRequestStates":[{"branch":"main","label":"v9.0.0","branchLabelMappingKey":"^v9.0.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/199371","number":199371,"mergeCommit":{"message":"[Docs]
Update Kibana ESQL docs (elastic#199371)\n\nThis PR updates ESQL docs currently
in the Kibana guide. I'll do another\r\nPR to the Elasticsearch docs to
update the docs there as well.\r\n\r\nRel:
https://github.com/elastic/platform-docs-team/issues/552","sha":"cd7447db36613dc71d361ded1d1dec25ea4ed3bc"}},{"branch":"8.16","label":"v8.16.0","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"8.x","label":"v8.17.0","branchLabelMappingKey":"^v8.17.0$","isSourceBranch":false,"state":"NOT_CREATED"}]}]
BACKPORT-->

Co-authored-by: florent-leborgne <[email protected]>

docs/concepts/esql.asciidoc

@@ -8,15 +8,12 @@ Based on the query, Lens suggestions in Discover create a visualization of the q
 
 {esql} comes with its own dedicated {esql} Compute Engine for greater efficiency. With one query you can search, aggregate, calculate and perform data transformations without leaving **Discover**. Write your query directly in **Discover** or use the **Dev Tools** with the {ref}/esql-rest.html[{esql} API].
 
-Here's how to use {esql} in the data view selector in **Discover**:
+You can switch to the ES|QL mode of Discover from the application menu bar.
 
-[role="screenshot"]
-image:images/esql-data-view-menu.png[An image of the Discover UI where users can access the {esql} feature, width=30%, align="center"]
-
-{esql} also features in-app help, so you can get started faster and don't have to leave the application to check syntax. 
+{esql} also features in-app help and suggestions, so you can get started faster and don't have to leave the application to check syntax. 
 
 [role="screenshot"]
-image:images/esql-in-app-help.png[An image of the Discover UI where users can browse the in-app help]
+image:images/esql-in-app-help.png[The ES|QL syntax reference and the autocomplete menu]
 
 You can also use ES|QL queries to create panels on your dashboards, create enrich policies, and create alerting rules.
 

docs/discover/try-esql.asciidoc

@@ -5,11 +5,17 @@ The Elasticsearch Query Language, {esql}, makes it easier to explore your data w
 
 In this tutorial we'll use the {kib} sample web logs in Discover and Lens to explore the data and create visualizations. 
 
+[TIP]
+====
+For the complete {esql} documentation, including tutorials, examples and the full syntax reference, refer to the {ref}/esql.html[{es} documentation].
+For a more detailed overview of {esql} in {kib}, refer to {ref}/esql-kibana.html[Use {esql} in Kibana].
+====
+
 [float]
 [[prerequisite]]
 === Prerequisite 
 
-To be able to select **Language {esql}** from the Data views menu the `enableESQL` setting must be enabled from **Stack Management > Advanced Settings**. It is enabled by default. 
+To view the {esql} option in **Discover**, the `enableESQL` setting must be enabled from Kibana's **Advanced Settings**. It is enabled by default. 
 
 [float]
 [[tutorial-try-esql]]
@@ -21,20 +27,22 @@ To load the sample data:
 . Click **Other sample data sets**.
 . On the Sample web logs card, click **Add data**.
 . Open the main menu and select *Discover*.
-. From the Data views menu, select *Language {esql}*.
+. 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.  
 
 . Set the time range to **Last 7 days**.
-. Expand image:images/expand-icon-2.png[An image of the expand icon] the query bar.
-. Put each processing command on a new line for better readability.
 . Copy the query below:
 +
 [source,esql]
 ----
-FROM kibana_sample_data_logs 
-| KEEP machine.os, machine.ram
+FROM kibana_sample_data_logs <1>
+| KEEP machine.os, machine.ram <2>
 ----
+<1> We're specifically looking for data from the sample web logs we just installed.
+<2> We're only keeping the `machine.os` and `machine.ram` fields in the results table.
++
+TIP: Put each processing command on a new line for better readability.
 +
 . Click **▶Run**.
 +
@@ -57,12 +65,14 @@ FROM kibana_sample_data_logs
 | LIMIT 10
 ----
 +
-. Click **▶Run**.
+. Click **▶Run** again. You can notice that the table is now limited to 10 results. The visualization also updated automatically based on the query, and broke down the data for you.
++
+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.
 +
 [role="screenshot"]
 image:images/esql-limit.png[An image of the extended query result]
 
-Let's sort the data by machine ram and filter out the destination GB. 
+We will now take it a step further to sort the data by machine ram and filter out the `GB` destination. 
 
 . Copy the query below:
 +
@@ -75,18 +85,51 @@ FROM kibana_sample_data_logs
 | LIMIT 10
 ----
 +
-. Click **▶Run**.
+. 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. 
 +
 [role="screenshot"]
 image:images/esql-full-query.png[An image of the full query result]
 +
 . Click **Save** to save the query and visualization to a dashboard. 
 
-To make changes to the visualization you can use the visualization drop-down. To make changes to the colors used or the axes, or click the pencil icon. This opens an in-line editor where you can change the colors and axes of the visualization. 
+[float]
+==== Edit the ES|QL visualization
+
+You can make changes to the visualization by clicking the pencil icon. This opens additional settings that let you adjust the chart type, axes, breakdown, colors, and information displayed to your liking. If you're not sure which route to go, check one of the suggestions available in the visualization editor.
+
+If you'd like to keep the visualization and add it to a dashboard, you can save it using the floppy disk icon.
+
+[float]
+==== ES|QL and time series data
+
+By default, ES|QL identifies time series data when an index contains a `@timestamp` field. This enables the time range selector and visualization options for your query.
+
+If your index doesn't have an explicit `@timestamp` field, but has a different time field, you can still enable the time range selector and visualization options by calling the `?_start` and `?_tend` parameters in your query.
+
+For example, the eCommerce sample data set doesn't have a `@timestamp` field, but has an `order_date` field.
+
+By default, when querying this data set, time series capabilities aren't active. No visualization is generated and the time picker is disabled.
+
+[source,esql]
+----
+FROM kibana_sample_data_ecommerce 
+| KEEP customer_first_name, email, products._id.keyword
+----
+
+image::images/esql-no-time-series.png[ESQL query without time series capabilities enabled]
+
+While still querying the same data set, by adding the `?_start` and `?_tend` parameters based on the `order_date` field, **Discover** enables times series capabilities.
+
+[source,esql]
+----
+FROM kibana_sample_data_ecommerce 
+| WHERE order_date >= ?_tstart and order_date <= ?_tend
+----
+
+image::images/esql-custom-time-series.png[ESQL query with a custom time field enabled]
+
+
+
+
 
-[TIP]
-====
-For the complete {esql} documentation, including tutorials, examples and the full syntax reference, refer to the {ref}/esql.html[{es} documentation].
-For a more detailed overview of {esql} in {kib}, refer to {ref}/esql-kibana.html[Use {esql} in Kibana].
-====
 

docs/user/dashboard/create-visualizations.asciidoc

@@ -213,7 +213,7 @@ You can then **Save** and add it to an existing or a new dashboard using the sav
 . From your dashboard, select **Add panel**.
 . Choose **ES|QL** under **Visualizations**. An ES|QL editor appears and lets you configure your query and its associated visualization. The **Suggestions** panel can help you find alternative ways to configure the visualization.
 +
-TIP: Check the link:esql-language.html[ES|QL reference] to get familiar with the syntax and optimize your query.
+TIP: Check the link:{ref}/esql-language.html[ES|QL reference] to get familiar with the syntax and optimize your query.
 . When editing your query or its configuration, run the query to update the preview of the visualization.
 +
 image:https://images.contentstack.io/v3/assets/bltefdd0b53724fa2ce/blt69dcceb4f1e12bc1/66c752d6aff77d384dc44209/edit-esql-visualization.gif[Previewing an ESQL visualization]
@@ -232,7 +232,7 @@ The Maps editor has extensive documentation. For your reading comfort, we have m
 . From your dashboard, select **Add panel**.
 . Choose **Field statistics** under **Visualizations**. An ES|QL editor appears and lets you configure your query with the fields and information that you want to show.
 +
-TIP: Check the link:esql-language.html[ES|QL reference] to get familiar with the syntax and optimize your query.
+TIP: Check the link:{ref}/esql-language.html[ES|QL reference] to get familiar with the syntax and optimize your query.
 . When editing your query or its configuration, run the query to update the preview of the visualization.
 +
 image:https://images.contentstack.io/v3/assets/bltefdd0b53724fa2ce/blte2b1371159f5b9ff/66fc6ca13804eb2532b20727/field-statistics-preview-8.16.0.gif[Editing a field statistics dashboard panel and running the query to update the preview]