leftjoin on(...), [columnbinding: expression]*

Performs a temporal left outer join between the default input and exactly one other dataset, preserving every left-hand row and filling projected right-hand values with null when there is no matching right-hand row.

The predicate and trailing column bindings follow the same on(...) and name:expression rules as join. Window functions are not accepted in trailing bindings.

Output dataset kind and time columns

The result kind is chosen with the same precedence as join (event beats interval beats resource beats table), except this verb rejects the combination where the left input is not an event dataset and the right input is an event dataset. Time column names on the output generally follow the left input; when the left is a table and the right is a resource or interval, valid-from and valid-to from the right are brought in with prefixed names.

Keys and grouping

As with other join-family verbs, primary-key and grouping metadata on the output are generally cleared or relaxed unless the implementation preserves them for a specific case; do not assume the joined row type keeps the left input’s primary key without checking the resulting schema.

Compared to lookup

lookup keeps the left dataset kind and time columns and is tailored for enriching from resources, intervals, or tables; use leftjoin when you need a general left outer join or when the right side is an event dataset.

Categories

• Join

Accelerable

leftjoin is always accelerable if the input is accelerable. A dataset that only uses accelerable verbs can be accelerated, making queries on the dataset respond faster.

Examples

leftjoin on(station_id = @station.id), city:@station.city

Left-outer join so every measurement row is kept, with city populated only when a matching station row exists and null otherwise.

leftjoin on(month_number = @months.month_number), month_label:@months.month_name

Demonstrate a left join keyed only on month_number, leaving month_label null when no corresponding row exists in months (for example invalid month values).