Merge branch 'main' into pinned-retriever

Author: mridula-s109

docs/changelog/126884.yaml

@@ -0,0 +1,5 @@
+pr: 126884
+summary: Rare terms aggregation false **positive** fix
+area: Aggregations
+type: bug
+issues: []

docs/changelog/127259.yaml

@@ -0,0 +1,5 @@
+pr: 127259
+summary: Replace auto-read with proper flow-control in HTTP pipeline
+area: Network
+type: enhancement
+issues: []

docs/reference/query-languages/esql.md

@@ -1,33 +1,23 @@
 ---
-navigation_title: "{{esql}} reference"
+navigation_title: "{{esql}}"
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/esql-language.html
 ---
 
 # {{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: