CDT Read Builders

class aerospike_sdk.aio.operations.cdt_read.CdtReadBuilder

Bases: Generic[T]

Terminal read actions and singular navigation for a CDT path.

The parent (type T) must expose add_operation(op) so the builder can register the produced operation before returning it.

Navigation fields (bin_name, ctx, to_ctx) are optional; when not provided, further navigation is not available (terminal-only).

Example:

Read values from a map key within a query::

    stream = await (
        session.query(key)
            .bin("settings").on_map_key("theme").get_values()
            .execute()
    )

__init__(parent, op_factory, return_type_cls, *, is_map, bin_name='', ctx=(), to_ctx=None, filterable=True)

on_each_child()

Continue from this selection as a path over every child.

Return type:

CdtPathBuilder[TypeVar(T)]

Returns:

A CdtPathBuilder one level below the current selection.

Example:

.bin("catalog").on_map_key("book").on_each_child().collect_values()

on_each_child_where(predicate)

Continue as a path over the children matching predicate.

Parameters:

predicate (Any) – An Exp over the element’s loop variable.

Return type:

CdtPathBuilder[TypeVar(T)]

Returns:

A CdtPathBuilder over the matching children.

on_map_keys_in(keys)

Continue as a path over the map entries whose key is in keys.

Parameters:

keys (Iterable[Any]) – The map keys to select.

Return type:

CdtPathBuilder[TypeVar(T)]

Returns:

A CdtPathBuilder over the selected entries.

Raises:

TypeError – If keys is a bare str, bytes or bytearray rather than a collection of keys.

Example:

.bin("catalog").on_map_key("prices").on_map_keys_in(["a", "c"]).collect_values()

and_filter(predicate)

Continue as a path that keeps this selection only if it matches predicate.

The server evaluates predicate against the element this step selected: a match continues the path with it, a miss selects nothing.

Example:

over_10 = Exp.gt(Exp.int_loop_var(LoopVarPart.VALUE), Exp.val(10))
stream = await (
    session.query(key)
        .bin("prices").on_map_key("book").and_filter(over_10).collect_values()
        .execute()
)

Parameters:

predicate (Any) – An Exp over the element’s loop variable.

Return type:

CdtPathBuilder[TypeVar(T)]

Returns:

A CdtPathBuilder over the filtered selection.

Raises:

TypeError – If this step is a range or multi-element selection, which has no single element to filter, or a map index or rank step, where the server does not return the filtered value correctly.

See also

CdtPathBuilder.and_filter(): the same filter after on_map_keys_in() or a step inside a path.

on_map_key(key, *, create_type=None)

Navigate into a map element by key.

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:

CdtReadBuilder[TypeVar(T)]

Returns:

CdtReadBuilder for reading the targeted element.

Example::

.bin(“m”).on_map_key(“x”).get_values()

on_map_index(index)

Navigate into a map element by index.

Parameters:

index (int) – Map index to target.

Return type:

CdtReadBuilder[TypeVar(T)]

Returns:

CdtReadBuilder for reading the targeted element.

on_map_rank(rank)

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

Parameters:

rank (int) – Rank position (0 = lowest value).

Return type:

CdtReadBuilder[TypeVar(T)]

Returns:

CdtReadBuilder for reading the targeted element.

on_list_index(index, *, order=None, pad=False)

Navigate into a list element by index.

Parameters:

• index (int) – List index (0-based, negative counts from end).

• order (Optional[ListOrderType]) – If set (or if pad is True), use create-on-missing list context with this order; when only pad is True, defaults to UNORDERED.

• pad (bool) – When using create-on-missing context, allow sparse indexes.

Return type:

CdtReadBuilder[TypeVar(T)]

Returns:

CdtReadBuilder for reading the targeted element.

Example::

.bin(“items”).on_list_index(0).get_values()

on_list_rank(rank)

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

Parameters:

rank (int) – Rank position (0 = lowest value).

Return type:

CdtReadBuilder[TypeVar(T)]

Returns:

CdtReadBuilder for reading the targeted element.

on_map_value(value)

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

Parameters:

value (Any) – Value to match.

Return type:

CdtReadInvertableBuilder[TypeVar(T)]

Returns:

CdtReadInvertableBuilder for reading the selection; further singular navigation is supported when this builder was produced from a nested path.

on_map_index_range(index, count=None)

Navigate into map elements by index range.

Return type:

CdtReadInvertableBuilder[TypeVar(T)]

on_map_key_range(start, end)

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

