From ec8c0226928e519a7cdc9a333a3cadea43376410 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Wed, 7 May 2025 11:51:49 +0200 Subject: [PATCH 1/2] [DOCS][8.x] ESQL: Document LU JOIN/MV_EXPAND not respecting SORT --- docs/reference/esql/esql-lookup-join.asciidoc | 24 +++++++++++++++++++ .../esql/processing-commands/lookup.asciidoc | 2 +- .../processing-commands/mv_expand.asciidoc | 7 ++++++ 3 files changed, 32 insertions(+), 1 deletion(-) diff --git a/docs/reference/esql/esql-lookup-join.asciidoc b/docs/reference/esql/esql-lookup-join.asciidoc index 81ba6cea16902..d2d1951a989d4 100644 --- a/docs/reference/esql/esql-lookup-join.asciidoc +++ b/docs/reference/esql/esql-lookup-join.asciidoc @@ -231,6 +231,30 @@ To obtain a join key with a compatible type, use a For a complete list of supported data types and their internal representations, see the <>. +[discrete] +[[esql-lookup-join-usage-notes]] +==== Usage notes + +This section covers important details about `LOOKUP JOIN` that impact query behavior and results. Review these details to ensure your queries work as expected and to troubleshoot unexpected results. + +[discrete] +[[esql-lookup-join-usage-notes-name-collisions]] +===== Handling name collisions + +When fields from the lookup index match existing column names, the new columns override the existing ones. +Before the `LOOKUP JOIN` command, preserve columns by either: + +* Using `RENAME` to assign non-conflicting names +* Using `EVAL` to create new columns with different names + +[discrete] +[[esql-lookup-join-usage-notes-sorting]] +===== Sorting behavior + +The output rows produced by `LOOKUP JOIN` can be in any order and may not +respect preceding `SORT`s. To guarantee a certain ordering, place a `SORT` after +any `LOOKUP JOIN`s. + [discrete] [[esql-lookup-join-limitations]] ==== Limitations diff --git a/docs/reference/esql/processing-commands/lookup.asciidoc b/docs/reference/esql/processing-commands/lookup.asciidoc index 1a8a4823d2e2c..46bcf6545b3f9 100644 --- a/docs/reference/esql/processing-commands/lookup.asciidoc +++ b/docs/reference/esql/processing-commands/lookup.asciidoc @@ -50,7 +50,7 @@ results, the output will contain one row for each matching combination. [TIP] ==== -In case of name collisions, the newly created columns will override existing columns. +For important information about using `LOOKUP JOIN`, refer to <>. ==== *Examples* diff --git a/docs/reference/esql/processing-commands/mv_expand.asciidoc b/docs/reference/esql/processing-commands/mv_expand.asciidoc index 010701f7fc8ee..e7d256f6fc46f 100644 --- a/docs/reference/esql/processing-commands/mv_expand.asciidoc +++ b/docs/reference/esql/processing-commands/mv_expand.asciidoc @@ -19,6 +19,13 @@ MV_EXPAND column `column`:: The multivalued column to expand. +[WARNING] +====== +The output rows produced by `MV_EXPAND` can be in any order and may not respect +preceding `SORT`s. To guarantee a certain ordering, place a `SORT` after any +`MV_EXPAND`s. +====== + *Example* [source.merge.styled,esql] From a075cc94d8cc0c8867f9fb6de18494ead7b268ba Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Wed, 7 May 2025 11:56:43 +0200 Subject: [PATCH 2/2] Fix nasty asciidoc backticks --- docs/reference/esql/esql-lookup-join.asciidoc | 3 +-- docs/reference/esql/processing-commands/mv_expand.asciidoc | 4 ++-- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/reference/esql/esql-lookup-join.asciidoc b/docs/reference/esql/esql-lookup-join.asciidoc index d2d1951a989d4..f90a5c5b9ca4e 100644 --- a/docs/reference/esql/esql-lookup-join.asciidoc +++ b/docs/reference/esql/esql-lookup-join.asciidoc @@ -252,8 +252,7 @@ Before the `LOOKUP JOIN` command, preserve columns by either: ===== Sorting behavior The output rows produced by `LOOKUP JOIN` can be in any order and may not -respect preceding `SORT`s. To guarantee a certain ordering, place a `SORT` after -any `LOOKUP JOIN`s. +respect preceding `SORT` commands. To guarantee a certain ordering, place a `SORT` after any `LOOKUP JOIN` commands. [discrete] [[esql-lookup-join-limitations]] diff --git a/docs/reference/esql/processing-commands/mv_expand.asciidoc b/docs/reference/esql/processing-commands/mv_expand.asciidoc index e7d256f6fc46f..1139a9ce8f95c 100644 --- a/docs/reference/esql/processing-commands/mv_expand.asciidoc +++ b/docs/reference/esql/processing-commands/mv_expand.asciidoc @@ -22,8 +22,8 @@ The multivalued column to expand. [WARNING] ====== The output rows produced by `MV_EXPAND` can be in any order and may not respect -preceding `SORT`s. To guarantee a certain ordering, place a `SORT` after any -`MV_EXPAND`s. +preceding `SORT` commands. To guarantee a certain ordering, place a `SORT` after any +`MV_EXPAND` commands. ====== *Example*