Browse Source

Document remote lookup join in 9.2 (#134588)

* Document remote lookup join in 9.2
Stanislav Malyshev 3 weeks ago
parent
commit
2c6c042ed5
1 changed files with 11 additions and 2 deletions
  1. 11 2
      docs/reference/query-languages/esql/esql-lookup-join.md

+ 11 - 2
docs/reference/query-languages/esql/esql-lookup-join.md

@@ -37,7 +37,7 @@ The command requires two parameters:
 * The field(s) to join on. Can be either:
   * A single field name
   * A comma-separated list of field names {applies_to}`stack: ga 9.2`
-  
+
 ```esql
 LOOKUP JOIN <lookup_index> ON <field_name>  # Join on a single field
 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
 
 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.
 
+### Cross-cluster support
+
+{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).
+
+```esql
+FROM log-cluster-*:logs-* | LOOKUP JOIN hosts ON source.ip
+```
+
 ## Example
 
 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.
 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.
+* Cross cluster search is unsupported in versions prior to `9.2.0`. Both source and lookup indices must be local for these versions.
 * Currently, only matching on equality is supported.
 * In Stack versions `9.0-9.1`,`LOOKUP JOIN` can only use a single match field and a single index. Wildcards are not supported.
   * Aliases, datemath, and datastreams are supported, as long as the index pattern matches a single concrete index {applies_to}`stack: ga 9.1.0`.
 * 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.
 * 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`.
+* Cross-cluster `LOOKUP JOIN` can not be used after aggregations (`STATS`), `SORT` and `LIMIT` commands, and coordinator-side `ENRICH` commands.