Package cloud.google.com/go/spanner/spansql

Package spansql contains types and a parser for the Cloud Spanner SQL dialect.

To parse, use one of the Parse functions (ParseDDL, ParseDDLStmt, ParseQuery, etc.).

Sources:

https://cloud.google.com/spanner/docs/lexical
https://cloud.google.com/spanner/docs/query-syntax
https://cloud.google.com/spanner/docs/data-definition-language

Constants

True, False

const (
	True  = BoolLiteral(true)
	False = BoolLiteral(false)
)

MaxLen

const MaxLen = math.MaxInt64

MaxLen is a sentinel for Type's Len field, representing the MAX value.

Null

const Null = NullLiteral(0)

Star

const Star = StarExpr(0)

Star represents a "*" in an expression.

Functions

func IsKeyword

func IsKeyword(id string) bool

IsKeyword reports whether the identifier is a reserved keyword.

AddColumn

type AddColumn struct{ Def ColumnDef }

func (AddColumn) SQL

func (ac AddColumn) SQL() string

AddConstraint

type AddConstraint struct{ Constraint TableConstraint }

func (AddConstraint) SQL

func (ac AddConstraint) SQL() string

AddRowDeletionPolicy

type AddRowDeletionPolicy struct{ RowDeletionPolicy RowDeletionPolicy }

func (AddRowDeletionPolicy) SQL

func (ardp AddRowDeletionPolicy) SQL() string

AlterColumn

type AlterColumn struct {
	Name       ID
	Alteration ColumnAlteration
}

func (AlterColumn) SQL

func (ac AlterColumn) SQL() string

AlterDatabase

type AlterDatabase struct {
	Name       ID
	Alteration DatabaseAlteration

	Position Position // position of the "ALTER" token
}

AlterDatabase represents an ALTER DATABASE statement. https://cloud.google.com/spanner/docs/data-definition-language#alter-database

func (*AlterDatabase) Pos

func (ad *AlterDatabase) Pos() Position

func (AlterDatabase) SQL

func (ad AlterDatabase) SQL() string

func (*AlterDatabase) String

func (ad *AlterDatabase) String() string

AlterTable

type AlterTable struct {
	Name       ID
	Alteration TableAlteration

	Position Position // position of the "ALTER" token
}

func (*AlterTable) Pos

func (at *AlterTable) Pos() Position

func (AlterTable) SQL

func (at AlterTable) SQL() string

func (*AlterTable) String

func (at *AlterTable) String() string

ArithOp

type ArithOp struct {
	Op       ArithOperator
	LHS, RHS Expr // only RHS is set for Neg, Plus, BitNot
}

func (ArithOp) SQL

func (ao ArithOp) SQL() string

ArithOperator

type ArithOperator int

Neg, Plus, BitNot, Mul, Div, Concat, Add, Sub, BitShl, BitShr, BitAnd, BitXor, BitOr

const (
	Neg    ArithOperator = iota // unary -
	Plus                        // unary +
	BitNot                      // unary ~
	Mul                         // *
	Div                         // /
	Concat                      // ||
	Add                         // +
	Sub                         // -
	BitShl                      // < bitshr="">>
	BitAnd                      // &
	BitXor                      // ^
	BitOr                       // |
)

Array

type Array []Expr

Array represents an array literal.

func (Array) SQL

func (a Array) SQL() string

BoolExpr

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

BoolLiteral

type BoolLiteral bool

func (BoolLiteral) SQL

func (b BoolLiteral) SQL() string

BytesLiteral

type BytesLiteral string

func (BytesLiteral) SQL

func (bl BytesLiteral) SQL() string

Check

type Check struct {
	Expr BoolExpr

	Position Position // position of the "CHECK" token
}

Check represents a check constraint as part of a CREATE TABLE or ALTER TABLE statement.

func (Check) Pos

func (c Check) Pos() Position

func (Check) SQL

func (c Check) SQL() string

ColumnAlteration

type ColumnAlteration interface {
	SQL() string
	// contains filtered or unexported methods
}

ColumnAlteration is satisfied by SetColumnType and SetColumnOptions.

ColumnDef

type ColumnDef struct {
	Name    ID
	Type    Type
	NotNull bool

	Generated Expr // set of this is a generated column

	Options ColumnOptions

	Position Position // position of the column name
}

ColumnDef represents a column definition as part of a CREATE TABLE or ALTER TABLE statement.

