Skip to content
Query.Farm
Talk with Us

Arguments

On this page

Declaring, deriving, and binding function arguments.

struct Arguments

Section titled “struct Arguments”
source
type Arguments struct {
// Positional contains arguments indexed by position.
Positional  []arrow.Array
// Named contains arguments keyed by name.
Named  map[string]arrow.Array
// Schema is the original argument schema with VGI metadata.
Schema  *arrow.Schema
// Batch is the underlying record batch (1 row for scalars).
Batch  arrow.RecordBatch
}

Description

Arguments holds parsed function arguments from an Arrow IPC payload. Arguments arrive as Arrow IPC bytes with metadata markers on each field: vgi_arg (positional index), vgi_type (type category), vgi_const (constant flag), vgi_varargs (variadic flag).

Methods

method GetColumn

Section titled “method GetColumn”
source
func (a *Arguments) GetColumn(key interface{}) (arrow.Array, error)

GetColumn returns the Arrow array for the given key (int for positional, string for named).

method GetScalarBool

Section titled “method GetScalarBool”
source
func (a *Arguments) GetScalarBool(key interface{}) (bool, error)

GetScalarBool returns a bool scalar value.

method GetScalarBytes

Section titled “method GetScalarBytes”
source
func (a *Arguments) GetScalarBytes(key interface{}) ([]byte, error)

GetScalarBytes returns a []byte scalar value.

method GetScalarDuration

Section titled “method GetScalarDuration”
source
func (a *Arguments) GetScalarDuration(key interface{}) (time.Duration, error)

GetScalarDuration returns a time.Duration scalar from a Duration-typed argument (any unit). Auto-converts the underlying integer to Go’s native ns precision. Useful for DuckDB INTERVAL arguments declared as vgi:"type=duration_ms" (etc.) in argument structs.

method GetScalarFloat64

Section titled “method GetScalarFloat64”
source
func (a *Arguments) GetScalarFloat64(key interface{}) (float64, error)

GetScalarFloat64 returns a float64 scalar value.

method GetScalarInt64

Section titled “method GetScalarInt64”
source
func (a *Arguments) GetScalarInt64(key interface{}) (int64, error)

GetScalarInt64 returns an int64 scalar value from the argument at the given position or name. For named access, pass a string key.

method GetScalarString

Section titled “method GetScalarString”
source
func (a *Arguments) GetScalarString(key interface{}) (string, error)

GetScalarString returns a string scalar value.

method GetScalarTime

Section titled “method GetScalarTime”
source
func (a *Arguments) GetScalarTime(key interface{}) (time.Time, error)

GetScalarTime returns a time.Time scalar from a Timestamp-typed argument. Honors the array’s unit (s/ms/us/ns) and timezone. UTC is used when the timestamp type is naive.

method IsNull

Section titled “method IsNull”
source
func (a *Arguments) IsNull(key interface{}) bool

IsNull checks if the argument at the given position/name is null.

method NumArgs

Section titled “method NumArgs”
source
func (a *Arguments) NumArgs() int

NumArgs returns the total number of arguments.

function ParseArguments

Section titled “function ParseArguments”
source
func ParseArguments(data []byte) (*Arguments, error)

ParseArguments deserializes Arrow IPC bytes into Arguments. The arguments IPC contains ALL declared arguments in the schema. Each field may have VGI metadata: vgi_arg=“named” for named args, vgi_const=“true” for constant params. The batch row contains scalar values for const params and null/placeholder values for column params.

method Release

Section titled “method Release”
source
func (a *Arguments) Release()

Release releases the underlying batch.

method RemapPositionalArgs

Section titled “method RemapPositionalArgs”
source
func (a *Arguments) RemapPositionalArgs(specs []ArgSpec)

RemapPositionalArgs remaps DuckDB’s sequential const-arg numbering back to the original ArgSpec positions. DuckDB only sends const params in the args struct and numbers them sequentially (0, 1, …), but functions expect them at their declared positions. For example, if specs are:

