Background Task Builders¶

Chainable builders for server-side background operations on datasets.

class aerospike_sdk.aio.background.BackgroundTaskSession[source]¶

Bases: object

Choose a dataset-wide background job (update, delete, touch, or UDF).

From background_task(). Each method returns a builder to add filters, bin operations or UDF arguments, then await ...execute() for a server ExecuteTask.

Example

Background update with a filter:

task = await (
    session.background_task()
    .update(users)
    .where("$.active == true")
    .bin("score").add(1)
    .execute()
)

See also

execute_udf(): Foreground UDF on keys.

__init__(session)[source]¶: Bind to session; prefer Session.background_task().

update(dataset)[source]¶

Start a query_operate update over records in dataset.

Parameters:: dataset (DataSet) – Namespace/set scope for the scan.
Return type:: BackgroundOperationBuilder
Returns:: BackgroundOperationBuilder — add where, bin, then BackgroundOperationBuilder.execute().
Raises:: ValueError – On execute if no bin operations were added.

delete(dataset)[source]¶

Start a background delete of all records matching optional filters.

Parameters:: dataset (DataSet) – Namespace/set to scan.
Return type:: BackgroundOperationBuilder
Returns:: BackgroundOperationBuilder (no bin ops required for delete).

touch(dataset)[source]¶

Start a background touch (TTL refresh) for matching records.

Parameters:: dataset (DataSet) – Namespace/set to scan.
Return type:: BackgroundOperationBuilder
Returns:: BackgroundOperationBuilder — optional expire_record_after_seconds.

execute_udf(dataset)[source]¶

Start a background UDF executed via query_execute_udf.

Parameters:: dataset (DataSet) – Namespace/set scope.
Return type:: BackgroundUdfFunctionBuilder
Returns:: BackgroundUdfFunctionBuilder — call BackgroundUdfFunctionBuilder.function() then BackgroundUdfBuilder.passing() and BackgroundUdfBuilder.execute().

class aerospike_sdk.aio.background.BackgroundWriteBinBuilder[source]¶

Bases: object

Per-bin write helper for background updates (put / add only).

Obtained from BackgroundOperationBuilder.bin(). Call set_to() or add(), which return the parent builder for further chaining.

Example:

builder.bin("score").add(10)

__init__(parent, bin_name)[source]¶: Capture the bin name; prefer BackgroundOperationBuilder.bin().

set_to(value)[source]¶

Set the bin to value (Operation.put).

Parameters:: value (Any) – The value to write.
Return type:: BackgroundOperationBuilder
Returns:: The parent BackgroundOperationBuilder.

add(value)[source]¶

Add a numeric value to the bin (Operation.add).

Parameters:: value (Any) – Numeric amount to add (may be negative).
Return type:: BackgroundOperationBuilder
Returns:: The parent BackgroundOperationBuilder.

class aerospike_sdk.aio.background.BackgroundOperationBuilder[source]¶

Bases: object

Configure filters, TTL, and operations for query_operate.

Not all query-policy knobs are wired through to PAC for background jobs; records_per_second is stored for API parity but may not affect the underlying call.

See also

BackgroundTaskSession.update(): Typical construction path.

__init__(session, dataset, op_type)[source]¶

where(expression)[source]¶

Overloads:

self, expression (str) → BackgroundOperationBuilder
self, expression (FilterExpression) → BackgroundOperationBuilder

Restrict the scan with an AEL or FilterExpression predicate.

Returns:: This builder for chaining.

Example::: builder.where(“$.status == ‘inactive’”)

bin(name)[source]¶

Start a scalar write on name (update jobs only).

Return type:: BackgroundWriteBinBuilder

Example::: builder.bin(“score”).add(10)

expire_record_after_seconds(seconds)[source]¶

Set record TTL in seconds for touches/updates when supported by policy.

Return type:: BackgroundOperationBuilder

records_per_second(rps)[source]¶

Store a throttle hint (may be unused depending on PAC background API).

Return type:: BackgroundOperationBuilder

fail_on_filtered_out()[source]¶

Unsupported for background tasks (raises TypeError).

Return type:: BackgroundOperationBuilder

respond_all_keys()[source]¶

Unsupported for background tasks (raises TypeError).

Return type:: BackgroundOperationBuilder

async execute()[source]¶

Start the server job and return an ExecuteTask.

Raises:

ValueError – For update without bin operations.
RuntimeError – If the SDK client is not connected.
AerospikeError – On PAC errors (converted).

Example:

task = await (
    session.background_task()
        .update(users)
        .bin("visits").add(1)
        .execute()
)
await task.wait_till_complete()

Return type:: ExecuteTask

class aerospike_sdk.aio.background.BackgroundUdfFunctionBuilder[source]¶

Bases: object

Pick module and function for a dataset background UDF.

__init__(session, dataset)[source]¶

function(package_name, function_name)[source]¶

Select the registered package and Lua entrypoint.

Parameters:

package_name (str) – Server module name (no .lua suffix).
function_name (str) – Lua function to invoke.

Return type:

BackgroundUdfBuilder

Returns:

BackgroundUdfBuilder for arguments and execution.

Raises:

ValueError – If either string is empty.

class aerospike_sdk.aio.background.BackgroundUdfBuilder[source]¶

Bases: object

Arguments, optional filter, and execution for query_execute_udf.

__init__(session, dataset, package_name, function_name)[source]¶

passing(*args)[source]¶

Set Lua arguments after the implicit record parameter.

Return type:: BackgroundUdfBuilder
Returns:: This builder for chaining.

Example::: builder.passing(“arg1”, 42)

where(expression)[source]¶

Overloads:

self, expression (str) → BackgroundUdfBuilder
self, expression (FilterExpression) → BackgroundUdfBuilder

Optional predicate limiting which records invoke the UDF.

records_per_second(rps)[source]¶

Throttle hint stored for API parity (may not affect PAC).

Return type:: BackgroundUdfBuilder

fail_on_filtered_out()[source]¶

Unsupported (raises TypeError).

Return type:: BackgroundUdfBuilder

respond_all_keys()[source]¶

Unsupported (raises TypeError).

Return type:: BackgroundUdfBuilder

async execute()[source]¶

Start the background UDF job.

Raises:

RuntimeError – If the client is not connected.
AerospikeError – On PAC errors (converted).

Example:

task = await (
    session.background_task()
        .execute_udf(users)
        .function("mypkg", "expire_old")
        .passing(30)
        .execute()
)
await task.wait_till_complete()

Return type:: ExecuteTask