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.