Query Builders¶

class aerospike_sdk.aio.operations.query.QueryBuilder[source]¶

Bases: _WriteVerbs

Chain reads, writes, UDF calls, filters, and policies before execute.

Start from query() or query(). Use where() or filter_expression() for server-side predicates, bins() or bin() for projections, and transition methods such as upsert() for writes. Await execute() for a RecordStream.

Example

Set-wide read with filter and projection:

stream = await (
    session.query(users)
        .where("$.status == 'active'")
        .bins(["user_id", "name"])
        .execute()
)
async for row in stream:
    if row.is_ok and row.record:
        print(row.record.bins)

Point read on a key, then chain an upsert:

stream = await (
    session.query(users.id("u1"))
        .bins(["name"])
        .upsert(users.id("u1"))
        .put({"last_seen": 123})
        .execute()
)

See also

WriteSegmentBuilder: Bin writes after a write verb. QueryBinBuilder: Per-bin read operations.

__init__(client, namespace, set_name, behavior=None, indexes_monitor=None, cached_read_policy=None, cached_write_policy=None, txn=None)[source]¶

Initialize a QueryBuilder.

Parameters:

client (Client) – The underlying async client.
namespace (str) – The namespace name.
set_name (str) – The set name.
behavior (Optional[Behavior]) – Optional Behavior for deriving policies.
indexes_monitor (Optional[IndexesMonitor]) – Optional monitor providing cached index metadata for transparent filter generation from AEL expressions.
cached_read_policy (Optional[ReadPolicy]) – Pre-computed read policy from the session.
cached_write_policy (Optional[WritePolicy]) – Pre-computed write policy from the session.
txn (Optional[Txn]) – Optional active Txn captured from a transactional session at construction; every policy this builder hands to the PAC gets stamped with it. None means no transaction participation. Callers rarely pass this directly — transactional sessions thread it through automatically.

with_txn(txn)[source]¶

Opt this builder into (or out of) a specific transaction.

Overrides any transaction captured at construction. Pass None to opt out of an ambient transaction (useful inside a TransactionalSession when a single operation must run outside the MRT).

Parameters:: txn (Optional[Txn]) – The Txn to participate in, or None to run without a transaction.
Return type:: QueryBuilder
Returns:: This builder for method chaining.

Example

>>> async with session.begin_transaction() as tx:
...     await tx.upsert(k1).bin("v").set_to(1).execute()
...     # Run this one write outside the transaction:
...     await tx.upsert(k2).with_txn(None).bin("v").set_to(2).execute()

bins(bin_names)[source]¶

Restrict the read to a non-empty set of bin names.

Mutually exclusive with with_no_bins().

Parameters:: bin_names (List[str]) – Non-empty list of bin names to return.
Return type:: QueryBuilder
Returns:: This builder for method chaining.
Raises:: ValueError – If bin_names is empty or with_no_bins() was already called.

Example

Restrict a query or key read to specific bins:

stream = await session.query(users.id(1)).bins(["name", "email"]).execute()

See also

with_no_bins(): Metadata-only reads without bin payloads. bin(): Per-bin operations (CDT, expressions).

bin(bin_name)[source]¶

Start a bin-level read operation.

Returns a QueryBinBuilder for specifying how to read from the named bin (simple get, CDT navigation, or expression read).

Parameters:: bin_name (str) – The bin to operate on.
Return type:: QueryBinBuilder[QueryBuilder]
Returns:: A QueryBinBuilder for method chaining.

Example:

rs = await session.query(users.id(1)) \
    .bin("settings").on_map_key("theme").get_values() \
    .bin("age").get() \
    .execute()

add_operation(op)[source]¶

Append a read operation produced by a bin or CDT builder.

Return type:: None

with_write_operations(operations)[source]¶

Attach scalar write operations for a background dataset task.

Prefer aerospike_sdk.aio.session.Session.background_task() for chained bin writes. Use with execute_background_task() on a dataset query (no keys). Only Operation and ExpOperation.write-style writes are valid; list, map, bit, and HLL operations are rejected before calling the client.

Parameters:: operations (Sequence[Any]) – Sequence of write operations (e.g. Operation.put, Operation.touch).
Return type:: QueryBuilder
Returns:: self for method chaining.

with_no_bins()[source]¶

Specify that no bins should be read (header-only query).

This method is useful when you only need to check for record existence or get metadata like generation numbers, without reading the actual data.

This method cannot be used together with bins().

Return type:: QueryBuilder
Returns:: self for method chaining.
Raises:: ValueError – If used together with bins().

filter(filter_obj)[source]¶

Add a secondary index filter to the query.

Parameters:: filter_obj (Filter) – The filter to add.
Return type:: QueryBuilder
Returns:: This builder for method chaining.

filter_expression(expression)[source]¶

Set a FilterExpression for server-side filtering.

FilterExpression allows complex server-side filtering that doesn’t require secondary indexes. This is more efficient than client-side filtering as it reduces network traffic and processing.

Parameters:: expression (FilterExpression) – The FilterExpression to apply.
Return type:: QueryBuilder
Returns:: self for method chaining.

Example:

# Filter by multiple conditions server-side
filter_exp = FilterExpression.and_([
    FilterExpression.eq(
        FilterExpression.string_bin("category"),
        FilterExpression.string_val("Shoes")
    ),
    FilterExpression.eq(
        FilterExpression.string_bin("usage"),
        FilterExpression.string_val("Sports")
    )
])
recordset = await client.query("test", "products").filter_expression(filter_exp).execute()

where(expression)[source]¶

Overloads:

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

Apply a server-side filter for dataset queries or keyed reads that support it.

String arguments are parsed with the AEL; prefer f-strings for dynamic literals. Pass a pre-built FilterExpression when constructing filters programmatically.

Parameters:: expression (Union[str, FilterExpression]) – AEL string or FilterExpression.
Returns:: This builder for chaining.

Example

qb = session.query(ds).where(“$.status == ‘active’”) qb = session.query(ds).where(f”$.score > {min_score}”)

See also

default_where(): Default filter for chained operations without their own. filter_expression(): Attach an expression without AEL parsing.

with_index_context(index_context)[source]¶

Explicitly override the secondary index metadata used for filter generation.

Most applications do not need this method. The client automatically discovers and caches secondary index metadata from the cluster in the background. Use this only when you need to force a specific index context that differs from the live cluster state.

Parameters:: index_context (IndexContext) – Index metadata for the query’s namespace.
Return type:: QueryBuilder
Returns:: This builder for method chaining.

See also

IndexContext

with_policy(policy)[source]¶

Set the query policy.

Parameters:: policy (QueryPolicy) – The query policy to use.
Return type:: QueryBuilder
Returns:: self for method chaining.

with_read_policy(policy)[source]¶

Set the read policy (for single key or batch key queries).

Parameters:: policy (ReadPolicy) – The read policy to use.
Return type:: QueryBuilder
Returns:: self for method chaining.

partition(partition_filter)[source]¶

