diff --git a/docs/reference/query-languages/esql/_snippets/commands/layout/lookup-join.md b/docs/reference/query-languages/esql/_snippets/commands/layout/lookup-join.md index e25a0c75d8b85..2d39b39b11e8e 100644 --- a/docs/reference/query-languages/esql/_snippets/commands/layout/lookup-join.md +++ b/docs/reference/query-languages/esql/_snippets/commands/layout/lookup-join.md @@ -42,7 +42,7 @@ If multiple documents in the lookup index match a single row in your 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 [Usage notes](../../../../esql/esql-lookup-join.md#usage-notes). :::: **Examples** diff --git a/docs/reference/query-languages/esql/_snippets/commands/layout/mv_expand.md b/docs/reference/query-languages/esql/_snippets/commands/layout/mv_expand.md index 9812a7d0c2335..3e204a2a3d1be 100644 --- a/docs/reference/query-languages/esql/_snippets/commands/layout/mv_expand.md +++ b/docs/reference/query-languages/esql/_snippets/commands/layout/mv_expand.md @@ -22,6 +22,12 @@ 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** :::{include} ../examples/mv_expand.csv-spec/simple.md diff --git a/docs/reference/query-languages/esql/esql-lookup-join.md b/docs/reference/query-languages/esql/esql-lookup-join.md index 302681a511e00..d57437833c1b2 100644 --- a/docs/reference/query-languages/esql/esql-lookup-join.md +++ b/docs/reference/query-languages/esql/esql-lookup-join.md @@ -156,9 +156,27 @@ To obtain a join key with a compatible type, use a [conversion function](/refere For a complete list of supported data types and their internal representations, see the [Supported Field Types documentation](/reference/query-languages/esql/limitations.md#_supported_types). +## 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. + +### 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 + +### 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. + ## Limitations -The following are the current limitations with `LOOKUP JOIN` +The following are the current limitations with `LOOKUP JOIN`: * Indices in [`lookup` mode](/reference/elasticsearch/index-settings/index-modules.md#index-mode-setting) are always single-sharded. * Cross cluster search is unsupported initially. Both source and lookup indices must be local.