Joins two LogScale searches. When joining two searches, you need to define
the keys/fields that are used to match up results. This is done using the
field=name or
field=[name,name,...] parameter. If you want to
join on a single field name, you can use the syntax
fieldName =~ join(...) to specify
the field.
If the subquery has a different field that you want to match against, then
use the parameter key=[name1,name2,...] to
designate the names of keys inside the subquery. The value of keys
defaults to the value of field.
join() is a filter function which in the default
mode=inner lets the events through that match on
the join keys. If you specify mode=left then events
that do not match the join key(s) will also be let through.
If you specify include=[field, field, ...] then
those fields are extracted from the result of the subquery, and added to
matching events. For events in the subquery that do not have one or more
of the named include fields, the output will be the empty string.
Using the parameter max=N (which defaults to
max=1) you can specify how many
rows/events are picked up in the subquery. If a subquery has multiple
events with the same join key, then up to max rows are emitted.
You can use the parameters start and
end to specify an alternative time interval for the
query. The parameter view can be used to direct the subquery to run in a
different repository or view, and the
live=true|false parameter can be used to control if
the subquery runs as a live query. The defaults for all these parameters
are inherited from the main query containing the
join(...) usage.
The join() function also has a concept of a maximum
size of the resultset of the inner query specified with the
limit=100000 parameter.
Warning
The join() function does two passes over the data
and can therefore not run truly live.
When used in a live query, the query will be run in a repeated mode instead, in which the server chooses the repetition interval based on the resources used by the function.
This can impact the liveness of the query, in that long-running repeated queries can be throttled, and thus be less live than expected.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
end | string | false | End of time interval of subquery (milliseconds since UTC or 2d, 24h, 10sec, etc). Defaults to that of the main query. | |
field | [string] | true | Specifies which field in the event (log line) must match the given column value. | |
include | [string] | false | Specifies columns to include from the subquery. Default to none. | |
key | [string] | false | Specifies which fields of the subquery to join on. Defaults to the value of the field parameter. | |
limit | number | false | 100000 | Specifies the maximum number of rows in the subquery 1..100000. |
| Minimum | 1 | |||
| Maximum | 200000 | |||
live | boolean | false | Control if the subquery runs as live or static query Defaults to that of the main query. | |
max | number | false | 1 | Maximum number of events found in subquery if several share join key. |
mode | string | false | inner | Specifies the mode (inner or left) of the join. Defaults to inner. |
| Valid Values | inner | |||
| left | ||||
query | Function | false | The subquery to execute producing the values to join with. [a] | |
repo | string | false | Specify which view/repo in which to perform the subquery. Defaults to that of the main query. | |
start | string | false | Start of time interval of subquery (milliseconds since UTC or 2d, 24h, 10sec, etc). Defaults to that of the main query. | |
view | string | false | Specify which view/repo in which to perform the subquery. Defaults to that of the main query. | |
Find some examples at Joins section.