lookup join first draft

Author: georgewallace

docs/images/esql-lookup-join.png

@@ -39,6 +39,7 @@ An {{esql}} source command produces a table, typically with data from {{es}}. An
 * [`GROK`](#esql-grok)
 * [`KEEP`](#esql-keep)
 * [`LIMIT`](#esql-limit)
+* [`LOOKUP JOIN`](#esql-lookup-join)
 * [preview] [`MV_EXPAND`](#esql-mv_expand)
 * [`RENAME`](#esql-rename)
 * [`SORT`](#esql-sort)
@@ -663,6 +664,50 @@ FROM employees
 | LIMIT 5
 ```
 
+## `LOOKUP JOIN` [esql-lookup-join]
+
+`LOOKUP JOIN` is useful for any scenario where you need to pull in information from a lookup index to streamline data enrichment and analysis.
+
+**Syntax**
+
+```esql
+FROM firewall_logs
+| LOOKUP JOIN threat_list ON source.IP
+```
+
+**Parameters**
+
+TBD
+
+**Description**
+
+TBD
+
+**Examples**
+
+TBD
+
+```esql
+FROM firewall_logs
+| LOOKUP JOIN threat_list ON source.IP
+```
+
+
+```esql
+FROM system_metrics
+| LOOKUP JOIN host_inventory ON host.name
+| LOOKUP JOIN employees ON host.name
+```
+
+TBD
+
+```esql
+FROM app_logs
+| LOOKUP JOIN service_owners ON service_id
+```
+
+
+In case of name collisions, the newly created columns will override existing columns.
 
 ## `MV_EXPAND` [esql-mv_expand]
 

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

@@ -0,0 +1,38 @@
+---
+navigation_title: "LOOKUP JOIN"
+mapped_pages:
+  - https://www.elastic.co/guide/en/elasticsearch/reference/current/esql-enrich-data.html
+---
+
+# LOOKUP JOIN [esql-lookup-join]
+
+The {{esql}} [`LOOKUP join`](/reference/query-languages/esql/esql-commands.md#esql-lookup-index) processing command combines, at query-time, data from one or more source indexes with field-value combinations found in an input table.
+
+For example, you can use `LOOKUP JOIN` to:
+
+* Pull in environment or ownership details for each host to enrich your metrics data
+* Quickly see if any source IPs match known malicious addresses.
+* Tag logs with the owning team or escalation info for faster triage and incident response.
+
+
+### How the `LOOKUP JOIN` command works [esql-how-lookup-join-works]
+
+The `LOOKUP JOIN` command adds new columns to a table, with data from {{es}} indices. It requires a few special components:
+
+:::{image} ../../../images/esql-lookup-join.png
+:alt: esql lookup join
+:::
+
+
+$$$esql-source-index$$$
+
+Source index
+:   An index which stores enrich data that the `LOOKUP` command can add to input tables. You can create and manage these indices just like a regular {{es}} index. You can use multiple source indices in an enrich policy. You also can use the same source index in multiple enrich policies.
+
+
+### Prerequisites [esql-enrich-prereqs]
+
+To use `LOOKUP JOIN`, you must have:
+
+* Data types of join key and join field in the lookup index need to generally be the same - up to widening of data types, where e.g. `short,byte` are considered equal to `integer`. Also, text fields can be used on the left hand side if and only if there is an exact subfield whose name is suffixed with `.keyword`.
+

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

@@ -513,6 +513,7 @@ toc:
           - file: query-languages/esql/esql-multivalued-fields.md
           - file: query-languages/esql/esql-process-data-with-dissect-grok.md
           - file: query-languages/esql/esql-enrich-data.md
+          - file: query-languages/esql/esql-lookup-join.md
           - file: query-languages/esql/esql-implicit-casting.md
           - file: query-languages/esql/esql-time-spans.md
           - file: query-languages/esql/limitations.md