diff --git a/docs/concepts/esql.asciidoc b/docs/concepts/esql.asciidoc new file mode 100644 index 0000000000000..413db3ed35bbc --- /dev/null +++ b/docs/concepts/esql.asciidoc @@ -0,0 +1,40 @@ +[[esql]] +=== {esql} + +preview::[] + +The Elasticsearch Query Language, {esql}, has been created to make exploring your data faster and easier using the **Discover** application. From version 8.11 you can try this new feature, which is enabled by default. + +[role="screenshot"] +image:images/esql-data-view-menu.png[An image of the Discover UI where users can access the {esql} feature, width=30%] + +This new piped language allows you to chain together multiple commands to query your data. Based on the query, Lens suggestions in Discover create a visualization of the query results. + +{esql} comes with its own dedicated {esql} Compute Engine for greater efficiency. From 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]. + +{esql} also features in-app help, 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] + +For more detailed information about the {esql} language, refer to {ref}/esql-language.html[Learning {esql}]. + +[float] +[[esql-observability]] +==== {observability} + +{esql} makes it much easier to analyze metrics, logs and traces from a single query. Find performance issues fast by defining fields on the fly, enriching data with lookups, and using simultaneous query processing. Combining {esql} with {ml} and AiOps can improve detection accuracy and use aggregated value thresholds. + +[float] +[[esql-security]] +==== Security + +Use {esql} to retrieve important information for investigation by using lookups. Enrich data and create new fields on the go to gain valuable insight for faster decision-making and actions. For example, perform a lookup on an IP address to identify its geographical location, its association with known malicious entities, or whether it belongs to a known cloud service provider all from one search bar. {esql} ensures more accurate alerts by incorporating aggregated values in detection rules. + +[float] +[[esql-whats-next]] +==== What's next? + +Full documentation for this language is available in the {es} documentation, refer to {ref}/esql.html[{esql}]. + +Alternatively, a short tutorial is available in the **Discover** section <>. \ No newline at end of file diff --git a/docs/concepts/images/esql-activated.png b/docs/concepts/images/esql-activated.png new file mode 100644 index 0000000000000..f1ac82548d4d4 Binary files /dev/null and b/docs/concepts/images/esql-activated.png differ diff --git a/docs/concepts/images/esql-data-view-menu.png b/docs/concepts/images/esql-data-view-menu.png new file mode 100644 index 0000000000000..fbbbdf44d315c Binary files /dev/null and b/docs/concepts/images/esql-data-view-menu.png differ diff --git a/docs/concepts/images/esql-in-app-help.png b/docs/concepts/images/esql-in-app-help.png new file mode 100644 index 0000000000000..eb818a11cbacb Binary files /dev/null and b/docs/concepts/images/esql-in-app-help.png differ diff --git a/docs/concepts/index.asciidoc b/docs/concepts/index.asciidoc index d7a18c7af1e7e..5e02b8f0d4d7c 100644 --- a/docs/concepts/index.asciidoc +++ b/docs/concepts/index.asciidoc @@ -155,8 +155,11 @@ include::data-views.asciidoc[] include::set-time-filter.asciidoc[] +include::esql.asciidoc[] + include::kuery.asciidoc[] include::lucene.asciidoc[] include::save-query.asciidoc[] + diff --git a/docs/discover/images/esql-activated.png b/docs/discover/images/esql-activated.png new file mode 100644 index 0000000000000..f1ac82548d4d4 Binary files /dev/null and b/docs/discover/images/esql-activated.png differ diff --git a/docs/discover/images/esql-full-query.png b/docs/discover/images/esql-full-query.png new file mode 100644 index 0000000000000..1d4a37af23a60 Binary files /dev/null and b/docs/discover/images/esql-full-query.png differ diff --git a/docs/discover/images/esql-limit.png b/docs/discover/images/esql-limit.png new file mode 100644 index 0000000000000..dbc9edc3cdc13 Binary files /dev/null and b/docs/discover/images/esql-limit.png differ diff --git a/docs/discover/images/esql-machine-os-ram.png b/docs/discover/images/esql-machine-os-ram.png new file mode 100644 index 0000000000000..2c936cecb9498 Binary files /dev/null and b/docs/discover/images/esql-machine-os-ram.png differ diff --git a/docs/discover/images/try-esql.png b/docs/discover/images/try-esql.png new file mode 100644 index 0000000000000..87abbf2fd3d73 Binary files /dev/null and b/docs/discover/images/try-esql.png differ diff --git a/docs/discover/try-esql.asciidoc b/docs/discover/try-esql.asciidoc new file mode 100644 index 0000000000000..cc6e4d62f17c4 --- /dev/null +++ b/docs/discover/try-esql.asciidoc @@ -0,0 +1,91 @@ +[[try-esql]] +== Try {esql} + +preview::[] + +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. + +[float] +[[prerequisite]] +=== Prerequisite + +To be able to select **Try {esql}** from the Data views menu the `discover:enableESQL` setting must be enabled from **Stack Management > Advanced Settings**. It is enabled by default. + +[float] +[[tutorial-try-esql]] +=== Trying {esql} + +To load the sample data: + +. On the home page, click **Try 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 *Try {esql}*. + +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 +---- ++ +. Click **Update**. ++ +[role="screenshot"] +image:images/esql-machine-os-ram.png[An image of the query result] ++ +[NOTE] +==== +{esql} keywords are not case sensitive. +==== + +Let's add `geo.dest` to our query, to find out the geographical destination of the visits, and limit the results. + +. Copy the query below: ++ +[source,esql] +---- +FROM kibana_sample_data_logs +| KEEP machine.os, machine.ram, geo.dest +| LIMIT 10 +---- ++ +. Click **Update**. ++ +[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. + +. Copy the query below: ++ +[source,esql] +---- +FROM kibana_sample_data_logs +| KEEP machine.os, machine.ram, geo.dest +| SORT machine.ram desc +| WHERE geo.dest != "GB" +| LIMIT 10 +---- ++ +. Click **Update**. ++ +[role="screenshot"] +image:images/esql-full-query.png[] ++ +. 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. + +To learn more about {esql}, try other tutorials, see more examples and reference material, refer to {ref}/esql.html[{esql}]. + + diff --git a/docs/user/discover.asciidoc b/docs/user/discover.asciidoc index 6f35e9a9d59ba..e2b3fc2e0916e 100644 --- a/docs/user/discover.asciidoc +++ b/docs/user/discover.asciidoc @@ -346,4 +346,7 @@ include::{kib-repo-dir}/discover/field-statistics.asciidoc[] include::{kib-repo-dir}/discover/log-pattern-analysis.asciidoc[] -include::{kib-repo-dir}/discover/search-sessions.asciidoc[] \ No newline at end of file +include::{kib-repo-dir}/discover/search-sessions.asciidoc[] + +include::{kib-repo-dir}/discover/try-esql.asciidoc[] +