sqlengine

package
v0.0.0-...-dfee7fc Latest Latest
Warning

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

 Go to latest Published: Aug 15, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Overview

Package sql parses and evaluates the SQL-style scalar filter language used by xvec.

Index

Constants

View Source 
const MaxContainValues = 32

MaxContainValues matches the baseline maximum array field length.

View Source 
const MaxFilterBytes = 1 << 20
View Source 
const MaxParseDepth = 256

Variables

View Source 
var (

	// ErrCorruptInvertedIndex identifies an invalid Pebble-backed INVERT
	// snapshot. It is distinct from query and schema validation errors.
	ErrCorruptInvertedIndex = errors.New("sql: corrupt inverted index")
)

Functions

func Format 

func Format(expression Expr) string

Format renders a deterministic normalized filter for diagnostics.

func RewriteFilter 

func RewriteFilter(expression Expr) (Expr, RewriteStats)

RewriteFilter returns a new expression tree. OR-connected equality and IN predicates on the same identifier are coalesced into one IN predicate. Unlike the pinned implementation, inequality under OR is deliberately not rewritten because doing so would change Boolean semantics.

Types

type AnalysisError 

type AnalysisError struct {
	Position Position
	Message  string
}

AnalysisError identifies a semantically invalid filter at its source position after syntax parsing succeeded.

func (*AnalysisError) Error 

func (e *AnalysisError) Error() string

type BoundPredicate 

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

BoundPredicate is a schema-typed predicate kernel. The analyzer constructs it from the syntax AST; Evaluate then performs no parsing or numeric casts.

func NewComparisonPredicate 

func NewComparisonPredicate(operator PredicateOperator, right Value) (BoundPredicate, error)

func NewLikePredicate 

func NewLikePredicate(pattern string) (BoundPredicate, error)

func NewNullPredicate 

func NewNullPredicate(negated bool) BoundPredicate

func NewSetPredicate 

func NewSetPredicate(operator PredicateOperator, negated bool, values []Value) (BoundPredicate, error)

NewSetPredicate binds IN or a contain predicate. IN requires a non-empty set; contain predicates intentionally retain baseline empty-set semantics.

func (BoundPredicate) Evaluate 

func (p BoundPredicate) Evaluate(left Value) (Truth, error)

Evaluate applies a bound predicate to a field value.

func (BoundPredicate) LikePattern 

func (p BoundPredicate) LikePattern() *LikePattern

func (BoundPredicate) Negated 

func (p BoundPredicate) Negated() bool

func (BoundPredicate) Operator 

func (p BoundPredicate) Operator() PredicateOperator

func (BoundPredicate) SetSize 

func (p BoundPredicate) SetSize() int

type CallExpr 

type CallExpr struct {
	Name      string
	Arguments []ValueExpr
	Range     Span
}

CallExpr is a function invocation. Arguments may be literals, identifiers, vectors, or nested calls; semantic validation happens in the analyzer.

func (*CallExpr) NodeSpan 

func (e *CallExpr) NodeSpan() Span

func (*CallExpr) String 

func (e *CallExpr) String() string

type Expr 

type Expr interface {
	NodeSpan() Span
	String() string
	// contains filtered or unexported methods
}

Expr is any filter AST expression.

func ParseFilter 

func ParseFilter(input string) (Expr, error)

ParseFilter parses one complete SQL-style filter expression.

type Field 

type Field struct {
	Name             string
	Kind             ValueKind
	Array            bool
	Nullable         bool
	Filterable       bool
	Indexed          bool
	RangeOptimized   bool
	ExtendedWildcard bool
}

Field describes the scalar runtime shape needed by filter analysis. A field with Filterable=false remains visible so diagnostics can distinguish an unsupported vector/FTS target from a missing field.

type IdentifierExpr 

type IdentifierExpr struct {
	Name  string
	Range Span
}

IdentifierExpr preserves the source spelling of a field or function name.

func (*IdentifierExpr) NodeSpan 

func (e *IdentifierExpr) NodeSpan() Span

func (*IdentifierExpr) String 

func (e *IdentifierExpr) String() string

type IndexSet 

type IndexSet map[string]*InvertedIndex

IndexSet maps schema field names to sealed snapshot-local indexes.

type InvertedIndex 

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

InvertedIndex stores exact postings for one scalar or homogeneous array field. Build calls are serialized; after Seal, searches are concurrent-safe.

