[DOCS][9.x] Improve ESQL reference docs information architecture (#127248)

* [DOCS][9.0]  Improve ESQL reference docs IA

- reorganized es|ql reference documentation from flat list to logical hierarchy
- created three main sections: syntax reference , special fields, advanced operations
- renamed pages with more consistent and task-oriented titles
- aligned navigation titles with page content
- improved introductory text for each section
- used parallel phrasing for similar concepts
- clarified the relationship between reference docs and conceptual docs


Co-authored-by: Alexander Spies <alexander.spies@elastic.co>

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

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.

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.
 

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.
 

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$$$

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.

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.

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:
 

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

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

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.

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