From e83fd169daa1ce426217f8b5cbc304bbb662d27f Mon Sep 17 00:00:00 2001 From: Liam Thompson <32779855+leemthompo@users.noreply.github.com> Date: Wed, 7 May 2025 12:26:16 +0200 Subject: [PATCH] [DOCS][8.x] ESQL: Document LU JOIN/MV_EXPAND not respecting SORT (#127813) * [DOCS][8.x] ESQL: Document LU JOIN/MV_EXPAND not respecting SORT * Fix nasty asciidoc backticks --- docs/reference/esql/esql-lookup-join.asciidoc | 23 +++++++++++++++++++ .../esql/processing-commands/lookup.asciidoc | 2 +- .../processing-commands/mv_expand.asciidoc | 7 ++++++ 3 files changed, 31 insertions(+), 1 deletion(-) diff --git a/docs/reference/esql/esql-lookup-join.asciidoc b/docs/reference/esql/esql-lookup-join.asciidoc index 81ba6cea16902..f90a5c5b9ca4e 100644 --- a/docs/reference/esql/esql-lookup-join.asciidoc +++ b/docs/reference/esql/esql-lookup-join.asciidoc @@ -231,6 +231,29 @@ 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` commands. To guarantee a certain ordering, place a `SORT` after any `LOOKUP JOIN` commands. + [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..1139a9ce8f95c 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` commands. To guarantee a certain ordering, place a `SORT` after any +`MV_EXPAND` commands. +====== + *Example* [source.merge.styled,esql]