func NewInvertedIndex 

func NewInvertedIndex(field Field) (*InvertedIndex, error)

func OpenInvertedIndex 

func OpenInvertedIndex(ctx context.Context, path string) (*InvertedIndex, error)

OpenInvertedIndex opens and validates an immutable Pebble INVERT directory.

func (*InvertedIndex) Add 

func (i *InvertedIndex) Add(row uint64, value Value) error

Add indexes a snapshot-local row ordinal exactly once.

func (*InvertedIndex) Field 

func (i *InvertedIndex) Field() Field

func (*InvertedIndex) RowCount 

func (i *InvertedIndex) RowCount() uint64

func (*InvertedIndex) Save 

func (i *InvertedIndex) Save(ctx context.Context, path string) error

Save writes a sealed index into a new Pebble directory. The directory is an immutable snapshot after Save returns.

func (*InvertedIndex) Seal 

func (i *InvertedIndex) Seal() error

Seal publishes sorted term and array-length dictionaries.

func (*InvertedIndex) Search 

func (i *InvertedIndex) Search(predicate BoundPredicate) (InvertedResult, error)

Search applies a field predicate. General LIKE forms that cannot be served without false negatives return Supported=false.

func (*InvertedIndex) SearchArrayLength 

func (i *InvertedIndex) SearchArrayLength(predicate BoundPredicate) (InvertedResult, error)

SearchArrayLength applies a comparison to indexed array lengths.

type InvertedResult 

type InvertedResult struct {
	Bitmap    *container.Bitmap
	Supported bool
	Strategy  InvertedStrategy
	Terms     int
}

InvertedResult is an immutable search result. Supported=false instructs the planner to use forward evaluation for that predicate.

type InvertedStrategy 

type InvertedStrategy uint8

InvertedStrategy identifies how an index search produced its candidate set. 

const (
	InvertedExact InvertedStrategy = iota + 1
	InvertedPostingUnion
	InvertedSortedRange
	InvertedTermScan
	InvertedPrefix
	InvertedSuffix
	InvertedPrefixSuffix
	InvertedNull
	InvertedArrayLength
)

func (InvertedStrategy) String 

func (s InvertedStrategy) String() string

type LikeMode 

type LikeMode uint8

LikeMode exposes the cheapest exact interpretation of a LIKE pattern. The later inverted-index planner uses this classification without changing forward-evaluation results. 

const (
	LikeExact LikeMode = iota + 1
	LikeAny
	LikePrefix
	LikeSuffix
	LikeContains
	LikeGeneral
)

func (LikeMode) String 

func (m LikeMode) String() string

type LikePattern 

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

LikePattern is an immutable, concurrency-safe compiled SQL LIKE pattern. Percent matches any rune sequence, underscore one rune, and backslash makes the following rune literal.

func CompileLike 

func CompileLike(pattern string) (*LikePattern, error)

CompileLike validates UTF-8 and compiles a whole-string LIKE matcher using Go's linear-time RE2 engine.

func (*LikePattern) Literal 

func (p *LikePattern) Literal() string

Literal returns the unescaped exact, prefix, suffix, or contained text. It is empty for ANY and GENERAL patterns.

func (*LikePattern) Match 

func (p *LikePattern) Match(value string) bool

func (*LikePattern) Mode 

func (p *LikePattern) Mode() LikeMode

func (*LikePattern) Raw 

func (p *LikePattern) Raw() string

type ListExpr 

type ListExpr struct {
	Values []*LiteralExpr
	Range  Span
}

ListExpr contains IN or contain literals. Parser rules keep IN lists non-empty while contain lists may be empty.

func (*ListExpr) NodeSpan 

func (e *ListExpr) NodeSpan() Span

func (*ListExpr) String 

func (e *ListExpr) String() string

type LiteralExpr 

type LiteralExpr struct {
	Kind  LiteralKind
	Text  string
	Raw   string
	Range Span
}

LiteralExpr retains a normalized literal Text and its original source Raw. Integer and float values intentionally remain textual until schema analysis so the full UINT64 range is representable.

func (*LiteralExpr) NodeSpan 

func (e *LiteralExpr) NodeSpan() Span

func (*LiteralExpr) String 

func (e *LiteralExpr) String() string

type LiteralKind 

type LiteralKind uint8

LiteralKind distinguishes untyped syntax literals before schema analysis. 

const (
	LiteralInteger LiteralKind = iota + 1
	LiteralFloat
	LiteralString
	LiteralBool
)

func (LiteralKind) String 

func (k LiteralKind) String() string

type LogicalExpr 

type LogicalExpr struct {
	Operator LogicalOperator
	Left     Expr
	Right    Expr
	Range    Span
}

LogicalExpr is a binary AND or OR expression.

func (*LogicalExpr) NodeSpan 

func (e *LogicalExpr) NodeSpan() Span

func (*LogicalExpr) String 

func (e *LogicalExpr) String() string

type LogicalOperator 

type LogicalOperator uint8

LogicalOperator joins Boolean filter expressions. 

const (
	LogicalAnd LogicalOperator = iota + 1
	LogicalOr
)

func (LogicalOperator) String 

func (o LogicalOperator) String() string

type ParseError 

type ParseError struct {
	Position Position
	Message  string
}

ParseError reports the exact token or byte at which lexing/parsing failed.

func (*ParseError) Error 

func (e *ParseError) Error() string

type Plan 

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

Plan is an immutable, concurrency-safe forward filter execution plan.

func BuildPlan 

func BuildPlan(input string, schema Schema) (*Plan, error)

BuildPlan parses, rewrites, analyzes, and optimizes one complete filter.

func (*Plan) AlwaysFalse 

func (p *Plan) AlwaysFalse() bool

func (*Plan) Candidates 

func (p *Plan) Candidates(indexes IndexSet, totalRows uint64) (bitmap *container.Bitmap, used, exact bool, err error)

Candidates returns a safe row-ordinal prefilter. used=false means no safe index prefilter exists. exact reports whether the bitmap itself represents the complete SQL match set; callers may always forward-verify candidates.

func (*Plan) Evaluate 

func (p *Plan) Evaluate(resolve Resolver) (Truth, error)

func (*Plan) Explain 

func (p *Plan) Explain() string

func (*Plan) Fields 

func (p *Plan) Fields() []Field

func (*Plan) Match 

func (p *Plan) Match(resolve Resolver) (bool, error)

func (*Plan) Normalized 

func (p *Plan) Normalized() string

func (*Plan) Stats 

func (p *Plan) Stats() PlanStats

type PlanStats 

type PlanStats struct {
	EqualitySets         int
	EmptyContainRewrites int
	ConstantFolds        int
}

PlanStats describes deterministic rewrites and optimizations applied while building an executable filter plan.

type Position 

type Position struct {
	Offset int
	Line   int
	Column int
}

Position identifies a UTF-8 source location. Offset is a zero-based byte offset; Line and Column are one-based Unicode code-point coordinates.

type PredicateExpr 

type PredicateExpr struct {
	Operator PredicateOperator
	Left     ValueExpr
	Right    ValueExpr
	Negated  bool
	Range    Span
}

PredicateExpr compares a field or function call with a value. Negated is valid for IN, CONTAIN_ALL, CONTAIN_ANY, and IS NULL.

func (*PredicateExpr) NodeSpan 

func (e *PredicateExpr) NodeSpan() Span

func (*PredicateExpr) String 

func (e *PredicateExpr) String() string

type PredicateOperator 

type PredicateOperator uint8

PredicateOperator identifies one relation predicate. 

const (
	PredicateEQ PredicateOperator = iota + 1
	PredicateNE
	PredicateLT
	PredicateLE
	PredicateGT
	PredicateGE
	PredicateLike
	PredicateIn
	PredicateContainAll
	PredicateContainAny
	PredicateIsNull
)

func (PredicateOperator) String 

func (o PredicateOperator) String() string

type Resolver 

type Resolver func(field Field) (Value, error)

Resolver returns one typed field value. Missing nullable fields should be returned as typed NULL by the storage adapter.

type RewriteStats 

type RewriteStats struct {
	EqualitySets int
}

RewriteStats records semantics-preserving syntax rewrites.

type Schema 

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

Schema is an immutable filter-analysis schema.

func NewSchema 

func NewSchema(fields []Field) (Schema, error)

func (Schema) Field 

func (s Schema) Field(name string) (Field, bool)

func (Schema) Fields 

func (s Schema) Fields() []Field

Fields returns independent descriptors in schema order.

type Span 

type Span struct {
	Start Position
	End   Position
}

Span is a half-open source range [Start, End).

type Token 

type Token struct {
	Kind TokenKind
	Text string
	Span Span
}

Token preserves original source text and its half-open range.

func Lex 

func Lex(input string) ([]Token, error)

Lex tokenizes one filter. Keywords are case-insensitive while token text and identifiers preserve their original spelling. SQL comments are ignored.

type TokenKind 

type TokenKind uint8

TokenKind classifies filter syntax tokens. 

const (
	TokenEOF TokenKind = iota
	TokenIdentifier
	TokenInteger
	TokenFloat
	TokenString
	TokenTrue
	TokenFalse
	TokenOr
	TokenAnd
	TokenNot
	TokenIn
	TokenContainAll
	TokenContainAny
	TokenBetween
	TokenLike
	TokenWhere
	TokenSelect
	TokenFrom
	TokenAs
	TokenBy
	TokenOrder
	TokenAsc
	TokenDesc
	TokenLimit
	TokenIs
	TokenNull
	TokenEqual
	TokenNotEqual
	TokenLess
	TokenLessEqual
	TokenGreater
	TokenGreaterEqual
	TokenLeftParen
	TokenRightParen
	TokenLeftBracket
	TokenRightBracket
	TokenComma
)

func (TokenKind) String 

func (k TokenKind) String() string

type Truth 

type Truth uint8

Truth is a SQL three-valued Boolean. A filter retains only TruthTrue; comparisons against NULL propagate TruthUnknown through logical operators. 

const (
	TruthUnknown Truth = iota
	TruthFalse
	TruthTrue
)

func (Truth) And 

func (t Truth) And(other Truth) Truth

func (Truth) Match 

func (t Truth) Match() bool

func (Truth) Not 

func (t Truth) Not() Truth

func (Truth) Or 

func (t Truth) Or(other Truth) Truth

func (Truth) String 

func (t Truth) String() string

type Value 

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

Value is an immutable typed scalar, homogeneous array, or typed NULL. Its constructors clone byte and array data so a bound predicate remains safe to share between concurrent readers.

func ArrayValue 

func ArrayValue(kind ValueKind, elements ...Value) (Value, error)

ArrayValue builds a homogeneous non-null array. Empty arrays retain their element kind. Nested arrays and null elements are deliberately unsupported.

func BinaryValue 

func BinaryValue(value []byte) Value

func BoolValue 

func BoolValue(value bool) Value

func Float32Value 

func Float32Value(value float32) (Value, error)

Float32Value stores the exact value represented by value.

func Float64Value 

func Float64Value(value float64) (Value, error)

Float64Value rejects non-finite values, which are not valid document data.

func Int32Value 

func Int32Value(value int32) Value

func Int64Value 

func Int64Value(value int64) Value

func NullValue 

func NullValue(kind ValueKind, array bool) (Value, error)

NullValue returns a typed scalar or array NULL.

func StringValue 

func StringValue(value string) Value

func Uint32Value 

func Uint32Value(value uint32) Value

func Uint64Value 

func Uint64Value(value uint64) Value

func (Value) IsArray 

func (v Value) IsArray() bool

func (Value) IsNull 

func (v Value) IsNull() bool

func (Value) Kind 

func (v Value) Kind() ValueKind

func (Value) Len 

func (v Value) Len() (int, bool)

Len returns an array length and false for scalar or NULL values.

type ValueExpr 

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

ValueExpr is a relation operand or function argument.

type ValueKind 

type ValueKind uint8

ValueKind identifies an exact scalar storage type. Width remains part of the kind so schema binding cannot accidentally narrow or widen a value. 

const (
	ValueBinary ValueKind = iota + 1
	ValueString
	ValueBool
	ValueInt32
	ValueInt64
	ValueUint32
	ValueUint64
	ValueFloat32
	ValueFloat64
)

func (ValueKind) String 

func (k ValueKind) String() string

type VectorExpr 

type VectorExpr struct {
	Rows   [][]*LiteralExpr
	Matrix bool
	Range  Span
}

VectorExpr preserves one vector or a matrix of numeric literal rows.

func (*VectorExpr) NodeSpan 

func (e *VectorExpr) NodeSpan() Span

func (*VectorExpr) String 

func (e *VectorExpr) String() string

Source Files

View all Source files

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.