duckdb

package module
v1.8.3 Latest Latest
Warning

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

 Go to latest Published: Nov 5, 2024 License: MIT Imports: 20 Imported by: 109

README

Go SQL driver for DuckDB

The DuckDB driver conforms to the built-in database/sql interface.

Tests status GoDoc

Installation

go get github.com/marcboeker/go-duckdb
Windows

On windows, the correct version of gcc and the neccesary runtime libraries needs to be installed. One method to do this is using msys64. To begin, install msys64 using their installer. Once this is done, open a msys64 shell and run

pacman -S mingw-w64-ucrt-x86_64-gcc

select yes when neccesary, its ok if the shell closes. Then add gcc to the path using whatever method you prefer. In powershell this is $env:PATH = "C:\msys64\ucrt64\bin:$env:PATH". Once this is done, you can compile this package on windows.

Usage

go-duckdb hooks into the database/sql interface provided by the Go stdlib. To open a connection, simply specify the driver type as duckdb.

db, err := sql.Open("duckdb", "")
check(err)
defer db.Close()

This creates an in-memory instance of DuckDB. To open a persistent database, you need to specify a filepath to the database file. If the file does not exist, then DuckDB creates it.

db, err := sql.Open("duckdb", "/path/to/foo.db")
check(err)
defer db.Close()

If you want to set specific config options for DuckDB, you can add them as query style parameters in the form of name=value pairs to the DSN.

db, err := sql.Open("duckdb", "/path/to/foo.db?access_mode=read_only&threads=4")
check(err)
defer db.Close()

Alternatively, you can use sql.OpenDB. That way, you can perform initialization steps in a callback function before opening the database. Here's an example that configures some database parameters when opening a database with sql.OpenDB(connector).

connector, err := duckdb.NewConnector("/path/to/foo.db?access_mode=read_only&threads=4", func(execer driver.ExecerContext) error {
    bootQueries := []string{
        "SET schema=main",
        "SET search_path=main",
    }

    for _, query := range bootQueries {
        _, err = execer.ExecContext(context.Background(), query, nil)
        if err != nil {
			return err
        }
    }
    return nil
})
check(err)

db := sql.OpenDB(connector)
defer db.Close()

Please refer to the database/sql documentation for further usage instructions.

Notes and FAQs

undefined: conn

When building this package, some people run into an undefined: conn error. This is due to the go compiler determining that CGO is not available. This can happen due to a few issues.

The first noted in the comment here is that the buildtools are not installed. To fix this for ubuntu, you can install them using:

sudo apt-get update && sudo apt-get install build-essential

Another issue is when you are cross-compiling, since the go compiler automatically disables CGO when cross-compiling. To enable cgo when cross-compiling use CC={C cross compiler} CGO_ENABLED=1 {command} to force-enable CGO and set the right cross-compiler.

TIMESTAMP vs. TIMESTAMP_TZ

In the C API, DuckDB stores both TIMESTAMP and TIMESTAMP_TZ as duckdb_timestamp, which holds the number of microseconds elapsed since January 1, 1970 UTC (i.e., an instant without offset information). When passing a time.Time to go-duckdb, go-duckdb transforms it to an instant with UnixMicro(), even when using TIMESTAMP_TZ. Later, scanning either type of value returns an instant, as SQL types do not model time zone information for individual values.

Memory Allocation

DuckDB lives in-process. Therefore, all its memory lives in the driver. All allocations live in the host process, which is the Go application. Especially for long-running applications, it is crucial to call the corresponding Close-functions as specified in database/sql. The following is a list of examples.

db, err := sql.Open("duckdb", "")
defer db.Close()

conn, err := db.Conn(context.Background())
defer conn.Close()

rows, err := conn.QueryContext(context.Background(), "SELECT 42")
// Alternatively, rows.Next() has to return false.
rows.Close()

appender, err := NewAppenderFromConn(conn, "", "test")
defer appender.Close()

// If not passed to sql.OpenDB.
connector, err := NewConnector("", nil)
defer connector.Close()

DuckDB Appender API

If you want to use the DuckDB Appender API, you can obtain a new Appender by passing a DuckDB connection to NewAppenderFromConn(). See examples/appender.go for a complete example.

connector, err := duckdb.NewConnector("test.db", nil)
check(err)
defer connector.Close()

conn, err := connector.Connect(context.Background())
check(err)
defer conn.Close()

