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 ¶
- func Evaluate(alloc *memory.Allocator, expr Expression, input columnar.Datum, ...) (columnar.Datum, error)
- func ForEach(e Expression, fn func(Expression))
- func Reduce(alloc *memory.Allocator, e Expression, ...) (columnar.Datum, error)
- func Walk(e Expression, fn func(Expression))
- type Binary
- type BinaryOp
- type Column
- type Constant
- type Exclude
- type Expression
- type Extract
- type Identity
- type Include
- type MakeStruct
- type Regexp
- type Unary
- type UnaryOp
- type ValueSet
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:
- Identity resolves to the input datum directly.
- Column requires the input to be a *columnar.Struct and looks up the field by name.
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 )
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 ¶
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 ¶
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.
type ValueSet ¶
ValueSet is an Expression used as the right-hand side of a BinaryOpIn.
ValueSet cannot be evaluated directly into a datum.