Skip to main content
Version: v1.8.0

join

Operator

join combine data from two inputs using a join predicate

Synopsis

<left-input>
| [anti|inner|left|right] join (
<right-input>
) on <left-key>=<right-key> [<field>:=<right-expr>, ...]

( => <left-input> => <right-input> )
| [anti|inner|left|right] join on <left-key>=<right-key> [<field>:=<right-expr>, ...]
Note

The first join syntax shown above was more recently introduced and is in some ways similar to other languages such as SQL. The second was the original join syntax in Zed. Most joins can be expressed using either syntax. See the join tutorial for details.

Description

The join operator combines records from two inputs based on whether the <left-key> expression (evaluated in the context of the left input) is equal to the <right-key> expression (evaluated in the context of the right input) omitting values where there is no match (or including them in the case of anti join).

The available join types are:

  • inner - output only values that match
  • left - output all left values with merged components from <right-expr>
  • right - output as a left join but with the roles of the inputs and <right-expr> reversed
  • anti - output left values whose left key does not have a matching right key

For anti join, the <right-expr> is undefined and thus cannot be specified.

Currently, only exact equi-join is supported and the inputs must be sorted in ascending order by their respective keys. Also, the join keys must be field expressions. A future version of join will not require sorted inputs and will have more flexible join expressions.

Examples

The join tutorial includes several examples.