// Obtain an appender from the connection.
// NOTE: The table 'test_tbl' must exist in test.db.
appender, err := NewAppenderFromConn(conn, "", "test_tbl")
check(err)
defer appender.Close()

err = appender.AppendRow(...)
check(err)

DuckDB Profiling API

This section describes using the DuckDB Profiling API. DuckDB's profiling information is connection-local. The following example walks you through the necessary steps to obtain the ProfilingInfo type, which contains all available metrics. Please refer to the DuckDB documentation on configuring and collecting specific metrics.

  • First, you need to obtain a connection.
  • Then, you enable profiling for the connection.
  • Now, for each subsequent query on this connection, DuckDB will collect profiling information.
    • Optionally, you can turn off profiling at any point.
  • Next, you execute the query for which you want to obtain profiling information.
  • Finally, directly after executing the query, retrieve any available profiling information.

For readability, we omit error handling in this example.

db, err := sql.Open("duckdb", "")
con, err := db.Conn(context.Background())

_, err = con.ExecContext(context.Background(), `PRAGMA enable_profiling = 'no_output'`)
_, err = con.ExecContext(context.Background(), `PRAGMA profiling_mode = 'detailed'`)

res, err := con.QueryContext(context.Background(), `SELECT 42`)
info, err := GetProfilingInfo(con)
err = res.Close()

_, err = con.ExecContext(context.Background(), `PRAGMA disable_profiling`)
err = con.Close()
err = db.Close()

DuckDB Apache Arrow Interface

If you want to use the DuckDB Arrow Interface, you can obtain a new Arrow by passing a DuckDB connection to NewArrowFromConn().

connector, err := duckdb.NewConnector("", nil)
check(err)
defer connector.Close()

conn, err := connector.Connect(context.Background())
check(err)
defer conn.Close()

// Obtain the Arrow from the connection.
arrow, err := duckdb.NewArrowFromConn(conn)
check(err)

rdr, err := arrow.QueryContext(context.Background(), "SELECT * FROM generate_series(1, 10)")
check(err)
defer rdr.Release()

for rdr.Next() {
  // Process each record.
}

The Arrow interface is a heavy dependency. If you do not need it, you can disable it by passing -tags=no_duckdb_arrow to go build. This will be made opt-in in V2.

go build -tags="no_duckdb_arrow"

Vendoring

If you want to vendor a module containing go-duckdb, please use modvendor to include the missing header files and libraries. See issue #174 for more details.

  1. go install github.com/goware/modvendor@latest
  2. go mod vendor
  3. modvendor -copy="**/*.a **/*.h" -v

Now you can build your module as usual.

Linking DuckDB

By default, go-duckdb statically links DuckDB into your binary. Statically linking DuckDB increases your binary size.

go-duckdb bundles pre-compiled static libraries for some OS and architecture combinations.

  • MacOS: amd64, arm64.
  • Linux: amd64, arm64.
  • FreeBSD: amd64.
  • Windows: amd64.

Alternatively, you can dynamically link DuckDB by passing -tags=duckdb_use_lib to go build. You must have a copy of libduckdb available on your system (.so on Linux or .dylib on macOS), which you can download from the DuckDB releases page. For example:

# On Linux.
CGO_ENABLED=1 CGO_LDFLAGS="-L/path/to/libs" go build -tags=duckdb_use_lib main.go
LD_LIBRARY_PATH=/path/to/libs ./main

# On macOS.
CGO_ENABLED=1 CGO_LDFLAGS="-L/path/to/libs" go build -tags=duckdb_use_lib main.go
DYLD_LIBRARY_PATH=/path/to/libs ./main

DuckDB Extensions

go-duckdb statically builds the JSON extension for its pre-compiled libraries. Additionally, automatic extension loading is enabled. The extensions available differ between the pre-compiled libraries. Thus, if you fail to install and load an extension, you might have to link a custom DuckDB.

Specifically, for MingW (Windows), there are no distributed extensions (yet). You can statically include them by extending the BUILD_EXTENSIONS="json" variable in the Makefile.

Documentation

Overview

Package duckdb implements a database/sql driver for the DuckDB database.

Example (SimpleConnection) 
// Connect to DuckDB using '[database/sql.Open]'.
db, err := sql.Open("duckdb", "?access_mode=READ_WRITE")
checkErr(err, "failed to open connection to duckdb: %s")
defer db.Close()

ctx := context.Background()

createStmt := `CREATE table users(name VARCHAR, age INTEGER)`
_, err = db.ExecContext(ctx, createStmt)
checkErr(err, "failed to create table: %s")

insertStmt := `INSERT INTO users(name, age) VALUES (?, ?);`
res, err := db.ExecContext(ctx, insertStmt, "Marc", 30)
checkErr(err, "failed to insert users: %s")

rowsAffected, err := res.RowsAffected()
checkErr(err, "failed to get number of rows affected")
fmt.Printf("Inserted %d row(s) into users table", rowsAffected)

Output:

Inserted 1 row(s) into users table

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func GetDataChunkCapacity added in v1.7.1 

func GetDataChunkCapacity() int

GetDataChunkCapacity returns the capacity of a data chunk.

func RegisterReplacementScan added in v1.7.1 

func RegisterReplacementScan(connector *Connector, cb ReplacementScanCallback)

func RegisterScalarUDF added in v1.8.1 

func RegisterScalarUDF(c *sql.Conn, name string, f ScalarFunc) error

RegisterScalarUDF registers a user-defined scalar function. *sql.Conn is the SQL connection on which to register the scalar function. name is the function name, and f is the scalar function's interface ScalarFunc. RegisterScalarUDF takes ownership of f, so you must pass it as a pointer.

func RegisterScalarUDFSet added in v1.8.1 

func RegisterScalarUDFSet(c *sql.Conn, name string, functions ...ScalarFunc) error

RegisterScalarUDFSet registers a set of user-defined scalar functions with the same name. This enables overloading of scalar functions. E.g., the function my_length() can have implementations like my_length(LIST(ANY)) and my_length(VARCHAR). *sql.Conn is the SQL connection on which to register the scalar function set. name is the function name of each function in the set. functions contains all ScalarFunc functions of the scalar function set.

func RegisterTableUDF added in v1.8.3 

func RegisterTableUDF[TFT TableFunction](c *sql.Conn, name string, f TFT) error

RegisterTableUDF registers a user-defined table function. Projection pushdown is enabled by default.

func SetChunkValue added in v1.8.1 

func SetChunkValue[T any](chunk DataChunk, colIdx int, rowIdx int, val T) error

SetChunkValue writes a single value to a column in a data chunk. The difference with `chunk.SetValue` is that `SetChunkValue` does not require casting the value to `any` (implicitly). NOTE: Custom ENUM types must be passed as string.

func SetRowValue added in v1.8.3 

func SetRowValue[T any](row Row, colIdx int, val T) error

SetRowValue sets the value at colIdx to val. Returns an error on failure, and nil for non-projected columns.

Types

type Appender 

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

Appender holds the DuckDB appender. It allows efficient bulk loading into a DuckDB database.

func NewAppenderFromConn 

func NewAppenderFromConn(driverConn driver.Conn, schema, table string) (*Appender, error)

NewAppenderFromConn returns a new Appender from a DuckDB driver connection.

func (*Appender) AppendRow 

func (a *Appender) AppendRow(args ...driver.Value) error

AppendRow loads a row of values into the appender. The values are provided as separate arguments.

func (*Appender) Close 

func (a *Appender) Close() error

Close the appender. This will flush the appender to the underlying table. It is vital to call this when you are done with the appender to avoid leaking memory.

func (*Appender) Flush 

func (a *Appender) Flush() error

Flush the data chunks to the underlying table and clear the internal cache. Does not close the appender, even if it returns an error. Unless you have a good reason to call this, call Close when you are done with the appender.

type Arrow added in v1.6.0 

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

Arrow exposes DuckDB Apache Arrow interface. https://duckdb.org/docs/api/c/api#arrow-interface

func NewArrowFromConn added in v1.6.0 

func NewArrowFromConn(driverConn driver.Conn) (*Arrow, error)

NewArrowFromConn returns a new Arrow from a DuckDB driver connection.

func (*Arrow) QueryContext added in v1.6.0 

func (a *Arrow) QueryContext(ctx context.Context, query string, args ...any) (array.RecordReader, error)

QueryContext prepares statements, executes them, returns Apache Arrow array.RecordReader as a result of the last executed statement. Arguments are bound to the last statement.

func (*Arrow) RegisterView added in v1.8.2 

func (a *Arrow) RegisterView(reader array.RecordReader, name string) (release func(), err error)

RegisterView registers an Arrow record reader as a view with the given name in DuckDB. The returned release function must be called to release the memory once the view is no longer needed.

type CardinalityInfo added in v1.8.3 

type CardinalityInfo struct {
	// The absolute Cardinality.
	Cardinality uint
	// IsExact indicates whether the cardinality is exact.
	Exact bool
}

CardinalityInfo contains the cardinality of a (table) function. If it is impossible or difficult to determine the exact cardinality, an approximate cardinality may be used.

type ChunkTableFunction added in v1.8.3 

type ChunkTableFunction = tableFunction[ChunkTableSource]

A ChunkTableFunction is a type which can be bound to return a ChunkTableSource.

type ChunkTableSource added in v1.8.3 

type ChunkTableSource interface {

	// FillChunk takes a Chunk and fills it with values.
	// It returns true, if there are more chunks to fill.
	FillChunk(DataChunk) error
	// contains filtered or unexported methods
}

A ChunkTableSource represents anything that produces rows in a vectorised way. The cardinality is requested before function initialization. After initializing the ChunkTableSource, go-duckdb requests the rows. It sequentially calls the FillChunk method with a single thread.

type ColumnInfo added in v1.8.3 

type ColumnInfo struct {
	// The column Name.
	Name string
	// The column type T.
	T TypeInfo
}

ColumnInfo contains the metadata of a column.

type Composite 

type Composite[T any] struct {
	// contains filtered or unexported fields
}

Use as the `Scanner` type for any composite types (maps, lists, structs)

func (Composite[T]) Get 

func (s Composite[T]) Get() T

func (*Composite[T]) Scan 

func (s *Composite[T]) Scan(v any) error

type Connector added in v1.6.0 

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

func NewConnector 

func NewConnector(dsn string, connInitFn func(execer driver.ExecerContext) error) (*Connector, error)

NewConnector opens a new Connector for a DuckDB database. The user must close the Connector, if it is not passed to the sql.OpenDB function. Otherwise, sql.DB closes the Connector when calling sql.DB.Close().

Example 
c, err := NewConnector("duckdb?access_mode=READ_WRITE", func(execer driver.ExecerContext) error {
	initQueries := []string{
		`SET memory_limit = '10GB';`,
		`SET threads TO 1;`,
	}

	ctx := context.Background()
	for _, query := range initQueries {
		_, err := execer.ExecContext(ctx, query, nil)
		if err != nil {
			return err
		}
	}
	return nil
})
checkErr(err, "failed to create new duckdb connector: %s")
defer c.Close()

db := sql.OpenDB(c)
defer db.Close()

var value string
row := db.QueryRow(`SELECT value FROM duckdb_settings() WHERE name = 'memory_limit';`)
if row.Scan(&value) != nil {
	log.Fatalf("failed to scan row: %s", err)
}

fmt.Printf("Setting memory_limit is %s", value)

Output:

Setting memory_limit is 9.3 GiB

func (*Connector) Close added in v1.6.0 

func (c *Connector) Close() error

func (*Connector) Connect added in v1.6.0 

func (c *Connector) Connect(context.Context) (driver.Conn, error)

func (*Connector) Driver added in v1.6.0 

func (*Connector) Driver() driver.Driver

type DataChunk added in v1.7.1 

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

DataChunk storage of a DuckDB table.

func (*DataChunk) GetSize added in v1.7.1 

func (chunk *DataChunk) GetSize() int

GetSize returns the internal size of the data chunk.

func (*DataChunk) GetValue added in v1.7.1 

func (chunk *DataChunk) GetValue(colIdx int, rowIdx int) (any, error)

GetValue returns a single value of a column.

func (*DataChunk) SetSize added in v1.7.1 

func (chunk *DataChunk) SetSize(size int) error

SetSize sets the internal size of the data chunk. Cannot exceed GetCapacity().

func (*DataChunk) SetValue added in v1.7.1 

func (chunk *DataChunk) SetValue(colIdx int, rowIdx int, val any) error

SetValue writes a single value to a column in a data chunk. Note that this requires casting the type for each invocation. NOTE: Custom ENUM types must be passed as string.

type Decimal 

type Decimal struct {
	Width uint8
	Scale uint8
	Value *big.Int
}

func (*Decimal) Float64 

func (d *Decimal) Float64() float64

type Driver 

