UDF Builders

Foreground UDF execution builders (single-key, batch, and chained operations).

Chain state and chaining methods live on the shared, runtime-agnostic bases in aerospike_sdk.udf_shared; this module adds the async execute() terminal.

class aerospike_sdk.aio.operations.udf.UdfBuilder

Bases: _UdfBuilderBase[QueryBuilder]

Supply UDF arguments, optional filter, then execute or chain another operation.

After UdfFunctionBuilder.function(), call passing() with values passed to Lua (after the implicit record argument). Use execute_udf() to append another UDF segment, or query() / write verbs to switch operation type. Await execute() to run the accumulated chain.

Example:

stream = await (
    session.execute_udf(key)
        .function("my_pkg", "my_func")
        .passing(1, "x")
        .execute()
)

See also

execute_udf(): Entry point.

async execute(on_error=None)

Run the current builder state and return a RecordStream.

Requires UdfFunctionBuilder.function() to have been called for the pending UDF operation.

Parameters:

on_error (Union[ErrorStrategy, Callable[[Key, int, AerospikeError], None], None]) – Same as QueryBuilder.execute().

Return type:

RecordStream

Returns:

Stream of per-key results and optional udf_result fields.

Example:

stream = await (
    session.execute_udf(k1, k2)
        .function("pkg", "fn")
        .execute()
)

Raises:

ValueError – If no UDF function was selected before execute.

__init__(qb)

default_expire_record_after(duration)

Default TTL from a datetime.timedelta.

Return type:

Self

default_expire_record_after_seconds(seconds)

Default TTL, in seconds, for chained operations without their own.

Return type:

Self

default_expire_record_at(when)

Default TTL expressed as an absolute expiry instant.

Return type:

Self

default_expiry_from_server_default()

Default chained operations to the namespace’s configured TTL.

Return type:

Self

default_never_expire()

Default chained operations to never expire.

Return type:

Self

default_where(expression, *params)

Filter applied to chained operations that do not call where.

Return type:

Self

default_with_durable_delete()

Prefer durable deletes when resolving policy defaults.

Return type:

Self

default_with_no_change_in_expiration()

Default chained operations to leave the existing TTL untouched.

Return type:

Self

default_without_durable_delete()

Prefer non-durable deletes when resolving policy defaults.

Return type:

Self

delete(arg1, *more_keys)

Finalize the UDF operation and start a delete segment.

Return type:

WriteSegmentBuilder

Returns:

A write-segment builder for chaining.

execute_udf(*keys)

Finalize this UDF operation and start another on keys.

Parameters:

*keys (Key) – One or more keys for the next UDF segment.

Return type:

UdfFunctionBuilder

Returns:

A new UdfFunctionBuilder to call function again.

Raises:

ValueError – If no keys are provided.

exists(arg1, *more_keys)

Finalize the UDF operation and start an exists-check segment.

Return type:

WriteSegmentBuilder

Returns:

A write-segment builder for chaining.

expire_record_after(duration)

Set the TTL using a datetime.timedelta.

Equivalent to expire_record_after_seconds() with seconds derived from duration — convenient when the caller already has a timedelta (timedelta(days=30), etc.). A timedelta resolving to -1, -2, or 0 seconds selects the corresponding TTL sentinel.

Parameters:

duration (timedelta) – Time-to-live.

Return type:

Self

Returns:

self for method chaining.

expire_record_after_seconds(seconds)

Set the TTL on the current operation.

Parameters:

seconds (int) – Time-to-live in seconds. A positive value sets an explicit TTL; the sentinels -1, -2, and 0 select never-expire, no-change, and namespace-default respectively (see never_expire(), with_no_change_in_expiration(), and expiry_from_server_default() for named equivalents). The value is not range-checked here — one the client cannot represent is rejected when the operation is built.

Return type:

Self

Returns:

self for method chaining.

expire_record_at(when)

Set the TTL so the record expires at an absolute point in time.

A naive when is interpreted in local time; pass a timezone-aware datetime for explicit UTC or other zones.

Parameters:

when (datetime) – Future point at which the record should expire.

Return type:

Self

Returns:

self for method chaining.

Raises:

ValueError – If when is not strictly in the future.

