relalg

package
v0.1.19 Latest Latest
Warning

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

 Go to latest Published: Oct 17, 2026 License: MIT Imports: 2 Imported by: 0

Documentation

Overview

Package relalg defines a dialect-neutral relational algebra intermediate representation (IR). DML tools construct Expr trees (logical plans); the codegen package renders them into dialect-specific SQL.

The IR is relationally complete for safe read queries (selection, projection, aggregation, sort, limit, distinct) and DML (insert/update/delete over a predicate). Join and union are intentionally absent until needed — the surface stays deterministic, inject-proof, and gateable, excluding NL2SQL.

Expr and Predicate are sealed interfaces: their marker methods (rel, pred) are unexported, so external packages cannot add nodes. This keeps the algebra closed and the codegen exhaustively matchable.

Index

Constants

View Source 
const DefaultMaxINCardinality = 1000

DefaultMaxINCardinality is the safe default used by ValidatePredicate.

Variables

View Source 
var ErrINCardinality = errors.New("relalg: invalid IN cardinality")

ErrINCardinality is returned when an IN-list is empty, malformed, or exceeds the configured bound.

View Source 
var ErrInvalidAggFunc = errors.New("relalg: invalid aggregate function")

ErrInvalidAggFunc is returned when an aggregate uses a function outside the whitelist.

View Source 
var ErrInvalidOp = errors.New("relalg: invalid operator")

ErrInvalidOp is returned when a predicate uses an operator outside the whitelist.

View Source 
var ErrInvalidPredicate = errors.New("relalg: invalid predicate")

ErrInvalidPredicate is returned when a known predicate has an empty or otherwise malformed shape.

View Source 
var ErrUnknownPredicate = errors.New("relalg: unknown predicate")

ErrUnknownPredicate is returned when ValidatePredicate encounters a predicate type it does not recognize.

Functions

func HasExists added in v0.1.18 

func HasExists(p Predicate) bool

HasExists reports an EXISTS anywhere in p.

func ValidatePredicate 

func ValidatePredicate(p Predicate) error

ValidatePredicate recursively checks that every Condition uses a whitelisted operator. It returns nil for a nil predicate. Codegen calls this before rendering so malformed input fails early rather than producing bad SQL.

func ValidatePredicateWithMaxINCardinality 

func ValidatePredicateWithMaxINCardinality(p Predicate, maxIN int) error

ValidatePredicateWithMaxINCardinality validates a predicate and bounds every IN/NOT IN list. maxIN must be positive; zero never means unbounded.

Types

type AggCall 

type AggCall struct {
	Func     AggFunc
	Field    string
	Distinct bool
	// Name is the output column the call is known by above the γ node: a
	// τ or a Having names it (or a group-by field). The SQL never aliases
	// it: the call itself is rendered where it is named.
	Name string
}

AggCall is one aggregate in a γ node.

type AggFunc 

type AggFunc string

AggFunc is a whitelisted aggregate function name. Like Op, a user-supplied value never reaches SQL as a raw function string, preventing injection. 

const (
	AggCount AggFunc = "count"
	AggSum   AggFunc = "sum"
	AggAvg   AggFunc = "avg"
	AggMin   AggFunc = "min"
	AggMax   AggFunc = "max"
)

Whitelisted aggregate functions.

func (AggFunc) Valid 

func (f AggFunc) Valid() bool

Valid reports whether f is a whitelisted aggregate function.

type Aggregate 

type Aggregate struct {
	Input      Expr
	GroupBy    []string
	Aggregates []AggCall
}

Aggregate applies γ (grouping and aggregation) to its input.

type And 

type And struct{ Preds []Predicate }

And combines predicates conjunctively.

type Call 

type Call struct {
	Procedure RelationRef
	Args      []any
}

Call invokes a stored procedure with positional arguments.

type Condition 

type Condition struct {
	Field string
	Op    Op
	Value any
}

Condition is a leaf: field op value.

type Delete 

type Delete struct {
	Target    RelationRef
	Predicate Predicate
}

Delete is the relational assignment for delete, constrained by a predicate.

type Distinct 

type Distinct struct {
	Input Expr
}

Distinct applies δ (deduplication) to its input.

type Exists added in v0.1.18 

type Exists struct {
	Relation  RelationRef
	On        []JoinPair
	Predicate Predicate
}