Restrict a dataset query using a PAC PartitionFilter.

Prefer on_partition() or on_partition_range() for common cases.

Parameters:: partition_filter (PartitionFilter) – Built filter (all partitions, by id, by range, etc.).
Return type:: QueryBuilder
Returns:: This builder for chaining.

See also

on_partition_range(): Inclusive start, exclusive end partition ids.

on_partitions(*partition_ids)[source]¶

Set partitions to query by partition IDs.

Parameters:: *partition_ids (int) – One or more partition IDs to query.
Return type:: QueryBuilder
Returns:: self for method chaining.

Example:

query = session.query(dataset).on_partitions(1, 2, 3)

on_partition(part_id)[source]¶

Target a specific partition for the query.

This method restricts the query to a single partition. This can be useful for load balancing or when you know the data distribution across partitions.

Parameters:: part_id (int) – The partition ID to target (0-4095)
Return type:: QueryBuilder
Returns:: self for method chaining
Raises:: ValueError – If part_id is out of range

Example:

query = session.query(dataset).on_partition(5)

on_partition_range(start_incl, end_excl)[source]¶

Target a range of partitions for the query.

This method restricts the query to a specific range of partitions. This can be useful for load balancing, parallel processing, or when you know the data distribution across partitions.

The partition range can only be set once per query. Subsequent calls with different ranges will overwrite the previous range.

Parameters:

start_incl (int) – Start partition (inclusive, 0-4095)
end_excl (int) – End partition (exclusive, 1-4096)

Return type:

QueryBuilder

Returns:

self for method chaining

Raises:

ValueError – If partition range is invalid

Example:

# Query partitions 0-2047 (first half)
query = session.query(dataset).on_partition_range(0, 2048)

# Query partitions 100-199
query = session.query(dataset).on_partition_range(100, 200)

chunk_size(chunk_size)[source]¶

Tune server-side streaming chunk size (maps to query policy max_records chunking).

This method controls how many records are fetched per chunk from the server when using server-side streaming. The chunk size affects memory usage and network round trips (Larger values reduce round trips; smaller values bound memory per fetch). This is distinct from client-side pagination.

Parameters:: chunk_size (int) – Records per chunk; must be positive.
Return type:: QueryBuilder
Returns:: This builder for chaining.
Raises:: ValueError – If chunk_size <= 0.

Example:

query = session.query(dataset).chunk_size(100)

See also

max_records(): Cap total records returned.

records_per_second(rps)[source]¶

Set the maximum records per second for the query.

Parameters:: rps (int) – Maximum records per second to process.
Return type:: QueryBuilder
Returns:: self for method chaining.

Example:

query = session.query(dataset).records_per_second(1000)

max_records(max_records)[source]¶

Set the maximum number of records to return.

Parameters:: max_records (int) – Maximum number of records to return.
Return type:: QueryBuilder
Returns:: self for method chaining.

Example:

query = session.query(dataset).max_records(10000)

limit(limit)[source]¶

Set the maximum number of records to return (alias for max_records).

This method is an alias for max_records(). It limits the total number of records returned by the query. Once the limit is reached, the query will stop processing.

Parameters:: limit (int) – Maximum number of records to return (must be > 0).
Return type:: QueryBuilder
Returns:: self for method chaining.
Raises:: ValueError – If limit is <= 0.

Example:

query = session.query(dataset).limit(100)

expected_duration(duration)[source]¶

Set the expected duration of the query.

Parameters:: duration (QueryDuration) – Expected duration (QueryDuration.LONG, QueryDuration.SHORT, or QueryDuration.LONG_RELAX_AP).
Return type:: QueryBuilder
Returns:: self for method chaining.

Example:

from aerospike_async import QueryDuration
query = session.query(dataset).expected_duration(QueryDuration.SHORT)

with_hint(hint)[source]¶

Attach a query hint for secondary index selection or scheduling.

A hint can redirect which secondary index is used (index_name), remap the filter to a different bin (bin_name), or override the expected query duration (query_duration). Only one call to with_hint is allowed per builder.

Example:

stream = await (
    session.query(dataset)
        .filter(Filter.equal("age", 30))
        .with_hint(QueryHint(index_name="age_idx"))
        .execute()
)

Parameters:: hint (QueryHint) – A QueryHint instance.
Return type:: QueryBuilder
Returns:: This builder for method chaining.
Raises:: ValueError – If with_hint has already been called on this builder.

See also

QueryHint

replica(replica)[source]¶

Set the replica preference for the query.

Parameters:: replica (Replica) – Replica preference. One of Replica.MASTER, Replica.MASTER_PROLES, Replica.RANDOM, Replica.SEQUENCE, or Replica.PREFER_RACK.
Return type:: QueryBuilder
Returns:: self for method chaining.

Example:

from aerospike_async import Replica
query = session.query(dataset).replica(Replica.SEQUENCE)

base_policy(base_policy)[source]¶

Set the base policy for the query.

Parameters:: base_policy (BasePolicy) – The base policy to use.
Return type:: QueryBuilder
Returns:: self for method chaining.

Example:

from aerospike_async import BasePolicy
base = BasePolicy()
query = session.query(dataset).base_policy(base)

fail_on_filtered_out()[source]¶

Surface rows that fail a filter as FILTERED_OUT instead of omitting them.

Applies to key-based reads where a filter excludes the record. Without this flag, filtered keys may be absent from the stream depending on policy.

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

See also

respond_all_keys(): Include missing-key rows in batch reads.

respond_all_keys()[source]¶

Ensure batch/point reads emit one row per requested key, including not-found.

Missing keys appear as non-OK RecordResult entries (typically KEY_NOT_FOUND) instead of being skipped.

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

See also

fail_on_filtered_out(): Filter mismatch vs missing key.

default_where(expression)[source]¶

Overloads:

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

Set a filter applied to any chained operation that does not call where().

When a chain contains multiple operations (reads, writes, UDFs), each operation inherits this filter unless it supplies its own where().

Example:

stream = await (
    session.upsert(k1)
        .bin("status").set_to("active")
        .where(f"$.age >= {min_age}")
    .delete(k2, k3)
    .upsert(k4)
        .bin("flag").set_to(True)
    .default_where("$.active == true")
    .execute()
)
# upsert(k1) keeps its own where(); the delete and
# second upsert inherit default_where.

Parameters:: expression (Union[str, FilterExpression]) – AEL string or FilterExpression.
Returns:: This builder for chaining.

See also

where(): Per-operation filter on the current operation.

default_expire_record_after_seconds(seconds)[source]¶

Set a default TTL applied to chained operations that lack their own.

Parameters:: seconds (int) – Time-to-live in seconds (must be > 0).
Return type:: QueryBuilder
Returns:: self for method chaining.
Raises:: ValueError – If seconds is <= 0.

default_never_expire()[source]¶

Set the default TTL to never expire (TTL = -1).

Return type:: QueryBuilder

default_with_no_change_in_expiration()[source]¶