position 0: const (header)
position 1: non-const (payload) — not in args
position 2: const (config)

DuckDB sends positional_0=header, positional_1=config. This method remaps so that Positional[0]=header, Positional[2]=config, allowing functions to access args by their declared positions.

method getColumn

Section titled “method getColumn”
source
func (a *Arguments) getColumn(key interface{}) (arrow.Array, error)

struct BindParams

Section titled “struct BindParams”
source
type BindParams struct {
// FunctionName is the name of the function being bound.
FunctionName  string
// SchemaName is the catalog schema that owns the function being bound.
// Empty when the caller named no schema (COPY handler binds, which are
// advertised at catalog level rather than inside a schema).
SchemaName  string
// FunctionType is the type of the function.
FunctionType  FunctionType
// Args are the parsed function arguments.
Args  *Arguments
// InputSchema is the input table schema (nil for table functions).
InputSchema  *arrow.Schema
// Settings is a map of DuckDB setting names to their scalar values.
Settings  map[string]interface{}
// Secrets is a map of secret names to their value maps.
Secrets  Secrets
// AttachOpaqueData is the catalog attachment identifier.
AttachOpaqueData  []byte
// TransactionOpaqueData is the transaction identifier.
TransactionOpaqueData  []byte
// ResolvedSecretsProvided is true on the second phase of a two-phase bind,
// indicating that scoped secrets have been resolved and are in Secrets.
ResolvedSecretsProvided  bool
// AtUnit/AtValue carry the AT (TIMESTAMP|VERSION ...) time-travel clause for
// this scan, threaded onto the bind request embedded in init. Both nil when
// the scan has no AT clause. For function-backed tables this is the only
// place the per-scan AT is visible (the actual on_bind RPC runs once at
// attach with no AT), so read it at NewState via ProcessParams.AtUnit/AtValue.
AtUnit  *string
AtValue  *string
// CopyFrom carries the COPY ... FROM context when this bind opens a
// COPY-FROM scan (nil otherwise). A CopyFromFunction's OnBind reads its
// ExpectedSchema here. Mirrors Python's BindParams.bind_call.copy_from.
CopyFrom  *CopyFromContext
// CopyTo carries the COPY ... TO context when this bind opens a COPY-TO sink
// (nil otherwise). Mirrors Python's BindParams.bind_call.copy_to. A
// CopyToFunction reads its destination via ProcessParams.CopyTo at
// process/combine; OnBind returns an empty output schema.
CopyTo  *CopyToContext
// Auth is the authentication context for the current request.
// Always non-nil; unauthenticated requests receive vgirpc.Anonymous().
Auth  *vgirpc.AuthContext


// txBackend is the worker's shared storage backend, injected so OnBind can
// reach transaction-scoped state via TransactionStorage(). Unexported.
txBackend  FunctionStorage
}

Description

BindParams holds the parameters available during the bind phase.

Methods

method AttachStore

Section titled “method AttachStore”
source
func (p *BindParams) AttachStore() (*AttachStore, error)

AttachStore returns an attach-scoped key/value store bound to this bind’s AttachOpaqueData (the per-ATTACH plaintext). It persists across queries, so OnBind can read/pin per-collection state that Process/Combine will later see through ProcessParams.AttachScope. Errors if the backend lacks AttachStateStorage or the bind has no attach context.

method TransactionStorage

Section titled “method TransactionStorage”
source
func (p *BindParams) TransactionStorage() *TransactionStorage

TransactionStorage is a per-transaction key/value view over the worker’s shared storage, scoped to BindParams.TransactionOpaqueData. Returns nil when the bind is not running inside a transaction (no caching possible).

struct BindResponse

