Sync Query Builders¶

Synchronous query and write-verb builders delegating to aio.operations.query.

class aerospike_sdk.sync.operations.query.SyncQueryBuilder[source]¶

Bases: _SyncWriteVerbs

Configure and run reads, queries, and write segments synchronously.

Every chain method forwards to QueryBuilder. execute() blocks on the owning loop manager and returns SyncRecordStream. Detailed parameter semantics (filters, policies, CDT, on_error) are documented on the async builder.

See also

QueryBuilder

__init__(async_client, namespace, set_name, loop_manager, query_builder=None)[source]¶: Attach or create an async QueryBuilder and the sync loop.

bins(bin_names)[source]¶

Specify which bins to retrieve.

Return type:: SyncQueryBuilder

bin(bin_name)[source]¶

Start a bin-level read operation.

Return type:: QueryBinBuilder[SyncQueryBuilder]

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.

Return type:: SyncQueryBuilder

with_no_bins()[source]¶

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

Return type:: SyncQueryBuilder

filter(filter_obj)[source]¶

Add a filter to the query.

Return type:: SyncQueryBuilder

filter_expression(expression)[source]¶

Set a FilterExpression for server-side filtering.

Return type:: SyncQueryBuilder

where(expression)[source]¶

Overloads:

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

Set the query filter from an AEL string or FilterExpression.

with_policy(policy)[source]¶

Set the query policy.

Return type:: SyncQueryBuilder

with_read_policy(policy)[source]¶

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

Return type:: SyncQueryBuilder

partition(partition_filter)[source]¶

Set the partition filter.

Return type:: SyncQueryBuilder

on_partitions(*partition_ids)[source]¶

Set partitions to query by partition IDs.

Return type:: SyncQueryBuilder

on_partition(part_id)[source]¶

Target a specific partition for the query.

Return type:: SyncQueryBuilder

on_partition_range(start_incl, end_excl)[source]¶

Target a range of partitions for the query.

Return type:: SyncQueryBuilder

chunk_size(chunk_size)[source]¶

Set the chunk size for server-side streaming.

Return type:: SyncQueryBuilder

records_per_second(rps)[source]¶

Set the maximum records per second for the query.

Return type:: SyncQueryBuilder

max_records(max_records)[source]¶

Set the maximum number of records to return.

Return type:: SyncQueryBuilder

limit(limit)[source]¶

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

Return type:: SyncQueryBuilder

expected_duration(duration)[source]¶

Set the expected duration of the query.

Return type:: SyncQueryBuilder

with_hint(hint)[source]¶

Attach a query hint for secondary index selection or scheduling.

Forwards to with_hint().

Parameters:: hint (QueryHint) – A QueryHint instance.
Return type:: SyncQueryBuilder
Returns:: This builder for method chaining.

See also

QueryHint

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 in the background.

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

replica(replica)[source]¶

Set the replica preference for the query.

Return type:: SyncQueryBuilder

base_policy(base_policy)[source]¶

Set the base policy for the query.

Return type:: SyncQueryBuilder

fail_on_filtered_out()[source]¶

Include filtered-out records in the stream with FILTERED_OUT code.

Return type:: SyncQueryBuilder

respond_all_keys()[source]¶

Return null for missing keys instead of omitting them.

Return type:: SyncQueryBuilder

default_where(expression)[source]¶

Overloads:

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

Set a default filter for all chained operations that lack their own.

default_expire_record_after_seconds(seconds)[source]¶

Set a default TTL for all chained operations that lack their own.

Return type:: SyncQueryBuilder

default_never_expire()[source]¶

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

Return type:: SyncQueryBuilder

default_with_no_change_in_expiration()[source]¶

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

Return type:: SyncQueryBuilder

default_expiry_from_server_default()[source]¶

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

Return type:: SyncQueryBuilder

query(arg1, *more_keys)[source]¶

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

Return type:: SyncQueryBuilder

execute_background_task()[source]¶

Run a background write for this dataset query (see QueryBuilder).

Return type:: ExecuteTask

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

Run a background UDF for this dataset query (see QueryBuilder).

Return type:: ExecuteTask

execute(on_error=None)[source]¶

Run the configured query or write chain and block until the stream is ready.

Parameters:: on_error (Union[ErrorStrategy, Callable[[Key, int, AerospikeError], None], None]) – Same as execute() (ErrorStrategy or callback).
Return type:: SyncRecordStream
Returns:: SyncRecordStream.

See also

execute()

class aerospike_sdk.sync.operations.query.SyncWriteSegmentBuilder[source]¶

Bases: _SyncWriteVerbs

Synchronous multi-key write segment (mirrors WriteSegmentBuilder).

Bin scalars, CDT, expressions, and policies delegate to the embedded async segment; execute() returns SyncRecordStream.

See also

WriteSegmentBuilder

__init__(wsb, loop_manager)[source]¶

bin(bin_name)[source]¶

Start a bin-level write operation.

Return type:: SyncWriteBinBuilder

add_operation(op)[source]¶

Append an operation (used by CDT action builders).

Return type:: None

put(bins)[source]¶

Set multiple bins at once.

Return type:: SyncWriteSegmentBuilder

set_bins(bins)[source]¶

Alias for put().

Return type:: SyncWriteSegmentBuilder

set_to(bin_name, value)[source]¶

Set a bin to value.

Return type:: SyncWriteSegmentBuilder

add(bin_name, value)[source]¶

Add a numeric value to a bin.

Return type:: SyncWriteSegmentBuilder