Return type:

CdtReadInvertableBuilder[TypeVar(T)]

on_map_rank_range(rank, count=None)

Navigate into map elements by rank range.

Return type:

CdtReadInvertableBuilder[TypeVar(T)]

on_map_value_range(start, end)

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

Return type:

CdtReadInvertableBuilder[TypeVar(T)]

on_map_key_relative_index_range(key, index, count=None)

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

Return type:

CdtReadInvertableBuilder[TypeVar(T)]

on_map_value_relative_rank_range(value, rank, count=None)

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

Return type:

CdtReadInvertableBuilder[TypeVar(T)]

on_map_key_list(keys)

Navigate into map elements matching a list of keys.

Parameters:

keys (Sequence[Any]) – Map keys to match.

Return type:

CdtReadInvertableBuilder[TypeVar(T)]

Returns:

CdtReadInvertableBuilder for reading 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)

Navigate into map elements matching a list of values.

Parameters:

values (Sequence[Any]) – Values to match.

Return type:

CdtReadInvertableBuilder[TypeVar(T)]

Returns:

CdtReadInvertableBuilder for reading the matched elements.

Raises:

TypeError – If values is a bare str, bytes or bytearray rather than a collection of values.

on_list_value(value)

Navigate into list elements matching a value.

Return type:

CdtReadInvertableBuilder[TypeVar(T)]

on_list_index_range(index, count=None)

Navigate into list elements by index range.

Return type:

CdtReadInvertableBuilder[TypeVar(T)]

on_list_rank_range(rank, count=None)

Navigate into list elements by rank range.

Return type:

CdtReadInvertableBuilder[TypeVar(T)]

on_list_value_range(start, end)

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

Return type:

CdtReadInvertableBuilder[TypeVar(T)]

on_list_value_relative_rank_range(value, rank, count=None)

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

Return type:

CdtReadInvertableBuilder[TypeVar(T)]

on_list_value_list(values)

Navigate into list elements matching a list of values.

Parameters:

values (Sequence[Any]) – Values to match.

Return type:

CdtReadInvertableBuilder[TypeVar(T)]

Returns:

CdtReadInvertableBuilder for reading the matched elements.

Raises:

TypeError – If values is a bare str, bytes or bytearray rather than a collection of values.

get_values()

Return value(s) at the current CDT selection.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

Example::

.bin(“m”).on_map_key(“x”).get_values()

get_keys()

Return map keys at the current CDT selection.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

get_keys_and_values()

Return map key-value pairs at the current CDT selection.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

See also

get_as_map(): The same entries as an unordered dict. get_as_ordered_map(): The same entries as a key-ordered SortedMap.

get_as_map()

Return the selected map entries as an unordered dict.

The server returns the entries as an unordered map rather than as key-value pairs, so the result makes no promise about order; use get_keys_and_values() to keep the server’s selection order or get_as_ordered_map() for key order.

Example:

stream = await (
    session.query(players.id("p-1001"))
    .bin("scores").on_map_key_range("a", "m").get_as_map()
    .execute()
)
early = (await stream.first_or_raise()).record.bins["scores"]

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

Raises:

TypeError – If the selection is on a list rather than a map.

See also

get_keys_and_values(): Entries in selection order, as a dict. get_as_ordered_map(): Entries in key order, as a SortedMap.

get_as_ordered_map()

Return the selected map entries as a key-ordered SortedMap.

Unlike get_keys_and_values(), which keeps the order the server selected the entries in (rank order for a rank range), the result is ordered by key whatever the bin’s own map order. Writing it back to a bin stores that map key-ordered.

Example:

stream = await (
    session.query(players.id("p-1001"))
    .bin("scores").on_map_rank_range(-3, 3).get_as_ordered_map()
    .execute()
)
top_three = (await stream.first_or_raise()).record.bins["scores"]
# SortedMap({"amy": 870, "raj": 910, "zoe": 955})

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

Raises:

TypeError – If the selection is on a list rather than a map.

See also

get_keys_and_values(): Entries in selection order, as a dict.

count()

Return the count of elements at the current CDT selection.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

get_indexes()

Return indexes of the selected CDT elements.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

get_reverse_indexes()

Return reverse indexes of the selected CDT elements.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

get_ranks()

Return ranks of the selected CDT elements.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

get_reverse_ranks()

Return reverse ranks of the selected CDT elements.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

exists()

Check whether the selected CDT element(s) exist.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

map_size()

Return the element count of the map at the current CDT path.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

