Skip to content
Query.Farm
Talk with Us

Scalar functions

On this page

One row in, one value out — the annotation-driven shape.

annotation Const

Section titled “annotation Const”
source
public @interface Const

Description

Marks a compute() parameter as a const positional arg (bind-time constant). The Java type drives Arrow type inference: long → INT64, double → FLOAT64, String → UTF8, boolean → BOOL.

Equivalent to vgi-python’s Annotated[int, ConstParam(doc=...)].

annotation OutputLength

Section titled “annotation OutputLength”
source
public @interface OutputLength

Description

Inject the batch row count. Use for functions that emit values driven by row index (e.g. random_bytes(seed, length) — no vector input). Parameter type must be int.

Equivalent to vgi-python’s Annotated[int, OutputLength()].

record ScalarBindParams

Section titled “record ScalarBindParams”
source
public record ScalarBindParams( String functionName, Arguments arguments, Schema inputSchema, Map<String, Object> settings, byte[] secrets, boolean resolvedSecretsProvided)

Description

Parameters passed to ScalarFunction#onBind.

inputSchema may be null if no input columns were bound. settings carries DuckDB session settings the worker declared.

Members

ScalarBindParams(String functionName, Arguments arguments, Schema inputSchema, Map<String, Object> settings)

Convenience constructor for bindings with no secrets.

class ScalarFn

Section titled “class ScalarFn”
source
public abstract class ScalarFn implements ScalarFunction

Description

Pythonic scalar function base. Subclass and define a single compute() method; the framework reads its signature to derive FunctionSpec, output schema, and per-batch dispatch.

compute() signature rules

  • Parameters annotated @Vector are per-row inputs. The parameter’s Java type (concrete Arrow vector class) drives Arrow type inference. Use @Vector(any=true) FieldVector for any-typed inputs and @Vector(varargs=true) List<FieldVector> for varargs.

  • Parameters annotated @Const are bind-time constant positional args. Type mapping: long/int → INT64, double → FLOAT64, String → UTF8, boolean → BOOL.

  • Parameters annotated @Setting pull from session settings.

  • @OutputLength int — injected batch row count.

  • The last parameter that is an Arrow vector class (unannotated) is the output — pre-allocated by the framework with the right row count. compute() returns void.

For dynamic output types override #outputType(Schema, Arguments).

Members

String name()

SQL function name.

String description()

One-line description (shown by duckdb_functions()).

FunctionMetadata metadata()

Override for richer metadata (categories, pushdown, etc.).

FunctionSpec spec()

{@inheritDoc}

List<ArgSpec> argumentSpecs()

Argument specs. Default: auto-derived from compute() parameter annotations + Arrow vector class type-mapping. Override when arguments use nested Arrow types (STRUCT, LIST, FixedSizeList) whose children can’t be inferred from the Java vector class alone. compute() still drives the per-batch dispatch — only argument metadata changes.

BindResponse onBind(ScalarBindParams params)

{@inheritDoc}

Resolves #outputSchema first (so fixtures with domain-specific reject messages report before the framework’s generic type-bound check), then enforces any declared TypeBoundPredicates.

VectorSchemaRoot process(ScalarProcessParams params, VectorSchemaRoot input, BufferAllocator alloc)

{@inheritDoc}

Binds the input columns, consts, and settings to compute()’s parameters and invokes it via a cached MethodHandle into a framework-allocated output vector.

void close()
Object resolve(ScalarProcessParams params, VectorSchemaRoot input, BufferAllocator alloc, int vectorIdx)
Object resolve(ScalarProcessParams params, VectorSchemaRoot input, BufferAllocator alloc, int vectorIdx)
Object resolve(ScalarProcessParams params, VectorSchemaRoot input, BufferAllocator alloc, int vectorIdx)
Object resolve(ScalarProcessParams params, VectorSchemaRoot input, BufferAllocator alloc, int vectorIdx)
Object resolve(ScalarProcessParams params, VectorSchemaRoot input, BufferAllocator alloc, int vectorIdx)
Object resolve(ScalarProcessParams params, VectorSchemaRoot input, BufferAllocator alloc, int vectorIdx)
Object resolve(ScalarProcessParams params, VectorSchemaRoot input, BufferAllocator alloc, int vectorIdx)

interface ScalarFunction

Section titled “interface ScalarFunction”
source
public interface ScalarFunction extends FunctionDescriptor

Description

A scalar VGI function: 1:1 row mapping. Output row count must equal input row count.

Mirrors vgi.ScalarFunction in vgi-go.

record ScalarProcessParams

Section titled “record ScalarProcessParams”
source
public record ScalarProcessParams( String functionName, Arguments arguments, Schema outputSchema, Map<String, Object> settings, byte[] secrets)

Description

Parameters passed to ScalarFunction#process.

annotation Setting

Section titled “annotation Setting”
source
public @interface Setting

Description

Marks a compute() parameter as a session setting. Same type-mapping rules as Const.

Equivalent to vgi-python’s Annotated[..., Setting("key")].

annotation Vector

Section titled “annotation Vector”
source
public @interface Vector

Description

Marks a compute() parameter as a per-row input column (vector arg). The Java type of the parameter must be a concrete Arrow vector class (BigIntVector, VarCharVector, Float8Vector, …); the Arrow type for the farm.query.vgi.function.FunctionSpec entry is inferred from it.

Equivalent to vgi-python’s Annotated[pa.Int64Array, Param(doc=...)].