Function metadata & params

On this page

The shared bind/process parameter types and the metadata every shape declares.

record ArgSpec

source

public record ArgSpec( String name, int position, ArrowType arrowType, String doc, boolean isConst, boolean hasDefault, String defaultValue, List<TypeBoundPredicate> typeBound, boolean varargs, boolean anyType, boolean tableInput, List<Field> children, Constraints constraints)

Description

Argument specification for a VGI function parameter. Mirrors vgi-go ArgSpec.

anyType=true declares an “any” parameter — DuckDB matches the argument against any concrete type at bind time. tableInput=true declares a TABLE-typed input (table-in-out functions). Both are reflected in field metadata as vgi_type=any / vgi_type=table; the arrowType field is a placeholder (null type) for both.

children carries the child Fields for nested Arrow types (struct fields, list element type, fixed-size-list element type). Required by the Arrow schema deserialiser on the C++ side for ArrowType.List, ArrowType.FixedSizeList, and ArrowType.Struct.

Members

ArgSpec

Canonical constructor: rejects positional + hasDefault (DuckDB’s binder does not apply per-positional defaults — declaring one is dead metadata at the SQL call site; use #named(String, ArrowType, String) for defaultable kwarg-style arguments) and normalises a null constraints to Constraints#NONE.

record Arguments

source

public record Arguments(List<Object> positional, Map<String, Object> named, List<ArrowType> positionalTypes, List<Field> positionalFields)

Description

Parsed arguments to a VGI function call. Positional values are scalar Arrow objects (Long, Double, String, etc.), Named are similarly typed.

positionalTypes preserves the source Arrow type per positional arg (TINYINT vs BIGINT, FLOAT vs DOUBLE, …) so callers that emit a dynamically-typed output schema can preserve the user’s exact type. positionalFields additionally carries the source Field including ARROW:extension:* metadata, which DuckDB uses to round- trip types like HUGEINT (sent as FixedSizeBinary(16) with extension arrow.opaque / type_name=hugeint). Callers that need lossless type round-trip should rebuild output fields from positionalFieldAt rather than positionalTypeAt.

Members

Arguments(List<Object> positional, Map<String, Object> named)

Construct with no per-positional type or field metadata.

Arguments(List<Object> positional, Map<String, Object> named, List<ArrowType> positionalTypes)

Construct with positional types but no per-positional field metadata.

Arguments empty()

Empty arguments, used for speculative catalog-discovery binds.

Object positionalAt(int index)

Positional value at index, or null when out of range.

ArrowType positionalTypeAt(int index)

Source Arrow type of the positional argument at index.

Field positionalFieldAt(int index)

Source Field for the positional argument at index, including any ARROW:extension:* metadata (DuckDB lossless type tagging). Returns null when not available.

long namedLong(String name, long defaultValue)

Typed accessor for a named long argument with a default.

double namedDouble(String name, double defaultValue)

Typed accessor for a named double argument with a default.

boolean namedBool(String name, boolean defaultValue)

Typed accessor for a named boolean argument with a default.

String namedString(String name, String defaultValue)

Typed accessor for a named string argument with a default.

String positionalString(int index, String defaultValue)

Typed accessor for a positional string argument with a default.

long positionalLong(int index, long defaultValue)

Typed accessor for a positional long argument with a default.

double positionalDouble(int index, double defaultValue)

Typed accessor for a positional double argument with a default.

boolean positionalBool(int index, boolean defaultValue)

Typed accessor for a positional boolean argument with a default.

class BoolConstraint

source

public static final class BoolConstraint

Description

A boolean-valued constraint.

Members

boolean required()

Resolve, throwing when the argument is missing or null.

boolean orElse(boolean defaultValue)

Resolve, substituting defaultValue when missing or null.

void notNull()

See LongConstraint#notNull().

class Builder

source

public static final class Builder

Description

Fluent builder; positional adders auto-number, #named does not.

Members

Builder description(String description)

Shorthand for metadata(FunctionMetadata.describe(description)).

Builder metadata(FunctionMetadata metadata)

Set the function metadata.

Builder arg(String argName, ArrowType type)

Positional runtime-column argument (non-const).

Builder constArg(String argName, ArrowType type)

Positional compile-time-constant argument (bind-validated).

Builder nested(String argName, ArrowType type, List<Field> children)

Positional nested-type argument (struct/list/map) with explicit children.

Builder varargs(String argName, ArrowType type)

Positional varargs argument.

Builder any(String argName, TypeBoundPredicate… bounds)

Positional “any”-typed argument matched at bind time against bounds.

Builder table(String argName)

Positional TABLE-typed input (table-in-out functions).

Builder named(String argName, ArrowType type, String defaultValue)

Named-only (kwarg) argument with a default; consumes no positional slot.

Builder arg(ArgSpec spec)

Escape hatch: append a fully-formed ArgSpec verbatim (no auto-numbering). For shapes the fluent methods don’t compose, e.g. varargs + any-typed. Position, if any, must be set on the spec.

FunctionSpec build()

Build the immutable FunctionSpec.

class ConstraintEnforcer

source

public final class ConstraintEnforcer

Description

Bind-time enforcement of per-argument value constraints (closed choice set, numeric range, and regex pattern) declared on a function’s const arguments.

Shared by every function-kind bind path (scalar, table, table-in-out, table-buffering, aggregate) so a declared constraint is rejected at bind regardless of function type, mirroring the Python SDK’s Arg._validate. Column (non-const) arguments are not enforced here — that is the type-bound check’s domain.

Members

void enforce(Arguments args, List<ArgSpec> specs)

Validate a function’s const arguments against their declared constraints.

Const arguments are numbered sequentially (the i-th const spec reads the i-th positional value); a value that violates a declared choices / ge/le/gt/lt / pattern constraint throws IllegalArgumentException. A null (absent) value is skipped, matching the other SDKs.

record Constraints

source

public record Constraints( List<Object> choices, Number ge, Number le, Number gt, Number lt, String pattern)

Description

Discovery-facing per-argument validation constraints, surfaced as Arrow field metadata by ArgumentSpecSerializer and read by the C++ vgi_function_arguments() diagnostic. Mirrors the per-argument constraint fields on vgi-python’s Param / ConstParam.

Every field is optional (null = absent). The serializer encodes them presence-only: choices → vgi_choices (JSON array), ge/le/gt/lt → a single vgi_range interval-notation string, pattern → vgi_pattern (raw regex).

Members

Constraints NONE = new Constraints(null, null, null, null, null, null)

The empty constraint set (every field absent).

Constraints

Defensive copy of choices so the record stays immutable.

boolean isEmpty()

{@code true when no constraint at all is present}.

Constraints range(Number ge, Number le, Number gt, Number lt)

Numeric bounds only (no choices / pattern), any of which may be null.

Constraints choices(List<Object> choices)

Closed-set constraint only.

Constraints pattern(String pattern)

Regex constraint only.

ArgSpec(String name, int position, ArrowType arrowType, String doc, boolean isConst, boolean hasDefault, String defaultValue, List<TypeBoundPredicate> typeBound, boolean varargs, boolean anyType, boolean tableInput)

Full constructor with an empty children list (non-nested types).

ArgSpec(String name, int position, ArrowType arrowType, String doc, boolean isConst, boolean hasDefault, String defaultValue, List<TypeBoundPredicate> typeBound, boolean varargs, boolean anyType, boolean tableInput, List<Field> children)

Full constructor with explicit children but no constraints (delegates with Constraints#NONE).

ArgSpec withConstraints(Constraints newConstraints)

Return a copy of this spec carrying newConstraints (a null argument normalises to Constraints#NONE). All other components are preserved.

ArgSpec(String name, int position, ArrowType arrowType)

Minimal positional runtime-column argument (non-const, no doc, no bounds).

ArgSpec(String name, int position, ArrowType arrowType, boolean isConst)

Positional argument with explicit const flag.

ArgSpec(String name, int position, ArrowType arrowType, String doc, boolean isConst, boolean hasDefault, String defaultValue, List<TypeBoundPredicate> typeBound, boolean varargs, boolean anyType)

Constructor for the non-table case (tableInput=false).

ArgSpec any(String name, int position, List<TypeBoundPredicate> typeBound)

“Any”-typed positional argument matched against typeBound at bind time.

ArgSpec table(String name, int position)

TABLE-typed positional input, for table-in-out functions.

ArgSpec named(String name, ArrowType type, String defaultValue)

Named-only constant argument (no positional slot, accessible only via arg => value syntax). The most common shape for fixture configuration knobs like batch_size, logging, etc.

ArgSpec positional(String name, int position, ArrowType type)

Plain positional const argument with no default value.

ArgSpec varargs(String name, int position, ArrowType type)

Positional varargs constant argument (e.g. make_pairs(a, b, c, d, ...)).

ArgSpec nested(String name, int position, ArrowType arrowType, List<Field> children, boolean varargs)

Construct an ArgSpec for a nested Arrow type (struct/list/fixed_list) with explicit child field shape. varargs switches the spec to varargs.

class DoubleConstraint

source

public static final class DoubleConstraint

Description

A double-valued constraint; rejects NaN/±Inf unless #allowNonFinite().

Members

DoubleConstraint ge(double v)

Require value >= v.

DoubleConstraint le(double v)

Require value <= v.

DoubleConstraint between(double lo, double hi)

Require value within [lo, hi] (inclusive both ends).

DoubleConstraint allowNonFinite()

Permit NaN and infinite values, which are otherwise rejected.

double required()

Resolve, throwing when the argument is missing or null.

double orElse(double defaultValue)

Resolve, substituting defaultValue when missing or null.

void notNull()

See LongConstraint#notNull().

interface FunctionDescriptor

source

public interface FunctionDescriptor

Description

Common surface for scalar, table, table-in-out, and aggregate function implementations: a name, metadata, and an argument-spec list. Pulled out so catalog-functions plumbing (FunctionInfo construction) can treat all four kinds uniformly.

A function declares this constant data once via #spec(); the name()/metadata()/argumentSpecs() accessors default to reading it. Implement spec() (returning a static final FunctionSpec for the common case) and you get all three for free. Functions whose metadata is genuinely computed may instead override the three accessors directly — the defaults below only apply when they are not overridden.

record FunctionMetadata

source

public record FunctionMetadata( String description, Stability stability, NullHandling nullHandling, boolean autoApplyFilters, boolean projectionPushdown, boolean filterPushdown, boolean samplingPushdown, List<String> categories, OrderPreservation orderPreservation, boolean supportsBatchIndex, PartitionKind partitionKind, boolean lateMaterialization, List<String> supportedExpressionFilters, List<FunctionExample> examples, Map<String, String> tags)

Description

Metadata describing a VGI function. Mirrors vgi-go FunctionMetadata.

Members

FunctionMetadata

Compact constructor: normalise tags to a non-null, defensively copied map so #tags() never returns null and callers can’t mutate the metadata’s tags through the original reference.

record FunctionSpec

source

public record FunctionSpec(String name, FunctionMetadata metadata, List<ArgSpec> argumentSpecs)

Description

The constant descriptor data a VGI function declares once: its SQL name, its FunctionMetadata, and its ArgSpec list. Returned from FunctionDescriptor#spec(); the name()/metadata()/ argumentSpecs() accessors default to reading this record, so a function implements one method instead of three.

Does not carry an output schema — output is declared per function kind (AggregateFunction.outputSchema() / onBind(...)), so there is nothing shareable to hoist here.

Build with #builder(String): positional adders (Builder#arg, Builder#constArg, Builder#nested, Builder#varargs, Builder#any, Builder#table) auto-assign positions 0, 1, 2, … in call order, so the author never writes — and so cannot transpose — an index. Builder#named declares a kwarg-style argument with no positional slot (position = -1). Builder#arg(ArgSpec) is an escape hatch for exotic combinations (e.g. varargs + any-typed) the fluent methods don’t cover.

Members

FunctionSpec

Canonical constructor: normalizes a null argument list to empty and defensively copies.

FunctionSpec(String name, FunctionMetadata metadata)

name + metadata, no arguments.

Builder builder(String name)

Start a fluent builder for the named function.

class LongConstraint

source

public static final class LongConstraint

Description

A long-valued constraint with optional inclusive range bounds.

Members

LongConstraint ge(long v)

Require value >= v.

LongConstraint le(long v)

Require value <= v.

LongConstraint between(long lo, long hi)

Require value within [lo, hi] (inclusive both ends).

long required()

Resolve, throwing when the argument is missing or null.

long orElse(long defaultValue)

Resolve, substituting defaultValue when missing or null.

void notNull()

Speculative-bind-time validator: rejects explicit NULL, tolerates absence, applies range check if a value is present. Use in onBind so catalog-discovery calls (which pass Arguments#empty()) don’t fail.

class NamedSlot

source

public final class NamedSlot

Description

A selected named (kwarg) argument awaiting a type constraint.

Members

LongConstraint asLong()

Interpret the value as a long.

DoubleConstraint asDouble()

Interpret the value as a double.

StringConstraint asString()

Interpret the value as a string.

BoolConstraint asBool()

Interpret the value as a boolean.

enum NullHandling

source

public enum NullHandling

Description

How null inputs propagate. Mirrors vgi-go NullHandling.

enum OrderPreservation

source

public enum OrderPreservation

Description

Wire enum for FunctionInfo.order_preservation. Mirrors the three values DuckDB recognises in TableFunction::order_preservation_type.

Members

String wireName()

The canonical on-wire order_preservation string (mirrors vgi-python’s OrderPreservation enum names, which the C++ parser validates against). The Java constant names follow DuckDB’s OrderPreservationType instead, so they differ.

class ParameterExtractor

source

public final class ParameterExtractor

Description

Fluent, validating wrapper around Arguments.

Replaces the hand-rolled cast + null-check + range-check ceremony in fixture onBind/createProducer bodies. Slot (#positional or #named) → constraint (asLong / asDouble / asString / asBool) → terminal (required / orElse).

`ParameterExtractor p = ParameterExtractor.of(params.arguments());
  long count    = p.positional(0, "count").asLong().ge(1).required();
  long batch    = p.named("batch_size").asLong().ge(1).orElse(1000L);
  double inc    = p.named("increment").asDouble().orElse(1.0);
  String layout = p.named("layout").asString().oneOf("first","middle","last").orElse("first");
  boolean log   = p.named("logging").asBool().orElse(false);`

Semantics:

• required() throws IllegalArgumentException when the argument is missing or wire-null.

• orElse(default) substitutes the default when the argument is missing or wire-null (matches the pre-existing Arguments.namedLong(name, default) behaviour).

• between(min, max) is inclusive both ends.

• asDouble() accepts Number and BigDecimal (coerced via doubleValue()) and rejects NaN / ±Inf by default; call allowNonFinite() to opt in.

Not thread-safe — wraps a snapshot of Arguments taken at the bind/create-producer thread and is intended to be discarded after use.

Fixtures that need lossless type-metadata round-trip (Field#getMetadata() / extension types / dict-encoded enums) must continue to use #positionalFieldAt(int) directly; the slot+constraint API deliberately narrows values to plain Java types and erases that metadata.

Members

ParameterExtractor of(Arguments args)

Wrap an Arguments snapshot.

PositionalSlot positional(int index, String displayName)

Begin extracting the positional argument at index.

NamedSlot named(String name)

Begin extracting the named (kwarg) argument name.

List<Object> varargsFrom(int startIndex)

Varargs view of positional arguments from startIndex onward. Returns List#of() when there are no remaining positionals.

Field positionalFieldAt(int index)

Source Field for the positional argument at index (lossless type metadata).

ArrowType positionalTypeAt(int index)

Source Arrow type for the positional argument at index.

int positionalCount()

Number of positional arguments supplied.

Arguments arguments()

The wrapped raw arguments.

enum PartitionKind

source

public enum PartitionKind

Description

Wire enum for FunctionInfo.partition_kind — the partition shape a table function declares over its vgi.partition_column-annotated output-schema fields. Mirrors vgi-python’s PartitionKind. DuckDB consumes only #SINGLE_VALUE_PARTITIONS today (plans PhysicalPartitionedAggregate); the others are wire-declarable and fall back to HASH_GROUP_BY.

Members

FunctionMetadata(String description, Stability stability, NullHandling nullHandling, boolean autoApplyFilters, boolean projectionPushdown, boolean filterPushdown, boolean samplingPushdown, List<String> categories, OrderPreservation orderPreservation)

Convenience constructor defaulting batch-index, partition-kind, and late-materialization off.

FunctionMetadata(String description, Stability stability, NullHandling nullHandling, boolean autoApplyFilters, boolean projectionPushdown, boolean filterPushdown, boolean samplingPushdown, List<String> categories)

Convenience constructor with no declared order preservation.

FunctionMetadata(String description, Stability stability, NullHandling nullHandling, boolean autoApplyFilters, boolean projectionPushdown, boolean filterPushdown, boolean samplingPushdown)

Convenience constructor with no categories and no declared order preservation.

FunctionMetadata describe(String description)

Minimal metadata: description only, consistent/default with no pushdown.

FunctionMetadata withPushdown(boolean projection, boolean filter, boolean autoApply)

Builder convenience: same description, opt into filter+projection pushdown.

FunctionMetadata withSamplingPushdown()

Opt into sampling pushdown.

FunctionMetadata withCategories(String… cats)

Set the SQL function categories.

FunctionMetadata withOrderPreservation(OrderPreservation op)

Set the declared output ordering guarantee.

FunctionMetadata withBatchIndex()

Opt into supports_batch_index: every emitted batch must carry a vgi_batch_index tag (see EmitMetadata#batchIndex).

FunctionMetadata withPartitionKind(PartitionKind kind)

Declare a non-default PartitionKind over the output schema’s vgi.partition_column-annotated fields.

FunctionMetadata withLateMaterialization()

Opt into DuckDB’s late-materialization optimizer. Only meaningful for a table function whose output exposes an is_row_id virtual column and that also declares filter + projection pushdown (see late_materialization.test).

FunctionMetadata withSupportedExpressionFilters(String… names)

Declare the expression-filter function names this table function can receive pushed down and apply itself (e.g. "&&", "st_intersects_extent", "list_contains"). The engine only pushes an expression filter into the function when every function name in the predicate tree appears here; otherwise it keeps a FILTER node above the scan. Surfaced on the wire as FunctionInfo.supported_expression_filters.

FunctionMetadata withExamples(List<FunctionExample> examples)

Declare the documented usage examples surfaced on FunctionInfo.examples. Each FunctionExample carries an example sql string, a human-readable description, and an optional expected_output.

FunctionMetadata withTags(Map<String, String> more)

Merge worker-provided metadata tags surfaced on FunctionInfo.tags and reported through DuckDB’s function tags map. Typical keys are vgi.columns_md (required by lint rule VGI307 for table functions with a dynamic schema) and vgi.description_md. The given tags are merged into any already declared on this metadata (later keys overwrite duplicates); existing tags not present in more are preserved. Any tags the SDK derives internally and any prior worker tags are kept — this never clobbers them wholesale.

FunctionMetadata withTag(String key, String value)

Add or overwrite a single metadata tag (e.g. vgi.columns_md), merging with any tags already declared. See #withTags(Map).

class PositionalSlot

source

public final class PositionalSlot

Description

A selected positional argument awaiting a type constraint.

Members

LongConstraint asLong()

Interpret the value as a long.

DoubleConstraint asDouble()

Interpret the value as a double.

StringConstraint asString()

Interpret the value as a string.

BoolConstraint asBool()

Interpret the value as a boolean.

enum Stability

source

public enum Stability

Description

Function output determinism. Mirrors vgi-go FunctionStability.

class StringConstraint

source

public static final class StringConstraint

Description

A string-valued constraint with optional allowed-set and non-empty checks.

Members

StringConstraint oneOf(String… values)

Restrict to one of the given values.

StringConstraint nonEmpty()

Reject the empty string.

String required()

Resolve, throwing when the argument is missing or null.

String orElse(String defaultValue)

Resolve, substituting defaultValue when missing or null.

void notNull()

See LongConstraint#notNull().

record TaggedUnion

source

public record TaggedUnion(String tag, Object value)

Description

A decoded Arrow union value that preserves the active member discriminator.

A plain UnionVector.getObject(row) returns only the active member’s value, dropping the type id that identifies which member is active. TaggedUnion pairs the active member’s field name (tag) with its decoded value so callers can recover the union’s discriminator after the Arrow round-trip.

Mirrors the Python framework’s TaggedUnion. Produced by farm.query.vgi.internal.VectorScalarCodec#read for org.apache.arrow.vector.complex.UnionVector (sparse, as emitted by DuckDB) cells.

enum TypeBoundPredicate

source

public enum TypeBoundPredicate

Description

Predicate enum for “any”-typed argument validation. Mirrors vgi-go.

Members

String description()

User-facing description used in bind-time violation messages (e.g. add_values: col1 must be numeric (got VARCHAR)).