type Driver struct{}

func (Driver) Open 

func (d Driver) Open(dsn string) (driver.Conn, error)

func (Driver) OpenConnector 

func (Driver) OpenConnector(dsn string) (driver.Connector, error)

type Error added in v1.7.1 

type Error struct {
	Type ErrorType
	Msg  string
}

func (*Error) Error added in v1.7.1 

func (e *Error) Error() string

func (*Error) Is added in v1.7.1 

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

type ErrorType added in v1.7.1 

type ErrorType int
const (
	ErrorTypeInvalid              ErrorType = iota // invalid type
	ErrorTypeOutOfRange                            // value out of range error
	ErrorTypeConversion                            // conversion/casting error
	ErrorTypeUnknownType                           // unknown type error
	ErrorTypeDecimal                               // decimal related
	ErrorTypeMismatchType                          // type mismatch
	ErrorTypeDivideByZero                          // divide by 0
	ErrorTypeObjectSize                            // object size exceeded
	ErrorTypeInvalidType                           // incompatible for operation
	ErrorTypeSerialization                         // serialization
	ErrorTypeTransaction                           // transaction management
	ErrorTypeNotImplemented                        // method not implemented
	ErrorTypeExpression                            // expression parsing
	ErrorTypeCatalog                               // catalog related
	ErrorTypeParser                                // parser related
	ErrorTypePlanner                               // planner related
	ErrorTypeScheduler                             // scheduler related
	ErrorTypeExecutor                              // executor related
	ErrorTypeConstraint                            // constraint related
	ErrorTypeIndex                                 // index related
	ErrorTypeStat                                  // stat related
	ErrorTypeConnection                            // connection related
	ErrorTypeSyntax                                // syntax related
	ErrorTypeSettings                              // settings related
	ErrorTypeBinder                                // binder related
	ErrorTypeNetwork                               // network related
	ErrorTypeOptimizer                             // optimizer related
	ErrorTypeNullPointer                           // nullptr exception
	ErrorTypeIO                                    // IO exception
	ErrorTypeInterrupt                             // interrupt
	ErrorTypeFatal                                 // Fatal exceptions are non-recoverable, and render the entire DB in an unusable state
	ErrorTypeInternal                              // Internal exceptions indicate something went wrong internally (i.e. bug in the code base)
	ErrorTypeInvalidInput                          // Input or arguments error
	ErrorTypeOutOfMemory                           // out of memory
	ErrorTypePermission                            // insufficient permissions
	ErrorTypeParameterNotResolved                  // parameter types could not be resolved
	ErrorTypeParameterNotAllowed                   // parameter types not allowed
	ErrorTypeDependency                            // dependency
	ErrorTypeHTTP
	ErrorTypeMissingExtension // Thrown when an extension is used but not loaded
	ErrorTypeAutoLoad         // Thrown when an extension is used but not loaded
	ErrorTypeSequence
	ErrorTypeInvalidConfiguration // An invalid configuration was detected (e.g. a Secret param was missing, or a required setting not found)
)

type Interval 

type Interval struct {
	Days   int32 `json:"days"`
	Months int32 `json:"months"`
	Micros int64 `json:"micros"`
}

type Map 

type Map map[any]any

func (*Map) Scan 

func (m *Map) Scan(v any) error

type ParallelChunkTableFunction added in v1.8.3 

type ParallelChunkTableFunction = tableFunction[ParallelChunkTableSource]

A ParallelChunkTableFunction is a type which can be bound to return a ParallelChunkTableSource.

type ParallelChunkTableSource added in v1.8.3 

type ParallelChunkTableSource interface {

	// FillChunk takes a Chunk and fills it with values.
	// It returns true, if there are more chunks to fill.
	FillChunk(any, DataChunk) error
	// contains filtered or unexported methods
}

A ParallelChunkTableSource represents anything that produces rows in a vectorised way. The cardinality is requested before function initialization. After initializing the ParallelChunkTableSource, go-duckdb requests the rows. It simultaneously calls the FillChunk method with multiple threads. If ParallelTableSourceInfo.MaxThreads is greater than one, FillChunk must use synchronization primitives to avoid race conditions.

type ParallelRowTableFunction added in v1.8.3 

type ParallelRowTableFunction = tableFunction[ParallelRowTableSource]

A ParallelRowTableFunction is a type which can be bound to return a ParallelRowTableSource.

