expr

package
v4.0.0-rc.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 20, 2026 License: AGPL-3.0 Imports: 5 Imported by: 0

Documentation

Overview

Package expr provides utilities for evaluating expressions against columnar.Datum values with a selection vector.

Package expr is EXPERIMENTAL and currently only intended to be used by github.com/grafana/loki/v4/pkg/dataobj.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Evaluate

func Evaluate(alloc *memory.Allocator, expr Expression, input columnar.Datum, selection memory.Bitmap) (columnar.Datum, error)

Evaluate processes expr against the provided input datum, producing a datum as a result using alloc.

The input datum determines how expressions resolve:

When selection is non-empty, only selected rows (where the bit is set) are guaranteed to have meaningful results in compute operations. Unselected rows have undefined values. Use compute.Filter on the return datum to materialize a selection. A zero-value memory.Bitmap selects all rows.

The return type of Evaluate depends on the expression provided. See the documentation for implementations of Expression for what they produce when evaluated. Scalar results are broadcast to the length of an Array input.

func ForEach

func ForEach(e Expression, fn func(Expression))

ForEach calls fn on each direct child expression of e. Leaf nodes have no children, so fn is never called for them.

func Reduce

func Reduce(alloc *memory.Allocator, e Expression, fn func(Expression) (columnar.Datum, error), selection memory.Bitmap) (columnar.Datum, error)

Reduce evaluates e by calling fn to resolve each child expression into a columnar.Datum, then computing the parent operation on those results.

Reduce is used when the caller wants to hook into evaluating sub-expressions.

Leaf expressions (Constant, Identity, Column) have no children to reduce and are delegated directly to fn.

func Walk

func Walk(e Expression, fn func(Expression))

Walk calls fn on e and then recursively on every descendant expression in pre-order. Nil expressions are silently skipped.

Types

type Binary

type Binary struct {
	Left  Expression
	Op    BinaryOp
	Right Expression
}

Binary is an Expression that performs a binary operation against a left and a right expression.

The result of the expression depends on value of BinaryOp. The documentation of BinaryOp will describe the behavior of the expression.

type BinaryOp

type BinaryOp int

BinaryOp denotes a binary operation to perform against two arguments.

const (
	// BinaryOpInvalid indicates an invalid binary operation. Evaluating a
	// BinaryOpInvalid will result in an error.
	BinaryOpInvalid BinaryOp = iota

	// BinaryOpEQ performs an equality (==) check of the left and right
	// expressions. The expressions must be of the same type.
	//
	// The result is a bool datum, which is either a bool scalar if both
	// arguments are scalars, otherwise the result is a bool array.
	BinaryOpEQ

	// BinaryOpNEQ performs an inequality (!=) check of the left and right
	// expressions. The expressions must be of the same type.
	//
	// The result is a bool datum, which is either a bool scalar if both
	// arguments are scalars, otherwise the result is a bool array.
	BinaryOpNEQ

	// BinaryOpGT performs a greater than (>) check of the left and right
	// expressions. The expressions must be of the same type, and must be
	// ordered (numeric or UTF8).
	//
	// The result is a bool datum, which is either a bool scalar if both
	// arguments are scalars, otherwise the result is a bool array.
	BinaryOpGT

	// BinaryOpGTE performs a greater than or equal (>=) check of the left and
	// right expressions. The expressions must be of the same type, and must be
	// ordered (numeric or UTF8).
	//
	// The result is a bool datum, which is either a bool scalar if both
	// arguments are scalars, otherwise the result is a bool array.
	BinaryOpGTE

	// BinaryOpLT performs a less than (<) check of the left and right
	// expressions. The expressions must be of the same type, and must be
	// ordered (numeric or UTF8).
	//
	// The result is a bool datum, which is either a bool scalar if both
	// arguments are scalars, otherwise the result is a bool array.
	BinaryOpLT

	// BinaryOpLTE performs a less than or equal (<=) check of the left and
	// right expressions. The expressions must be of the same type, and must be
	// ordered (numeric or UTF8).
	//
	// The result is a bool datum, which is either a bool scalar if both
	// arguments are scalars, otherwise the result is a bool array.
	BinaryOpLTE

	// BinaryOpAND performs a logical AND (&&) operation on the left and right
	// expressions. The expressions must be of bool type.
	//
	// The result is a bool datum, which is either a bool scalar if both
	// arguments are scalars, otherwise the result is a bool array.
	BinaryOpAND

	// BinaryOpOR performs a logical OR (||) operation on the left and right
	// expressions. The expressions must be of bool type.
	//
	// The result is a bool datum, which is either a bool scalar if both
	// arguments are scalars, otherwise the result is a bool array.
	BinaryOpOR

	// BinaryOpMatchRegex performs a regex match of the left and right expressions.
	//
	// The left expression denotes the datum to search, and must be a UTF8
	// scalar or array. The right expression denotes the regular expression to
	// match with, and must be a [Regexp]. If the expression matches the UTF8
	// value, the result is true.
	//
	// The result is a bool datum, which is either a bool scalar if both
	// arguments are scalars, otherwise the result is a bool array.
	BinaryOpMatchRegex

	// BinaryOpIn performs a membership check of the left and right expressions.
	//
	// The left expression denotes the datum to search. The right
	// expression denotes the set of values to search for, and must
	// be a [ValueSet] matching the left datum's type.
	//
	// If the value is found in the set, the result is true.
	//
	// The result is a bool datum, which is either a bool scalar if the
	// left datum is a scalar, otherwise the result is a bool array.
	BinaryOpIn

	// BinaryOpHasSubstr performs a case-sensitive substring check of the left
	// and right expressions.
	//
	// The left expression denotes the "haystack" to search, and must be a UTF8
	// scalar or array. The right expression denotes the "needle" to search
	// with, and must be a UTF8 scalar. If the needle is found in the haystack,
	// the result is true.
	//
	// The result is a bool datum, which is either a bool scalar if both
	// arguments are scalars, otherwise the result is a bool array.
	BinaryOpHasSubstr

	// BinaryOpHasSubstrIgnoreCase performs a case-insensitive substring check
	// of the left and right expressions.
	//
	// The left expression denotes the "haystack" to search, and must be a UTF8
	// scalar or array. The right expression denotes the "needle" to search
	// with, and must be a UTF8 scalar. If the needle is found in the haystack
	// (ignoring case), the result is true.
	//
	// The result is a bool datum, which is either a bool scalar if both
	// arguments are scalars, otherwise the result is a bool array.
	BinaryOpHasSubstrIgnoreCase
)