expiry_from_server_default()

Use the namespace’s default TTL for this record (TTL = 0).

Return type:

Self

fail_on_filtered_out()

Mark filtered-out records with FILTERED_OUT result code.

Return type:

Self

include_missing_keys()

For batch UDF, emit a row per requested key (including not-found).

Return type:

Self

Returns:

This builder for chaining.

See also

QueryBuilder.include_missing_keys(): Same flag for reads.

insert(arg1, *more_keys)

Finalize the UDF operation and start an insert-only write segment.

Return type:

WriteSegmentBuilder

Returns:

A write-segment builder for chaining.

never_expire()

Set this record to never expire (TTL = -1).

Return type:

Self

passing(*args)

Set positional arguments forwarded to the Lua function.

The Aerospike server automatically passes the record as the first argument to the UDF; values provided here follow it.

Parameters:

*args (Any) – Values serialized by the async client (scalars, lists, maps, bytes).

Return type:

Self

Returns:

This builder for chaining.

Example::

builder.passing(“binName”, 42)

query(arg1, *more_keys)

Close the UDF operation and begin a read query segment.

Parameters:

• arg1 (Union[Key, List[Key]]) – One key or a list of keys.

• *more_keys (Key) – Additional keys when arg1 is a single key.

Return type:

TypeVar(_QB, bound= _QueryBuilderBase)

Returns:

The wrapped query builder for chaining.

replace(arg1, *more_keys)

Finalize the UDF operation and start a replace write segment.

Return type:

WriteSegmentBuilder

Returns:

A write-segment builder for chaining.

replace_if_exists(arg1, *more_keys)

Finalize the UDF operation and start a replace-if-exists segment.

Return type:

WriteSegmentBuilder

Returns:

A write-segment builder for chaining.

touch(arg1, *more_keys)

Finalize the UDF operation and start a touch segment.

Return type:

WriteSegmentBuilder

Returns:

A write-segment builder for chaining.

update(arg1, *more_keys)

Finalize the UDF operation and start an update-only write segment.

Return type:

WriteSegmentBuilder

Returns:

A write-segment builder for chaining.

upsert(arg1, *more_keys)

Finalize the UDF operation and start an upsert write segment.

Return type:

WriteSegmentBuilder

Returns:

A write-segment builder for chaining.

where(expression, *params)

Apply a filter expression so the UDF runs only when the predicate matches.

Overloads:

• self, expression (str), params (Any) → Self

• self, expression (FilterExpression) → Self

Parameters:

• expression (Union[str, FilterExpression]) – AEL string or FilterExpression.

• *params (Any) – Values for printf placeholders in an AEL template. See QueryBuilder.where() for the interpolation contract.

Returns:

This builder for chaining.

Raises:

ValueError – If where has already been called on this operation.

See also

QueryBuilder.where(): Same AEL for reads.

with_durable_delete()

Force durable delete for this UDF invocation.

Return type:

Self

with_no_change_in_expiration()

Preserve the record’s existing TTL (TTL = -2).

Return type:

Self

with_txn(txn)

Opt the chain into (or out of) a specific transaction.

Parameters:

txn (Optional[Txn]) – The Txn to participate in, or None to run without a transaction, including an implicit batch-write one.

Return type:

Self

Returns:

This builder for chaining.

without_durable_delete()

Force non-durable delete for this UDF invocation.

Return type:

Self

class aerospike_sdk.aio.operations.udf.UdfFunctionBuilder

Bases: _UdfFunctionBuilderBase[QueryBuilder]

First step of foreground UDF chaining: choose package and Lua function name.

Produced by execute_udf() or UdfBuilder.execute_udf(). Call function() before UdfBuilder.passing() or UdfBuilder.execute().

Example:

stream = await (
    session.execute_udf(key)
        .function("my_module", "my_func")
        .execute()
)

__init__(qb)

function(package, function_name)

Select the registered module and function to invoke.

Parameters:

• package (str) – Server-side module name (no .lua suffix).

• function_name (str) – Lua function symbol exported by the module.

Return type:

UdfBuilder

Returns:

A UdfBuilder for arguments and execution.

Raises:

ValueError – If package or function_name is empty.