diff --git a/docs/reference/query-languages/esql.md b/docs/reference/query-languages/esql.md index bd910f167270..034794af7d8e 100644 --- a/docs/reference/query-languages/esql.md +++ b/docs/reference/query-languages/esql.md @@ -1,5 +1,5 @@ --- -navigation_title: "{{esql}} reference" +navigation_title: "{{esql}}" mapped_pages: - https://www.elastic.co/guide/en/elasticsearch/reference/current/esql-language.html --- @@ -7,27 +7,17 @@ mapped_pages: # {{esql}} reference [esql-language] :::{note} -This section provides detailed **reference information**. +This section provides detailed **reference information** about the {{esql}} language, including syntax, functions, and operators. -For overview, conceptual, and getting started information, refer to the [{{esql}} language](docs-content://explore-analyze/query-filter/languages/esql.md) in the **Explore and analyze** section. +For overview, conceptual, and getting started information, refer to the [{{esql}} language overview](docs-content://explore-analyze/query-filter/languages/esql.md) in the **Explore and analyze** section. ::: -* [Syntax reference](/reference/query-languages/esql/esql-syntax.md) -* [Commands](/reference/query-languages/esql/esql-commands.md) -* [Functions overview](/reference/query-languages/esql/esql-functions-operators.md#esql-functions) -* [Metadata fields](/reference/query-languages/esql/esql-metadata-fields.md) -* [Multivalued fields](/reference/query-languages/esql/esql-multivalued-fields.md) -* [Data enrichment](/reference/query-languages/esql/esql-enrich-data.md) -* [Data processing with DISSECT and GROK](/reference/query-languages/esql/esql-process-data-with-dissect-grok.md) -* [Implicit casting](/reference/query-languages/esql/esql-implicit-casting.md) -* [Time spans](/reference/query-languages/esql/esql-time-spans.md) - - - - - - - - +{{esql}} is a piped query language for exploring and analyzing data in {{es}}. It is designed to be easy to use and understand, while also being powerful enough to handle complex data processing. +This reference section provides detailed technical information about {{esql}} features, syntax, and behavior: +* [Syntax reference](esql/esql-syntax-reference.md): Learn the basic syntax of commands, functions, and operators +* [Advanced workflows](esql/esql-advanced.md): Learn how to handle more complex tasks with these guides, including how to extract, transform, and combine data from multiple indices +* [Types and fields](esql/esql-types-and-fields.md): Learn about how {{esql}} handles different data types and special fields +* [Limitations](esql/limitations.md): Learn about the current limitations of {{esql}} +* [Examples](esql/esql-examples.md): Explore some example queries \ No newline at end of file diff --git a/docs/reference/query-languages/esql/esql-advanced.md b/docs/reference/query-languages/esql/esql-advanced.md new file mode 100644 index 000000000000..33171bdd4b34 --- /dev/null +++ b/docs/reference/query-languages/esql/esql-advanced.md @@ -0,0 +1,11 @@ +--- +navigation_title: "Advanced workflows" +--- + +# Advanced workflows in {{esql}} + +These guides provide detailed information about more advanced workflows in {{esql}}. + +* [Extract data with `DISSECT` and `GROK`](/reference/query-languages/esql/esql-process-data-with-dissect-grok.md): Learn how to extract and transform structured data from unstructured text. +* [Augment data with `ENRICH`](/reference/query-languages/esql/esql-enrich-data.md): Learn how to combine data from different indices. +* [Join data with `LOOKUP JOIN`](/reference/query-languages/esql/esql-lookup-join.md): Learn how to join data from different indices. \ No newline at end of file diff --git a/docs/reference/query-languages/esql/esql-enrich-data.md b/docs/reference/query-languages/esql/esql-enrich-data.md index 2871120459f4..ac225622700f 100644 --- a/docs/reference/query-languages/esql/esql-enrich-data.md +++ b/docs/reference/query-languages/esql/esql-enrich-data.md @@ -1,11 +1,10 @@ --- -navigation_title: "Data enrichment" +navigation_title: "Combine data with ENRICH" mapped_pages: - https://www.elastic.co/guide/en/elasticsearch/reference/current/esql-enrich-data.html --- -# Data enrichment [esql-enrich-data] - +# Combine data from multiple indices with `ENRICH` [esql-enrich-data] The {{esql}} [`ENRICH`](/reference/query-languages/esql/commands/processing-commands.md#esql-enrich) processing command combines, at query-time, data from one or more source indexes with field-value combinations found in {{es}} enrich indexes. diff --git a/docs/reference/query-languages/esql/esql-lookup-join.md b/docs/reference/query-languages/esql/esql-lookup-join.md index dc01cd2b0f9f..302681a511e0 100644 --- a/docs/reference/query-languages/esql/esql-lookup-join.md +++ b/docs/reference/query-languages/esql/esql-lookup-join.md @@ -1,10 +1,10 @@ --- -navigation_title: "Correlate data with LOOKUP JOIN" +navigation_title: "Join data with LOOKUP JOIN" mapped_pages: - https://www.elastic.co/guide/en/elasticsearch/reference/8.18/_lookup_join.html --- -# LOOKUP JOIN [esql-lookup-join-reference] +# Join data from multiple indices with `LOOKUP JOIN` [esql-lookup-join-reference] The {{esql}} [`LOOKUP JOIN`](/reference/query-languages/esql/commands/processing-commands.md#esql-lookup-join) processing command combines data from your {{esql}} query results table with matching records from a specified lookup index. It adds fields from the lookup index as new columns to your results table based on matching values in the join field. diff --git a/docs/reference/query-languages/esql/esql-multivalued-fields.md b/docs/reference/query-languages/esql/esql-multivalued-fields.md index cf6826e85342..9e065f3cfc93 100644 --- a/docs/reference/query-languages/esql/esql-multivalued-fields.md +++ b/docs/reference/query-languages/esql/esql-multivalued-fields.md @@ -6,7 +6,6 @@ mapped_pages: # {{esql}} multivalued fields [esql-multivalued-fields] - {{esql}} is fine reading from multivalued fields: $$$esql-multivalued-fields-reorders$$$ diff --git a/docs/reference/query-languages/esql/esql-process-data-with-dissect-grok.md b/docs/reference/query-languages/esql/esql-process-data-with-dissect-grok.md index 40e5d8ad095f..0e21b34b4bb0 100644 --- a/docs/reference/query-languages/esql/esql-process-data-with-dissect-grok.md +++ b/docs/reference/query-languages/esql/esql-process-data-with-dissect-grok.md @@ -1,10 +1,10 @@ --- -navigation_title: "Data processing with DISSECT and GROK" +navigation_title: "Extract data with DISSECT and GROK" mapped_pages: - https://www.elastic.co/guide/en/elasticsearch/reference/current/esql-process-data-with-dissect-and-grok.html --- -# Data processing with DISSECT and GROK [esql-process-data-with-dissect-and-grok] +# Extract data from unstructured text with `DISSECT` and `GROK`[esql-process-data-with-dissect-and-grok] Your data may contain unstructured strings that you want to structure. This makes it easier to analyze the data. For example, log messages may contain IP addresses that you want to extract so you can find the most active IP addresses. diff --git a/docs/reference/query-languages/esql/esql-syntax-reference.md b/docs/reference/query-languages/esql/esql-syntax-reference.md new file mode 100644 index 000000000000..0576aa7e03fe --- /dev/null +++ b/docs/reference/query-languages/esql/esql-syntax-reference.md @@ -0,0 +1,13 @@ +--- +navigation_title: "Syntax reference" +--- + +# ES|QL syntax reference + +This section covers the essential syntax of the ES|QL language. + +* [Basic syntax](esql-syntax.md): Learn the fundamentals of ES|QL query structure, including pipes, commands, and expressions. + +* [Commands](esql-commands.md): Discover the core commands for data retrieval, filtering, aggregation, and transformation. + +* [Functions and operators](esql-functions-operators.md): Explore the full range of functions and operators available for data manipulation and analysis. \ No newline at end of file diff --git a/docs/reference/query-languages/esql/esql-syntax.md b/docs/reference/query-languages/esql/esql-syntax.md index 42cf166d64ce..248c85ddd95d 100644 --- a/docs/reference/query-languages/esql/esql-syntax.md +++ b/docs/reference/query-languages/esql/esql-syntax.md @@ -1,14 +1,12 @@ --- -navigation_title: "Syntax reference" +navigation_title: "Basic syntax" mapped_pages: - https://www.elastic.co/guide/en/elasticsearch/reference/current/esql-syntax.html --- -# {{esql}} syntax reference [esql-syntax] +# Basic {{esql}} syntax [esql-syntax] - - -## Basic syntax [esql-basic-syntax] +## Query structure [esql-basic-syntax] An {{esql}} query is composed of a [source command](/reference/query-languages/esql/esql-commands.md) followed by an optional series of [processing commands](/reference/query-languages/esql/esql-commands.md), separated by a pipe character: `|`. For example: diff --git a/docs/reference/query-languages/esql/esql-time-spans.md b/docs/reference/query-languages/esql/esql-time-spans.md index 25d5b65c2603..0d4c285a1861 100644 --- a/docs/reference/query-languages/esql/esql-time-spans.md +++ b/docs/reference/query-languages/esql/esql-time-spans.md @@ -6,7 +6,6 @@ mapped_pages: # {{esql}} time spans [esql-time-spans] - Time spans represent intervals between two datetime values. There are currently two supported types of time spans: * `DATE_PERIOD` specifies intervals in years, quarters, months, weeks and days diff --git a/docs/reference/query-languages/esql/esql-types-and-fields.md b/docs/reference/query-languages/esql/esql-types-and-fields.md new file mode 100644 index 000000000000..f3ef7e447c9e --- /dev/null +++ b/docs/reference/query-languages/esql/esql-types-and-fields.md @@ -0,0 +1,15 @@ +--- +navigation_title: "Types and fields" +--- + +# Types and special fields in {{esql}} + +This section details how {{esql}} handles different data types and special fields. + +* [Implicit casting](esql-implicit-casting.md): Understand how {{esql}} automatically converts between data types in expressions. + +* [Time spans](esql-time-spans.md): Learn how to work with time intervals in {{esql}}. + +* [Metadata fields](esql-metadata-fields.md): Learn about the metadata fields supported by {{esql}}, including `_index` and `_score`. + +* [Multivalued fields](esql-multivalued-fields.md): Learn how to work with fields that contain multiple values in {{esql}}. diff --git a/docs/reference/query-languages/esql/limitations.md b/docs/reference/query-languages/esql/limitations.md index 77f98538a09f..615876d80662 100644 --- a/docs/reference/query-languages/esql/limitations.md +++ b/docs/reference/query-languages/esql/limitations.md @@ -6,8 +6,6 @@ mapped_pages: # {{esql}} limitations [esql-limitations] - - ## Result set size limit [esql-max-rows] By default, an {{esql}} query returns up to 1,000 rows. You can increase the number of rows up to 10,000 using the [`LIMIT`](/reference/query-languages/esql/commands/processing-commands.md#esql-limit) command. diff --git a/docs/reference/query-languages/toc.yml b/docs/reference/query-languages/toc.yml index aa442511d1e7..861435ccdc8c 100644 --- a/docs/reference/query-languages/toc.yml +++ b/docs/reference/query-languages/toc.yml @@ -84,32 +84,39 @@ toc: - file: query-dsl/regexp-syntax.md - file: esql.md children: - - file: esql/esql-syntax.md - - file: esql/esql-commands.md + - file: esql/esql-syntax-reference.md children: - - file: esql/commands/source-commands.md - - file: esql/commands/processing-commands.md - - file: esql/esql-functions-operators.md + - file: esql/esql-syntax.md + - file: esql/esql-commands.md + children: + - file: esql/commands/source-commands.md + - file: esql/commands/processing-commands.md + - file: esql/esql-functions-operators.md + children: + - file: esql/functions-operators/aggregation-functions.md + - file: esql/functions-operators/grouping-functions.md + - file: esql/functions-operators/conditional-functions-and-expressions.md + - file: esql/functions-operators/date-time-functions.md + - file: esql/functions-operators/ip-functions.md + - file: esql/functions-operators/math-functions.md + - file: esql/functions-operators/search-functions.md + - file: esql/functions-operators/spatial-functions.md + - file: esql/functions-operators/string-functions.md + - file: esql/functions-operators/type-conversion-functions.md + - file: esql/functions-operators/mv-functions.md + - file: esql/functions-operators/operators.md + - file: esql/esql-advanced.md children: - - file: esql/functions-operators/aggregation-functions.md - - file: esql/functions-operators/grouping-functions.md - - file: esql/functions-operators/conditional-functions-and-expressions.md - - file: esql/functions-operators/date-time-functions.md - - file: esql/functions-operators/ip-functions.md - - file: esql/functions-operators/math-functions.md - - file: esql/functions-operators/search-functions.md - - file: esql/functions-operators/spatial-functions.md - - file: esql/functions-operators/string-functions.md - - file: esql/functions-operators/type-conversion-functions.md - - file: esql/functions-operators/mv-functions.md - - file: esql/functions-operators/operators.md - - file: esql/esql-metadata-fields.md - - file: esql/esql-multivalued-fields.md - - file: esql/esql-process-data-with-dissect-grok.md - - file: esql/esql-enrich-data.md - - file: esql/esql-lookup-join.md - - file: esql/esql-implicit-casting.md - - file: esql/esql-time-spans.md + - file: esql/esql-process-data-with-dissect-grok.md + - file: esql/esql-enrich-data.md + - file: esql/esql-lookup-join.md + - file: esql/esql-types-and-fields.md + children: + - file: esql/esql-implicit-casting.md + - file: esql/esql-time-spans.md + - file: esql/esql-metadata-fields.md + - file: esql/esql-multivalued-fields.md + - file: esql/limitations.md - file: esql/esql-examples.md - file: sql.md