Marker methods seal the Predicate interface. Exists holds when a row of Relation matches the row it is evaluated on (On: the row's Left column equals Relation's Right one) and Predicate, which names Relation's columns unqualified.

type Expr 

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

Expr is a relational algebra expression (logical plan node). Sealed: external packages cannot implement it.

func Input added in v0.1.13 

func Input(e Expr) (Expr, bool)

Input is the input of a unary node (σ, π, γ, τ, limit, δ); false for a scan, a literal relation or a write, which have none.

type Having added in v0.1.18 

type Having struct {
	Input     Expr
	Predicate Predicate
}

Having keeps the groups of an aggregate whose predicate is TRUE. Its conditions name the aggregate's output: a group-by field or an AggCall's Name.

type Insert 

type Insert struct {
	Target  RelationRef
	Columns []string
	Tuples  []Tuple
}

Insert is the relational assignment for create. Tuples supply the rows.

type Join added in v0.1.18 

type Join struct {
	Input          Expr
	Right          RelationRef
	Alias          string
	On             []JoinPair
	RightPredicate Predicate
}

Join extends each row of its input with the row of Right that matches On and RightPredicate, or with NULLs when none does: a left outer join of a relation matching at most one row (On names a key of Right). Right's columns are named Alias.column above it; RightPredicate (Right's row policy) names them unqualified.

type JoinPair added in v0.1.18 

type JoinPair struct {
	Left, Right string
}

JoinPair is one equality of a join: a column of the left side and one of the right.

type Limit 

type Limit struct {
	Input  Expr
	Count  int64
	Offset int64
}

Limit bounds the row count (and optional offset) of its input.

type Not 

type Not struct{ P Predicate }

Not negates a predicate.

type Op 

type Op string

Op is a whitelisted comparison operator. User input never reaches SQL as a raw operator string, preventing injection. 

const (
	OpEq        Op = "eq"
	OpNe        Op = "ne"
	OpGt        Op = "gt"
	OpGte       Op = "gte"
	OpLt        Op = "lt"
	OpLte       Op = "lte"
	OpIn        Op = "in"
	OpNotIn     Op = "not_in"
	OpLike      Op = "like"
	OpIsNull    Op = "is_null"
	OpIsNotNull Op = "is_not_null"
)

func (Op) Valid 

func (o Op) Valid() bool

Valid reports whether op is a whitelisted operator.

type Or 

type Or struct{ Preds []Predicate }

Or combines predicates disjunctively.

type OrderTerm 

type OrderTerm struct {
	Field string
	Dir   string
	// Nullable marks a field that may hold NULL. NULLs sort last whatever
	// the direction; a term not nullable is rendered without placing them
	// (the database's default), which keeps an index usable for the order.
	Nullable bool
}

OrderTerm is one column in a τ node. Dir is "asc" or "desc".

type Predicate 

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

Predicate is a parameterized boolean expression tree. Values bind to args at codegen time, never string-interpolated, preventing injection. Sealed.

type Project 

type Project struct {
	Input Expr
	Items []ProjectItem
}

Project applies π (column picking / renaming) to its input.

type ProjectItem 

type ProjectItem struct {
	Field string
	Alias string
}

ProjectItem is one column in a projection: the source field and an optional alias.

func ProjectFields added in v0.1.13 

func ProjectFields(fields []string) []ProjectItem

ProjectFields is the projection of fields, each as it is named.

type RelationRef 

type RelationRef struct {
	Schema string
	Name   string
}

RelationRef names a base relation (table/view/procedure) by schema and name.

type Scan 

type Scan struct {
	Relation RelationRef
	Alias    string
}

Scan is a base relation reference.

type Select 

type Select struct {
	Input     Expr
	Predicate Predicate
}

Select applies σ (filtering) to its input.

type SetItem 

type SetItem struct {
	Field string
	Value any
}

SetItem is one field=value assignment in an update.

type Sort 

type Sort struct {
	Input   Expr
	OrderBy []OrderTerm
}

Sort applies τ (ordering) to its input.

type Tuple 

type Tuple []any

Tuple is a literal row of values, used in insert and IN-lists.

type Update 

type Update struct {
	Target    RelationRef
	Predicate Predicate
	Set       []SetItem
}

Update is the relational assignment for update, constrained by a predicate.

Source Files

View all Source files

Directories

Path Synopsis
Package interp is the reference interpreter for the committed read-path subset of the relalg IR.
 Package interp is the reference interpreter for the committed read-path subset of the relalg IR.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.