Skip to content

Commit 5e811fb

Browse files
smalyshevgmjehovich
authored andcommitted
Document remote lookup join in 9.2 (elastic#134588)
* Document remote lookup join in 9.2
1 parent 32a9b09 commit 5e811fb

File tree

1 file changed

+11
-2
lines changed

1 file changed

+11
-2
lines changed

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

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ The command requires two parameters:
3737
* The field(s) to join on. Can be either:
3838
* A single field name
3939
* A comma-separated list of field names {applies_to}`stack: ga 9.2`
40-
40+
4141
```esql
4242
LOOKUP JOIN <lookup_index> ON <field_name> # Join on a single field
4343
LOOKUP JOIN <lookup_index> ON <field_name1>, <field_name2>, <field_name3> # Join on multiple fields
@@ -49,6 +49,14 @@ LOOKUP JOIN <lookup_index> ON <field_name1>, <field_name2>, <field_name3> # Joi
4949

5050
If you're familiar with SQL, `LOOKUP JOIN` has left-join behavior. This means that if no rows match in the lookup index, the incoming row is retained and `null`s are added. If many rows in the lookup index match, `LOOKUP JOIN` adds one row per match.
5151

52+
### Cross-cluster support
53+
54+
{applies_to}`stack: ga 9.2.0` Remote lookup joins are supported in [cross-cluster queries](/reference/query-languages/esql/esql-cross-clusters.md). The lookup index must exist on _all_ remote clusters being queried, because each cluster uses its local lookup index data. This follows the same pattern as [remote mode Enrich](/reference/query-languages/esql/esql-cross-clusters.md#esql-enrich-remote).
55+
56+
```esql
57+
FROM log-cluster-*:logs-* | LOOKUP JOIN hosts ON source.ip
58+
```
59+
5260
## Example
5361

5462
You can run this example for yourself if you'd like to see how it works, by setting up the indices and adding sample data.
@@ -201,9 +209,10 @@ any `LOOKUP JOIN`s.
201209
The following are the current limitations with `LOOKUP JOIN`:
202210

203211
* Indices in [`lookup` mode](/reference/elasticsearch/index-settings/index-modules.md#index-mode-setting) are always single-sharded.
204-
* Cross cluster search is unsupported initially. Both source and lookup indices must be local.
212+
* Cross cluster search is unsupported in versions prior to `9.2.0`. Both source and lookup indices must be local for these versions.
205213
* Currently, only matching on equality is supported.
206214
* In Stack versions `9.0-9.1`,`LOOKUP JOIN` can only use a single match field and a single index. Wildcards are not supported.
207215
* Aliases, datemath, and datastreams are supported, as long as the index pattern matches a single concrete index {applies_to}`stack: ga 9.1.0`.
208216
* The name of the match field in `LOOKUP JOIN lu_idx ON match_field` must match an existing field in the query. This may require `RENAME`s or `EVAL`s to achieve.
209217
* The query will circuit break if there are too many matching documents in the lookup index, or if the documents are too large. More precisely, `LOOKUP JOIN` works in batches of, normally, about 10,000 rows; a large amount of heap space is needed if the matching documents from the lookup index for a batch are multiple megabytes or larger. This is roughly the same as for `ENRICH`.
218+
* Cross-cluster `LOOKUP JOIN` can not be used after aggregations (`STATS`), `SORT` and `LIMIT` commands, and coordinator-side `ENRICH` commands.

0 commit comments

Comments
 (0)