Section titled “struct BindResponse”
source
type BindResponse struct {
// OutputSchema is the Arrow schema for the function's output.
OutputSchema  *arrow.Schema
// OpaqueData is optional opaque data passed to the init phase.
OpaqueData  []byte
// SecretScopeRequest, when non-nil, signals a two-phase bind scope request.
// The extension will resolve scoped secrets and re-call bind with
// ResolvedSecretsProvided=true and the resolved secrets in Secrets.
SecretScopeRequest  []SecretLookup
}

Description

BindResponse is returned by a function’s OnBind method.

Methods

function BindInputSchema

Section titled “function BindInputSchema”
source
func BindInputSchema(params *BindParams) (*BindResponse, error)

BindInputSchema creates a BindResponse that passes through the input schema as the output schema. This is the common pattern for table-in-out functions that don’t transform the schema. InputSchema is expected to be non-nil for table-in-out functions.

function BindResult

Section titled “function BindResult”
source
func BindResult(outputType arrow.DataType) (*BindResponse, error)

BindResult creates a BindResponse with a single “result” column of the given type.

function BindResultFromInput

Section titled “function BindResultFromInput”
source
func BindResultFromInput(params *BindParams, fieldIndex int, defaultType arrow.DataType, promoteFn func(arrow.DataType) arrow.DataType) (*BindResponse, error)

BindResultFromInput derives the output type from a single input schema field, applying promoteFn to determine the result type. fieldIndex must be >= 0.

function BindResultFromInputs

Section titled “function BindResultFromInputs”
source
func BindResultFromInputs(params *BindParams, fieldIndices []int, defaultType arrow.DataType, combineFn func([]arrow.DataType) arrow.DataType) (*BindResponse, error)

BindResultFromInputs derives the output type from multiple input schema fields, applying combineFn to determine the result type. All fieldIndices must be >= 0.

function BindSchema

Section titled “function BindSchema”
source
func BindSchema(schema *arrow.Schema) (*BindResponse, error)

BindSchema creates a BindResponse from an output schema. This is the table-function equivalent of BindResult (which creates a single-column schema).

interface DynamicToStringHook

Section titled “interface DynamicToStringHook”
source
type DynamicToStringHook interface {
// DynamicToString returns key/value diagnostics surfaced under EXPLAIN ANALYZE for the current scan.
DynamicToString(ctx context.Context, params *DynamicToStringParams) (keys []string, values []string, err error)
}

Description

DynamicToStringHook is the optional interface a TableFunction may implement to surface per-execution diagnostics under EXPLAIN ANALYZE. The C++ extension calls this once per scan thread (in OperatorProfiler::FinishSource); the last writer wins for the operator’s Extra Info.

The returned key/value pairs are merged into DuckDB’s InsertionOrderPreservingMap. Order is preserved over the wire via parallel keys/values lists.

struct DynamicToStringParams

Section titled “struct DynamicToStringParams”
source
type DynamicToStringParams struct {
// FunctionName is the table function being profiled.
FunctionName  string
// AttachOpaqueData identifies the catalog the function was invoked under
// (nil when the call carried no attachment).
AttachOpaqueData  []byte
// GlobalExecutionID matches the execution_id returned from init_global
// for this scan; the function uses it to look up storage written during
// process().
GlobalExecutionID  []byte
// Storage is the cross-process scratchpad keyed by GlobalExecutionID.
// Use Storage.Snapshot() to read every worker's per-tick contribution
// without draining the table.
Storage  *ExecutionStorage
// Auth is the authentication context for the call.
Auth  *vgirpc.AuthContext
}

Description

DynamicToStringParams carries the per-call inputs.

struct TransactionStorage

Section titled “struct TransactionStorage”
source
type TransactionStorage struct {
back  FunctionStorage
txID  []byte
}

Description

TransactionStorage caches values per (transaction_opaque_data, key) via the worker’s FunctionStorage transaction-state table.

Methods

method GetOne

Section titled “method GetOne”
source
func (t *TransactionStorage) GetOne(key []byte) ([]byte, error)

GetOne returns the stored value for key, or (nil, nil) if absent.

method PutOne

Section titled “method PutOne”
source
func (t *TransactionStorage) PutOne(key, value []byte) error

PutOne stores value under key for this transaction.

struct arrowTypeInfo

Section titled “struct arrowTypeInfo”
source
type arrowTypeInfo struct {
ArrowTypeName  string
DataType  arrow.DataType
}

Description

arrowTypeInfo carries both the canonical wire-protocol name (used by ArgumentSpecs for catalog serialization) and the concrete Arrow DataType (used when the spec is a struct/list/fixed_list and the name alone is insufficient).

Methods

function inferArrowType

Section titled “function inferArrowType”
source
func inferArrowType(t reflect.Type) arrowTypeInfo

struct candidate

Section titled “struct candidate”
source
type candidate struct {
fn  interface{}
origin  funcOrigin
}

Description

candidate pairs a registered implementation with the origin recorded for it, so the resolver can filter on the declaring schema/catalog.

Methods

function collect

Section titled “function collect”
source
func collect[T any](w *Worker, reg map[string][]T, kind funcKind, name string, out []candidate) []candidate

collect appends every registration of (kind, name) from one registry.

struct fieldBinding

Section titled “struct fieldBinding”
source
type fieldBinding struct {
FieldIndex  int
Field    reflect.StructField
Spec    ArgSpec
}

Description

fieldBinding caches the parsed tag plus reflection info for one field.

Methods

function parseArgBindings

Section titled “function parseArgBindings”
source
func parseArgBindings(t reflect.Type) ([]fieldBinding, error)

struct functionLookup

Section titled “struct functionLookup”
source
type functionLookup struct {
// Name is the function name the caller invoked.
Name  string
// Type is the DuckDB-side function type (scalar/table/aggregate/...).
Type  FunctionType
// Schema is the catalog schema the caller named, lowercased by the
// resolver. Empty when the caller named none (a COPY handler bind, or a
// pre-1.1.0 client), which widens the lookup to every schema.
Schema  string
// Catalog is the catalog the call arrived through, derived from the
// attachment. Empty when there is no attachment (or it could not be
// opened), which disables catalog scoping for this lookup.
Catalog  string
// Args and InputSchema drive overload resolution within the matched set.
Args    *Arguments
InputSchema  *arrow.Schema
}

Description

functionLookup names the implementation a call is asking for. A function name alone is not a unique key — the same name may be declared in two schemas of one catalog, or in two catalogs served by one worker process — so resolution takes the whole (catalog, schema, name) triple plus the argument shape.

function BindArgs

Section titled “function BindArgs”
source
func BindArgs(args *Arguments, target any) error

BindArgs populates target (a non-nil pointer to a struct) from args using the same vgi:"..." tag conventions as DeriveArgSpecs. Missing or null arguments fall back to the declared default; otherwise the field keeps its zero value.

function RegisterTypeBound

Section titled “function RegisterTypeBound”
source
func RegisterTypeBound(name string, pred TypeBoundPredicate)

RegisterTypeBound registers a named TypeBoundPredicate so it can be referenced via bound=name in argument tags. Names are case-insensitive. Re-registering a name replaces the previous predicate.

function ValidateAggregateConstConstraints

Section titled “function ValidateAggregateConstConstraints”
source
func ValidateAggregateConstConstraints(specs []ArgSpec, args *Arguments) error

ValidateAggregateConstConstraints enforces const-argument constraints for aggregate functions at aggregate_bind. Unlike the scalar/table bind path, aggregate const arguments are numbered sequentially by DuckDB (positional_0, positional_1, …) rather than remapped to their declared positions, and may arrive either in the positional slice or as named “positional_N” entries — so this walks const specs in declaration order and checks both. A value that violates a declared constraint yields an *ArgumentError.

function ValidateArgConstraints

Section titled “function ValidateArgConstraints”
source
func ValidateArgConstraints(specs []ArgSpec, args *Arguments) error

ValidateArgConstraints enforces the discovery constraints declared on a function’s const arguments against the actual bound values. Const arguments are bind-time scalars, so this runs once at bind (mirroring the Python SDK’s Arg._validate): a value that violates a declared choices / numeric-range / pattern constraint yields an *ArgumentError. Column (non-const) arguments and type bounds are not handled here (type bounds are ValidateTypeBounds’ job). A null const value skips its value constraints, matching the Python SDK.

function aggregateConstArg

Section titled “function aggregateConstArg”
source
func aggregateConstArg(args *Arguments, i int) arrow.Array

aggregateConstArg returns the i-th sequential const argument array — DuckDB delivers it as either a named “positional_i” entry or positional index i.

function assignDefault

Section titled “function assignDefault”
source
func assignDefault(field reflect.Value, def string) error

assignDefault parses the textual DefaultValue and writes it into field.

function assignScalar

Section titled “function assignScalar”
source
func assignScalar(field reflect.Value, args *Arguments, key any) error

assignScalar extracts the Arrow scalar at key and writes it into field. Supports primitives, []byte, and time.Time. Returns a typed error for unsupported field kinds so callers can extend Arguments to handle them.

function bindOneField

Section titled “function bindOneField”
source
func bindOneField(field reflect.Value, b fieldBinding, args *Arguments) error

bindOneField populates a single struct field from the matching argument.

function choicesContain

Section titled “function choicesContain”
source
func choicesContain(choices []any, value any) bool

choicesContain reports whether value equals one of the declared choices, comparing numerically when both are numbers and by identity otherwise.

function constScalarValue

Section titled “function constScalarValue”
source
func constScalarValue(col arrow.Array) (any, bool)

constScalarValue extracts a const argument’s scalar value as a Go native (int64 / float64 / string / bool). The bool result is false for kinds we don’t compare against constraints.

function crossSchemaAmbiguity

Section titled “function crossSchemaAmbiguity”
source
func crossSchemaAmbiguity(cands []candidate, name, schema string) error

crossSchemaAmbiguity reports the error for an unqualified call whose surviving candidates span several schemas — the caller named no schema and there is no non-arbitrary winner. Returns nil when the call is unambiguous.

function encodeChoicesJSON

Section titled “function encodeChoicesJSON”
source
func encodeChoicesJSON(choices []any) string

encodeChoicesJSON JSON-encodes an argument’s closed set of allowed values for the vgi_choices field-metadata key (a JSON array). On marshal failure it falls back to a JSON array of each element’s fmt string form rather than dropping the whole registration.

function encodeDefaultJSON

Section titled “function encodeDefaultJSON”
source
func encodeDefaultJSON(spec ArgSpec) string

encodeDefaultJSON JSON-encodes an ArgSpec’s default value for the vgi_default field-metadata key. Go stores the default as the raw textual DefaultValue, so this parses it against the declared arg type to produce a typed JSON scalar (e.g. int64 default “5” -> 5, string default “x” -> "x", bool “true” -> true). On any parse/marshal failure it falls back to the JSON string form of the raw value rather than dropping the whole registration.

function formatBound

Section titled “function formatBound”
source
func formatBound(f float64) string

formatBound renders a numeric bound for interval notation. Whole numbers print without a trailing “.0” (0, not 0.0); genuinely fractional bounds keep their decimal. Uses the ‘f’ form so bounds never fall into scientific notation.

function formatRange

Section titled “function formatRange”
source
func formatRange(ge, le, gt, lt *float64) string

formatRange builds interval notation from an argument’s numeric bounds.

Inclusive bounds (ge/le) render as square brackets, exclusive bounds (gt/lt) as parentheses, and an open side as -inf / +inf. When both an inclusive and exclusive bound are present on the same side the exclusive one wins (matching the Python reference). Returns “” when the argument has no numeric bound at all (the caller treats “” as “omit the vgi_range key”).