type ParallelRowTableSource added in v1.8.3 

type ParallelRowTableSource interface {

	// FillRow takes a Row and fills it with values.
	// It returns true, if there are more rows to fill.
	FillRow(any, Row) (bool, error)
	// contains filtered or unexported methods
}

A ParallelRowTableSource represents anything that produces rows in a non-vectorised way. The cardinality is requested before function initialization. After initializing the ParallelRowTableSource, go-duckdb requests the rows. It simultaneously calls the FillRow method with multiple threads. If ParallelTableSourceInfo.MaxThreads is greater than one, FillRow must use synchronisation primitives to avoid race conditions.

type ParallelTableSourceInfo added in v1.8.3 

type ParallelTableSourceInfo struct {
	// MaxThreads is the maximum number of threads on which to run the table source function.
	// If set to 0, it uses DuckDB's default thread configuration.
	MaxThreads int
}

ParallelTableSourceInfo contains information for initializing a parallelism-aware table source.

type ProfilingInfo added in v1.8.1 

type ProfilingInfo struct {
	// Metrics contains all key-value pairs of the current node.
	// The key represents the name and corresponds to the measured value.
	Metrics map[string]string
	// Children contains all children of the node and their respective metrics.
	Children []ProfilingInfo
}

ProfilingInfo is a recursive type containing metrics for each node in DuckDB's query plan. There are two types of nodes: the QUERY_ROOT and OPERATOR nodes. The QUERY_ROOT refers exclusively to the top-level node; its metrics are measured over the entire query. The OPERATOR nodes refer to the individual operators in the query plan.

func GetProfilingInfo added in v1.8.1 

func GetProfilingInfo(c *sql.Conn) (ProfilingInfo, error)

GetProfilingInfo obtains all available metrics set by the current connection.

type ReplacementScanCallback added in v1.7.1 

type ReplacementScanCallback func(tableName string) (string, []any, error)

type Row added in v1.8.3 

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

Row represents one row in duckdb. It references the internal vectors.

func (Row) IsProjected added in v1.8.3 

func (r Row) IsProjected(colIdx int) bool

IsProjected returns whether the column is projected.

func (Row) SetRowValue added in v1.8.3 

func (r Row) SetRowValue(colIdx int, val any) error

SetRowValue sets the value at colIdx to val. Returns an error on failure.

type RowTableFunction added in v1.8.3 

type RowTableFunction = tableFunction[RowTableSource]

A RowTableFunction is a type which can be bound to return a RowTableSource.

type RowTableSource added in v1.8.3 

type RowTableSource interface {

	// FillRow takes a Row and fills it with values.
	// It returns true, if there are more rows to fill.
	FillRow(Row) (bool, error)
	// contains filtered or unexported methods
}

A RowTableSource represents anything that produces rows in a non-vectorised way. The cardinality is requested before function initialization. After initializing the RowTableSource, go-duckdb requests the rows. It sequentially calls the FillRow method with a single thread.

type ScalarFunc added in v1.8.1 

type ScalarFunc interface {
	// Config returns ScalarFuncConfig to configure the scalar function.
	Config() ScalarFuncConfig
	// Executor returns ScalarFuncExecutor to execute the scalar function.
	Executor() ScalarFuncExecutor
}

ScalarFunc is the user-defined scalar function interface. Any scalar function must implement a Config function, and an Executor function.

type ScalarFuncConfig added in v1.8.1 

type ScalarFuncConfig struct {
	// InputTypeInfos contains Type information for each input parameter of the scalar function.
	InputTypeInfos []TypeInfo
	// ResultTypeInfo holds the Type information of the scalar function's result type.
	ResultTypeInfo TypeInfo

	// VariadicTypeInfo configures the number of input parameters.
	// If this field is nil, then the input parameters match InputTypeInfos.
	// Otherwise, the scalar function's input parameters are set to variadic, allowing any number of input parameters.
	// The Type of the first len(InputTypeInfos) parameters is configured by InputTypeInfos, and all
	// remaining parameters must match the variadic Type. To configure different variadic parameter types,
	// you must set the VariadicTypeInfo's Type to TYPE_ANY.
	VariadicTypeInfo TypeInfo
	// Volatile sets the stability of the scalar function to volatile, if true.
	// Volatile scalar functions might create a different result per row.
	// E.g., random() is a volatile scalar function.
	Volatile bool
	// SpecialNullHandling disables the default NULL handling of scalar functions, if true.
	// The default NULL handling is: NULL in, NULL out. I.e., if any input parameter is NULL, then the result is NULL.
	SpecialNullHandling bool
}

