CDT Write Builders¶

class aerospike_sdk.aio.operations.cdt_write.CdtWriteBuilder[source]¶

Bases: _RemoveMixin, CdtReadBuilder[T]

CDT action builder with read, remove, and write terminals.

Inherits all read terminals and navigation from CdtReadBuilder. Adds remove(), and on map-key paths set_to() / add(). Navigation returns CdtWriteBuilder to preserve write capability.

Example

Set a nested map value and remove another key:

await (
    session.upsert(key)
        .bin("settings").on_map_key("theme").set_to("dark")
        .bin("settings").on_map_key("old_key").remove()
        .execute()
)

__init__(parent, op_factory, remove_factory, return_type_cls, *, is_map, bin_name='', ctx=(), to_ctx=None, set_to_factory=None, add_factory=None)[source]¶

on_map_key(key, *, create_type=None)[source]¶

Navigate into a map element by key (supports set_to / add).

Parameters:

key (Any) – Map key to target.
create_type (Optional[MapOrder]) – If set, use a create-on-missing context for this key with the given map key order.

Return type:

CdtWriteBuilder[TypeVar(T)]

Returns:

CdtWriteBuilder for writing the targeted element.

on_map_index(index)[source]¶

Navigate into a map element by index.

Return type:: CdtWriteBuilder[TypeVar(T)]

on_map_rank(rank)[source]¶

Navigate into a map element by rank (0 = lowest value).

Return type:: CdtWriteBuilder[TypeVar(T)]

on_list_index(index, *, order=None, pad=False)[source]¶

Navigate into a list element by index.

Return type:: CdtWriteBuilder[TypeVar(T)]

on_list_rank(rank)[source]¶

Navigate into a list element by rank (0 = lowest value).

Return type:: CdtWriteBuilder[TypeVar(T)]

on_map_value(value)[source]¶

Navigate into map elements matching a value (may match multiple).

Return type:: CdtWriteInvertableBuilder[TypeVar(T)]

on_map_index_range(index, count=None)[source]¶

Navigate into map elements by index range.

Return type:: CdtWriteInvertableBuilder[TypeVar(T)]

on_map_key_range(start, end)[source]¶

Navigate into map elements by key range [start, end).

Return type:: CdtWriteInvertableBuilder[TypeVar(T)]

on_map_rank_range(rank, count=None)[source]¶

Navigate into map elements by rank range.

Return type:: CdtWriteInvertableBuilder[TypeVar(T)]

on_map_value_range(start, end)[source]¶

Navigate into map elements by value range [start, end).

Return type:: CdtWriteInvertableBuilder[TypeVar(T)]

on_map_key_relative_index_range(key, index, count=None)[source]¶

Navigate into map entries by index range relative to an anchor key.

Return type:: CdtWriteInvertableBuilder[TypeVar(T)]

on_map_value_relative_rank_range(value, rank, count=None)[source]¶

Navigate into map entries by value rank range relative to an anchor.

Return type:: CdtWriteInvertableBuilder[TypeVar(T)]

on_map_key_list(keys)[source]¶

Navigate into map elements matching a list of keys.

Return type:: CdtWriteInvertableBuilder[TypeVar(T)]

on_map_value_list(values)[source]¶

Navigate into map elements matching a list of values.

Return type:: CdtWriteInvertableBuilder[TypeVar(T)]

on_list_value(value)[source]¶

Navigate into list elements matching a value.

Return type:: CdtWriteInvertableBuilder[TypeVar(T)]

on_list_index_range(index, count=None)[source]¶

Navigate into list elements by index range.

Return type:: CdtWriteInvertableBuilder[TypeVar(T)]

on_list_rank_range(rank, count=None)[source]¶

Navigate into list elements by rank range.

Return type:: CdtWriteInvertableBuilder[TypeVar(T)]

on_list_value_range(start, end)[source]¶

Navigate into list elements by value range [start, end).

Return type:: CdtWriteInvertableBuilder[TypeVar(T)]

on_list_value_relative_rank_range(value, rank, count=None)[source]¶

Navigate into list elements by value rank range relative to anchor.

Return type:: CdtWriteInvertableBuilder[TypeVar(T)]

on_list_value_list(values)[source]¶

Navigate into list elements matching a list of values.

Return type:: CdtWriteInvertableBuilder[TypeVar(T)]

set_to(value)[source]¶

Set the value at the current CDT path.

Requires prior on_map_key() navigation.

Parameters:: value (Any) – New value to store.
Return type:: TypeVar(T)

Example:

.bin("m").on_map_key("color").set_to("blue")

Raises:: TypeError – If not preceded by on_map_key() navigation.

add(value)[source]¶

Increment the value at the current CDT path.

Parameters:: value (Any) – Numeric value to add.
Return type:: TypeVar(T)
Returns:: The parent builder for chaining.
Raises:: TypeError – If not preceded by on_map_key() navigation.

map_clear()[source]¶

Remove all entries from the map at the current CDT path.

Return type:: TypeVar(T)
Returns:: The parent builder for chaining.

map_upsert_items(items, *, order=None, persist_index=False, no_fail=False, partial=False)[source]¶

Put multiple map entries (create or update each key).

Parameters:

items (Any) – Mapping or sequence of (key, value) pairs.
order (MapOrder | None) – Map key order for the policy.
persist_index (bool) – Maintain a persistent index on the map.
no_fail (bool) – Do not raise on write failures.
partial (bool) – Allow partial success for bulk operations.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

map_insert_items(items, *, order=None, persist_index=False, no_fail=False, partial=False)[source]¶

Put map entries only for keys that do not yet exist.

Parameters:

items (Any) – Mapping or sequence of (key, value) pairs.
order (MapOrder | None) – Map key order for the policy.
persist_index (bool) – Maintain a persistent index on the map.
no_fail (bool) – Do not raise on write failures.
partial (bool) – Allow partial success for bulk operations.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

map_update_items(items, *, order=None, persist_index=False, no_fail=False, partial=False)[source]¶

Update existing map entries only (no new keys).

Parameters:

items (Any) – Mapping or sequence of (key, value) pairs.
order (MapOrder | None) – Map key order for the policy.
persist_index (bool) – Maintain a persistent index on the map.
no_fail (bool) – Do not raise on write failures.
partial (bool) – Allow partial success for bulk operations.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

map_create(order)[source]¶

Create an empty map with the given key order.

Parameters:: order (MapOrder) – Key sort order for the map.
Return type:: TypeVar(T)
Returns:: The parent builder for chaining.

map_set_policy(order)[source]¶

Set map sort order policy without changing entries.

Parameters:: order (MapOrder) – Key sort order to apply.
Return type:: TypeVar(T)
Returns:: The parent builder for chaining.

list_clear()[source]¶

Remove all elements from the list at the current CDT path.

Return type:: TypeVar(T)
Returns:: The parent builder for chaining.

list_sort(flags=ListSortFlags.DEFAULT)[source]¶

Sort the list at the current path.

Parameters:: flags (ListSortFlags) – Sort behaviour flags (default DEFAULT).
Return type:: TypeVar(T)
Returns:: The parent builder for chaining.

list_append_items(items, *, unique=False, bounded=False, no_fail=False, partial=False)[source]¶

Append values to an unordered list.

Parameters:

items (Sequence[Any]) – Values to append.
unique (bool) – Reject items that already exist in the list.
bounded (bool) – Reject inserts beyond the current list bounds.
no_fail (bool) – Do not raise on write failures.
partial (bool) – Allow partial success for bulk operations.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

Example:

.bin("tags").on_map_key("items").list_append_items([10, 20])

list_add_items(items, *, unique=False, bounded=False, no_fail=False, partial=False)[source]¶

