Help us shape the future of Go! Take the 2026 Go Developer Survey

bqsql

package
v1.9.0 Latest Latest
Warning

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

Go to latest
Published: Oct 27, 2026 License: MIT Imports: 26 Imported by: 0

Documentation

Overview

Package bqsql runs a GoogleSQL subset on SQLite and converts BigQuery values between their REST encodings.

Index

Constants

View Source
const (
	OpWrite        = "WRITE"
	OpCreateTable  = "CREATE_TABLE"
	OpCreateView   = "CREATE_VIEW"
	OpCreateSchema = "CREATE_SCHEMA"
	OpDropTable    = "DROP_TABLE"
	OpDropView     = "DROP_VIEW"
	OpDropSchema   = "DROP_SCHEMA"
	OpAlter        = "ALTER"
)

Effect operations.

View Source
const (
	ModeNullable = "NULLABLE"
	ModeRequired = "REQUIRED"
	ModeRepeated = "REPEATED"
)

Schema modes.

View Source
const (
	TimestampLayout = "2006-01-02 15:04:05.000000"
	DateLayout      = "2006-01-02"
	DatetimeLayout  = "2006-01-02T15:04:05.000000"
	TimeLayout      = "15:04:05.000000"
)

Canonical stored encodings of temporal values.

Variables

View Source
var ErrSchema = errors.New("invalid schema")

ErrSchema is wrapped by every schema validation failure.

View Source
var ErrSyntax = errors.New("syntax error")

ErrSyntax is wrapped by every parse failure.

View Source
var ErrValue = errors.New("invalid value")

ErrValue is wrapped by every value conversion failure.

Functions

func Cell

func Cell(f Field, stored any) any

Cell converts a stored value into the REST "v" encoding for f.

func CellFor

func CellFor(f Field, stored any, o CellOptions) any

CellFor converts a stored value into the REST "v" encoding for f under o.

func FormatFloat

func FormatFloat(f float64) string

FormatFloat renders f as the REST API does: shortest round-trip digits, with ".0" on whole numbers.

func FormatNumeric

func FormatNumeric(f float64) string

FormatNumeric renders f as a NUMERIC with scale 9 and no trailing zeros.

func FormatTemporal

func FormatTemporal(k Kind, t time.Time) string

FormatTemporal renders t in the canonical stored encoding for k.

func FromSQLite

func FromSQLite(f Field, v any) (any, error)

FromSQLite converts a value read from SQLite into the stored form for f.

func LogicalBytes

func LogicalBytes(f Field, stored any) int64

LogicalBytes estimates the logical storage size of a stored value the way BigQuery bills it.

func NormalizeSchema

func NormalizeSchema(fs []Field) error

NormalizeSchema validates fs and rewrites type and mode names to their REST spellings.

func ParseRecord

func ParseRecord(fields []Field, obj map[string]any, o ParseOptions) ([]any, error)

ParseRecord converts a JSON object into a positional record for fields.

func ParseTemporal

func ParseTemporal(k Kind, v any) (time.Time, error)

ParseTemporal parses the many spellings BigQuery accepts for TIMESTAMP, DATE, DATETIME and TIME.

func ParseValue

func ParseValue(f Field, v any, o ParseOptions) (any, error)

ParseValue converts a decoded JSON value into the stored form for f. Stored scalars are strings, records are positional []any and repeated fields are []any; NULL is nil.

func Row

func Row(fields []Field, row []any) map[string]any

Row converts a stored row into the REST {"f":[{"v":...}]} encoding.

func RowFor

func RowFor(fields []Field, row []any, o CellOptions) map[string]any

RowFor converts a stored row into the REST {"f":[{"v":...}]} encoding under o.

func ToSQLite

func ToSQLite(f Field, stored any) driver.Value

ToSQLite converts a stored value into the value bound into SQLite: scalars map to INTEGER, REAL or TEXT and records and arrays to JSON text.

Types

type Catalog

type Catalog interface {
	Table(ref TableRef) (*TableData, bool)
	DatasetExists(project, dataset string) bool
}

Catalog resolves tables for the compiler.

type CellOptions

type CellOptions struct {
	// Int64Timestamp renders TIMESTAMP cells as integer microseconds, as formatOptions.useInt64Timestamp requests.
	Int64Timestamp bool
}

CellOptions tunes the REST cell encoding.

type Column

type Column struct {
	Name string
	Type Type
}

Column is a named, typed struct member or relation column.

func FieldColumns

func FieldColumns(fs []Field) []Column

FieldColumns converts schema fields into typed columns.

type Effect

type Effect struct {
	Options    map[string]string
	Ref        TableRef
	Op         string
	ViewQuery  string
	AlterOp    string
	Fields     []Field
	Rows       [][]any
	OrReplace  bool
	IfNotExist bool
	IfExists   bool
	Cascade    bool
}

Effect is a catalog change a statement asks the caller to apply.

type ErrKind

type ErrKind uint8

ErrKind classifies a query failure for HTTP status mapping.

const (
	ErrInvalid ErrKind = iota
	ErrNotFound
	ErrExists
	ErrRuntime
	ErrUnsupported
)

Error kinds.

type Error

type Error struct {
	Message string
	Kind    ErrKind
}

Error is a query analysis or execution failure.

func AsError

func AsError(err error) *Error

AsError returns err as an *Error, wrapping syntax errors as invalid-query failures.

func (*Error) Error

func (e *Error) Error() string

Error implements error.

type Field

type Field struct {
	Name        string  `json:"name"`
	Type        string  `json:"type"`
	Mode        string  `json:"mode,omitempty"`
	Description string  `json:"description,omitempty"`
	MaxLength   string  `json:"maxLength,omitempty"`
	Precision   string  `json:"precision,omitempty"`
	Scale       string  `json:"scale,omitempty"`
	Fields      []Field `json:"fields,omitempty"`
}

Field is one schema column in the REST TableFieldSchema encoding.

func ColumnFields

func ColumnFields(cols []Column) []Field

ColumnFields renders typed columns as schema fields.

func TypeField

func TypeField(name string, t Type) Field

TypeField renders a column as a schema field with REST type names.

func (Field) SQLType

func (f Field) SQLType() Type

SQLType converts the schema field, including its mode, into a Type.

type Input

type Input struct {
	Catalog Catalog
	Project string
	Dataset string
	Params  []Param
}

Input configures one statement run.

type Kind

type Kind uint8

Kind is a GoogleSQL type family.

const (
	KindUnknown Kind = iota
	KindInt
	KindFloat
	KindBool
	KindString
	KindBytes
	KindTimestamp
	KindDate
	KindTime
	KindDatetime
	KindNumeric
	KindBigNumeric
	KindJSON
	KindGeography
	KindStruct
	KindArray
)

Type kinds.

func KindOf

func KindOf(name string) (Kind, bool)

KindOf resolves a REST or GoogleSQL scalar type name.

func (Kind) IsNumber

func (k Kind) IsNumber() bool

IsNumber reports whether k is INT64, FLOAT64, NUMERIC or BIGNUMERIC.

func (Kind) RESTName

func (k Kind) RESTName() string

RESTName is the type name the REST API reports for k.

func (Kind) SQLName

func (k Kind) SQLName() string

SQLName is the GoogleSQL spelling of k.

type Param

type Param struct {
	Value any
	Name  string
	Field Field
}

Param is a query parameter; Name is empty for positional parameters and Value is in stored form.

type ParseOptions

type ParseOptions struct {
	IgnoreUnknown bool
}

ParseOptions tunes ParseValue.

type Query

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

Query is a parsed SELECT statement, possibly with set operations, CTEs, ORDER BY and LIMIT.

type Result

type Result struct {
	Statement string
	Fields    []Field
	Rows      [][]any
	Effects   []Effect
	Affected  int64
	Inserted  int64
	Updated   int64
	Deleted   int64
	Kind      StmtKind
}

Result is the outcome of one statement.

func Run

func Run(ctx context.Context, st *Statement, in *Input, dryRun bool) (*Result, error)

Run executes st. With dryRun set, queries are only analysed and the result carries the schema alone.

type Statement

type Statement struct {
	Text string

	Kind StmtKind
	// contains filtered or unexported fields
}

Statement is one parsed GoogleSQL statement.

func ParseStatement

func ParseStatement(sql string) (*Statement, error)

ParseStatement parses a single GoogleSQL statement.

type StmtKind

type StmtKind uint8

StmtKind classifies a parsed statement.

const (
	StmtQuery StmtKind = iota
	StmtInsert
	StmtUpdate
	StmtDelete
	StmtMerge
	StmtCreateTable
	StmtCreateView
	StmtCreateSchema
	StmtDrop
	StmtTruncate
	StmtAlter
)

Statement kinds.

func (StmtKind) DML

func (k StmtKind) DML() bool

DML reports whether the statement modifies table rows.

type TableData

type TableData struct {
	Ref       TableRef
	ViewQuery string
	Fields    []Field
	Rows      [][]any
}

TableData is a table's schema and rows as the catalog holds them.

type TableRef

type TableRef struct {
	Project string
	Dataset string
	Table   string
}

TableRef names a table.

func (TableRef) String

func (r TableRef) String() string

String renders the legacy project:dataset.table form BigQuery error messages use.

type Type

type Type struct {
	Elem   *Type
	Fields []Column
	Kind   Kind
}

Type is a GoogleSQL type; Elem is set for arrays and Fields for structs.

func (Type) IsNumeric

func (t Type) IsNumeric() bool

IsNumeric reports whether the type is a number.

Jump to

Keyboard shortcuts

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