Documentation
¶
Overview ¶
Package logical provides a logical query plan representation for data processing operations.
The logical plan is represented using static single-assignment (SSA) form of intermediate representation (IR) for the operations performed on log data.
For an introduction to SSA form, see https://en.wikipedia.org/wiki/Static_single_assignment_form.
The primary interfaces of this package are:
- Value, an expression that yields a value. - Instruction, a statement that consumes values and performs computation. - Plan, a sequence of instructions that produces a result.
A computation that also yields a result implements both the Value and Instruction interfaces. See the documentation comments on each type for which of those interfaces it implements.
Values are representable as either:
- A column value (such as in ColumnRef), - a relation (such as in Select), or - a value literal (such as in Literal).
The SSA form forms a graph: each Value may appear as an operand of one or more [Instruction]s.
Index ¶
- func PrintTree(w io.StringWriter, value Value)
- type BinOp
- type Builder
- func (b *Builder) Limit(skip uint64, fetch uint64) *Builder
- func (b *Builder) Schema() *schema.Schema
- func (b *Builder) Select(predicate Value) *Builder
- func (b *Builder) Sort(column ColumnRef, ascending, nullsFirst bool) *Builder
- func (b *Builder) ToPlan() (*Plan, error)
- func (b *Builder) Value() Value
- type ColumnRef
- type Instruction
- type Limit
- type Literal
- func (lit Literal) ByteArray() []byte
- func (lit Literal) Int64() int64
- func (lit Literal) IsNull() bool
- func (lit Literal) Kind() types.LiteralKind
- func (lit Literal) Name() string
- func (lit *Literal) Schema() *schema.Schema
- func (lit Literal) String() string
- func (lit Literal) Uint64() uint64
- func (lit Literal) Value() any
- type MakeTable
- type Plan
- type Return
- type Select
- type Sort
- type UnaryOp
- type Value
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func PrintTree ¶
func PrintTree(w io.StringWriter, value Value)
PrintTree prints the given value and its dependencies as a tree structure to w.
Types ¶
type BinOp ¶
The BinOp instruction yields the result of binary operation Left Op Right. BinOp implements both Instruction and Value.
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder provides an ergonomic interface for constructing a Plan.
func NewBuilder ¶
NewBuilder creates a new Builder from a Value, where the starting Value is usually a MakeTable.
func (*Builder) Schema ¶
Schema returns the schema of the data that will be produced by this Builder.
type ColumnRef ¶
type ColumnRef struct {
Column string // Name of the column being referenced.
Type types.ColumnType // Type of the column being referenced.
}
A ColumnRef referenes a column within a table relation. ColumnRef only implements Value.
func (*ColumnRef) Name ¶
Name returns the identifier of the ColumnRef, which combines the column type and column name being referenced.
type Instruction ¶
type Instruction interface {
// String returns the disassembled SSA form of the Instruction. This does not
// include the name of the Value if the Instruction also implements [Value].
String() string
// contains filtered or unexported methods
}
An Instruction is an SSA instruction that computes a new Value or has some effect.
Instructions that define a value (e.g., BinOp) also implement the Value interface; an Instruction that only has an effect (e.g., Return) does not.
type Limit ¶
type Limit struct {
Table Value // Table relation to limit.
// Skip is the number of rows to skip before returning results. A value of 0
// means no rows are skipped.
Skip uint64
// Fetch is the maximum number of rows to return. A value of 0 means all rows
// are returned (after applying Skip).
Fetch uint64
// contains filtered or unexported fields
}
The Limit instruction limits the number of rows from a table relation. Limit implements Instruction and Value.
type Literal ¶
type Literal struct {
// contains filtered or unexported fields
}
A Literal represents a literal value known at plan time. Literal only implements Value.
The zero value of a Literal is a NULL value.
func LiteralByteArray ¶
LiteralByteArray creates a new Literal value from a byte slice.
func LiteralInt64 ¶
LiteralInt64 creates a new Literal value from a 64-bit integer.
func LiteralString ¶
LiteralString creates a new Literal value from a string.
func LiteralUint64 ¶
LiteralUint64 creates a new Literal value from a 64-bit unsigned integer.
func (Literal) ByteArray ¶
ByteArray returns lit's value as a byte slice. It panics if lit is not a [LiteralKindByteArray].
func (Literal) Int64 ¶
Int64 returns lit's value as an int64. It panics if lit is not a [LiteralKindInt64].
func (Literal) Kind ¶
func (lit Literal) Kind() types.LiteralKind
Kind returns the kind of value represented by the literal.
func (Literal) String ¶
String returns a printable form of the literal, even if lit is not a [LiteralKindString].
type MakeTable ¶
type MakeTable struct {
// Selector is used to generate a table relation. All streams for which the
// selector passes are included in the resulting table.
//
// It is invalid for Selector to include a [ColumnRef] that is not
// [ColumnTypeBuiltin] or [ColumnTypeLabel].
Selector Value
// contains filtered or unexported fields
}
The MakeTable instruction yields a table relation from an identifier. MakeTable implements both Instruction and Value.
type Plan ¶
type Plan struct {
Instructions []Instruction // Instructions of the plan in order.
}
A Plan represents a sequence of [Instruction]s that ultimately produce a Value.
The first Return instruction in the plan denotes the final output.
type Return ¶
type Return struct {
Value Value // The value to return.
}
The Return instruction yields a value to return from a plan. Return implements Instruction.
type Select ¶
type Select struct {
Table Value // The table relation to filter.
// Predicate is used to filter rows from Table. Each row is checked against
// the given Predicate, and only rows for which the Predicate is true are
// returned.
Predicate Value
// contains filtered or unexported fields
}
The Select instruction filters rows from a table relation. Select implements both Instruction and Value.
type Sort ¶
type Sort struct {
Table Value // The table relation to sort.
Column ColumnRef // The column to sort by.
Ascending bool // Whether to sort in ascending order.
NullsFirst bool // Controls whether NULLs appear first (true) or last (false).
// contains filtered or unexported fields
}
The Sort instruction sorts rows from a table relation. Sort implements both Instruction and Value.
type UnaryOp ¶
The UnaryOp instruction yields the result of unary operation Op Value. UnaryOp implements both Instruction and Value.
type Value ¶
type Value interface {
// Name returns an identifier for this Value (such as "%1"), which is used
// when this Value appears as an operand of an Instruction.
//
// If the Value was not created by the logical planner, Name instead returns
// the pointer address of the Value.
Name() string
// String returns human-readable information about the Value. If Value also
// implements [Instruction], String returns the disassembled form of the
// Instruction as documented by [Instruction.String].
String() string
// Schema returns the type of this Value.
Schema() *schema.Schema
// contains filtered or unexported methods
}
A Value is an SSA value that can be referenced by an Instruction.