func (ColumnDef) Pos

func (cd ColumnDef) Pos() Position

func (ColumnDef) SQL

func (cd ColumnDef) SQL() string

ColumnOptions

type ColumnOptions struct {
	// AllowCommitTimestamp represents a column OPTIONS.
	// `true` if query is `OPTIONS (allow_commit_timestamp = true)`
	// `false` if query is `OPTIONS (allow_commit_timestamp = null)`
	// `nil` if there are no OPTIONS
	AllowCommitTimestamp *bool
}

ColumnOptions represents options on a column as part of a CREATE TABLE or ALTER TABLE statement.

func (ColumnOptions) SQL

func (co ColumnOptions) SQL() string

Comment

type Comment struct {
	Marker   string // Opening marker; one of "#", "--", "/*".
	Isolated bool   // Whether this comment is on its own line.
	// Start and End are the position of the opening and terminating marker.
	Start, End Position
	Text       []string
}

Comment represents a comment.

func (*Comment) Pos

func (c *Comment) Pos() Position

func (*Comment) String

func (c *Comment) String() string

ComparisonOp

type ComparisonOp struct {
	Op       ComparisonOperator
	LHS, RHS Expr

	// RHS2 is the third operand for BETWEEN.
	// "

func (ComparisonOp) SQL

func (co ComparisonOp) SQL() string

ComparisonOperator

type ComparisonOperator int

Lt, Le, Gt, Ge, Eq, Ne, Like, NotLike, Between, NotBetween

const (
	Lt ComparisonOperator = iota
	Le
	Gt
	Ge
	Eq
	Ne // both "!=" and "<>"
	Like
	NotLike
	Between
	NotBetween
)

Constraint

type Constraint interface {
	SQL() string
	Node
	// contains filtered or unexported methods
}

CreateIndex

type CreateIndex struct {
	Name    ID
	Table   ID
	Columns []KeyPart

	Unique       bool
	NullFiltered bool

	Storing    []ID
	Interleave ID

	Position Position // position of the "CREATE" token
}

CreateIndex represents a CREATE INDEX statement. https://cloud.google.com/spanner/docs/data-definition-language#create-index

func (*CreateIndex) Pos

func (ci *CreateIndex) Pos() Position

func (CreateIndex) SQL

func (ci CreateIndex) SQL() string

func (*CreateIndex) String

func (ci *CreateIndex) String() string

CreateTable

type CreateTable struct {
	Name              ID
	Columns           []ColumnDef
	Constraints       []TableConstraint
	PrimaryKey        []KeyPart
	Interleave        *Interleave
	RowDeletionPolicy *RowDeletionPolicy

	Position Position // position of the "CREATE" token
}

CreateTable represents a CREATE TABLE statement. https://cloud.google.com/spanner/docs/data-definition-language#create_table

func (*CreateTable) Pos

func (ct *CreateTable) Pos() Position

func (CreateTable) SQL

func (ct CreateTable) SQL() string

func (*CreateTable) String

func (ct *CreateTable) String() string

CreateView

type CreateView struct {
	Name      ID
	OrReplace bool
	Query     Query

	Position Position // position of the "CREATE" token
}

CreateView represents a CREATE [OR REPLACE] VIEW statement. https://cloud.google.com/spanner/docs/data-definition-language#view_statements

func (*CreateView) Pos

func (cv *CreateView) Pos() Position

func (CreateView) SQL

func (cv CreateView) SQL() string

func (*CreateView) String

func (cv *CreateView) String() string

DDL

type DDL struct {
	List []DDLStmt

	Filename string // if known at parse time

	Comments []*Comment // all comments, sorted by position
}

DDL represents a Data Definition Language (DDL) file.

func ParseDDL

func ParseDDL(filename, s string) (*DDL, error)

ParseDDL parses a DDL file.

The provided filename is used for error reporting and will appear in the returned structure.

func (*DDL) InlineComment

func (ddl *DDL) InlineComment(n Node) *Comment

InlineComment returns the comment on the same line as a node, or nil if there's no inline comment. The returned comment is guaranteed to be a single line.

func (*DDL) LeadingComment

func (ddl *DDL) LeadingComment(n Node) *Comment

LeadingComment returns the comment that immediately precedes a node, or nil if there's no such comment.

DDLStmt

type DDLStmt interface {
	SQL() string
	Node
	// contains filtered or unexported methods
}

DDLStmt is satisfied by a type that can appear in a DDL.

func ParseDDLStmt

func ParseDDLStmt(s string) (DDLStmt, error)

ParseDDLStmt parses a single DDL statement.

DMLStmt

type DMLStmt interface {
	SQL() string
	// contains filtered or unexported methods
}

DMLStmt is satisfied by a type that is a DML statement.

func ParseDMLStmt

func ParseDMLStmt(s string) (DMLStmt, error)

ParseDMLStmt parses a single DML statement.

DatabaseAlteration

type DatabaseAlteration interface {
	SQL() string
	// contains filtered or unexported methods
}

DatabaseOptions

type DatabaseOptions struct {
	OptimizerVersion       *int
	VersionRetentionPeriod *string
	EnableKeyVisualizer    *bool
}

DatabaseOptions represents options on a database as part of a ALTER DATABASE statement.

func (DatabaseOptions) SQL

func (do DatabaseOptions) SQL() string

DateLiteral

type DateLiteral civil.Date

DateLiteral represents a date literal. https://cloud.google.com/spanner/docs/lexical#date_literals

func (DateLiteral) SQL

func (dl DateLiteral) SQL() string

Delete

type Delete struct {
	Table ID
	Where BoolExpr
}

func (*Delete) SQL

func (d *Delete) SQL() string

func (*Delete) String

func (d *Delete) String() string

DropColumn

type DropColumn struct{ Name ID }

func (DropColumn) SQL

func (dc DropColumn) SQL() string

DropConstraint

type DropConstraint struct{ Name ID }

func (DropConstraint) SQL

func (dc DropConstraint) SQL() string

DropIndex

type DropIndex struct {
	Name ID

	Position Position // position of the "DROP" token
}

func (*DropIndex) Pos

func (di *DropIndex) Pos() Position

func (DropIndex) SQL

func (di DropIndex) SQL() string

func (*DropIndex) String

func (di *DropIndex) String() string

DropRowDeletionPolicy

type DropRowDeletionPolicy struct{}

func (DropRowDeletionPolicy) SQL

func (drdp DropRowDeletionPolicy) SQL() string

DropTable

type DropTable struct {
	Name ID

	Position Position // position of the "DROP" token
}

func (*DropTable) Pos

func (dt *DropTable) Pos() Position

func (DropTable) SQL

func (dt DropTable) SQL() string

func (*DropTable) String

func (dt *DropTable) String() string

DropView

type DropView struct {
	Name ID

	Position Position // position of the "DROP" token
}

func (*DropView) Pos

func (dv *DropView) Pos() Position

func (DropView) SQL

func (dv DropView) SQL() string

func (*DropView) String

func (dv *DropView) String() string

Expr

type Expr interface {
	SQL() string
	// contains filtered or unexported methods
}

FloatLiteral

type FloatLiteral float64

FloatLiteral represents a floating point literal. https://cloud.google.com/spanner/docs/lexical#floating-point-literals

func (FloatLiteral) SQL

func (fl FloatLiteral) SQL() string

ForeignKey

type ForeignKey struct {
	Columns    []ID
	RefTable   ID
	RefColumns []ID

	Position Position // position of the "FOREIGN" token
}

ForeignKey represents a foreign key definition as part of a CREATE TABLE or ALTER TABLE statement.

func (ForeignKey) Pos

func (fk ForeignKey) Pos() Position

func (ForeignKey) SQL

func (fk ForeignKey) SQL() string

Func

type Func struct {
	Name string // not ID
	Args []Expr
}

Func represents a function call.

func (Func) SQL

func (f Func) SQL() string

ID

type ID string

func (ID) SQL

func (id ID) SQL() string

InOp

type InOp struct {
	LHS    Expr
	Neg    bool
	RHS    []Expr
	Unnest bool
}

func (InOp) SQL

func (io InOp) SQL() string

IntegerLiteral

type IntegerLiteral int64

IntegerLiteral represents an integer literal. https://cloud.google.com/spanner/docs/lexical#integer-literals

func (IntegerLiteral) SQL

func (il IntegerLiteral) SQL() string

Interleave

type Interleave struct {
	Parent   ID
	OnDelete OnDelete
}

Interleave represents an interleave clause of a CREATE TABLE statement.

IsExpr

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

IsOp

type IsOp struct {
	LHS Expr
	Neg bool
	RHS IsExpr
}

func (IsOp) SQL

func (io IsOp) SQL() string

JoinType

type JoinType int

InnerJoin, CrossJoin, FullJoin, LeftJoin, RightJoin

const (
	InnerJoin JoinType = iota
	CrossJoin
	FullJoin
	LeftJoin
	RightJoin
)

KeyPart

type KeyPart struct {
	Column ID
	Desc   bool
}

KeyPart represents a column specification as part of a primary key or index definition.

func (KeyPart) SQL

func (kp KeyPart) SQL() string

LiteralOrParam

type LiteralOrParam interface {
	SQL() string
	// contains filtered or unexported methods
}

LiteralOrParam is implemented by integer literal and parameter values.

LogicalOp

type LogicalOp struct {
	Op       LogicalOperator
	LHS, RHS BoolExpr // only RHS is set for Not
}

func (LogicalOp) SQL

func (lo LogicalOp) SQL() string

LogicalOperator

type LogicalOperator int

And, Or, Not

const (
	And LogicalOperator = iota
	Or
	Not
)

Node

type Node interface {
	Pos() Position
}

Node is implemented by concrete types in this package that represent things appearing in a DDL file.

NullLiteral

type NullLiteral int

func (NullLiteral) SQL

func (NullLiteral) SQL() string

OnDelete

type OnDelete int

NoActionOnDelete, CascadeOnDelete

const (
	NoActionOnDelete OnDelete = iota
	CascadeOnDelete
)

func (OnDelete) SQL

func (od OnDelete) SQL() string

Order

type Order struct {
	Expr Expr
	Desc bool
}

func (Order) SQL

func (o Order) SQL() string

Param

type Param string

Param represents a query parameter.

func (Param) SQL

func (p Param) SQL() string

Paren

type Paren struct {
	Expr Expr
}

Paren represents a parenthesised expression.

func (Paren) SQL

func (p Paren) SQL() string

PathExp

type PathExp []ID

PathExp represents a path expression.

The grammar for path expressions is not defined (see b/169017423 internally), so this captures the most common form only, namely a dotted sequence of identifiers.

func (PathExp) SQL

func (pe PathExp) SQL() string

Position

type Position struct {
	Line   int // 1-based line number
	Offset int // 0-based byte offset
}

Position describes a source position in an input DDL file. It is only valid if the line number is positive.

func (Position) IsValid

func (pos Position) IsValid() bool

func (Position) String

func (pos Position) String() string

Query

type Query struct {
	Select Select
	Order  []Order

	Limit, Offset LiteralOrParam
}

func ParseQuery

func ParseQuery(s string) (Query, error)

ParseQuery parses a query string.

func (Query) SQL

func (q Query) SQL() string

ReplaceRowDeletionPolicy

type ReplaceRowDeletionPolicy struct{ RowDeletionPolicy RowDeletionPolicy }

func (ReplaceRowDeletionPolicy) SQL

func (rrdp ReplaceRowDeletionPolicy) SQL() string

RowDeletionPolicy

type RowDeletionPolicy struct {
	Column  ID
	NumDays int64
}

RowDeletionPolicy represents an row deletion policy clause of a CREATE, ALTER TABLE statement.

func (RowDeletionPolicy) SQL

func (rdp RowDeletionPolicy) SQL() string

Select

type Select struct {
	Distinct bool
	List     []Expr
	From     []SelectFrom
	Where    BoolExpr
	GroupBy  []Expr

	// When the FROM clause has TABLESAMPLE operators,
	// TableSamples will be populated 1:1 with From;
	// FROM clauses without will have a nil value.
	TableSamples []*TableSample

	// If the SELECT list has explicit aliases ("AS alias"),
	// ListAliases will be populated 1:1 with List;
	// aliases that are present will be non-empty.
	ListAliases []ID
}

func (Select) SQL

func (sel Select) SQL() string

SelectFrom

type SelectFrom interface {
	SQL() string
	// contains filtered or unexported methods
}

SelectFrom represents the FROM clause of a SELECT. https://cloud.google.com/spanner/docs/query-syntax#from_clause

SelectFromJoin

type SelectFromJoin struct {
	Type     JoinType
	LHS, RHS SelectFrom

	// Join condition.
	// At most one of {On,Using} may be set.
	On    BoolExpr
	Using []ID

	// Hints are suggestions for how to evaluate a join.
	// https://cloud.google.com/spanner/docs/query-syntax#join-hints
	Hints map[string]string
}

SelectFromJoin is a SelectFrom that joins two other SelectFroms. https://cloud.google.com/spanner/docs/query-syntax#join_types

func (SelectFromJoin) SQL

func (sfj SelectFromJoin) SQL() string

SelectFromTable

type SelectFromTable struct {
	Table ID
	Alias ID // empty if not aliased
	Hints map[string]string
}

SelectFromTable is a SelectFrom that specifies a table to read from.

func (SelectFromTable) SQL

func (sft SelectFromTable) SQL() string

SelectFromUnnest

type SelectFromUnnest struct {
	Expr  Expr
	Alias ID // empty if not aliased

}

SelectFromUnnest is a SelectFrom that yields a virtual table from an array. https://cloud.google.com/spanner/docs/query-syntax#unnest

func (SelectFromUnnest) SQL

func (sfu SelectFromUnnest) SQL() string

SetColumnOptions

type SetColumnOptions struct{ Options ColumnOptions }

func (SetColumnOptions) SQL

func (sco SetColumnOptions) SQL() string

SetColumnType

type SetColumnType struct {
	Type    Type
	NotNull bool
}

func (SetColumnType) SQL

func (sct SetColumnType) SQL() string

SetDatabaseOptions

type SetDatabaseOptions struct{ Options DatabaseOptions }

func (SetDatabaseOptions) SQL

func (sdo SetDatabaseOptions) SQL() string

SetOnDelete

type SetOnDelete struct{ Action OnDelete }

func (SetOnDelete) SQL

func (sod SetOnDelete) SQL() string

StarExpr

type StarExpr int

func (StarExpr) SQL

func (StarExpr) SQL() string

StringLiteral

type StringLiteral string

func (StringLiteral) SQL

func (sl StringLiteral) SQL() string

TableAlteration

type TableAlteration interface {
	SQL() string
	// contains filtered or unexported methods
}

TableAlteration is satisfied by AddColumn, DropColumn, AddConstraint, DropConstraint, SetOnDelete and AlterColumn, AddRowDeletionPolicy, ReplaceRowDeletionPolicy, DropRowDeletionPolicy.

TableConstraint

type TableConstraint struct {
	Name       ID // may be empty
	Constraint Constraint

	Position Position // position of the "CONSTRAINT" token, or Constraint.Pos()
}

TableConstraint represents a constraint on a table.

func (TableConstraint) Pos

func (tc TableConstraint) Pos() Position

func (TableConstraint) SQL

func (tc TableConstraint) SQL() string

TableSample

type TableSample struct {
	Method   TableSampleMethod
	Size     Expr
	SizeType TableSampleSizeType
}

TableSampleMethod

type TableSampleMethod int

Bernoulli, Reservoir

const (
	Bernoulli TableSampleMethod = iota
	Reservoir
)

TableSampleSizeType

type TableSampleSizeType int

PercentTableSample, RowsTableSample

const (
	PercentTableSample TableSampleSizeType = iota
	RowsTableSample
)

TimestampLiteral

type TimestampLiteral time.Time

TimestampLiteral represents a timestamp literal. https://cloud.google.com/spanner/docs/lexical#timestamp_literals

func (TimestampLiteral) SQL

func (tl TimestampLiteral) SQL() string

Type

type Type struct {
	Array bool
	Base  TypeBase // Bool, Int64, Float64, Numeric, String, Bytes, Date, Timestamp
	Len   int64    // if Base is String or Bytes; may be MaxLen
}

Type represents a column type.

func (Type) SQL

func (t Type) SQL() string

TypeBase

type TypeBase int

Bool, Int64, Float64, Numeric, String, Bytes, Date, Timestamp, JSON

const (
	Bool TypeBase = iota
	Int64
	Float64
	Numeric
	String
	Bytes
	Date
	Timestamp
	JSON
)

func (TypeBase) SQL

func (tb TypeBase) SQL() string

Update

type Update struct {
	Table ID
	Items []UpdateItem
	Where BoolExpr
}

func (*Update) SQL

func (u *Update) SQL() string

func (*Update) String

func (u *Update) String() string

UpdateItem

type UpdateItem struct {
	Column ID
	Value  Expr // or nil for DEFAULT
}