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, filterable=True)[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.

Parameters:: keys (Sequence[Any]) – Map keys to match.
Return type:: CdtWriteInvertableBuilder[TypeVar(T)]
Returns:: CdtWriteInvertableBuilder for writing the matched elements.
Raises:: TypeError – If keys is a bare str, bytes or bytearray rather than a collection of keys.

on_map_value_list(values)[source]¶

Navigate into map elements matching a list of values.

Parameters:: values (Sequence[Any]) – Values to match.
Return type:: CdtWriteInvertableBuilder[TypeVar(T)]
Returns:: CdtWriteInvertableBuilder for writing the matched elements.
Raises:: TypeError – If values is a bare str, bytes or bytearray rather than a collection of values.

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.

Parameters:: values (Sequence[Any]) – Values to match.
Return type:: CdtWriteInvertableBuilder[TypeVar(T)]
Returns:: CdtWriteInvertableBuilder for writing the matched elements.
Raises:: TypeError – If values is a bare str, bytes or bytearray rather than a collection of values.

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(value, *, unique=False, bounded=False, no_fail=False)[source]¶

Append value to the end of the unordered list at the current path.

Parameters:

value (Any) – Value to append.
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)

Returns:

The parent builder for chaining.

Raises:

ElementExistsError – At execution, if unique is set, the value is already in the list, and no_fail is not set.

Example:

await (
    session.update(key)
    .bin("teams").on_map_key("team1").list_append("Diana")
    .execute()
)

See also

list_add_items(): Add several values in one operation. list_append(): Append to the end of an unordered list.

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=True, persist_index=False)[source]¶

Create an empty list with the given order.

Parameters:

order (ListOrderType) – Element ordering for the list.
pad (bool) – When creating through a context path, allow the target index to leave a gap, filling the skipped entries with None. Defaults to True. Has no effect on a top-level list, which has no context element to carry the flag.
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)

str_insert(index, value, *, flags=0)[source]¶

Splice value into the string at this CDT path at codepoint index.

Example:

await (
    session.upsert(key)
        .bin("tags").on_list_index(1).str_insert(0, "#")
        .execute()
)

Parameters:

index (int) – Codepoint index to splice at; negative counts from the end.
value (str) – String to insert.
flags (int | StringWriteFlags) – OR-combined StringWriteFlags bitmask.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

str_overwrite(index, value, *, flags=0)[source]¶

Overwrite codepoints starting at index with value.

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

str_concat(value, *, flags=0)[source]¶

Append value (one string or a list of strings, in order).

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

str_append(value, *, flags=0)[source]¶

Append value to the end of the string at this CDT path.

Example:

await (
    session.upsert(key)
        .bin("names").on_map_key("first").str_append("!")
        .execute()
)

Parameters:

value (str) – String to append.
flags (int | StringWriteFlags) – OR-combined StringWriteFlags bitmask.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

str_prepend(value, *, flags=0)[source]¶

Prepend value to the start of the string at this CDT path.

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

str_snip(start, end=None, *, flags=0)[source]¶

Remove the codepoint range [start, end); end omitted truncates to the end.

Parameters:

start (int) – Codepoint index where the removed range starts.
end (Optional[int]) – Exclusive end of the removed range, or None to remove through the end of the string. flags require an explicit end.
flags (int | StringWriteFlags) – OR-combined StringWriteFlags bitmask.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

str_replace(needle, replacement, *, flags=0)[source]¶

Replace the first occurrence of needle with replacement.

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

str_replace_all(needle, replacement, *, flags=0)[source]¶

Replace every occurrence of needle with replacement.

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

str_regex_replace(pattern, replacement, flags=0, *, write_flags=0)[source]¶

Replace the first match of the ICU regex pattern.

Set GLOBAL in flags to replace every match.

Server returns OP_NOT_APPLICABLE (subcode SubCode.OPNOT_STRING_REGEX_LIMIT_EXCEEDED) if matching exceeds the server’s regex resource budget.

Parameters:

pattern (str) – ICU regex pattern.
replacement (str) – Replacement text.
flags (int | StringRegexFlags) – OR-combined StringRegexFlags bitmask.
write_flags (int | StringWriteFlags) – OR-combined StringWriteFlags bitmask (UPDATE_ONLY / NO_FAIL).

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

str_upper(*, flags=0)[source]¶

Uppercase the string at this CDT path in place.

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

str_lower(*, flags=0)[source]¶

Lowercase the string at this CDT path in place.

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

str_case_fold(*, flags=0)[source]¶

Case-fold the string at this CDT path (locale-independent lowercase).

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

str_normalize_nfc(*, flags=0)[source]¶

Normalize the string at this CDT path to Unicode NFC in place.

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

str_trim_start(*, flags=0)[source]¶

Strip leading whitespace from the string at this CDT path.

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

str_trim_end(*, flags=0)[source]¶

Strip trailing whitespace from the string at this CDT path.

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

str_trim(*, flags=0)[source]¶

Strip whitespace from both ends of the string at this CDT path.

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

str_pad_start(target_length, pad_string, *, flags=0)[source]¶

Left-pad with pad_string to target_length codepoints.

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

str_pad_end(target_length, pad_string, *, flags=0)[source]¶

Right-pad with pad_string to target_length codepoints.

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

str_repeat(count, *, flags=0)[source]¶

Repeat the string at this CDT path count times.

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

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.