func (BinaryOp) String

func (op BinaryOp) String() string

String returns the string representation of op. If op is out of bounds, it returns "INVALID."

type Column

type Column struct{ Name string }

Column is an Expression that looks up the column by name in the record batch supplied to Evaluate.

If the column doesn't exist, a Null column is produced.

type Constant

type Constant struct{ Value columnar.Scalar }

Constant is an Expression that produces a scalar value. When a Constant is the final result evaluated against an Array, it is broadcast to the Array's length.

type Exclude

type Exclude struct {
	Names []string
	Value Expression
}

Exclude is an Expression that evaluates Value and returns a new *columnar.Struct with the fields matching Names removed.

Names that don't exist in the source struct are silently ignored.

type Expression

type Expression interface {
	// contains filtered or unexported methods
}

Expression represents an operation that can be evaluated to produce a result.

func Map

func Map(e Expression, fn func(Expression) Expression) Expression

Map returns a shallow copy of e with each direct child expression replaced by the result of fn. Leaf nodes (Column, Constant, Identity, Regexp, ValueSet) have no children and are returned unchanged.

type Extract

type Extract struct {
	Name  string
	Value Expression
}

Extract is an Expression that evaluates Value and extracts the field with the given Name from the resulting *columnar.Struct.

If the field doesn't exist, a Null column is produced.

type Identity

type Identity struct{}

Identity is an Expression that resolves to the input datum passed to Evaluate. It represents "the current data in scope" and is used by leaf-level layout readers where column references have been rewritten to Identity by parent readers.

type Include

type Include struct {
	Names []string
	Value Expression
}

Include is an Expression that evaluates Value and returns a new *columnar.Struct containing only the fields with the given Names.

Names that don't exist in the source struct are silently skipped.

type MakeStruct

type MakeStruct struct {
	Names  []string
	Values []Expression
}

MakeStruct is an Expression that evaluates each of the Values expressions and constructs a new *columnar.Struct with the given Names. Each value must evaluate to a columnar.Array, and all arrays must have the same length.

type Regexp

type Regexp struct{ Expression *regexp.Regexp }

Regexp is an Expression used as the right-hand side of a BinaryOpMatchRegex.

Regexp cannot be evaluated directly into a datum.

type Unary

type Unary struct {
	Op    UnaryOp
	Value Expression
}

Unary is an Expression that performs a unary operation against a single argument.

The result of the expression depends on value of UnaryOp. The documentation of UnaryOp will describe the behavior of the expression.

type UnaryOp

type UnaryOp int

UnaryOp denotes a unary operation to perform against a single argument.

const (
	// UnaryOpInvalid indicates an invalid unary operation. Evaluating a
	// UnaryOpInvalid will result in an error.
	UnaryOpInvalid UnaryOp = iota

	// UnaryOpNOT represents a logical NOT operation over a boolean value.
	UnaryOpNOT
)

func (UnaryOp) String

func (op UnaryOp) String() string

String returns the string representation of op. If op is out of bounds, it returns "INVALID."

type ValueSet

type ValueSet struct{ Values *columnar.Set }

ValueSet is an Expression used as the right-hand side of a BinaryOpIn.

ValueSet cannot be evaluated directly into a datum.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL