vectorsql

package
v0.0.0-...-effd846 Latest Latest
Warning

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

 Go to latest Published: Jun 29, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package vectorsql implements the VectorSQL language surface of spec 12: a hand-written recursive-descent lexer and parser over the formal grammar (§15), the AST the parser emits (§17.2), the strict error model (§14), and a binder that resolves a parsed statement against the catalog and lowers a kNN SELECT to the planner's BoundQuery. VectorSQL is a strict SQL subset: no JOIN, no CTE, one FROM table per query, with first-class vector distance operators and a FUSION clause for hybrid search.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BindCreateTable 

func BindCreateTable(st *CreateTableStmt) (*catalog.Schema, error)

BindCreateTable lowers a parsed CREATE TABLE to a catalog.Schema (spec 12 §3.1). It maps each SQL column type to the catalog's vector or metadata column kind, applies the implicit primary key rule, and rejects more than one vector column per the index SPI contract.

func ParseVectorLiteral 

func ParseVectorLiteral(s string) ([]float32, error)

ParseVectorLiteral parses the textual vector form `[x, y, z]` into a float32 slice (spec 12 §2.6). Whitespace around brackets and commas is tolerated; an empty vector and a non-numeric element are both errors.

Types

type AlterTableStmt 

type AlterTableStmt struct {
	Table     string
	Action    string // "add_column" | "drop_column" | "rename_table" | "rename_column"
	Column    *ColumnSpec
	DropCol   string
	NewName   string
	OldColumn string
}

AlterTableStmt is ALTER TABLE (spec 12 §3.4).

type Assignment 

type Assignment struct {
	Column string
	Value  Expr
}

Assignment is one `col = expr` of an UPDATE SET or ON CONFLICT DO UPDATE.

type BetweenExpr 

type BetweenExpr struct {
	Expr Expr
	Lo   Expr
	Hi   Expr
	Not  bool
}

BetweenExpr is `expr [NOT] BETWEEN lo AND hi`.

type BinaryExpr 

type BinaryExpr struct {
	Op    string
	Left  Expr
	Right Expr
}

BinaryExpr is an infix operator (logical, comparison, arithmetic, concat, or array containment); Op holds the canonical operator text.

type BoolLit 

type BoolLit struct {
	Value  bool
	Offset int
}

BoolLit is TRUE or FALSE.

type BoundSelect 

type BoundSelect struct {
	BoundQuery query.BoundQuery
	IsKNN      bool
	// VectorParam names the parameter supplying the query vector, or is empty when the
	// vector is a literal already placed in BoundQuery.Vector.
	VectorParam ParamRef
	HasParam    bool
	// Projections are the metadata column names the select list requests.
	Projections []string
}

BoundSelect is the result of binding a SELECT (spec 12 §17.3). For a kNN query it carries the planner's BoundQuery and, when the query vector is a literal, the resolved vector. When the vector rides in a parameter, Query holds nil and the db layer ([14]) substitutes the bound value before planning.

func BindSelect 

func BindSelect(st *SelectStmt, coll *catalog.Collection) (*BoundSelect, error)

BindSelect resolves a SELECT against a collection and detects the kNN plan shape of spec 12 §17.3: exactly one ORDER BY item that is a distance operator on the vector column, plus a bounded LIMIT. A matching query lowers to a query.BoundQuery; the WHERE clause lowers to a storage.Predicate. A non-kNN SELECT is reported as unsupported in M6 because the planner only serves kNN and point lookups.

type CaseExpr 

type CaseExpr struct {
	Operand Expr // nil for a searched CASE
	Whens   []WhenClause
	Else    Expr
}

CaseExpr is a searched or simple CASE expression (spec 12 §19.13).

type CastExpr 

type CastExpr struct {
	Expr Expr
	Type *TypeRef
}

CastExpr is `expr :: type` (spec 12 §6.4).

type ColumnRef 

type ColumnRef struct {
	Table  string // qualifier, "" when unqualified
	Name   string
	Offset int
}

ColumnRef is a column reference, optionally table-qualified (spec 12 §17.2).

type ColumnSpec 

type ColumnSpec struct {
	Name       string
	Type       *TypeRef
	NotNull    bool
	Nullable   bool
	PrimaryKey bool
	Unique     bool
	Default    Expr
}

ColumnSpec is one column definition of a CREATE TABLE (spec 12 §3.1).

type CopyStmt 

type CopyStmt struct {
	Table   string
	Columns []string
	Source  string // file path, or "" for STDIN
	Stdin   bool
	Format  string // "jsonl" | "csv" | "binary"
	Options map[string]Expr
}

CopyStmt is COPY ... FROM (spec 12 §4.5).

type CreateIndexStmt 

type CreateIndexStmt struct {
	Unique      bool
	IfNotExists bool
	Name        string
	Table       string
	IndexType   string // hnsw | ivfflat | ivfpq | diskann | flat | fts5
	Column      string
	Opclass     string
	Options     map[string]Expr
	Where       Expr
}

CreateIndexStmt is CREATE INDEX (spec 12 §3.2, §17.2).

type CreateTableStmt 

type CreateTableStmt struct {
	IfNotExists bool
	Name        string
	Columns     []ColumnSpec
	PrimaryKey  []string // table-level PRIMARY KEY columns
	Uniques     [][]string
	Checks      []Expr
}

CreateTableStmt is CREATE TABLE (spec 12 §3.1).

type DeallocateStmt 

type DeallocateStmt struct {
	Name string // "" with All set means DEALLOCATE ALL
	All  bool
}

DeallocateStmt is DEALLOCATE (spec 12 §9.2).

type DeleteStmt 

type DeleteStmt struct {
	Table     string
	Where     Expr
	Returning []ExprAlias
	ReturnAll bool
}

DeleteStmt is DELETE (spec 12 §4.3).

type DistanceExpr 

type DistanceExpr struct {
	Op    DistanceOp
	Left  Expr
	Right Expr
}

DistanceExpr is the kNN-defining operator: column DistanceOp query (spec 12 §17.2).

type DistanceOp 

type DistanceOp uint8

DistanceOp identifies a vector distance operator (spec 12 §17.2). The values match the four operators of the grammar. 

const (
	OpL2Distance     DistanceOp = iota // <->
	OpCosineDistance                   // <=>
	OpNegInnerProd                     // <#>
	OpL1Distance                       // <+>
)

func (DistanceOp) String 

func (o DistanceOp) String() string

String renders the operator's source token.

type DropStmt 

type DropStmt struct {
	Index    bool // false = TABLE, true = INDEX
	IfExists bool
	Name     string
	OnTable  string // for DROP INDEX ON table(col)
	OnColumn string
}

DropStmt is DROP TABLE or DROP INDEX (spec 12 §3.3).

type ExecuteStmt 

type ExecuteStmt struct {
	Name string
	Args []Expr
}

ExecuteStmt is EXECUTE (spec 12 §9.2).

type ExplainStmt 

type ExplainStmt struct {
	Analyze bool
	Options map[string]Expr
	Body    Stmt
}

ExplainStmt is EXPLAIN / EXPLAIN ANALYZE (spec 12 §10).

type Expr 

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

Expr is the marker interface for an expression node.

type ExprAlias 

type ExprAlias struct {
	Expr  Expr
	Alias string
}

ExprAlias is one select-list or RETURNING item: an expression with an optional AS alias (spec 12 §5.2).

type FloatLit 

type FloatLit struct {
	Value  float64
	Offset int
}

FloatLit is a float literal parsed to float64 (spec 12 §2.5.2).

type FuncCall 

type FuncCall struct {
	Name     string
	Args     []Expr
	Star     bool // count(*)
	Distinct bool
	Filter   Expr // FILTER (WHERE expr), nil if absent
	Offset   int
}

FuncCall is a function application, optionally with DISTINCT args or a FILTER clause (spec 12 §8.1).

type FusionClause 

type FusionClause struct {
	Streams []FusionStream
	Options map[string]Expr
}

FusionClause is the hybrid-search FUSION clause (spec 12 §7.2).

type FusionStream 

type FusionStream struct {
	Keyword bool // false = VECTOR stream, true = KEYWORD stream

	// VECTOR stream: column DistanceOp query.
	Column string
	Op     DistanceOp
	Query  Expr
	// KEYWORD stream: MATCH (cols) AGAINST (query).
	MatchCols []string
	Against   Expr
	Options   map[string]Expr
}

FusionStream is one input to a FUSION: a dense vector kNN stream or a keyword match stream (spec 12 §7.2, §7.4).

type InExpr 

type InExpr struct {
	Expr Expr
	List []Expr
	Sub  *SelectStmt
	Not  bool
}

InExpr is `expr [NOT] IN (list)`. Sub is a subquery alternative; List is the value list form. Exactly one is set.

type InsertStmt 

type InsertStmt struct {
	Table      string
	Columns    []string
	Rows       [][]Expr
	OnConflict *OnConflict
	Returning  []ExprAlias
	ReturnAll  bool
}

InsertStmt is INSERT or UPSERT (spec 12 §4.1, §4.2).

type IntLit 

type IntLit struct {
	Value  int64
	Offset int
}

IntLit is an integer literal already parsed to int64 (spec 12 §2.5.1).

type IsNullExpr 

type IsNullExpr struct {
	Expr Expr
	Not  bool
}

IsNullExpr is `expr IS [NOT] NULL`.

type JSONExpr 

type JSONExpr struct {
	Expr Expr
	Key  string
	Text bool
}

JSONExpr is `expr -> 'k'` or `expr ->> 'k'` (spec 12 §6.5). Text is true for ->>.

type LikeExpr 

type LikeExpr struct {
	Expr    Expr
	Pattern Expr
	Not     bool
	Insens  bool // ILIKE
}

LikeExpr is `expr [NOT] LIKE/ILIKE pattern`.

