Skip to content

ESQL: Improve LOOKUP JOIN page #125798

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Mar 28, 2025
Merged

ESQL: Improve LOOKUP JOIN page #125798

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
8 changes: 5 additions & 3 deletions docs/reference/query-languages/esql/esql-lookup-join.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ The `LOOKUP JOIN` command adds new columns to a table, with data from {{es}} ind

## 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 `null`s. 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 @@ -112,7 +112,9 @@ To use `LOOKUP JOIN`, the following requirements must be met:
* Numeric types follow these compatibility rules:
* `short` and `byte` are compatible with `integer` (all represented as `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 [conversion function](/reference/query-languages/esql/esql-functions-operators.md#esql-type-conversion-functions) if needed.

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).

Expand All @@ -121,7 +123,7 @@ For a complete list of supported data types and their internal representations,
The following are the current limitations with `LOOKUP JOIN`

* Indices in [lookup](/reference/elasticsearch/index-settings/index-modules.md#index-mode-setting) mode are always single-sharded.
* Cross cluster search is unsupported. Both source and lookup indices must be local.
* 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.
Expand Down
Loading