ESQL: Document LU JOIN/MV_EXPAND not respecting SORT (elastic#127718) (elastic#127808)

(cherry picked from commit 9e3ae5b)

Co-authored-by: Alexander Spies <[email protected]>

Author: leemthompo

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**

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

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.