type NullLit 

type NullLit struct{ Offset int }

NullLit is the SQL NULL.

type OnConflict 

type OnConflict struct {
	Columns   []string
	DoNothing bool
	Assigns   []Assignment
}

OnConflict is the ON CONFLICT clause of an upsert (spec 12 §4.2).

type OrderItem 

type OrderItem struct {
	Expr       Expr
	Desc       bool
	NullsFirst bool
	NullsSet   bool // whether NULLS FIRST/LAST was given explicitly
}

OrderItem is one ORDER BY term (spec 12 §5.4).

type ParamRef 

type ParamRef struct {
	Name   string // for :name; "" for positional
	Pos    int    // for $N, 1-based; 0 for named
	Offset int
}

ParamRef is a named (:name) or positional ($N) parameter (spec 12 §2.6).

type PragmaStmt 

type PragmaStmt struct {
	Scope string // qualifier before the dot, "" if none
	Name  string
	Value Expr // for `= value` or `(value)`; nil for a bare read
}

PragmaStmt is PRAGMA (spec 12 §12).

type PrepareStmt 

type PrepareStmt struct {
	Name  string
	Types []*TypeRef
	Body  Stmt
}

PrepareStmt is PREPARE (spec 12 §9.2).

type ProfileStmt 

type ProfileStmt struct{ Body Stmt }

ProfileStmt is PROFILE (spec 12 §10.3).

type SelectStmt 

type SelectStmt struct {
	Distinct   bool
	DistinctOn []Expr
	Columns    []ExprAlias // empty means SELECT *
	Star       bool
	From       string
	FromAlias  string
	Where      Expr
	GroupBy    []Expr
	Having     Expr
	Fusion     *FusionClause
	OrderBy    []OrderItem
	Limit      Expr
	Offset     Expr
}

SelectStmt is a SELECT (spec 12 §5.1, §17.2).

type SetStmt 

type SetStmt struct {
	Local   bool
	Session bool
	Name    string
	Default bool // SET x = DEFAULT
	Value   Expr
}

SetStmt is SET (spec 12 §11.4).

type Star 

type Star struct{ Offset int }

Star is the * select-list or count(*) wildcard.

type Stmt 

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

Stmt is the marker interface for a top-level statement.

func Parse 

func Parse(src string) (Stmt, error)

Parse parses a single VectorSQL statement, with an optional trailing semicolon, and returns its AST (spec 12 §17.1). Trailing tokens after the statement are an error.

type StringLit 

type StringLit struct {
	Value  string
	Offset int
}

StringLit is a decoded string literal; it may later coerce to a vector, sparse, or multivec value at bind time (spec 12 §2.5.3 through §2.5.6).

type Token 

type Token struct {
	Kind   tokenKind
	Text   string // the canonical text: lowercased keyword/ident, raw literal value
	Offset int    // byte offset of the token start in the source
	// Param fields, set when Kind == tokParam.
	ParamName string // for :name
	ParamPos  int    // for $N, 1-based; 0 for named params
}

Token is one lexical unit with its source byte offset for error reporting.

type TxnStmt 

type TxnStmt struct {
	Kind      string // "begin" | "commit" | "rollback" | "savepoint" | "release" | "rollback_to"
	Isolation string // for begin
	Name      string // savepoint/release/rollback-to name
}

TxnStmt is a transaction-control statement (spec 12 §11.1).

type TypeRef 

type TypeRef struct {
	Name   string
	Arg    int
	HasArg bool
}

TypeRef is a column type with its optional dimension or length argument (spec 12 §3.1.1). Name is the canonical lowercased type keyword; Arg is the parenthesized integer for VECTOR/SPARSEVEC/MULTIVEC/VARCHAR.

type UnaryExpr 

type UnaryExpr struct {
	Op   string // "not" or "-"
	Expr Expr
}

UnaryExpr is a prefix operator: NOT or unary minus.

type UpdateStmt 

type UpdateStmt struct {
	Table     string
	Assigns   []Assignment
	Where     Expr
	Returning []ExprAlias
	ReturnAll bool
}

UpdateStmt is UPDATE (spec 12 §4.4).

type VecError 

type VecError struct {
	Code    string // symbolic code, e.g. "E_PARSE"
	Numeric int    // numeric code, e.g. 1000
	Message string // human-readable description
	Detail  string // optional context (column name, expected dimension, spec reference)
	Offset  int    // byte offset within the statement text; -1 when not positional
}

VecError is every error the VectorSQL frontend raises (spec 12 §14.4). It carries a stable symbolic code, a numeric code for programmatic dispatch, a human message, an optional detail string, and, for parse errors, the byte offset in the source.

func (*VecError) Error 

func (e *VecError) Error() string

Error renders the symbolic code and message, plus the offset for parse errors.

type WhenClause 

type WhenClause struct {
	When Expr
	Then Expr
}

WhenClause is one WHEN/THEN arm of a CASE.

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.