Set the default to preserve each record’s existing TTL (TTL = -2).

Return type:: QueryBuilder

default_expiry_from_server_default()[source]¶

Set the default TTL to the namespace’s server default (TTL = 0).

Return type:: QueryBuilder

query(arg1, *more_keys)[source]¶

Chain another query with new key(s) for batch/point stacking.

Finalizes the current query segment and begins a new one with the given key(s). Each segment can have its own bins, operations, and filter expression. Dataset (index) queries cannot be stacked.

Parameters:

arg1 (Union[Key, List[Key]]) – A single Key or a List[Key].
*more_keys (Key) – Additional keys (varargs).

Return type:

QueryBuilder

Returns:

self for method chaining.

Raises:

ValueError – If the current query is a dataset query (no keys).

Example:

rs = await session.query(users.ids(1, 2, 3)) \
    .bin("map").get() \
    .query(users.ids(4, 5, 6)) \
    .bin("name").get() \
    .execute()

async execute(on_error=None)[source]¶

Execute the query and return a RecordStream.

Handles single-key, batch-key, and dataset queries. When a chain contains multiple operations, each operation is executed and results are combined into a single stream.

Parameters:

on_error (Union[ErrorStrategy, Callable[[Key, int, AerospikeError], None], None]) –

Controls how per-record errors are surfaced.

None (default): single-key operations raise on error; batch / multi-key operations embed errors in the stream.
ErrorStrategy.IN_STREAM: always embed errors in the stream as RecordResult entries.
A callable (key, index, exception) -> None: errors are dispatched to the callback and excluded from the stream.

Return type:

RecordStream

Returns:

A RecordStream of RecordResult rows.

Raises:

AerospikeError – If the builder mixes dataset query with per-bin read operations (unsupported combination).
AerospikeError – Typed subclasses for timeouts, connection failures, etc. when the client raises instead of embedding errors.

Example

Single-key read with default error handling:

stream = await session.query(key).bins(["x"]).execute()
row = await stream.first_or_raise()

Multi-key read, keep errors in the stream:

stream = await (
    session.query(k1, k2, k3)
        .execute(on_error=ErrorStrategy.IN_STREAM)
)
rows = await stream.collect()

See also

ErrorStrategy: on_error options.

async execute_background_task()[source]¶

Run a background write against all records matching this dataset query.

Returns a server task handle; poll with wait_till_complete or query_status. Requires with_write_operations(); only scalar Operation / expression writes are allowed.

Raises:

ValueError – If the builder targets keys or has no write operations.
AerospikeError – If unsupported operation types are present.

Return type:

ExecuteTask

async execute_udf_background_task(package_name, function_name, args=None)[source]¶

Apply a registered UDF to matching records as a background task.

Do not use with_write_operations() on the same builder.

Raises:: ValueError – If the builder targets keys or has write operations set.
Return type:: ExecuteTask

class aerospike_sdk.aio.operations.query.WriteBinBuilder[source]¶

Bases: _WriteVerbs

Per-bin write builder inside a WriteSegmentBuilder.

Start with WriteSegmentBuilder.bin(). Scalar methods delegate to the segment; map_* and list_* append collection operations; hll_* and bit_* append HyperLogLog and blob bit operations; nested CDT builders capture context for maps and lists. Write verbs on this class finalize the segment and start a new one on new keys.

Example

Set a map key and append to a list within the same write:

await (
    session.upsert(key)
        .bin("config").on_map_key("level").set_to(5)
        .bin("tags").list_append(value="new_tag")
        .execute()
)

See also

QueryBinBuilder: Read-side analogue for queries.

__init__(segment, bin_name)[source]¶

set_to(value)[source]¶

Set the bin to value (Operation.put).

Return type:: WriteSegmentBuilder

add(value)[source]¶

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

Return type:: WriteSegmentBuilder

increment_by(value)[source]¶

Alias of add().

Return type:: WriteSegmentBuilder

append(value)[source]¶

String append (Operation.append).

Return type:: WriteSegmentBuilder

prepend(value)[source]¶

String prepend (Operation.prepend).

Return type:: WriteSegmentBuilder

remove()[source]¶

Drop the bin (write None).

Return type:: WriteSegmentBuilder

get()[source]¶

Return the bin value after writes complete (Operation.get_bin).

Return type:: WriteSegmentBuilder

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

Add value to an ordered list (sorted insert).

Parameters:

value (Any) – Element to insert in sorted order.
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:

WriteSegmentBuilder

Returns:

The parent WriteSegmentBuilder.

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

Append value to the end of an unordered list.

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:

WriteSegmentBuilder

Example::: .bin(“tags”).list_append(value=”python”)

map_clear()[source]¶

Remove all entries from the map bin.

Return type:: WriteSegmentBuilder
Returns:: The parent WriteSegmentBuilder.

map_size()[source]¶

Return the map element count (read within operate).

Return type:: WriteSegmentBuilder
Returns:: The parent WriteSegmentBuilder.

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:

WriteSegmentBuilder

Example::: .bin(“settings”).map_upsert_items({“theme”: “dark”, “lang”: “en”})

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:

WriteSegmentBuilder

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) – Key-value pairs to update for existing keys only.
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:

WriteSegmentBuilder

Returns:

The parent WriteSegmentBuilder.

map_create(order)[source]¶

Create an empty map with the given key order.

Parameters:: order (MapOrder) – Map key sort order.
Return type:: WriteSegmentBuilder
Returns:: The parent WriteSegmentBuilder.

map_set_policy(order)[source]¶

Set map sort order policy without changing entries.

Parameters:: order (MapOrder) – Map key sort order policy.
Return type:: WriteSegmentBuilder
Returns:: The parent WriteSegmentBuilder.

list_clear()[source]¶

Remove all elements from the list bin.

Return type:: WriteSegmentBuilder
Returns:: The parent WriteSegmentBuilder.

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

Sort the list bin.

Parameters:: flags (ListSortFlags) – Sort behavior flags.
Return type:: WriteSegmentBuilder
Returns:: The parent WriteSegmentBuilder.

list_size()[source]¶

Return the list element count (read within operate).

Return type:: WriteSegmentBuilder
Returns:: The parent WriteSegmentBuilder.

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

Append values to an unordered list.

Parameters:

items (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:

WriteSegmentBuilder

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

Insert values into an ordered list (sorted positions).

Parameters:

items (Any) – Sequence of values to insert in sorted 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:

WriteSegmentBuilder

Returns:

The parent WriteSegmentBuilder.

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

Create an empty list with the given order.

Parameters:

order (ListOrderType) – List element order.
pad (bool) – Whether to pad with None entries.
persist_index (bool) – Whether to persist element indices.

Return type:

WriteSegmentBuilder

Returns:

The parent WriteSegmentBuilder.

list_set_order(order)[source]¶

Set list sort order without changing elements.

Parameters:: order (ListOrderType) – List element order.
Return type:: WriteSegmentBuilder
Returns:: The parent WriteSegmentBuilder.

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

Insert value at index in an unordered list.

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:

WriteSegmentBuilder

Returns:

The parent WriteSegmentBuilder.

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

Insert a sequence of values starting at index.

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:

WriteSegmentBuilder

Returns:

The parent WriteSegmentBuilder.

See also

list_insert(), list_append_items()

list_set(index, value)[source]¶

Replace the element at index with value.

Parameters:

index (int) – List index (0-based; negative counts from the end).
value (Any) – New element value.

Return type:

WriteSegmentBuilder

Returns:

The parent WriteSegmentBuilder.

See also

list_get()

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

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

Parameters:

index (int) – List index (0-based; negative counts from the end).
value (int) – Amount to add; 1 uses a dedicated server path.

Return type:

WriteSegmentBuilder

Returns:

The parent WriteSegmentBuilder.

See also

list_set()

list_remove(index)[source]¶

Remove the element at index.

Parameters:: index (int) – List index (0-based; negative counts from the end).
Return type:: WriteSegmentBuilder
Returns:: The parent WriteSegmentBuilder.

See also

list_remove_range()

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

Remove count elements starting at index, or all from index onward.

Parameters:

index (int) – Starting list index.
count (Optional[int]) – Number of elements to remove; None removes through the end.

Return type:

WriteSegmentBuilder

Returns:

The parent WriteSegmentBuilder.

See also

list_remove()

list_pop(index)[source]¶

Remove and return the element at index (read in the operate result).

Parameters:: index (int) – List index (0-based; negative counts from the end).
Return type:: WriteSegmentBuilder
Returns:: The parent WriteSegmentBuilder.

See also

list_pop_range()

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

Pop count elements from index, or from index through the end.

Parameters:

index (int) – Starting list index.
count (Optional[int]) – Number of elements; None pops through the end.

Return type:

WriteSegmentBuilder

Returns:

The parent WriteSegmentBuilder.

See also

list_pop()

list_trim(index, count)[source]¶

Keep only count elements starting at index; remove the rest.

Parameters:

index (int) – Starting list index of the range to keep.
count (int) – Number of elements to keep.

Return type:

WriteSegmentBuilder

Returns:

The parent WriteSegmentBuilder.

See also

list_remove_range()

hll_init(index_bit_count, min_hash_bit_count=-1, flags=0)[source]¶

Initialize an empty HyperLogLog sketch in this bin.

Use before hll_add() on a new bin. Pass -1 for min_hash_bit_count to use the server default. Combine flags with values from HLLWriteFlags.

Example::: await ( session.upsert(key) .bin(“visitors”) .hll_init(12) .execute() )

Parameters:

index_bit_count (int) – Register width index bits (precision); typical values are in the 4–16 range per server documentation.
min_hash_bit_count (int) – Minimum hash bits, or -1 for default.
flags (int) – Optional HLL write flags (often 0 or DEFAULT).

Return type:

WriteSegmentBuilder

Returns:

The parent WriteSegmentBuilder for chaining.

See also

hll_add(): Add distinct values to the sketch. QueryBinBuilder.hll_get_count(): Read cardinality in a query. HLLWriteFlags

hll_add(values, index_bit_count=-1, min_hash_bit_count=-1, flags=0)[source]¶

Add distinct values to the HyperLogLog sketch in this bin.

The server hashes each element into the sketch. Use -1 for index or min-hash bit counts to inherit defaults.

Example::: await ( session.upsert(key) .bin(“visitors”) .hll_add([“user-1”, “user-2”]) .execute() )

Parameters:

values (Sequence[Any]) – Sequence of values (for example strings or blobs) to add.
index_bit_count (int) – Index bits, or -1 for default.
min_hash_bit_count (int) – Min-hash bits, or -1 for default.
flags (int) – Optional HLL write flags (often 0).

Return type:

WriteSegmentBuilder

Returns:

The parent WriteSegmentBuilder for chaining.

See also

hll_init(): Create an empty sketch. hll_get_count(): Read cardinality in the same operate batch. HLLWriteFlags

hll_set_union(hll_list, flags=0)[source]¶

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

Each entry in hll_list is typically another HLL blob (bytes) returned from a prior read.

Example::: await ( session.upsert(key) .bin(“merged”) .hll_set_union([other_hll_blob]) .execute() )

Parameters:

hll_list (Sequence[Any]) – Sketches to union into the target bin.
flags (int) – Optional HLL write flags (often 0).

Return type:

WriteSegmentBuilder

Returns:

The parent WriteSegmentBuilder for chaining.

See also

hll_get_union(): Non-destructive union read. hll_add(): Add raw values instead of whole sketches.

hll_fold(index_bit_count)[source]¶

Reduce sketch precision to a lower index_bit_count (merge registers).

Example::: await session.update(key).bin(“hll”).hll_fold(10).execute()

Parameters:: index_bit_count (int) – New (smaller) index bit width after folding.
Return type:: WriteSegmentBuilder
Returns:: The parent WriteSegmentBuilder for chaining.

See also

hll_init(): Initial precision when creating a sketch.

hll_refresh_count()[source]¶

Refresh the cached cardinality estimate stored with the sketch.

Example::: await session.update(key).bin(“hll”).hll_refresh_count().execute()

Return type:: WriteSegmentBuilder
Returns:: The parent WriteSegmentBuilder for chaining.

See also

hll_get_count(): Read the estimate in the same batch.

hll_get_count()[source]¶

Read the estimated cardinality in a multi-operation write (operate).

The result is returned for this bin when the write completes. For a read-only path, use QueryBinBuilder.hll_get_count().

Example::: stream = await ( session.update(key) .bin(“hll”) .hll_get_count() .execute() )

Return type:: WriteSegmentBuilder
Returns:: The parent WriteSegmentBuilder for chaining.

See also

QueryBinBuilder.hll_get_count(): Same read on a query builder. hll_add(): Populate the sketch before counting.

hll_describe()[source]¶

Read index and min-hash bit counts describing the stored sketch.

Example::: await session.update(key).bin(“hll”).hll_describe().execute()

Return type:: WriteSegmentBuilder
Returns:: The parent WriteSegmentBuilder for chaining.

See also

QueryBinBuilder.hll_describe(): Same read on a query builder.

hll_get_union(hll_list)[source]¶

Read the union sketch without modifying the stored bin.

Example::: await ( session.update(key) .bin(“hll”) .hll_get_union([peer_blob]) .execute() )

Parameters:: hll_list (Sequence[Any]) – Other sketches (blobs) to include in the union result.
Return type:: WriteSegmentBuilder
Returns:: The parent WriteSegmentBuilder for chaining.

See also

QueryBinBuilder.hll_get_union(): Same read on a query builder. hll_set_union(): Persist a union into the bin.

hll_get_union_count(hll_list)[source]¶

Read the estimated cardinality of the union with other sketches.

Example::: await ( session.update(key) .bin(“hll”) .hll_get_union_count([peer_blob]) .execute() )

Parameters:: hll_list (Sequence[Any]) – Other sketches to union for the estimate.
Return type:: WriteSegmentBuilder
Returns:: The parent WriteSegmentBuilder for chaining.

See also

QueryBinBuilder.hll_get_union_count(): Same read on a query.

hll_get_intersect_count(hll_list)[source]¶

Read the estimated intersection cardinality with other sketches.

Example::: await ( session.update(key) .bin(“hll”) .hll_get_intersect_count([peer_blob]) .execute() )

Parameters:: hll_list (Sequence[Any]) – Other sketches included in the intersection estimate.
Return type:: WriteSegmentBuilder
Returns:: The parent WriteSegmentBuilder for chaining.

See also

QueryBinBuilder.hll_get_intersect_count(): Same read on a query.

hll_get_similarity(hll_list)[source]¶

Read Jaccard similarity between this sketch and other sketches.

Example::: await ( session.update(key) .bin(“hll”) .hll_get_similarity([peer_blob]) .execute() )

Parameters:: hll_list (Sequence[Any]) – Other sketches to compare.
Return type:: WriteSegmentBuilder
Returns:: The parent WriteSegmentBuilder for chaining.

See also

QueryBinBuilder.hll_get_similarity(): Same read on a query.

bit_resize(byte_size, resize_flags=None, policy=None)[source]¶

Grow or shrink the raw bytes backing this bin.

When resize_flags is None, DEFAULT is used. When policy is None, a default BitPolicy is built from DEFAULT.

Example::: await session.upsert(key).bin(“flags”).bit_resize(4).execute()

Parameters:

byte_size (int) – Target size of the blob in bytes.
resize_flags (Optional[Any]) – Optional BitwiseResizeFlags value; None selects DEFAULT.
policy (Optional[Any]) – Optional BitPolicy; None selects a default policy.

Return type:

WriteSegmentBuilder

Returns:

The parent WriteSegmentBuilder for chaining.

See also

bit_insert(): Insert raw bytes at an offset. QueryBinBuilder.bit_get(): Read bits in a query.

bit_insert(byte_offset, value, policy=None)[source]¶

Insert value (bytes) at a byte offset in the blob bin.

Example::: await session.update(key).bin(“blob”).bit_insert(0, b”x01x02”).execute()

Parameters:

byte_offset (int) – Byte position at which to insert.
value (Any) – Bytes to insert.
policy (Optional[Any]) – Optional BitPolicy; None selects a default policy.

Return type:

WriteSegmentBuilder

Returns:

The parent WriteSegmentBuilder for chaining.

See also

bit_remove(): Remove a byte range.

bit_remove(byte_offset, byte_size, policy=None)[source]¶

Remove byte_size bytes starting at byte_offset.

Example::: await session.update(key).bin(“blob”).bit_remove(0, 2).execute()

Parameters:

byte_offset (int) – Start of the range to remove.
byte_size (int) – Number of bytes to remove.
policy (Optional[Any]) – Optional BitPolicy; None selects a default policy.

Return type:

WriteSegmentBuilder

Returns:

The parent WriteSegmentBuilder for chaining.

See also

bit_insert(): Insert bytes at an offset.

bit_set(bit_offset, bit_size, value, policy=None)[source]¶

Overwrite bit_size bits at bit_offset with value.

value is typically a small bytes object whose bits replace the range (see server documentation for encoding).

Example::: await session.update(key).bin(“blob”).bit_set(0, 8, b”xff”).execute()

Parameters:

bit_offset (int) – Starting bit index within the blob.
bit_size (int) – Width of the field in bits.
value (Any) – Bits to write (commonly bytes).
policy (Optional[Any]) – Optional BitPolicy; None selects a default policy.

Return type:

WriteSegmentBuilder

Returns:

The parent WriteSegmentBuilder for chaining.

See also

bit_get(): Read the same range in an operate or query. bit_or(), bit_xor(), bit_and(), bit_not()

bit_or(bit_offset, bit_size, value, policy=None)[source]¶

Bitwise OR value into the bit_size bits at bit_offset.

Example::: await session.update(key).bin(“blob”).bit_or(0, 8, b”x0f”).execute()

Parameters:

bit_offset (int) – Starting bit index.
bit_size (int) – Field width in bits.
value (Any) – Right-hand side of the OR (typically bytes).
policy (Optional[Any]) – Optional BitPolicy; None selects a default policy.

Return type:

WriteSegmentBuilder

Returns:

The parent WriteSegmentBuilder for chaining.

See also

bit_and() bit_xor() bit_not()

bit_xor(bit_offset, bit_size, value, policy=None)[source]¶

Bitwise XOR value into the bit_size bits at bit_offset.

Example::: await session.update(key).bin(“blob”).bit_xor(0, 8, b”xff”).execute()

Parameters:

bit_offset (int) – Starting bit index.
bit_size (int) – Field width in bits.
value (Any) – Right-hand side of the XOR (typically bytes).
policy (Optional[Any]) – Optional BitPolicy; None selects a default policy.

Return type:

WriteSegmentBuilder

Returns:

The parent WriteSegmentBuilder for chaining.

See also

bit_or() bit_and() bit_not()

bit_and(bit_offset, bit_size, value, policy=None)[source]¶

Bitwise AND value into the bit_size bits at bit_offset.

Example::: await session.update(key).bin(“blob”).bit_and(0, 8, b”xf0”).execute()

Parameters:

bit_offset (int) – Starting bit index.
bit_size (int) – Field width in bits.
value (Any) – Right-hand side of the AND (typically bytes).
policy (Optional[Any]) – Optional BitPolicy; None selects a default policy.

Return type:

WriteSegmentBuilder

Returns:

The parent WriteSegmentBuilder for chaining.

See also

bit_or() bit_xor() bit_not()

bit_not(bit_offset, bit_size, policy=None)[source]¶

Invert every bit in the range [bit_offset, bit_offset + bit_size).

Example::: await session.update(key).bin(“blob”).bit_not(0, 8).execute()

Parameters:

bit_offset (int) – Starting bit index.
bit_size (int) – Field width in bits.
policy (Optional[Any]) – Optional BitPolicy; None selects a default policy.

Return type:

WriteSegmentBuilder

Returns:

The parent WriteSegmentBuilder for chaining.

See also

bit_or() bit_xor() bit_and()

bit_lshift(bit_offset, bit_size, shift, policy=None)[source]¶

Left-shift the bit_size bits at bit_offset by shift bits.

Example::: await session.update(key).bin(“blob”).bit_lshift(0, 16, 2).execute()

Parameters:

bit_offset (int) – Starting bit index.
bit_size (int) – Field width in bits.
shift (int) – Number of bits to shift left.
policy (Optional[Any]) – Optional BitPolicy; None selects a default policy.

Return type:

WriteSegmentBuilder

Returns:

The parent WriteSegmentBuilder for chaining.

See also

bit_rshift()

bit_rshift(bit_offset, bit_size, shift, policy=None)[source]¶

Right-shift the bit_size bits at bit_offset by shift bits.

Example::: await session.update(key).bin(“blob”).bit_rshift(0, 16, 2).execute()

Parameters:

bit_offset (int) – Starting bit index.
bit_size (int) – Field width in bits.
shift (int) – Number of bits to shift right.
policy (Optional[Any]) – Optional BitPolicy; None selects a default policy.

Return type:

WriteSegmentBuilder

Returns:

The parent WriteSegmentBuilder for chaining.

See also

bit_lshift()

bit_add(bit_offset, bit_size, value, signed, action, policy=None)[source]¶

Add value to the integer encoded in bit_size bits at bit_offset.

action selects overflow behavior (for example WRAP).

Example::: from aerospike_sdk import BitwiseOverflowActions await ( session.update(key) .bin(“blob”) .bit_add(0, 16, 1, False, BitwiseOverflowActions.WRAP) .execute() )

Parameters:

bit_offset (int) – Starting bit index of the integer field.
bit_size (int) – Width of the integer in bits.
value (int) – Amount to add.
signed (bool) – True if the stored integer is signed.
action (Any) – Overflow policy (BitwiseOverflowActions).
policy (Optional[Any]) – Optional BitPolicy; None selects a default policy.

Return type:

WriteSegmentBuilder

Returns:

The parent WriteSegmentBuilder for chaining.

bit_subtract(bit_offset, bit_size, value, signed, action, policy=None)[source]¶

Subtract value from the integer in bit_size bits at bit_offset.

Example::: from aerospike_sdk import BitwiseOverflowActions await ( session.update(key) .bin(“blob”) .bit_subtract(0, 16, 1, False, BitwiseOverflowActions.SATURATE) .execute() )

Parameters:

bit_offset (int) – Starting bit index of the integer field.
bit_size (int) – Width of the integer in bits.
value (int) – Amount to subtract.
signed (bool) – True if the stored integer is signed.
action (Any) – Overflow policy (BitwiseOverflowActions).
policy (Optional[Any]) – Optional BitPolicy; None selects a default policy.

Return type:

WriteSegmentBuilder

Returns:

The parent WriteSegmentBuilder for chaining.

See also

bit_add() bit_set_int()

bit_set_int(bit_offset, bit_size, value, policy=None)[source]¶

Write integer value into bit_size bits at bit_offset.

Example::: await session.update(key).bin(“blob”).bit_set_int(0, 16, 42).execute()

Parameters:

bit_offset (int) – Starting bit index.
bit_size (int) – Width of the integer in bits.
value (int) – Integer to store.
policy (Optional[Any]) – Optional BitPolicy; None selects a default policy.

Return type:

WriteSegmentBuilder

Returns:

The parent WriteSegmentBuilder for chaining.

See also

bit_get_int() bit_add()

bit_get(bit_offset, bit_size)[source]¶

Read bit_size bits at bit_offset as raw bytes in a write operate.

For read-only access, use QueryBinBuilder.bit_get().

Example::: await session.update(key).bin(“blob”).bit_get(0, 8).execute()

Parameters:

bit_offset (int) – Starting bit index.
bit_size (int) – Number of bits to read.

Return type:

WriteSegmentBuilder

Returns:

The parent WriteSegmentBuilder for chaining.

See also

QueryBinBuilder.bit_get() bit_set()

bit_count(bit_offset, bit_size)[source]¶

Count bits set to 1 in bit_size bits starting at bit_offset.

Example::: await session.update(key).bin(“blob”).bit_count(0, 8).execute()

Parameters:

bit_offset (int) – Starting bit index.
bit_size (int) – Number of bits to scan.

Return type:

WriteSegmentBuilder

Returns:

The parent WriteSegmentBuilder for chaining.

See also

QueryBinBuilder.bit_count()

bit_lscan(bit_offset, bit_size, value)[source]¶

Return the leftmost bit index in the range matching value.

value is True to search for a set bit (1) or False for an unset bit (0).

Example::: await session.update(key).bin(“blob”).bit_lscan(0, 8, True).execute()

Parameters:

bit_offset (int) – Starting bit index.
bit_size (int) – Number of bits to scan.
value (bool) – True for set bits, False for unset bits.

Return type:

WriteSegmentBuilder

Returns:

The parent WriteSegmentBuilder for chaining.

bit_rscan(bit_offset, bit_size, value)[source]¶

Return the rightmost bit index in the range matching value.

Example::: await session.update(key).bin(“blob”).bit_rscan(0, 8, False).execute()

Parameters:

bit_offset (int) – Starting bit index.
bit_size (int) – Number of bits to scan.
value (bool) – True for set bits, False for unset bits.

Return type:

WriteSegmentBuilder

Returns:

The parent WriteSegmentBuilder for chaining.

bit_get_int(bit_offset, bit_size, signed)[source]¶

Decode an integer from bit_size bits at bit_offset.

Example::: await session.update(key).bin(“blob”).bit_get_int(0, 16, False).execute()

Parameters:

bit_offset (int) – Starting bit index.
bit_size (int) – Width of the integer in bits.
signed (bool) – True to interpret as two’s-complement signed.

Return type:

WriteSegmentBuilder

Returns:

The parent WriteSegmentBuilder for chaining.

select_from(expression, *, ignore_eval_failure=False)[source]¶

Read a computed value into this bin using an AEL expression.

Return type:: WriteSegmentBuilder

insert_from(expression, *, ignore_op_failure=False, ignore_eval_failure=False, delete_if_null=False)[source]¶

Write expression result only if bin does not already exist.

Return type:: WriteSegmentBuilder

update_from(expression, *, ignore_op_failure=False, ignore_eval_failure=False, delete_if_null=False)[source]¶

Write expression result only if bin already exists.

Return type:: WriteSegmentBuilder

upsert_from(expression, *, ignore_op_failure=False, ignore_eval_failure=False, delete_if_null=False)[source]¶

Write expression result, creating or overwriting the bin.

Return type:: WriteSegmentBuilder

on_map_index(index)[source]¶

Navigate to a map element by index.

Parameters:: index (int) – List index (0-based, negative counts from end).
Return type:: CdtWriteBuilder[WriteSegmentBuilder]
Returns:: CdtWriteBuilder for writing the targeted element(s).

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

Navigate to 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:

CdtWriteBuilder[WriteSegmentBuilder]

Returns:

CdtWriteBuilder for writing the targeted element(s).

on_map_rank(rank)[source]¶

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

Return type:: CdtWriteBuilder[WriteSegmentBuilder]

on_map_value(value)[source]¶

Navigate to map elements matching a value.

Parameters:: value (Any) – Value to match.
Return type:: CdtWriteInvertableBuilder[WriteSegmentBuilder]
Returns:: CdtWriteInvertableBuilder for writing the targeted element(s).

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

Navigate to map elements by index range.

Parameters:

index (int) – List index (0-based, negative counts from end).
count (Optional[int]) – Maximum entries to select; None for all remaining.

Return type:

CdtWriteInvertableBuilder[WriteSegmentBuilder]

Returns:

CdtWriteInvertableBuilder for writing the targeted element(s).

on_map_key_range(start, end)[source]¶

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

Parameters:

start (Any) – Inclusive range start.
end (Any) – Exclusive range end.

Return type:

CdtWriteInvertableBuilder[WriteSegmentBuilder]

Returns:

CdtWriteInvertableBuilder for writing the targeted element(s).

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

Navigate to map elements by rank range.

Parameters:

rank (int) – Rank position (0 = lowest value).
count (Optional[int]) – Maximum entries to select; None for all remaining.

Return type:

CdtWriteInvertableBuilder[WriteSegmentBuilder]

Returns:

CdtWriteInvertableBuilder for writing the targeted element(s).

on_map_value_range(start, end)[source]¶

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

Parameters:

start (Any) – Inclusive range start.
end (Any) – Exclusive range end.

Return type:

CdtWriteInvertableBuilder[WriteSegmentBuilder]

Returns:

CdtWriteInvertableBuilder for writing the targeted element(s).

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

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

Parameters:

key (Any) – Map key to target.
index (int) – Index offset from the anchor key.
count (Optional[int]) – Maximum entries to select; None for all remaining.

Return type:

CdtWriteInvertableBuilder[WriteSegmentBuilder]

Returns:

CdtWriteInvertableBuilder for writing the targeted element(s).

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

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

Parameters:

value (Any) – Value to match.
rank (int) – Rank offset from the anchor value.
count (Optional[int]) – Maximum entries to select; None for all remaining.

Return type:

CdtWriteInvertableBuilder[WriteSegmentBuilder]

Returns:

CdtWriteInvertableBuilder for writing the targeted element(s).

on_map_key_list(keys)[source]¶

Navigate to map elements matching a list of keys.

Parameters:: keys (List[Any]) – Map keys to match.
Return type:: CdtWriteInvertableBuilder[WriteSegmentBuilder]
Returns:: CdtWriteInvertableBuilder for writing the targeted element(s).

on_map_value_list(values)[source]¶

Navigate to map elements matching a list of values.

Parameters:: values (List[Any]) – Values to match.
Return type:: CdtWriteInvertableBuilder[WriteSegmentBuilder]
Returns:: CdtWriteInvertableBuilder for writing the targeted element(s).

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

Navigate to 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:

CdtWriteBuilder[WriteSegmentBuilder]

Returns:

CdtWriteBuilder for writing the targeted element(s).

Example::: .bin(“items”).on_list_index(0).set_to(“first”)

on_list_rank(rank)[source]¶

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

Parameters:: rank (int) – Rank position (0 = lowest value).
Return type:: CdtWriteBuilder[WriteSegmentBuilder]
Returns:: CdtWriteBuilder for writing the targeted element(s).

on_list_value(value)[source]¶

Navigate to list elements matching a value.

Parameters:: value (Any) – Value to match.
Return type:: CdtWriteInvertableBuilder[WriteSegmentBuilder]
Returns:: CdtWriteInvertableBuilder for writing the targeted element(s).

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

Navigate to list elements by index range.

Parameters:

index (int) – List index (0-based, negative counts from end).
count (Optional[int]) – Maximum entries to select; None for all remaining.

Return type:

CdtWriteInvertableBuilder[WriteSegmentBuilder]

Returns:

CdtWriteInvertableBuilder for writing the targeted element(s).

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

Navigate to list elements by rank range.

Parameters:

rank (int) – Rank position (0 = lowest value).
count (Optional[int]) – Maximum entries to select; None for all remaining.

Return type:

CdtWriteInvertableBuilder[WriteSegmentBuilder]

Returns:

CdtWriteInvertableBuilder for writing the targeted element(s).

on_list_value_range(start, end)[source]¶

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

Parameters:

start (Any) – Inclusive range start.
end (Any) – Exclusive range end.

Return type:

CdtWriteInvertableBuilder[WriteSegmentBuilder]

Returns:

CdtWriteInvertableBuilder for writing the targeted element(s).

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

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

Parameters:

value (Any) – Value to match.
rank (int) – Rank offset from the anchor value.
count (Optional[int]) – Maximum entries to select; None for all remaining.

Return type:

CdtWriteInvertableBuilder[WriteSegmentBuilder]

Returns:

CdtWriteInvertableBuilder for writing the targeted element(s).

on_list_value_list(values)[source]¶

Navigate to list elements matching a list of values.

Parameters:: values (List[Any]) – Values to match.
Return type:: CdtWriteInvertableBuilder[WriteSegmentBuilder]
Returns:: CdtWriteInvertableBuilder for writing the targeted element(s).

bin(bin_name)[source]¶

Start the next bin operation without leaving the write segment.

Return type:: WriteBinBuilder

query(arg1, *more_keys)[source]¶

Shortcut: finalize write segment and start a read segment.

Return type:: QueryBuilder

async execute(on_error=None)[source]¶

Shortcut: execute all accumulated specs.

Return type:: RecordStream

class aerospike_sdk.aio.operations.query.QueryBinBuilder[source]¶

Bases: _WriteVerbs, Generic[_T]

Per-bin reads and CDT navigation for QueryBuilder (and sync twin).

The type parameter is the parent builder type; the parent must implement add_operation. Use get() for whole-bin reads, select_from() for expression reads, on_map_* / on_list_* for paths, hll_* / bit_* for HyperLogLog and blob bit reads, then QueryBuilder.execute(). Write verbs delegate to the parent to chain writes after reads.

Example

Read map keys and list size in a single query:

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

See also

WriteBinBuilder: Per-bin write builder. CdtReadBuilder: Nested reads.

__init__(parent, bin_name)[source]¶

get()[source]¶

Include the bin value in the read result.

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

See also

select_from(): Virtual bin from an expression.

map_size()[source]¶

Return the number of entries in the map.

Return type:: TypeVar(_T)

list_size()[source]¶

Read list length into the operate/read result.

Return type:: TypeVar(_T)

list_get(index)[source]¶

Read the list element at index into the query result.

Parameters:: index (int) – List index (0-based; negative counts from the end).
Return type:: TypeVar(_T)
Returns:: The parent builder for chaining.

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

Read a contiguous slice of the list starting at index.

Parameters:

index (int) – Starting list index.
count (Optional[int]) – Number of elements; None reads through the end.

Return type:

TypeVar(_T)

Returns:

The parent builder for chaining.

See also

list_get()

hll_get_count()[source]¶

Read the estimated HyperLogLog cardinality for this bin.

The estimate appears under this bin’s name in the record returned from QueryBuilder.execute(). To read during a multi-op write, use WriteBinBuilder.hll_get_count().

Example::: stream = await session.query(key).bin(“visitors”).hll_get_count().execute()

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

hll_describe()[source]¶

Read index and min-hash bit parameters describing the stored sketch.

Example::: stream = await session.query(key).bin(“visitors”).hll_describe().execute()

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

See also

WriteBinBuilder.hll_describe()

hll_get_union(hll_list)[source]¶

Read the union sketch of this bin and hll_list without updating storage.

Example::: stream = await ( session.query(key).bin(“hll”).hll_get_union([peer_blob]).execute() )

Parameters:: hll_list (Sequence[Any]) – Other HLL blobs to include in the union result.
Return type:: TypeVar(_T)
Returns:: The parent query builder for chaining.

hll_get_union_count(hll_list)[source]¶

Read the estimated cardinality of the union with other sketches.

Example::: stream = await ( session.query(key).bin(“hll”).hll_get_union_count([peer_blob]).execute() )

Parameters:: hll_list (Sequence[Any]) – Other sketches included in the union estimate.
Return type:: TypeVar(_T)
Returns:: The parent query builder for chaining.

hll_get_intersect_count(hll_list)[source]¶

Read the estimated intersection cardinality with other sketches.

Example::: stream = await ( session.query(key) .bin(“hll”) .hll_get_intersect_count([peer_blob]) .execute() )

Parameters:: hll_list (Sequence[Any]) – Other sketches included in the intersection estimate.
Return type:: TypeVar(_T)
Returns:: The parent query builder for chaining.

hll_get_similarity(hll_list)[source]¶

Read Jaccard similarity between this sketch and other sketches.

Example::: stream = await ( session.query(key).bin(“hll”).hll_get_similarity([peer_blob]).execute() )

Parameters:: hll_list (Sequence[Any]) – Other sketches to compare.
Return type:: TypeVar(_T)
Returns:: The parent query builder for chaining.

See also

WriteBinBuilder.hll_get_similarity()

bit_get(bit_offset, bit_size)[source]¶

Read bit_size bits at bit_offset as raw bytes.

Example::: stream = await session.query(key).bin(“blob”).bit_get(0, 8).execute()

Parameters:

bit_offset (int) – Starting bit index.
bit_size (int) – Number of bits to read.

Return type:

TypeVar(_T)

Returns:

The parent query builder for chaining.

bit_count(bit_offset, bit_size)[source]¶

Count bits set to 1 in the given range.

Example::: stream = await session.query(key).bin(“blob”).bit_count(0, 8).execute()

Parameters:

bit_offset (int) – Starting bit index.
bit_size (int) – Number of bits to scan.

Return type:

TypeVar(_T)

Returns:

The parent query builder for chaining.

See also

WriteBinBuilder.bit_count()

bit_lscan(bit_offset, bit_size, value)[source]¶

Scan from the left for the first set (True) or unset (False) bit.

Example::: stream = await session.query(key).bin(“blob”).bit_lscan(0, 8, True).execute()

Parameters:

bit_offset (int) – Starting bit index.
bit_size (int) – Number of bits to scan.
value (bool) – True to find a 1 bit, False to find a 0 bit.

Return type:

TypeVar(_T)

Returns:

The parent query builder for chaining.

bit_rscan(bit_offset, bit_size, value)[source]¶

Scan from the right for the first set (True) or unset (False) bit.

Example::: stream = await session.query(key).bin(“blob”).bit_rscan(0, 8, False).execute()

Parameters:

bit_offset (int) – Starting bit index.
bit_size (int) – Number of bits to scan.
value (bool) – True to find a 1 bit, False to find a 0 bit.

Return type:

TypeVar(_T)

Returns:

The parent query builder for chaining.

bit_get_int(bit_offset, bit_size, signed)[source]¶

Decode an integer from bit_size bits at bit_offset.

Example::: stream = await ( session.query(key).bin(“blob”).bit_get_int(0, 16, False).execute() )

Parameters:

bit_offset (int) – Starting bit index.
bit_size (int) – Width of the integer in bits.
signed (bool) – True for two’s-complement signed decoding.

Return type:

TypeVar(_T)

Returns:

The parent query builder for chaining.

select_from(expression, *, ignore_eval_failure=False)[source]¶

Read a computed value into this bin using an AEL expression.

The result appears as a virtual bin in the returned record.

Parameters:

expression (Union[str, FilterExpression]) – AEL string or pre-built FilterExpression.
ignore_eval_failure (bool) – If True, silently return None when the expression cannot be evaluated (e.g. missing bin).

Return type:

TypeVar(_T)

Returns:

The parent builder for method chaining.

on_map_index(index)[source]¶

Navigate to a map element by index.

Parameters:: index (int) – List index (0-based, negative counts from end).
Return type:: CdtReadBuilder[TypeVar(_T)]
Returns:: CdtReadBuilder for reading the targeted element(s).

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

Navigate to 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(s).

on_map_rank(rank)[source]¶

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

Return type:: CdtReadBuilder[TypeVar(_T)]

on_map_value(value)[source]¶

Navigate to map elements matching a value.

Return type:: CdtReadInvertableBuilder[TypeVar(_T)]

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

Navigate to map elements by index range.

Return type:: CdtReadInvertableBuilder[TypeVar(_T)]

on_map_key_range(start, end)[source]¶

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

Return type:: CdtReadInvertableBuilder[TypeVar(_T)]

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

Navigate to map elements by rank range.

Return type:: CdtReadInvertableBuilder[TypeVar(_T)]

on_map_value_range(start, end)[source]¶

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

Return type:: CdtReadInvertableBuilder[TypeVar(_T)]

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

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

Parameters:

key (Any) – Map key to target.
index (int) – List index (0-based, negative counts from end).
count (Optional[int]) – Maximum entries to select; None for all remaining.

Return type:

CdtReadInvertableBuilder[TypeVar(_T)]

Returns:

CdtReadInvertableBuilder for reading the targeted element(s).

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

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

Return type:: CdtReadInvertableBuilder[TypeVar(_T)]

on_map_key_list(keys)[source]¶

Navigate to map elements matching a list of keys.

Return type:: CdtReadInvertableBuilder[TypeVar(_T)]

on_map_value_list(values)[source]¶

Navigate to map elements matching a list of values.

Return type:: CdtReadInvertableBuilder[TypeVar(_T)]

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

Navigate to a list element by index.

Parameters:

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)]

Example::: .bin(“items”).on_list_index(-1).get_values()

on_list_rank(rank)[source]¶

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

Return type:: CdtReadBuilder[TypeVar(_T)]

on_list_value(value)[source]¶

Navigate to list elements matching a value.

Return type:: CdtReadInvertableBuilder[TypeVar(_T)]

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

Navigate to list elements by index range.

Return type:: CdtReadInvertableBuilder[TypeVar(_T)]

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

Navigate to list elements by rank range.

Return type:: CdtReadInvertableBuilder[TypeVar(_T)]

on_list_value_range(start, end)[source]¶

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

Return type:: CdtReadInvertableBuilder[TypeVar(_T)]

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

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

Return type:: CdtReadInvertableBuilder[TypeVar(_T)]

on_list_value_list(values)[source]¶

Navigate to list elements matching a list of values.

Return type:: CdtReadInvertableBuilder[TypeVar(_T)]