logical

package
v3.5.4 Latest Latest
Warning

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

Go to latest
Published: Sep 4, 2025 License: AGPL-3.0 Imports: 7 Imported by: 0

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

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

type BinOp struct {
	Left, Right Value
	Op          types.BinaryOp
	// contains filtered or unexported fields
}

The BinOp instruction yields the result of binary operation Left Op Right. BinOp implements both Instruction and Value.

func (*BinOp) Name

func (b *BinOp) Name() string

Name returns an identifier for the BinOp operation.

func (*BinOp) Schema

func (b *BinOp) Schema() *schema.Schema

Schema returns the schema of the BinOp operation.

func (*BinOp) String

func (b *BinOp) String() string

String returns the disassembled SSA form of the BinOp instruction.

type Builder

type Builder struct {
	// contains filtered or unexported fields
}

Builder provides an ergonomic interface for constructing a Plan.

func NewBuilder

func NewBuilder(val Value) *Builder

NewBuilder creates a new Builder from a Value, where the starting Value is usually a MakeTable.

func (*Builder) Limit

func (b *Builder) Limit(skip uint64, fetch uint64) *Builder

Limit applies a Limit operation to the Builder.

func (*Builder) Schema

func (b *Builder) Schema() *schema.Schema

Schema returns the schema of the data that will be produced by this Builder.

func (*Builder) Select

func (b *Builder) Select(predicate Value) *Builder

Select applies a Select operation to the Builder.

func (*Builder) Sort

func (b *Builder) Sort(column ColumnRef, ascending, nullsFirst bool) *Builder

Sort applies a Sort operation to the Builder.

func (*Builder) ToPlan

func (b *Builder) ToPlan() (*Plan, error)

ToPlan converts the Builder to a Plan.

func (*Builder) Value

func (b *Builder) Value() Value

Value returns the underlying Value. This is useful when you need to access the value directly, such as when passing it to a function that operates on values rather than a 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

func (c *ColumnRef) Name() string

Name returns the identifier of the ColumnRef, which combines the column type and column name being referenced.

func (*ColumnRef) Schema

func (c *ColumnRef) Schema() *schema.Schema

Schema returns the schema of the column being referenced.

func (*ColumnRef) String

func (c *ColumnRef) String() string

String returns ColumnRef.Name.

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.

func (*Limit) Name

func (l *Limit) Name() string

Name returns an identifier for the Limit operation.

func (*Limit) Schema

func (l *Limit) Schema() *schema.Schema

Schema returns the schema of the limit operation.

func (*Limit) String

func (l *Limit) String() string

String returns the disassembled SSA form of the Limit instruction.

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

func LiteralByteArray(v []byte) *Literal

LiteralByteArray creates a new Literal value from a byte slice.

func LiteralInt64

func LiteralInt64(v int64) *Literal

LiteralInt64 creates a new Literal value from a 64-bit integer.

func LiteralString

func LiteralString(v string) *Literal

LiteralString creates a new Literal value from a string.

func LiteralUint64

func LiteralUint64(v uint64) *Literal

LiteralUint64 creates a new Literal value from a 64-bit unsigned integer.

func (Literal) ByteArray

func (lit Literal) ByteArray() []byte

ByteArray returns lit's value as a byte slice. It panics if lit is not a [LiteralKindByteArray].

func (Literal) Int64

func (lit Literal) Int64() int64

Int64 returns lit's value as an int64. It panics if lit is not a [LiteralKindInt64].

func (Literal) IsNull

func (lit Literal) IsNull() bool

IsNull returns true if lit is a [LiteralKindNull] value.

func (Literal) Kind

func (lit Literal) Kind() types.LiteralKind

Kind returns the kind of value represented by the literal.

func (Literal) Name

func (lit Literal) Name() string

Name returns the string form of the literal.

func (*Literal) Schema

func (lit *Literal) Schema() *schema.Schema

func (Literal) String

func (lit Literal) String() string

String returns a printable form of the literal, even if lit is not a [LiteralKindString].

func (Literal) Uint64

func (lit Literal) Uint64() uint64

Uint64 returns lit's value as a uint64. It panics if lit is not a [LiteralKindUint64].

func (Literal) Value

func (lit Literal) Value() any

Value returns lit's value as untyped interface{}.

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.

func (*MakeTable) Name

func (t *MakeTable) Name() string

Name returns an identifier for the MakeTable operation.

func (*MakeTable) Schema

func (t *MakeTable) Schema() *schema.Schema

Schema returns the schema of the table. This implements part of the Plan interface.

func (*MakeTable) String

func (t *MakeTable) String() string

String returns the disassembled SSA form of the MakeTable instruction.

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.

func (Plan) String

func (p Plan) String() string

String prints out the entire plan SSA.

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.

func (*Return) String

func (r *Return) String() string

String returns the disassembled SSA form of r.

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.

func (*Select) Name

func (s *Select) Name() string

Name returns an identifier for the Select operation.

func (*Select) Schema

func (s *Select) Schema() *schema.Schema

Schema returns the schema of the Select plan.

func (*Select) String

func (s *Select) String() string

String returns the disassembled SSA form of the Select instruction.

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.

func (*Sort) Name

func (s *Sort) Name() string

Name returns an identifier for the Sort operation.

func (*Sort) Schema

func (s *Sort) Schema() *schema.Schema

Schema returns the schema of the sort plan.

func (*Sort) String

func (s *Sort) String() string

String returns the disassembled SSA form of the Sort instruction.

type UnaryOp

type UnaryOp struct {
	Op    types.UnaryOp
	Value Value
	// contains filtered or unexported fields
}

The UnaryOp instruction yields the result of unary operation Op Value. UnaryOp implements both Instruction and Value.

func (*UnaryOp) Name

func (u *UnaryOp) Name() string

Name returns an identifier for the UnaryOp operation.

func (*UnaryOp) Schema

func (u *UnaryOp) Schema() *schema.Schema

Schema returns the schema of the UnaryOp plan.

func (*UnaryOp) String

func (u *UnaryOp) String() string

String returns the disassembled SSA form of the UnaryOp instruction.

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.

Jump to

Keyboard shortcuts

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