list_size()

Return the element count of the list at the current CDT path.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

list_join(separator=None)

Concatenate the string items of the list at the current CDT path.

The list must hold only strings; any other element type fails with PARAMETER_ERROR. An empty list joins to an empty string.

Parameters:

separator (Optional[str]) – Inserted between consecutive items. None = no separator.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

list_get(index)

Read the list element at index at the current CDT path.

Return type:

TypeVar(T)

list_get_range(index, count=None)

Read a slice of the list starting at index (through end if count is None).

Return type:

TypeVar(T)

str_strlen()

Return the Unicode codepoint count of the string at this CDT path.

Example:

stream = await (
    session.query(key)
        .bin("tags").on_list_index(1).str_strlen()
        .execute()
)

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

See also

str_byte_length(): UTF-8 byte length instead.

str_substr(start, end=None)

Return the codepoint range [start, end) of the string at this CDT path.

end omitted runs to the end of the string; negative start counts from the end. Out-of-bounds indexes clamp.

Parameters:

• start (int) – Codepoint index to start at.

• end (Optional[int]) – End-exclusive codepoint index. None means run to end.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

str_char_at(index)

Return the codepoint at index as a one-codepoint string.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

str_find(needle, occurrence=None)

Return the codepoint index of needle (-1 when absent).

Parameters:

• needle (str) – Substring to locate.

• occurrence (Optional[int]) – 1-based match index; -1 selects the last match. None means first occurrence.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

str_contains(needle)

Return True iff the string at this CDT path contains needle.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

str_starts_with(prefix)

Return True iff the string at this CDT path starts with prefix.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

str_ends_with(suffix)

Return True iff the string at this CDT path ends with suffix.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

str_to_integer()

Parse the string at this CDT path as int64.

Server returns OP_NOT_APPLICABLE (subcode SubCode.OPNOT_STRING_CONVERSION_FAILED) if it is not numeric.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

str_to_double()

Parse the string at this CDT path as float64.

Server returns OP_NOT_APPLICABLE (subcode SubCode.OPNOT_STRING_CONVERSION_FAILED) if it is not numeric.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

str_byte_length()

Return the UTF-8 byte count of the string at this CDT path.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

str_is_numeric(numeric_type=None)

Return True iff the string at this CDT path parses as a number.

Parameters:

numeric_type (Optional[StringNumericType]) – Restrict to INT or FLOAT. None = either.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

str_is_upper()

Return True iff every cased codepoint at this CDT path is uppercase.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

str_is_lower()

Return True iff every cased codepoint at this CDT path is lowercase.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

str_to_blob()

Return the UTF-8 bytes of the string at this CDT path as a blob.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

str_split(separator=None)

Split the string at this CDT path into a list.

Parameters:

separator (Optional[str]) – Substring to split on. None splits per codepoint.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

str_b64_decode()

Base64-decode the string at this CDT path, returning bytes.

Server returns OP_NOT_APPLICABLE (subcode SubCode.OPNOT_STRING_B64_INVALID) if it is not valid base64.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

str_regex_compare(pattern, flags=0)

Return True iff the ICU regex pattern matches the string at this CDT path.

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.

• flags (int | StringRegexFlags) – OR-combined StringRegexFlags bitmask.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

class aerospike_sdk.aio.operations.cdt_read.CdtReadInvertableBuilder

Bases: CdtReadBuilder[T]

Terminal read actions with inverted (all-others) variants.

Used for range and list selectors where INVERTED makes semantic sense (e.g. “all keys except those in this range”). When constructed with to_ctx set (e.g. after a singular value selector on a nested path), singular navigation methods continue the CDT path.

Example:

Get all map values *except* those in a key range::

    .bin("m").on_map_key_range("a", "d").get_all_other_values()

get_all_other_values()

Return all values except those matching the selection (INVERTED).

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

get_all_other_keys()

Return all map keys except those matching the selection.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

get_all_other_keys_and_values()

Return all map key-value pairs except those matching the selection.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

count_all_others()

Return the count of elements except those matching the selection.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

get_all_other_indexes()

Return indexes of all elements except those matching the selection.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

get_all_other_reverse_indexes()

Return reverse indexes of all elements except those matching the selection.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

get_all_other_ranks()

Return ranks of all elements except those matching the selection.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.

get_all_other_reverse_ranks()

Return reverse ranks of all elements except those matching the selection.

Return type:

TypeVar(T)

Returns:

The parent builder for chaining.