Skip to content

Commit e3836b5

Browse files
leemthompoalex-spies
leemthompo
and
alex-spies
authored
[DOCS][9.x] Improve ESQL reference docs information architecture (#127248) (#127380)
* [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 <[email protected]>
1 parent 70e495a commit e3836b5

12 files changed

+89
-60
lines changed

‎docs/reference/query-languages/esql.md‎

Lines changed: 10 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,23 @@
11
---
2-
navigation_title: "{{esql}} reference"
2+
navigation_title: "{{esql}}"
33
mapped_pages:
44
- https://www.elastic.co/guide/en/elasticsearch/reference/current/esql-language.html
55
---
66

77
# {{esql}} reference [esql-language]
88

99
:::{note}
10-
This section provides detailed **reference information**.
10+
This section provides detailed **reference information** about the {{esql}} language, including syntax, functions, and operators.
1111

12-
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.
12+
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.
1313
:::
1414

15-
* [Syntax reference](/reference/query-languages/esql/esql-syntax.md)
16-
* [Commands](/reference/query-languages/esql/esql-commands.md)
17-
* [Functions overview](/reference/query-languages/esql/esql-functions-operators.md#esql-functions)
18-
* [Metadata fields](/reference/query-languages/esql/esql-metadata-fields.md)
19-
* [Multivalued fields](/reference/query-languages/esql/esql-multivalued-fields.md)
20-
* [Data enrichment](/reference/query-languages/esql/esql-enrich-data.md)
21-
* [Data processing with DISSECT and GROK](/reference/query-languages/esql/esql-process-data-with-dissect-grok.md)
22-
* [Implicit casting](/reference/query-languages/esql/esql-implicit-casting.md)
23-
* [Time spans](/reference/query-languages/esql/esql-time-spans.md)
24-
25-
26-
27-
28-
29-
30-
31-
15+
{{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.
3216

17+
This reference section provides detailed technical information about {{esql}} features, syntax, and behavior:
3318

19+
* [Syntax reference](esql/esql-syntax-reference.md): Learn the basic syntax of commands, functions, and operators
20+
* [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
21+
* [Types and fields](esql/esql-types-and-fields.md): Learn about how {{esql}} handles different data types and special fields
22+
* [Limitations](esql/limitations.md): Learn about the current limitations of {{esql}}
23+
* [Examples](esql/esql-examples.md): Explore some example queries

‎docs/reference/query-languages/esql/esql-advanced.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
navigation_title: "Advanced workflows"
3+
---
4+
5+
# Advanced workflows in {{esql}}
6+
7+
These guides provide detailed information about more advanced workflows in {{esql}}.
8+
9+
* [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.
10+
* [Augment data with `ENRICH`](/reference/query-languages/esql/esql-enrich-data.md): Learn how to combine data from different indices.
11+
* [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‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,10 @@
11
---
2-
navigation_title: "Data enrichment"
2+
navigation_title: "Combine data with ENRICH"
33
mapped_pages:
44
- https://www.elastic.co/guide/en/elasticsearch/reference/current/esql-enrich-data.html
55
---
66

7-
# Data enrichment [esql-enrich-data]
8-
7+
# Combine data from multiple indices with `ENRICH` [esql-enrich-data]
98

109
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.
1110

‎docs/reference/query-languages/esql/esql-lookup-join.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
---
2-
navigation_title: "Correlate data with LOOKUP JOIN"
2+
navigation_title: "Join data with LOOKUP JOIN"
33
mapped_pages:
44
- https://www.elastic.co/guide/en/elasticsearch/reference/8.18/_lookup_join.html
55
---
66

7-
# LOOKUP JOIN [esql-lookup-join-reference]
7+
# Join data from multiple indices with `LOOKUP JOIN` [esql-lookup-join-reference]
88

99
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.
1010

‎docs/reference/query-languages/esql/esql-multivalued-fields.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,6 @@ mapped_pages:
66

77
# {{esql}} multivalued fields [esql-multivalued-fields]
88

9-
109
{{esql}} is fine reading from multivalued fields:
1110

1211
$$$esql-multivalued-fields-reorders$$$

‎docs/reference/query-languages/esql/esql-process-data-with-dissect-grok.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
---
2-
navigation_title: "Data processing with DISSECT and GROK"
2+
navigation_title: "Extract data with DISSECT and GROK"
33
mapped_pages:
44
- https://www.elastic.co/guide/en/elasticsearch/reference/current/esql-process-data-with-dissect-and-grok.html
55
---
66

7-
# Data processing with DISSECT and GROK [esql-process-data-with-dissect-and-grok]
7+
# Extract data from unstructured text with `DISSECT` and `GROK`[esql-process-data-with-dissect-and-grok]
88

99

1010
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‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
navigation_title: "Syntax reference"
3+
---
4+
5+
# ES|QL syntax reference
6+
7+
This section covers the essential syntax of the ES|QL language.
8+
9+
* [Basic syntax](esql-syntax.md): Learn the fundamentals of ES|QL query structure, including pipes, commands, and expressions.
10+
11+
* [Commands](esql-commands.md): Discover the core commands for data retrieval, filtering, aggregation, and transformation.
12+
13+
* [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‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,12 @@
11
---
2-
navigation_title: "Syntax reference"
2+
navigation_title: "Basic syntax"
33
mapped_pages:
44
- https://www.elastic.co/guide/en/elasticsearch/reference/current/esql-syntax.html
55
---
66

7-
# {{esql}} syntax reference [esql-syntax]
7+
# Basic {{esql}} syntax [esql-syntax]
88

9-
10-
11-
## Basic syntax [esql-basic-syntax]
9+
## Query structure [esql-basic-syntax]
1210

1311
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:
1412

‎docs/reference/query-languages/esql/esql-time-spans.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,6 @@ mapped_pages:
66

77
# {{esql}} time spans [esql-time-spans]
88

9-
109
Time spans represent intervals between two datetime values. There are currently two supported types of time spans:
1110

1211
* `DATE_PERIOD` specifies intervals in years, quarters, months, weeks and days

‎docs/reference/query-languages/esql/esql-types-and-fields.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
navigation_title: "Types and fields"
3+
---
4+
5+
# Types and special fields in {{esql}}
6+
7+
This section details how {{esql}} handles different data types and special fields.
8+
9+
* [Implicit casting](esql-implicit-casting.md): Understand how {{esql}} automatically converts between data types in expressions.
10+
11+
* [Time spans](esql-time-spans.md): Learn how to work with time intervals in {{esql}}.
12+
13+
* [Metadata fields](esql-metadata-fields.md): Learn about the metadata fields supported by {{esql}}, including `_index` and `_score`.
14+
15+
* [Multivalued fields](esql-multivalued-fields.md): Learn how to work with fields that contain multiple values in {{esql}}.

0 commit comments

Comments
 (0)