surrounding

Type of operation: Join

Description

Outer joins datasets by matching row time to a specified frame as well as column values.

Rows from the “right” (input) dataset that fall within the specified frame of at least one row in the “left” (default) dataset are unioned with the default dataset. The shape of output will be as if the right dataset and left dataset were combined using the union verb.

The column bindings are applied only to the rows of the input dataset. Rows from the right dataset will have these new columns set to null in the output.

Usage

surrounding frame, @source, [ column_binding_1, column_binding_2, ... ]

Argument	Type	Optional	Repeatable	Restrictions
frame	frame	no	no	constant
@source	dataset	no	no	dataset
column_binding	expression	yes	yes	none

Accelerable

surrounding 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

filter <panic>
surrounding frame(back: 2s, ahead: 2s), @logs, panic:true

After filtering to the rows matching “panic”, this pulls in all the rows from “logs” whose timestamp is within 2s of the filtered rows. In the output, rows from the input dataset will have “panic” field populated with true. Rows from the “logs” dataset will have this field set to null.