Batch Operation Builders

BatchOperationBuilder - Builder for chaining operations across multiple keys.

class aerospike_sdk.aio.operations.batch.BatchBinBuilder

Bases: object

Builder for chaining bin operations within a batch key operation.

Example

batch.insert(key).bin(“name”).set_to(“Alice”).bin(“age”).set_to(25)

__init__(key_op, bin_name)

set_to(value)

Set a bin value.

Parameters:

value (Any) – The value to set.

Return type:

BatchKeyOperationBuilder

Returns:

The parent BatchKeyOperationBuilder for chaining.

set_to_geo_json(geo_json)

Set the bin to a GeoJSON value from its string form.

The bin’s server-side particle type is GEOJSON, not STRING. Equivalent to set_to(GeoJSON(geo_json)) but reads naturally for spatial data.

Parameters:

geo_json (str) – A GeoJSON string (e.g. a Point, Polygon, or AeroCircle).

Return type:

BatchKeyOperationBuilder

Returns:

The parent BatchKeyOperationBuilder.

add(value)

Add value to the bin (numeric increment).

Return type:

BatchKeyOperationBuilder

increment_by(value)

Alias for add().

Return type:

BatchKeyOperationBuilder

append(value)

Append a string to a bin value.

Parameters:

value (str) – The string to append.

Return type:

BatchKeyOperationBuilder

Returns:

The parent BatchKeyOperationBuilder for chaining.

prepend(value)

Prepend a string to a bin value.

Parameters:

value (str) – The string to prepend.

Return type:

BatchKeyOperationBuilder

Returns:

The parent BatchKeyOperationBuilder for chaining.

select_from(expression, *, ignore_eval_failure=False)

Read the result of an expression into this bin.

Parameters:

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

• ignore_eval_failure (bool) – If True, suppress evaluation errors.

Return type:

BatchKeyOperationBuilder

Returns:

The parent BatchKeyOperationBuilder for chaining.

insert_from(expression, *, ignore_op_failure=False, ignore_eval_failure=False, delete_if_null=False)

Write expression result to this bin only if it does not already exist.

Parameters:

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

• ignore_op_failure (bool) – If True, suppress BIN_EXISTS_ERROR.

• ignore_eval_failure (bool) – If True, suppress evaluation errors.

• delete_if_null (bool) – If True, delete bin when expression evaluates to nil.

Return type:

BatchKeyOperationBuilder

Returns:

The parent BatchKeyOperationBuilder for chaining.

update_from(expression, *, ignore_op_failure=False, ignore_eval_failure=False, delete_if_null=False)

Write expression result to this bin only if it already exists.

Parameters:

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

• ignore_op_failure (bool) – If True, suppress BIN_NOT_FOUND.

• ignore_eval_failure (bool) – If True, suppress evaluation errors.

• delete_if_null (bool) – If True, delete bin when expression evaluates to nil.

Return type:

BatchKeyOperationBuilder

Returns:

The parent BatchKeyOperationBuilder for chaining.

upsert_from(expression, *, ignore_op_failure=False, ignore_eval_failure=False, delete_if_null=False)

Write expression result to this bin (create or update).

Parameters:

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

• ignore_op_failure (bool) – If True, suppress policy errors.

• ignore_eval_failure (bool) – If True, suppress evaluation errors.

• delete_if_null (bool) – If True, delete bin when expression evaluates to nil.

Return type:

BatchKeyOperationBuilder

Returns:

The parent BatchKeyOperationBuilder for chaining.

hll_init(config, *, create_only=False, update_only=False, no_fail=False, allow_fold=False)

Initialize an empty HyperLogLog sketch in this bin.

Semantics match aerospike_sdk.aio.operations.query.WriteBinBuilder.hll_init().

Return type:

BatchKeyOperationBuilder

hll_add(values, *, config=None, create_only=False, update_only=False, no_fail=False, allow_fold=False)

Add distinct values to the HyperLogLog sketch in this bin.

Semantics match aerospike_sdk.aio.operations.query.WriteBinBuilder.hll_add().

Return type:

BatchKeyOperationBuilder

hll_set_union(hll_list, *, create_only=False, update_only=False, no_fail=False, allow_fold=False)

Merge other HyperLogLog sketches into this bin (destructive union).

Return type:

BatchKeyOperationBuilder

hll_fold(index_bit_count)

Reduce sketch precision to a lower index_bit_count.

Return type:

BatchKeyOperationBuilder

hll_refresh_count()

Refresh the cached cardinality estimate.

Return type:

BatchKeyOperationBuilder

hll_get_count()

Read the estimated cardinality of the sketch.

Return type:

BatchKeyOperationBuilder

hll_describe()

Read the sketch’s index and minhash bit widths.

Return type:

BatchKeyOperationBuilder

hll_get_union(hll_list)

Read the union of this sketch with other sketches (non-destructive).

Return type:

BatchKeyOperationBuilder

hll_get_union_count(hll_list)

Read the estimated cardinality of the union with other sketches.

Return type:

BatchKeyOperationBuilder

hll_get_intersect_count(hll_list)

Read the estimated intersection cardinality with other sketches.

Return type:

BatchKeyOperationBuilder

hll_get_similarity(hll_list)

Read Jaccard similarity between this sketch and other sketches.

Return type:

BatchKeyOperationBuilder

class aerospike_sdk.aio.operations.batch.BatchKeyOperationBuilder

Bases: _BatchKeyOperationBuilderBase

Builder for a single key’s operation within a batch.

This class allows chaining bin operations and then continuing to add more keys to the batch.

Example

batch.insert(key1).bin(“name”).set_to(“Alice”)

.update(key2).bin(“counter”).add(1)

async execute(on_error=None)

Execute all batch operations.

Parameters:

on_error (Optional[Callable[[Key, int, AerospikeError], None]]) – Optional (key, index, exception) -> None callback. Failed per-key results are dispatched to the handler and excluded from the returned stream.

Return type:

RecordStream

async execute_stream(on_error=None)

Lazy streaming batch execute. See BatchOperationBuilder.execute_stream().

Return type:

RecordStream

class aerospike_sdk.aio.operations.batch.BatchOperationBuilder

Bases: _BatchOperationBuilderBase

Builder for chaining operations across multiple keys.

This class enables method chaining of operations on different keys, which are then executed as a single batch operation.

Example:

results = await session.batch() \
    .insert(key1).bin("name").set_to("Alice").bin("age").set_to(25) \
    .update(key2).bin("counter").add(1) \
    .delete(key3) \
    .execute()

The operations are collected and executed together using the async client’s batch_operate method for optimal performance.

async execute(on_error=None)

Execute all batch operations as a buffered call.

Awaits all per-key results before returning a RecordStream backed by a fully-materialized list. Writes are guaranteed to have completed server-side by the time this method returns; subsequent reads will observe the new state without races. Callers that don’t iterate the returned stream are safe — the “fire-and-forget” shape works as expected.

For true per-record streaming (records arrive at first-RTT, peak memory bounded), see execute_stream() — note its different semantics (completion-order yields, no writes-complete-on-return guarantee, peak memory bounded).

Internally dispatches as a single mixed PAC batch call over pre-wrapped BatchWriteOp / BatchReadOp / BatchDeleteOp entries — each per-key write carries its own BatchWritePolicy so the verb’s existence semantics (update requires existing, insert requires absent, …) are enforced on the wire. Results land in input order.

Example:

stream = await (
    session.batch()
    .insert(key1)
    .bin("name").set_to("Ada")
    .upsert(key2)
    .bin("n").set_to(1)
    .execute()
)
rows = await stream.collect()

Parameters:

on_error (Optional[Callable[[Key, int, AerospikeError], None]]) – Optional (key, index, exception) -> None callback. When set, failed per-key results are dispatched to the callback and excluded from the returned stream — the stream contains only successes. Cluster-level errors still raise.

Return type:

RecordStream

Returns:

A RecordStream of per-key RecordResult items, backed by a materialized list (positional via RecordResult.index).

Raises:

ValueError – If no operations have been added.

async execute_stream(on_error=None)

Lazy streaming batch execute — yields records in completion order.

Builds a single mixed PAC batch_stream call covering all ops (reads, writes, deletes) and returns a RecordStream whose __anext__ pulls (idx, BatchRecord) tuples from the PAC stream one at a time. First record arrives at first-RTT, not after all keys complete; peak memory is bounded.

Caveats — differ from execute():

• Yields completion order, not input order. Each RecordResult carries its originating op’s input position in RecordResult.index; sort after collecting if positional results are needed.

• Per-key errors inline on RecordResult (when on_error is unset); cluster-level errors raise from __anext__.

• No writes-complete-on-return guarantee. Per-node tasks dispatch in the background; if the caller awaits this method but never iterates the returned stream, server-side writes may still be in-flight when subsequent code runs. Callers that need writes-complete-on-return — or use the “fire-and-forget” shape (await session.batch()...execute_stream() without draining) — must use execute() instead.

Per-key op composition is inspected via aerospike_async.has_any_write_op() to choose the right PAC op wrapper: read-only op lists (e.g. AEL select_from expressions) land as BatchReadOp, write/mutation op lists as BatchWriteOp. Matches the wire-dispatch behavior of the buffered execute() path.

Parameters:

on_error (Optional[Callable[[Key, int, AerospikeError], None]]) – Optional (key, index, exception) -> None callback. When set, per-key failures are dispatched to the handler as records arrive and excluded from the returned stream; cluster-level errors still raise from __anext__.

Return type:

RecordStream

Returns:

A lazy RecordStream. async for it to drive PAC’s per-record yield.

Raises:

ValueError – If no operations have been added.