Insert values into an ordered list (sorted positions).

Parameters:

items (Sequence[Any]) – Values to insert.
unique (bool) – Reject items that already exist in the list.
bounded (bool) – Reject inserts beyond the current list bounds.
no_fail (bool) – Do not raise on write failures.
partial (bool) – Allow partial success for bulk operations.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

list_create(order, *, pad=False, persist_index=False)[source]¶

Create an empty list with the given order.

Parameters:

order (ListOrderType) – Element ordering for the list.
pad (bool) – If True, allow sparse indexes.
persist_index (bool) – If True, maintain a persistent index.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

list_set_order(order)[source]¶

Set list sort order without changing elements.

Parameters:: order (ListOrderType) – Sort order to apply.
Return type:: TypeVar(T)
Returns:: The parent builder for chaining.

list_insert(index, value, *, unique=False, bounded=False, no_fail=False)[source]¶

Insert value at index in the list at the current CDT path.

Parameters:

index (int) – List index (0-based; negative counts from the end).
value (Any) – Element to insert.
unique (bool) – Reject if the value already exists in the list.
bounded (bool) – Reject if index is beyond the current list bounds.
no_fail (bool) – Do not raise on write failures.

Return type:

TypeVar(T)

list_insert_items(index, items, *, unique=False, bounded=False, no_fail=False, partial=False)[source]¶

Insert items starting at index in the list at the current path.

Parameters:

index (int) – List index at which to insert the first element.
items (Sequence[Any]) – Values to insert in order.
unique (bool) – Reject items that already exist in the list.
bounded (bool) – Reject inserts beyond the current list bounds.
no_fail (bool) – Do not raise on write failures.
partial (bool) – Allow partial success for bulk operations.

Return type:

TypeVar(T)

list_set(index, value)[source]¶

Replace the list element at index with value.

Return type:: TypeVar(T)

list_increment(index, value=1)[source]¶

Add value to the numeric element at index (default 1).

Return type:: TypeVar(T)

list_remove(index)[source]¶

Remove the element at index from the list at the current path.

Return type:: TypeVar(T)

list_remove_range(index, count=None)[source]¶

Remove count elements from index, or through the end if count is None.

Return type:: TypeVar(T)

list_pop(index)[source]¶

Pop the element at index (returned in the operate result).

Return type:: TypeVar(T)

list_pop_range(index, count=None)[source]¶

Pop count elements from index, or through the end if count is None.

Return type:: TypeVar(T)

list_trim(index, count)[source]¶

Keep count elements starting at index; remove the rest.

Return type:: TypeVar(T)

class aerospike_sdk.aio.operations.cdt_write.CdtWriteInvertableBuilder[source]¶

Bases: CdtWriteBuilder[T], CdtReadInvertableBuilder[T]

CDT action builder with read, inverted-read, remove, and nested write paths.

Combines CdtWriteBuilder navigation (including invertable selectors) with inverted read terminals from CdtReadInvertableBuilder.

Example

Remove everything except the selected range:

.bin("m").on_map_value_range(0, 100).remove_all_others()

__init__(parent, op_factory, remove_factory, return_type_cls, *, is_map, bin_name='', ctx=(), to_ctx=None)[source]¶

remove_all_others(*, return_type=None)[source]¶

Remove all CDT elements except the selected ones.

The inverted selection flag is applied automatically; pass only the base return type (for example MapReturnType.COUNT), not OR’d with INVERTED.

Example:

await session.update(key).bin("m").on_map_key_range("b", "d").remove_all_others().execute()

stream = await (
    session.update(key)
        .bin("m")
        .on_map_key_range("b", "d")
        .remove_all_others(return_type=MapReturnType.VALUE)
        .execute()
)

Parameters:: return_type (Any) – What the server should return about the removed elements. When omitted, the server returns no removal metadata (NONE).
Return type:: TypeVar(T)
Returns:: The parent builder for chaining.