increment_by(bin_name, value)[source]¶

Alias for add().

Return type:: SyncWriteSegmentBuilder

get(bin_name)[source]¶

Read a bin value back within a write operate.

Return type:: SyncWriteSegmentBuilder

append(bin_name, value)[source]¶

Append a string to a bin.

Return type:: SyncWriteSegmentBuilder

prepend(bin_name, value)[source]¶

Prepend a string to a bin.

Return type:: SyncWriteSegmentBuilder

remove_bin(bin_name)[source]¶

Delete a bin from the record.

Return type:: SyncWriteSegmentBuilder

delete_record()[source]¶

Add a record-level delete to the current operate call.

Unlike delete() which targets a different key, this deletes the record being operated on as part of the same atomic operation.

Example:

stream = (
    session.upsert(key)
        .bin("name").get()
        .delete_record()
        .execute()
)

Return type:: SyncWriteSegmentBuilder
Returns:: This segment for chaining.

See also

delete(): Start a new delete segment for a key.

touch_record()[source]¶

Add a record-level touch to the current operate call.

Resets the record’s TTL as part of an atomic multi-operation call. Combine with expire_record_after_seconds() to set a new TTL.

Example:

stream = (
    session.upsert(key)
        .bin("score").get()
        .touch_record()
        .expire_record_after_seconds(120)
        .execute()
)

Return type:: SyncWriteSegmentBuilder
Returns:: This segment for chaining.

See also

touch(): Start a new touch segment for a key.

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

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

Return type:: SyncWriteSegmentBuilder

insert_from(bin_name, 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:: SyncWriteSegmentBuilder

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

Write expression result only if bin already exists.

Return type:: SyncWriteSegmentBuilder

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

Write expression result, creating or overwriting the bin.

Return type:: SyncWriteSegmentBuilder

query(arg1, *more_keys)[source]¶

Finalize current write segment and start a read segment.

Return type:: SyncQueryBuilder

where(expression)[source]¶

Set a filter expression on the current write segment.

Return type:: SyncWriteSegmentBuilder

expire_record_after_seconds(seconds)[source]¶

Set the TTL on the current write segment.

Return type:: SyncWriteSegmentBuilder

never_expire()[source]¶

Set this record to never expire (TTL = -1).

Return type:: SyncWriteSegmentBuilder

with_no_change_in_expiration()[source]¶

Preserve the record’s existing TTL (TTL = -2).

Return type:: SyncWriteSegmentBuilder

expiry_from_server_default()[source]¶

Use the namespace’s default TTL for this record (TTL = 0).

Return type:: SyncWriteSegmentBuilder

ensure_generation_is(generation)[source]¶

Set expected generation for optimistic locking.

Return type:: SyncWriteSegmentBuilder

durably_delete()[source]¶

Enable durable delete on the current segment.

Return type:: SyncWriteSegmentBuilder

respond_all_keys()[source]¶

Include results for missing keys in the stream.

Return type:: SyncWriteSegmentBuilder

fail_on_filtered_out()[source]¶

Mark filtered-out records with FILTERED_OUT result code.

Return type:: SyncWriteSegmentBuilder

replace_only()[source]¶

Change the current segment to replace-if-exists semantics.

Return type:: SyncWriteSegmentBuilder

execute(on_error=None)[source]¶

Flush accumulated write operations and return a synchronous result stream.

Parameters:: on_error (Union[ErrorStrategy, Callable[[Key, int, AerospikeError], None], None]) – Same as SyncQueryBuilder.execute().
Return type:: SyncRecordStream
Returns:: SyncRecordStream.

See also

execute()

class aerospike_sdk.sync.operations.query.SyncWriteBinBuilder[source]¶

Bases: _SyncWriteVerbs

Synchronous wrapper for bin-level write operations.

Per-bin write builder that captures a bin name and delegates all operations to the parent SyncWriteSegmentBuilder. HyperLogLog and blob bit operations use hll_* and bit_* methods, matching WriteBinBuilder.

__init__(sync_segment, bin_name)[source]¶

set_to(value)[source]¶

Set the bin to value.

Parameters:: value (Any) – New value to store.
Return type:: SyncWriteSegmentBuilder
Returns:: The parent SyncWriteSegmentBuilder.

add(value)[source]¶

Add a numeric value to the bin.

Parameters:: value (Any) – Numeric value to add.
Return type:: SyncWriteSegmentBuilder
Returns:: The parent SyncWriteSegmentBuilder.

increment_by(value)[source]¶

Alias for add().

Parameters:: value (Any) – Numeric value to add.
Return type:: SyncWriteSegmentBuilder
Returns:: The parent SyncWriteSegmentBuilder.

append(value)[source]¶

Append a string to the bin.

Parameters:: value (str) – String to append.
Return type:: SyncWriteSegmentBuilder
Returns:: The parent SyncWriteSegmentBuilder.

prepend(value)[source]¶

Prepend a string to the bin.

Parameters:: value (str) – String to prepend.
Return type:: SyncWriteSegmentBuilder
Returns:: The parent SyncWriteSegmentBuilder.

remove()[source]¶

Delete the bin from the record.

Return type:: SyncWriteSegmentBuilder
Returns:: The parent SyncWriteSegmentBuilder.

get()[source]¶

Read the bin value back within a write operate.

Return type:: SyncWriteSegmentBuilder
Returns:: The parent SyncWriteSegmentBuilder.

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

Add value to an ordered list (sorted insert).

Parameters:

value (Any) – Value 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: