native

type And ¶ added in v0.550100.0

type And struct {
	Left  Expr
	Right Expr
}

And is the conjunction of two predicates.

type Between ¶ added in v0.550100.0

type Between struct {
	Column  Column
	Negated bool
	Low     Literal
	High    Literal
}

Between is a [NOT] BETWEEN test with literal bounds (both inclusive).

type CatalogProvider ¶ added in v0.550100.0

type CatalogProvider interface {
	ResolveTable(ctx context.Context, schema, table string) (TableProvider, error)
}

CatalogProvider lazily resolves tables into a per-query snapshot. Return nil, nil for a missing table. Remote I/O must honor ctx. Repeated references share one resolved provider within a query; subsequent queries resolve afresh. Discovery/listing is deliberately separate from query-time resolution.

type Column ¶ added in v0.550100.0

type Column struct {
	Name  string `json:"name"`
	Index int    `json:"index"`
}

Column identifies a column of the registered table schema, by name and by index into that schema. Both refer to the full registered schema, independent of the scan's projection.

type Compare ¶ added in v0.550100.0

type Compare struct {
	Column  Column
	Op      CompareOp
	Literal Literal
}

Compare is a comparison between a column and a literal. The column is always on the left: the engine normalizes mirrored predicates (2 < id becomes id > 2) before pushing them down.

type CompareOp ¶ added in v0.550100.0

type CompareOp string

CompareOp is a comparison operator in a pushed-down predicate.

const (
	CompareEq   CompareOp = "eq"
	CompareNeq  CompareOp = "neq"
	CompareLt   CompareOp = "lt"
	CompareLtEq CompareOp = "lteq"
	CompareGt   CompareOp = "gt"
	CompareGtEq CompareOp = "gteq"
)

type Connection ¶

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

func (conn *Connection) Close()

func (conn *Connection) DeregisterTable(name string) error

func (conn *Connection) NewImport(name string) (*Import, error)

func (conn *Connection) Prepare(query string) (*Statement, error)

func (conn *Connection) RegisterArrowIPC(name string, data []byte) error

func (conn *Connection) RegisterArrowReaderZeroCopy(name string, reader array.RecordReader) error

func (conn *Connection) RegisterFFITableProvider(name string, provider unsafe.Pointer, providerDataFusionVersion string) error

func (conn *Connection) RegisterGo(name string, object any, kind int) error

type Database ¶

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

func OpenDatabase(dsn string) (*Database, error)

func (db *Database) Close()

func (db *Database) Connect(shared bool) (*Connection, error)

type DateParameter ¶

type DateParameter struct {
	Days int32
}

type DecimalParameter ¶

type DecimalParameter struct {
	Value     string
	Precision uint8
	Scale     int8
}

type DiscoverableCatalogProvider ¶ added in v0.550100.1

type DiscoverableCatalogProvider interface {
	CatalogProvider
	SchemaNames(ctx context.Context) ([]string, error)
	TableNames(ctx context.Context, schema string) ([]string, error)
}

DiscoverableCatalogProvider optionally lists schemas and tables for SQL metadata queries. Names are literal identifiers, not SQL fragments. Listings are refreshed for each metadata query; ordinary table queries only resolve referenced tables. Implementations must support concurrent calls and honor ctx. A nil list is empty. Duplicate names are ignored; empty/NUL names are errors. The reserved information_schema schema is supplied by DataFusion.

type DurationParameter ¶

type DurationParameter struct {
	Nanoseconds int64
}

type Error ¶

type Error struct {
	Kind    string
	Message string
}

func (e *Error) Error() string

func (e *Error) Is(target error) bool

func (e *Error) NativeErrorKind() string

type Expr ¶ added in v0.550100.0

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

Expr is a filter predicate pushed down to a PushdownTableProvider. It is a closed, bounded AST: the engine only ever pushes column-vs-literal comparisons, IS [NOT] NULL, [NOT] BETWEEN, [NOT] IN, and AND/OR/NOT combinations of those. Predicates outside these forms (functions, casts, arithmetic, LIKE, ...) are never pushed down; the engine evaluates them after the scan.

The concrete types are Compare, IsNull, Between, InList, And, Or, and Not. Providers pattern-match with a type switch:

switch e := expr.(type) {
case datafusion.Compare:
	// e.Column, e.Op, e.Literal
}

type Import ¶ added in v0.550100.0

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

Import owns unpublished native batches. Close also aborts an unfinished import.

func (i *Import) Append(data []byte) error

func (i *Import) Close()

func (i *Import) Commit(conn *Connection) error

type InList ¶ added in v0.550100.0

type InList struct {
	Column  Column
	Negated bool
	List    []Literal
}

InList is a [NOT] IN test against a list of literals.

type InsertOp ¶ added in v0.550100.0

type InsertOp int

InsertOp describes a requested write. Providers must reject unsupported modes.

const (
	InsertAppend InsertOp = iota
	InsertOverwrite
	InsertReplace
)

type IsNull ¶ added in v0.550100.0

type IsNull struct {
	Column  Column
	Negated bool
}

IsNull is an IS NULL test on a column; Negated makes it IS NOT NULL.

type Literal ¶ added in v0.550100.0

type Literal struct {
	Type     LiteralType
	Value    any
	Unit     TimeUnit
	TimeZone string
}

Literal is a typed literal value in a pushed-down predicate. Value holds the Go representation determined by Type:

LiteralBool      bool
LiteralInt8      int8       (int16/int32/int64 accordingly)
LiteralUint8     uint8      (uint16/uint32/uint64 accordingly)
LiteralFloat32   float32    (float64 accordingly)
LiteralUtf8      string
LiteralBinary    []byte
LiteralDate32    int32      (days since the Unix epoch)
LiteralDate64    int64      (milliseconds since the Unix epoch)
LiteralTimestamp int64      (in Unit since the Unix epoch)

Unit and TimeZone are set only for LiteralTimestamp; TimeZone may be empty for a timezone-less timestamp.

func (l *Literal) UnmarshalJSON(data []byte) error

type LiteralType ¶ added in v0.550100.0

type LiteralType string

LiteralType identifies the type of a literal value in a pushed-down predicate.

const (
	LiteralBool      LiteralType = "bool"
	LiteralInt8      LiteralType = "int8"
	LiteralInt16     LiteralType = "int16"
	LiteralInt32     LiteralType = "int32"
	LiteralInt64     LiteralType = "int64"
	LiteralUint8     LiteralType = "uint8"
	LiteralUint16    LiteralType = "uint16"
	LiteralUint32    LiteralType = "uint32"
	LiteralUint64    LiteralType = "uint64"
	LiteralFloat32   LiteralType = "float32"
	LiteralFloat64   LiteralType = "float64"
	LiteralUtf8      LiteralType = "utf8"
	LiteralBinary    LiteralType = "binary"
	LiteralDate32    LiteralType = "date32"
	LiteralDate64    LiteralType = "date64"
	LiteralTimestamp LiteralType = "timestamp"
)

type Not ¶ added in v0.550100.0

type Not struct {
	Expr Expr
}

Not negates a predicate.

type NullParameter ¶

type NullParameter struct {
	Type      ParameterType
	Precision uint8
	Scale     int8
	TimeZone  string
}

type Or ¶ added in v0.550100.0

type Or struct {
	Left  Expr
	Right Expr
}

Or is the disjunction of two predicates.

type ParameterType ¶

type ParameterType int32

const (
	ParameterBool ParameterType = iota + 1
	ParameterInt64
	ParameterUInt64
	ParameterFloat64
	ParameterString
	ParameterBinary
	ParameterDate
	ParameterTime
	ParameterTimestamp
	ParameterDuration
	ParameterDecimal
)

type PushdownTableProvider ¶ added in v0.550100.0

type PushdownTableProvider interface {
	TableProvider
	ScanWithOptions(context.Context, ScanOptions) (array.RecordReader, error)
}

PushdownTableProvider optionally accepts projection and conservative pruning. It must return precisely the projected schema, including field order.

type RecordReader ¶ added in v0.550000.2

type RecordReader interface {
	arrio.Reader
	Schema() *arrow.Schema
	Close() error
}

RecordReader owns a native result stream. Its schema is available before the first read, including for empty results. Close is idempotent and cancels work. Each returned batch has its own reference and must be released by the caller.

type ScalarFunction ¶ added in v0.550100.0

type ScalarFunction struct {
	Name       string
	Arguments  []arrow.DataType
	ReturnType arrow.DataType
	Volatility Volatility
	Evaluate   func(ctx context.Context, args []arrow.Array, rows int) (arrow.Array, error)
}

ScalarFunction is a typed, batch-oriented Go function. Evaluate owns its returned array; the bridge releases it. Arguments are borrowed for the call. rows is supplied separately so zero-argument functions can produce a batch. Calls may run concurrently. Blocking implementations must honor ctx.

type ScanOptions ¶ added in v0.550100.0

type ScanOptions struct {
	Projection []int
	Filters    []Expr
	Limit      int64
}

ScanOptions describes exact projection and advisory pruning. A nil Projection means all columns; an empty non-nil slice means zero columns, preserving rows. Filters are ANDed and rechecked by DataFusion. Limit is -1 without a safe hint.

type Statement ¶

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

func (stmt *Statement) Close()

func (stmt *Statement) ExecuteArrow(ctx context.Context, args []driver.NamedValue) (RecordReader, error)

func (stmt *Statement) NumInput() int

func (stmt *Statement) Serializes() bool

type TableProvider ¶ added in v0.550100.0

type TableProvider interface {
	Schema() *arrow.Schema
	Scan(context.Context) (array.RecordReader, error)
}

TableProvider supplies an independent reader for each scan. Readers transfer ownership to the engine; buffers are copied before native code retains them. Implementations must support concurrent calls and honor context cancellation.

type TimeParameter ¶

type TimeParameter struct {
	Nanoseconds int64
}

type TimeUnit ¶ added in v0.550100.0

type TimeUnit string

TimeUnit is the resolution of a timestamp literal.

const (
	TimeUnitSecond      TimeUnit = "s"
	TimeUnitMillisecond TimeUnit = "ms"
	TimeUnitMicrosecond TimeUnit = "us"
	TimeUnitNanosecond  TimeUnit = "ns"
)

type TimestampParameter ¶

type TimestampParameter struct {
	Nanoseconds int64
	TimeZone    string
}

type UInt64Parameter ¶

type UInt64Parameter struct {
	Value uint64
}

type Volatility ¶ added in v0.550100.0

type Volatility int

Volatility controls optimizer assumptions for an explicitly registered UDF.

const (
	Volatile  Volatility = iota // default: every call may return a different value
	Stable                      // identical arguments produce identical values within one query
	Immutable                   // identical arguments always produce identical values
)

type WritableTableProvider ¶ added in v0.550100.0

type WritableTableProvider interface {
	TableProvider
	InsertInto(context.Context, InsertOp, array.RecordReader) (uint64, error)
}

WritableTableProvider can consume INSERT input. The reader is borrowed for this call and released by the bridge. Retain batches to keep them beyond the call. Implementations must check reader.Err(), honor cancellation, and finish their commit/rollback before returning. Errors are never retried by the bridge.