Examples: ge=0,le=10 -> “[0, 10]”; gt=0 (no upper) -> “(0, +inf)”; ge=1,lt=10 -> “[1, 10)”.

function isBinaryFamily

Section titled “function isBinaryFamily”
source
func isBinaryFamily(dt arrow.DataType) bool

function isStringFamily

Section titled “function isStringFamily”
source
func isStringFamily(dt arrow.DataType) bool

function lookupKey

Section titled “function lookupKey”
source
func lookupKey(spec ArgSpec) any

function parseChoiceValue

Section titled “function parseChoiceValue”
source
func parseChoiceValue(arrowType, raw string) any

parseChoiceValue parses a single choices= tag element against the argument’s declared Arrow type name so the emitted vgi_choices JSON is typed (e.g. int args yield [1,2,3], not ["1","2","3"]). Unparseable / non-scalar types fall back to the raw string.

function parseDefaultTyped

Section titled “function parseDefaultTyped”
source
func parseDefaultTyped(arrowType, raw string) (any, bool)

parseDefaultTyped parses the raw textual default against the argument’s declared Arrow type name, returning a Go value whose json.Marshal form matches the value’s natural type. The bool reports whether a typed parse succeeded; false means the caller should fall back to the string form.

function resolveOverload

Section titled “function resolveOverload”
source
func resolveOverload(candidates []interface{}, args *Arguments, inputSchema *arrow.Schema) (interface{}, error)

resolveOverload picks the best-matching function from a list of candidates given the parsed arguments and optional input schema.

DuckDB resolves overloads on its side and sends only const args in args.Positional. The algorithm:

  1. Count matching: const spec count must match len(args.Positional)
  2. Type scoring: score const args and inputSchema fields
  3. Pick the candidate with the highest score

function schemasOf

Section titled “function schemasOf”
source
func schemasOf(cands []candidate) []string

schemasOf lists, sorted and deduplicated, the schemas the given candidates were declared in. Used to make a failed or ambiguous lookup actionable.

function scoreType

Section titled “function scoreType”
source
func scoreType(actual arrow.DataType, spec ArgSpec) int

scoreType scores how well an actual Arrow DataType matches a spec. Returns: 2 for exact match, 1 for family match, 0 for any-type spec, -1 for incompatible.

function snakeCase

Section titled “function snakeCase”
source
func snakeCase(s string) string

snakeCase converts a Go identifier to snake_case. Handles acronyms cleanly:

Count        → count
BatchSize    → batch_size
HTMLPath     → html_path
MyURL        → my_url
URLPath      → url_path
MyHTMLParser → my_html_parser
HTTPSPort    → https_port

Rule: insert “_” before an uppercase letter if (a) the previous rune is lowercase or a digit, or (b) the previous rune is uppercase AND the next rune is lowercase (end-of-acronym).

function specHasValueConstraints

Section titled “function specHasValueConstraints”
source
func specHasValueConstraints(spec ArgSpec) bool

specHasValueConstraints reports whether a spec declares any value constraint.

function splitTag

Section titled “function splitTag”
source
func splitTag(tag string) []string

splitTag splits a vgi tag into key=value parts. Two ergonomic exceptions:

  • Single-quoted values keep their commas: doc='hello, world'.
  • doc= (case-insensitive) consumes the rest of the tag if unquoted,
because doc strings naturally contain commas and quoting every one is
noisy. The trade-off: doc= must be the last entry in the tag, otherwise
keys that follow it become part of the doc string.

function toFloat

Section titled “function toFloat”
source
func toFloat(v any) (float64, bool)

toFloat coerces a numeric Go native to float64 for range/choice comparison.

function typesInSameFamily

Section titled “function typesInSameFamily”
source
func typesInSameFamily(a, b arrow.DataType) bool

typesInSameFamily checks if two types belong to the same type family.

function validateConstValue

Section titled “function validateConstValue”
source
func validateConstValue(spec ArgSpec, value any) error

validateConstValue checks one const value against its spec’s constraints.