ScalarFuncConfig contains the fields to configure a user-defined scalar function.

type ScalarFuncExecutor added in v1.8.1 

type ScalarFuncExecutor struct {
	// RowExecutor accepts a row-based execution function.
	// []driver.Value contains the row values, and it returns the row execution result, or error.
	RowExecutor func(values []driver.Value) (any, error)
}

ScalarFuncExecutor contains the callback function to execute a user-defined scalar function. Currently, its only field is a row-based executor.

type StructEntry added in v1.8.1 

type StructEntry interface {
	// Info returns a STRUCT entry's type information.
	Info() TypeInfo
	// Name returns a STRUCT entry's name.
	Name() string
}

StructEntry is an interface to provide STRUCT entry information.

func NewStructEntry added in v1.8.1 

func NewStructEntry(info TypeInfo, name string) (StructEntry, error)

NewStructEntry returns a STRUCT entry. info contains information about the entry's type, and name holds the entry's name.

type TableFunction added in v1.8.3 

type TableFunction interface {
	RowTableFunction | ParallelRowTableFunction | ChunkTableFunction | ParallelChunkTableFunction
}

TableFunction implements different table function types: RowTableFunction, ParallelRowTableFunction, ChunkTableFunction, and ParallelChunkTableFunction.

type TableFunctionConfig added in v1.8.3 

type TableFunctionConfig struct {
	// The Arguments of the table function.
	Arguments []TypeInfo
	// The NamedArguments of the table function.
	NamedArguments map[string]TypeInfo
}

TableFunctionConfig contains any information passed to DuckDB when registering the table function.

type Type added in v1.8.1 

type Type C.duckdb_type

Type wraps the corresponding DuckDB type enum. 

const (
	TYPE_INVALID      Type = C.DUCKDB_TYPE_INVALID
	TYPE_BOOLEAN      Type = C.DUCKDB_TYPE_BOOLEAN
	TYPE_TINYINT      Type = C.DUCKDB_TYPE_TINYINT
	TYPE_SMALLINT     Type = C.DUCKDB_TYPE_SMALLINT
	TYPE_INTEGER      Type = C.DUCKDB_TYPE_INTEGER
	TYPE_BIGINT       Type = C.DUCKDB_TYPE_BIGINT
	TYPE_UTINYINT     Type = C.DUCKDB_TYPE_UTINYINT
	TYPE_USMALLINT    Type = C.DUCKDB_TYPE_USMALLINT
	TYPE_UINTEGER     Type = C.DUCKDB_TYPE_UINTEGER
	TYPE_UBIGINT      Type = C.DUCKDB_TYPE_UBIGINT
	TYPE_FLOAT        Type = C.DUCKDB_TYPE_FLOAT
	TYPE_DOUBLE       Type = C.DUCKDB_TYPE_DOUBLE
	TYPE_TIMESTAMP    Type = C.DUCKDB_TYPE_TIMESTAMP
	TYPE_DATE         Type = C.DUCKDB_TYPE_DATE
	TYPE_TIME         Type = C.DUCKDB_TYPE_TIME
	TYPE_INTERVAL     Type = C.DUCKDB_TYPE_INTERVAL
	TYPE_HUGEINT      Type = C.DUCKDB_TYPE_HUGEINT
	TYPE_UHUGEINT     Type = C.DUCKDB_TYPE_UHUGEINT
	TYPE_VARCHAR      Type = C.DUCKDB_TYPE_VARCHAR
	TYPE_BLOB         Type = C.DUCKDB_TYPE_BLOB
	TYPE_DECIMAL      Type = C.DUCKDB_TYPE_DECIMAL
	TYPE_TIMESTAMP_S  Type = C.DUCKDB_TYPE_TIMESTAMP_S
	TYPE_TIMESTAMP_MS Type = C.DUCKDB_TYPE_TIMESTAMP_MS
	TYPE_TIMESTAMP_NS Type = C.DUCKDB_TYPE_TIMESTAMP_NS
	TYPE_ENUM         Type = C.DUCKDB_TYPE_ENUM
	TYPE_LIST         Type = C.DUCKDB_TYPE_LIST
	TYPE_STRUCT       Type = C.DUCKDB_TYPE_STRUCT
	TYPE_MAP          Type = C.DUCKDB_TYPE_MAP
	TYPE_ARRAY        Type = C.DUCKDB_TYPE_ARRAY
	TYPE_UUID         Type = C.DUCKDB_TYPE_UUID
	TYPE_UNION        Type = C.DUCKDB_TYPE_UNION
	TYPE_BIT          Type = C.DUCKDB_TYPE_BIT
	TYPE_TIME_TZ      Type = C.DUCKDB_TYPE_TIME_TZ
	TYPE_TIMESTAMP_TZ Type = C.DUCKDB_TYPE_TIMESTAMP_TZ
	TYPE_ANY          Type = C.DUCKDB_TYPE_ANY
	TYPE_VARINT       Type = C.DUCKDB_TYPE_VARINT
	TYPE_SQLNULL      Type = C.DUCKDB_TYPE_SQLNULL
)

