Skip to main content
vane
StarContact us
Vane Data / Reference

vane.cls.batch

vane.cls.batch converts a callable class into an Actor-backed batch Expression UDF. Each Actor reuses one instance and processes row-preserving projections as Arrow columns.

Signature

text
vane.cls.batch(
    *,
    actor_number: int | None = None,
    return_dtype: Any,
    name: str | None = None,
    batch_size: int | None = None,
    unnest: bool = False,
    gpus: float | None = 0,
) -> Callable[[type], VaneClassBatch]

Parameters

NameTypeDescriptionDefault
actor_numberPositive integerNumber of independent Actor instances. Booleans, floats, and numeric strings are invalidRequired
return_dtypeSQL type string, Vane DuckDBPyType, or supported pyarrow.DataTypeType of the single logical output columnRequired
nameNon-empty str or NoneUDF name in the plan; defaults to the class __qualname__None
batch_sizePositive integer or NoneMaximum rows per __call__None
unnestboolExpands a Struct result into projected columns; invalid for a non-Struct typeFalse
gpusFinite non-negative number or NoneGPU resource per Actor; positive values require Ray0

Returns and errors

Instantiate the decorated class, then use the instance to process columns in select(). The output has the same number of rows as the input. With unnest=False, the query produces one return_dtype column. With unnest=True, it expands the fields of a Struct return type into separate columns.

A direct call accepts only pyarrow.Array and pyarrow.ChunkedArray inputs of equal length. Query Actors are independent, batches have no Actor affinity or global ordering, and Actor reconstruction resets local state. Use instance state only for reconstructible resources or caches.

Invalid class definitions or arguments raise before data is processed. Constructor or __call__ errors, non-Arrow inputs or results, row-count mismatches, and values that do not match return_dtype raise during a direct call or when query results are fetched. Distributed backends may retry batches, so external effects must be idempotent.

Example

example.py
import vane




@vane.cls.batch(actor_number=2, return_dtype="BIGINT")
class Scale:
    def __init__(self, factor):
        self.factor = factor


    def __call__(self, values):
        import pyarrow.compute as pc


        return pc.multiply(values, self.factor)




scale = Scale(10)
source = vane.sql("SELECT * FROM (VALUES (1), (2), (3)) AS t(value)")
result = source.select(scale(vane.col("value")).alias("value"))


print(result.order("value").fetchall())
vane.close()

Output:

text
[(10,), (20,), (30,)]

Each Actor constructs its own Scale(10) instance. Calls receive Arrow columns, and every returned column remains the same length as its input batch.

Edit this page