Sync Query Builders¶

Synchronous query and write-segment builders.

Each sync class inherits state, chaining methods, and the blocking-IO dispatchers from the corresponding _*Base in aerospike_sdk.aio.operations.query. Concrete sync subclasses add sync execute() (Tier 1 / 1b / 2 dispatch) and override factory overrides (_start_write_verb, _promote) so chained types stay in the sync namespace.

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

Bases: _QueryBuilderBase, _WriteVerbs

Synchronous query builder.

Inherits state + chaining + blocking-IO dispatchers from _QueryBuilderBase. Provides sync execute() that routes through Tier 1 (fast path / multi-key list dispatch), Tier 1b (multi-spec blocking dispatch), or Tier 2 (dataset / SI / scan streaming) using PAC _blocking entries. No asyncio loop involved.

bin(bin_name)[source]¶

Open a per-bin read builder targeting this query builder.

Return type:: QueryBinBuilder[SyncQueryBuilder]

execute_background_task()[source]¶

Run a background write for this dataset query (synchronous).

Return type:: ExecuteTask

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

Run a background UDF for this dataset query (synchronous).

Return type:: ExecuteTask

execute(on_error=None)[source]¶

Run the configured query/write chain synchronously.

Tier 1: single-key + multi-key + all op-types (returns list). Tier 1b: multi-spec sequential dispatch via PAC batch_blocking. Tier 2: dataset / SI / scan streams (returns Recordset; lazy).

Return type:: SyncRecordStream

__init__(client, namespace, set_name, behavior=None, indexes_monitor=None, cached_read_policy=None, cached_write_policy=None, cached_read_policy_sc=None, cached_write_policy_sc=None, txn=None, namespace_mode_resolver=None, namespace_mode_resolver_blocking=None)¶

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.
namespace_mode_resolver (Optional[Callable[[str], Awaitable[Mode]]]) – Optional async callable namespace -> Mode used to apply AP vs SC behavior scopes before policies are built. Session-scoped builders supply this; client-only builders omit it.
namespace_mode_resolver_blocking (Optional[Callable[[str], Mode]]) – Sync counterpart used by execute_blocking() (the sync path bypassing asyncio).

add_operation(op)¶

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

Return type:: None

base_policy(base_policy)¶

Set the base policy for the query.

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

Example:

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

bins(bin_names)¶

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:: Self
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).

chunk_size(chunk_size)¶

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:: Self
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.

default_expire_record_after_seconds(seconds)¶

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:: Self
Returns:: self for method chaining.
Raises:: ValueError – If seconds is <= 0.

default_expiry_from_server_default()¶

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

Return type:: Self

default_never_expire()¶

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

Return type:: Self

default_where(expression)¶

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_with_no_change_in_expiration()¶

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

Return type:: Self

delete(arg1, *more_keys)¶

Open a delete segment.

Example::: await session.delete(key).execute()

Return type:: WriteSegmentBuilder
Returns:: WriteSegmentBuilder (often followed immediately by execute()).

execute_background_task_blocking()¶

Sync counterpart of execute_background_task().

Uses PAC query_operate_blocking — zero asyncio.

Return type:: ExecuteTask

execute_blocking_fast_path(on_error=None)¶

Try a blocking dispatch path; fall back to async when ineligible.

Handled shapes:

Single key, single spec — routes through _execute_single_key_direct_blocking() (PAC get_blocking / operate_blocking). Honors filter expressions, generation / TTL / durable-delete overrides, and record-delete ops via _make_read_policy() / _make_write_policy(). Caller-supplied on_error still falls back to the async path (handler dispositions on single-key land in Phase 2b).
Multi-key plain read, single spec — routes through _execute_batch_read_blocking() (PAC batch_read_blocking). Honors filter expressions via _make_batch_read_policy() and the resolved disposition (THROW / IN_STREAM / HANDLER).

Return type:: Optional[List[RecordResult]]
Returns:: A list of RecordResult on a hit. None when the spec shape isn’t yet handled by the blocking dispatch (delete / touch / exists / udf single-key ops, multi-key with per-key operate, dataset / SI queries, scans, UDF background — caller falls back to the async path).

execute_blocking_stream(on_error=None)¶

Dataset/SI/scan blocking dispatch returning a streaming source.

For keyless query shapes (session.query(dataset) or session.query(namespace, set_name)), build the policy + statement synchronously and call PAC query_blocking. Returns the raw Recordset (Python iterator that blocks per record) so the caller can wrap it in SyncRecordStream without materializing — memory stays bounded for arbitrarily large result sets.

Return type:: Optional[tuple]
Returns:: (kind, payload) where kind is "recordset" for non-chunked or "chunked" for chunk-resumable queries. The payload for "recordset" is the PAC Recordset; for "chunked" it is (recordset, reexecute_callable). Returns None when the spec shape isn’t a keyless dataset query (caller falls back).

execute_multispec_blocking(on_error=None)¶

Multi-spec blocking dispatch.

For builders that ended up with more than one _OperationSpec (chained queries), routes through either:

Sequential: when _specs_require_sequential_run() is true (e.g. any UDF spec), per-spec dispatch via _execute_spec_blocking(), results concatenated.
Mixed batch: combine all per-spec ops into a single PAC batch_blocking call.

Return type:: Optional[List[RecordResult]]
Returns:: Concatenated list of RecordResult on success. None when the builder has 0 or 1 specs (caller falls back — single-spec handled by execute_blocking_fast_path()).

execute_udf_background_task_blocking(package_name, function_name, args=None)¶

Sync counterpart of execute_udf_background_task().

Uses PAC query_execute_udf_blocking — zero asyncio.

Return type:: ExecuteTask

exists(arg1, *more_keys)¶

Open an exists-check segment.

Example::: stream = await session.exists(key).execute() found = (await stream.first_or_raise()).as_bool()

Return type:: WriteSegmentBuilder
Returns:: WriteSegmentBuilder.

expected_duration(duration)¶

Set the expected duration of the query.

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

Example:

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

fail_on_filtered_out()¶

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:: Self
Returns:: This builder for chaining.

See also

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

filter(filter_obj)¶

Add a secondary index filter to the query.

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

filter_expression(expression)¶

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:: Self
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()

insert(arg1, *more_keys)¶

Open a create-only segment (fails if the record exists).

Example::: await session.insert(key).put({“name”: “Ada”}).execute()

Return type:: WriteSegmentBuilder
Returns:: WriteSegmentBuilder for further bins and execute().

limit(limit)¶

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:: Self
Returns:: self for method chaining.
Raises:: ValueError – If limit is <= 0.

Example:

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

max_records(max_records)¶

Set the maximum number of records to return.

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

Example:

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

on_partition(part_id)¶

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:: Self
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)¶

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:

Self

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)

on_partitions(*partition_ids)¶

Set partitions to query by partition IDs.

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

Example:

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

partition(partition_filter)¶

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:: Self
Returns:: This builder for chaining.

See also

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

query(arg1, *more_keys)¶

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:

Self

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

records_per_second(rps)¶

Set the maximum records per second for the query.

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

Example:

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

replace(arg1, *more_keys)¶

Open a full replace segment (removes bins not written in this segment).

Example::: await session.replace(key).put({“a”: 1}).execute()

Return type:: WriteSegmentBuilder
Returns:: WriteSegmentBuilder.

replace_if_exists(arg1, *more_keys)¶

Open replace-if-exists semantics (like replace, but only if the record exists).

Example::: await session.replace_if_exists(key).put({“a”: 1}).execute()

Return type:: WriteSegmentBuilder
Returns:: WriteSegmentBuilder.

replica(replica)¶

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:: Self
Returns:: self for method chaining.

Example:

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

respond_all_keys()¶

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:: Self
Returns:: This builder for chaining.

See also

fail_on_filtered_out(): Filter mismatch vs missing key.

touch(arg1, *more_keys)¶

Open a touch segment (TTL refresh).

Example::: await session.touch(key).execute()

Return type:: WriteSegmentBuilder
Returns:: WriteSegmentBuilder.

update(arg1, *more_keys)¶

Open an update-only segment (fails if the record is missing).

Example::: await session.update(key).bin(“count”).add(1).execute()

Return type:: WriteSegmentBuilder
Returns:: WriteSegmentBuilder for further bins and execute().

upsert(arg1, *more_keys)¶

Open a create-or-update segment for the given key(s).

Example::: await session.upsert(key).put({“name”: “Bob”}).execute()

Return type:: WriteSegmentBuilder
Returns:: WriteSegmentBuilder for put / bin / execute.

See also

upsert(): Session entry point.

where(expression)¶

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_hint(hint)¶

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:: Self
Returns:: This builder for method chaining.
Raises:: ValueError – If with_hint has already been called on this builder.

See also

QueryHint

with_index_context(index_context)¶

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:: Self
Returns:: This builder for method chaining.

See also

IndexContext

with_no_bins()¶

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:: Self
Returns:: self for method chaining.
Raises:: ValueError – If used together with bins().

with_op_projection(*ops)¶

Project query results through one or more read operations.

The server applies ops to every matching record and returns the operation results in place of the configured bin set. Mutually exclusive with bins(): when a projection is set the server ignores the bin list. Subsequent calls replace the previous projection.

Server compatibility:

Servers older than 8.1.2 accept only the basic get_bin / get_header ops.
Server 8.1.2+ also accepts CDT, expression, bit, and HLL reads — for example CdtOperation.select_values("bin", [...]).

Parameters:: *ops (Any) – One or more native aerospike_async read operations.
Return type:: Self
Returns:: This builder for method chaining.

Example:

from aerospike_sdk import CTX, CdtOperation
stream = await (
    session.query(users)
        .with_op_projection(
            CdtOperation.select_values(
                "inventory", [CTX.map_key("books")]
            ),
        )
        .execute()
)

with_policy(policy)¶

Set the query policy.

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

with_read_policy(policy)¶

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

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

with_txn(txn)¶

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:: Self
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()

with_write_operations(operations)¶

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:: Self
Returns:: self for method chaining.

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

Bases: _WriteSegmentBuilderBase, _WriteVerbs

Synchronous write-segment builder.

Inherits state + chaining + execute_blocking_fast_path from _WriteSegmentBuilderBase. Provides sync execute() and overrides _start_write_verb so chained writes return SyncWriteSegmentBuilder.

query(arg1, *more_keys)[source]¶

Finalize this segment and open a fresh sync read query on new keys.

Return type:: SyncQueryBuilder

execute(on_error=None)[source]¶

Run the configured write segment synchronously.

Tries the inherited blocking fast path first; otherwise delegates to the wrapped query builder’s full dispatch.

Return type:: SyncRecordStream

__init__(qb)¶

add(bin_name, value)¶

Add a numeric value to a bin.

Return type:: Self

add_operation(op)¶

Append an operation (used by CDT action builders).

Return type:: None

append(bin_name, value)¶

Append a string to a bin.

Return type:: Self

bin(bin_name)¶

Start a bin-level write operation.

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

default_with_durable_delete()¶

Prefer durable deletes for this segment when resolving behavior defaults.

Return type:: Self

default_without_durable_delete()¶

Prefer non-durable deletes for this segment when resolving behavior defaults.

Return type:: Self

delete(arg1, *more_keys)¶

Open a delete segment.

Example::: await session.delete(key).execute()

Return type:: WriteSegmentBuilder
Returns:: WriteSegmentBuilder (often followed immediately by execute()).

delete_record()¶

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 = await (
    session.upsert(key)
        .bin("name").get()
        .delete_record()
        .execute()
)

See also

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

Return type:: Self

ensure_generation_is(generation)¶

Set expected generation for optimistic locking on the current segment.

Parameters:: generation (int) – The expected generation number (must be > 0).
Return type:: Self
Returns:: self for method chaining.
Raises:: ValueError – If generation is <= 0.

execute_blocking_fast_path(on_error=None)¶

Try the blocking single-key fast path via the parent query builder.

Mirrors execute() but uses PAC _blocking. Returns a list of RecordResult on success, None when the spec shape isn’t yet handled by the blocking dispatch. Raises a converted PAC exception on failure.

Return type:: Optional[List[Any]]

exists(arg1, *more_keys)¶

Open an exists-check segment.

Example::: stream = await session.exists(key).execute() found = (await stream.first_or_raise()).as_bool()

Return type:: WriteSegmentBuilder
Returns:: WriteSegmentBuilder.

expire_record_after_seconds(seconds)¶

Set the TTL on the current write segment.

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

expiry_from_server_default()¶

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

Return type:: Self

fail_on_filtered_out()¶

Mark filtered-out records with FILTERED_OUT result code.

Return type:: Self

get(bin_name)¶

Read a bin value back within a write operate.

Return type:: Self

increment_by(bin_name, value)¶

Alias for add().

Return type:: Self

insert(arg1, *more_keys)¶

Open a create-only segment (fails if the record exists).

Example::: await session.insert(key).put({“name”: “Ada”}).execute()

Return type:: WriteSegmentBuilder
Returns:: WriteSegmentBuilder for further bins and execute().

insert_from(bin_name, expression, *, ignore_op_failure=False, ignore_eval_failure=False, delete_if_null=False)¶

Write expression result only if bin does not already exist.

Return type:: Self

never_expire()¶

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

Return type:: Self

prepend(bin_name, value)¶

Prepend a string to a bin.

Return type:: Self

put(bins)¶

Apply Operation.put for each bin in the mapping.

Parameters:: bins (dict) – Map of bin name to value.
Return type:: Self

Example::: await session.upsert(key).put({“email”: “a@b.com”, “age”: 30}).execute()

See also

bin(): Per-bin CDT or scalar follow-ups.

remove_bin(bin_name)¶

Delete a bin from the record.

Return type:: Self

replace(arg1, *more_keys)¶

Open a full replace segment (removes bins not written in this segment).

Example::: await session.replace(key).put({“a”: 1}).execute()

Return type:: WriteSegmentBuilder
Returns:: WriteSegmentBuilder.

replace_if_exists(arg1, *more_keys)¶

Open replace-if-exists semantics (like replace, but only if the record exists).

Example::: await session.replace_if_exists(key).put({“a”: 1}).execute()

Return type:: WriteSegmentBuilder
Returns:: WriteSegmentBuilder.

replace_only()¶

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

The record must already exist; the operation fails with KEY_NOT_FOUND_ERROR if it does not. All existing bins are removed and only the bins specified in this segment are written.

Return type:: Self

respond_all_keys()¶

Include results for missing keys in the stream.

Return type:: Self

select_from(bin_name, expression, *, ignore_eval_failure=False)¶

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

Return type:: Self

set_bins(bins)¶

Alias for put().

Return type:: Self

set_to(bin_name, value)¶

Set a bin to value.

Return type:: Self

touch(arg1, *more_keys)¶

Open a touch segment (TTL refresh).

Example::: await session.touch(key).execute()

Return type:: WriteSegmentBuilder
Returns:: WriteSegmentBuilder.

touch_record()¶

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 = await (
    session.upsert(key)
        .bin("score").get()
        .touch_record()
        .expire_record_after_seconds(120)
        .execute()
)

See also

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

Return type:: Self

update(arg1, *more_keys)¶

Open an update-only segment (fails if the record is missing).

Example::: await session.update(key).bin(“count”).add(1).execute()

Return type:: WriteSegmentBuilder
Returns:: WriteSegmentBuilder for further bins and execute().

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

Write expression result only if bin already exists.

Return type:: Self

upsert(arg1, *more_keys)¶

Open a create-or-update segment for the given key(s).

Example::: await session.upsert(key).put({“name”: “Bob”}).execute()

Return type:: WriteSegmentBuilder
Returns:: WriteSegmentBuilder for put / bin / execute.

See also

upsert(): Session entry point.

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

Write expression result, creating or overwriting the bin.

Return type:: Self

where(expression)¶

Overloads:

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

Set a filter expression on the current write segment.

Parameters:: expression (Union[str, FilterExpression]) – AEL string or pre-built FilterExpression.
Returns:: self for method chaining.

with_durable_delete()¶

Enable durable delete on the current segment.

Return type:: Self

with_no_change_in_expiration()¶

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

Return type:: Self

with_txn(txn)¶

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

Delegates to the underlying query builder.

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

without_durable_delete()¶

Force a non-durable delete for this segment (may be rejected on SC).

Return type:: Self

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

Bases: _SingleKeyWriteSegmentBase, SyncWriteSegmentBuilder

Synchronous single-key write fast-path segment.

Inherits fast-path slot state from _SingleKeyWriteSegmentBase and overrides _promote() to construct a SyncQueryBuilder when escalating to the full query path.

execute(on_error=None)[source]¶

Run the single-key fast path synchronously.

Return type:: SyncRecordStream

__init__(client, key, op_type, behavior, write_policy, read_policy=None, txn=None, namespace_mode_resolver=None, namespace_mode_resolver_blocking=None, write_policy_sc=None, read_policy_sc=None)¶

add(bin_name, value)¶

Add a numeric value to a bin.

Return type:: Self

add_operation(op)¶

Append an operation (used by CDT action builders).

Return type:: None

append(bin_name, value)¶

Append a string to a bin.

Return type:: Self

bin(bin_name)¶

Start a bin-level write operation.

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

default_with_durable_delete()¶

Prefer durable deletes for this segment when resolving behavior defaults.

Return type:: Self

default_without_durable_delete()¶

Prefer non-durable deletes for this segment when resolving behavior defaults.

Return type:: Self

delete(arg1, *more_keys)¶

Open a delete segment.

Example::: await session.delete(key).execute()

Return type:: WriteSegmentBuilder
Returns:: WriteSegmentBuilder (often followed immediately by execute()).

delete_record()¶

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 = await (
    session.upsert(key)
        .bin("name").get()
        .delete_record()
        .execute()
)

See also

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

Return type:: Self

ensure_generation_is(generation)¶

Set expected generation for optimistic locking on the current segment.

Parameters:: generation – The expected generation number (must be > 0).
Returns:: self for method chaining.
Raises:: ValueError – If generation is <= 0.

execute_blocking_fast_path(on_error=None)¶

Blocking fast path. Promotes to a full builder first, then defers to the inherited QueryBuilder.execute_blocking_fast_path().

Returns a list of RecordResult on success; None when the spec shape isn’t eligible (caller falls back to runner-driven).

Return type:: Optional[List[RecordResult]]

exists(arg1, *more_keys)¶

Open an exists-check segment.

Example::: stream = await session.exists(key).execute() found = (await stream.first_or_raise()).as_bool()

Return type:: WriteSegmentBuilder
Returns:: WriteSegmentBuilder.

expire_record_after_seconds(seconds)¶

Set the TTL on the current write segment.

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

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

fail_on_filtered_out()¶: Mark filtered-out records with FILTERED_OUT result code.

get(bin_name)¶

Read a bin value back within a write operate.

Return type:: Self

increment_by(bin_name, value)¶

Alias for add().

Return type:: Self

insert(arg1, *more_keys)¶

Open a create-only segment (fails if the record exists).

Example::: await session.insert(key).put({“name”: “Ada”}).execute()

Return type:: WriteSegmentBuilder
Returns:: WriteSegmentBuilder for further bins and execute().

insert_from(bin_name, expression, *, ignore_op_failure=False, ignore_eval_failure=False, delete_if_null=False)¶

Write expression result only if bin does not already exist.

Return type:: Self

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

prepend(bin_name, value)¶

Prepend a string to a bin.

Return type:: Self

put(bins)¶

Apply Operation.put for each bin in the mapping.

Parameters:: bins (dict) – Map of bin name to value.
Return type:: Self

Example::: await session.upsert(key).put({“email”: “a@b.com”, “age”: 30}).execute()

See also

bin(): Per-bin CDT or scalar follow-ups.

query(arg1, *more_keys)¶: Finalize this segment and open a fresh sync read query on new keys.

remove_bin(bin_name)¶

Delete a bin from the record.

Return type:: Self

replace(arg1, *more_keys)¶

Open a full replace segment (removes bins not written in this segment).

Example::: await session.replace(key).put({“a”: 1}).execute()

Return type:: WriteSegmentBuilder
Returns:: WriteSegmentBuilder.

replace_if_exists(arg1, *more_keys)¶

Open replace-if-exists semantics (like replace, but only if the record exists).

Example::: await session.replace_if_exists(key).put({“a”: 1}).execute()

Return type:: WriteSegmentBuilder
Returns:: WriteSegmentBuilder.

replace_only()¶

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

The record must already exist; the operation fails with KEY_NOT_FOUND_ERROR if it does not. All existing bins are removed and only the bins specified in this segment are written.

Return type:: Self

respond_all_keys()¶: Include results for missing keys in the stream.

select_from(bin_name, expression, *, ignore_eval_failure=False)¶

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

Return type:: Self

set_bins(bins)¶

Alias for put().

Return type:: Self

set_to(bin_name, value)¶

Set a bin to value.

Return type:: Self

touch(arg1, *more_keys)¶

Open a touch segment (TTL refresh).

Example::: await session.touch(key).execute()

Return type:: WriteSegmentBuilder
Returns:: WriteSegmentBuilder.

touch_record()¶

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 = await (
    session.upsert(key)
        .bin("score").get()
        .touch_record()
        .expire_record_after_seconds(120)
        .execute()
)

See also

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

Return type:: Self

update(arg1, *more_keys)¶

Open an update-only segment (fails if the record is missing).

Example::: await session.update(key).bin(“count”).add(1).execute()

Return type:: WriteSegmentBuilder
Returns:: WriteSegmentBuilder for further bins and execute().

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

Write expression result only if bin already exists.

Return type:: Self

upsert(arg1, *more_keys)¶

Open a create-or-update segment for the given key(s).

Example::: await session.upsert(key).put({“name”: “Bob”}).execute()

Return type:: WriteSegmentBuilder
Returns:: WriteSegmentBuilder for put / bin / execute.

See also

upsert(): Session entry point.

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

Write expression result, creating or overwriting the bin.

Return type:: Self

where(expression)¶

Set a filter expression on the current write segment.

Parameters:: expression – AEL string or pre-built FilterExpression.
Returns:: self for method chaining.

with_durable_delete()¶

Enable durable delete on the current segment.

Return type:: Self

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

with_txn(txn)¶

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

Return type:: Self

without_durable_delete()¶

Force a non-durable delete for this segment (may be rejected on SC).

Return type:: Self