type TypeInfo added in v1.8.1 

type TypeInfo interface {
	// InternalType returns the Type.
	InternalType() Type
	// contains filtered or unexported methods
}

TypeInfo is an interface for a DuckDB type.

func NewDecimalInfo added in v1.8.1 

func NewDecimalInfo(width uint8, scale uint8) (TypeInfo, error)

NewDecimalInfo returns DECIMAL type information. Its input parameters are the width and scale of the DECIMAL type.

func NewEnumInfo added in v1.8.1 

func NewEnumInfo(first string, others ...string) (TypeInfo, error)

NewEnumInfo returns ENUM type information. Its input parameters are the dictionary values.

func NewListInfo added in v1.8.1 

func NewListInfo(childInfo TypeInfo) (TypeInfo, error)

NewListInfo returns LIST type information. childInfo contains the type information of the LIST's elements.

func NewMapInfo added in v1.8.1 

func NewMapInfo(keyInfo TypeInfo, valueInfo TypeInfo) (TypeInfo, error)

NewMapInfo returns MAP type information. keyInfo contains the type information of the MAP keys. valueInfo contains the type information of the MAP values.

func NewStructInfo added in v1.8.1 

func NewStructInfo(firstEntry StructEntry, others ...StructEntry) (TypeInfo, error)

NewStructInfo returns STRUCT type information. Its input parameters are the STRUCT entries.

func NewTypeInfo added in v1.8.1 

func NewTypeInfo(t Type) (TypeInfo, error)

NewTypeInfo returns type information for DuckDB's primitive types. It returns the TypeInfo, if the Type parameter is a valid primitive type. Else, it returns nil, and an error. Valid types are: TYPE_[BOOLEAN, TINYINT, SMALLINT, INTEGER, BIGINT, UTINYINT, USMALLINT, UINTEGER, UBIGINT, FLOAT, DOUBLE, TIMESTAMP, DATE, TIME, INTERVAL, HUGEINT, VARCHAR, BLOB, TIMESTAMP_S, TIMESTAMP_MS, TIMESTAMP_NS, UUID, TIMESTAMP_TZ, ANY].

type UUID added in v1.6.0 

type UUID [uuid_length]byte

func (*UUID) Scan added in v1.6.1 

func (u *UUID) Scan(v any) error

Source Files

View all Source files

Directories

Path Synopsis
deps
darwin_amd64
Package darwin_amd64 is required to provide support for vendoring modules DO NOT REMOVE
 Package darwin_amd64 is required to provide support for vendoring modules DO NOT REMOVE
darwin_arm64
Package darwin_arm64 is required to provide support for vendoring modules DO NOT REMOVE
 Package darwin_arm64 is required to provide support for vendoring modules DO NOT REMOVE
freebsd_amd64
Package freebsd_amd64 is required to provide support for vendoring modules DO NOT REMOVE
 Package freebsd_amd64 is required to provide support for vendoring modules DO NOT REMOVE
linux_amd64
Package linux_amd64 is required to provide support for vendoring modules DO NOT REMOVE
 Package linux_amd64 is required to provide support for vendoring modules DO NOT REMOVE
linux_arm64
Package linux_arm64 is required to provide support for vendoring modules DO NOT REMOVE
 Package linux_arm64 is required to provide support for vendoring modules DO NOT REMOVE
examples
appender
scalar_udf
simple
table_udf
table_udf_parallel

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.