Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 10 additions & 7 deletions docs/reference/esql/esql-lookup-join.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ contains multi-valued entries, those entries will not match anything
[[esql-lookup-join-example]]
==== Example

`LOOKUP JOIN` has left-join behavior. If no rows match in the looked index, `LOOKUP JOIN` retains the incoming row and adds `null`s. If many rows in the lookedup index match, `LOOKUP JOIN` adds one row per match.
`LOOKUP JOIN` has left-join behavior. If no rows match in the lookup index, `LOOKUP JOIN` retains the incoming row and adds nulls. If many rows in the lookup index match, `LOOKUP JOIN` adds one row per match.

In this example, we have two sample tables:

Expand Down Expand Up @@ -151,8 +151,11 @@ as the same type in {esql}
`int`)
*** `float`, `half_float`, and `scaled_float` are compatible
with `double` (all represented as `double`)
** For text fields: You can use text fields on the left-hand side of the
join only if they have a `.keyword` subfield
** For text fields: You can only use text fields as the join key on the
left-hand side of the join and only if they have a `.keyword` subfield

To obtain a join key with a compatible type, use a
<<esql-type-conversion-functions,conversion function>> if needed.

For a complete list of supported data types and their internal
representations, see the <<esql-supported-types,Supported Field Types documentation>>.
Expand All @@ -164,14 +167,14 @@ representations, see the <<esql-supported-types,Supported Field Types documentat
The following are the current limitations with `LOOKUP JOIN`

* Indices in <<index-mode-setting,lookup>> mode are always single-sharded.
* Cross cluster search is unsupported. Both source and lookup indices
* Cross cluster search is unsupported initially. Both source and lookup indices
must be local.
* Currently, only matching on equality is supported.
* `LOOKUP JOIN` can only use a single match field and a single index.
Wildcards, aliases, datemath, and datastreams are not supported.
* 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 name of the match field in
`LOOKUP JOIN lu++_++idx ON match++_++field` must match an existing field
in the query. This may require renames or evals 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
Expand Down