Skip to content

v1.0.0

Latest

Choose a tag to compare

@github-actions github-actions released this 11 Oct 01:01
bd159b3

Release Date: October 10, 2026

First stable release of the Aerospike Python SDK (aerospike-sdk): a fluent, async-first Python API for Aerospike with an independent synchronous surface, built on the Aerospike Python Native Client (aerospike-native) 1.0.0. Requires Python 3.11 or later and Aerospike Server 8.2.0 or later.

Breaking Changes

These apply when upgrading from 0.9.0-alpha.5.

  • Depend on aerospike-native 1.0.0, the renamed native client, in place of aerospike-async.
  • Require Python 3.11 or later and Aerospike Server 8.2.0 or later. Free-threaded Python 3.13t is no longer supported; 3.14t and 3.15t are.
  • Connect only through ClusterDefinition(...).connect(). Client and SyncClient are no longer public, the deprecated connection entry points are removed, and AsyncPool callbacks receive a Cluster. [CLIENT-5127] [CLIENT-5053]
  • Return an awaitable context manager from ClusterDefinition.connect(), so async with ClusterDefinition(...).connect() as cluster: works directly.
  • Drop the Sync prefix from the synchronous classes and export them only from aerospike_sdk.sync: Session, TransactionalSession, QueryBuilder, RecordStream, IndexBuilder, and InfoCommands.
  • Rename ClusterDefinition.validate_cluster_name_is() to cluster_name() and with_ip_map() to ip_map(), and replace the TLS builder (with_tls_config_of(), TlsBuilder) with keyword arguments on with_tls_config().
  • Accept only positional targets on session verbs: a DataSet, a Key, Key varargs, or a List[Key]. The key=, dataset=, namespace=, set_name=, and key_value= keywords are removed, and session.index() takes a DataSet.
  • Replace begin_transaction(), transaction_session(), and get_current_transaction() with transaction() and current_transaction(), and remove Session.batch(), Session.client, and TransactionalSession.rollback() (use abort()). Build batches by chaining verbs on the session.
  • Return TxnStatus from commit() and abort(), replacing CommitStatus and AbortStatus.
  • Remove the query builder's raw-policy escape hatches (with_policy(), with_read_policy(), base_policy(), replica()), along with max_records() (use limit()), filter_expression() (use where()), expected_duration(), with_index_context(), and the background-task methods (use the background builders). Each operation accepts one where().
  • Remove respond_all_keys; use include_missing_keys. [CLIENT-5026]
  • Rename the background builders' index_filters() to filter(), which takes one index filter.
  • Rename the index builder's numeric() to integer(), which creates INTEGER indexes. [CLIENT-4361]
  • Remove the flat Behavior shortcuts (total_timeout, socket_timeout, max_retries, retry_delay, send_key) from Behavior and derive_with_changes(); set them through Settings scopes. Public config dataclasses and QueryHint are keyword-only, and QueryHint.bin_name is removed.
  • Remove increment_by() from the write builders (use add()), OperationResult.get_long() and get_double() (use get_int() and get_float()), and Exp.device_size() and Exp.memory_size().
  • Remove the AEL parser exports (parse_ael, parse_ael_with_index, parse_ctx, ParseResult, AelParseException), Index, IndexContext, RegexFlag, and OnError. IndexTypeEnum is replaced by IndexType, and MaxErrorRate by MaxErrorRateError.
  • Make the RecordStream.from_* construction factories private.
  • Raise SDK AerospikeError subclasses from query streams instead of raw native-client exceptions, and default error messages to the result code description. [CLIENT-5492]
  • Raise RecordNotFoundError from or_raise terminals, and refuse operations on a transaction that has already committed or aborted.
  • Turn on list_create padding by default. [CLIENT-5518]
  • Run batch and query work against all nodes in parallel by default, instead of one node at a time; set max_concurrent_nodes on a scope to change it.

New Features

  • Support server-side AEL parsing and server-side index selection, with QueryHint.hard_hint, allow_scans_with_where, and explain plans. [CLIENT-4878] [CLIENT-5011] [CLIENT-5207]
  • Add string operations and expressions: the str_* verbs on bin and CDT builders, read_as_string, the Exp.string_* family, and CREATE_ONLY / UPDATE_ONLY string writes. [CLIENT-4827] [CLIENT-5358] [CLIENT-5368]
  • Add a fluent CDT path surface: on_each_child, on_each_child_where, on_map_keys_in, and_filter, and collect_values_as_expression_read. [CLIENT-5564]
  • Add list_join to the query, operate, and nested CDT builders, and the bit base64-encode operation and expression. [CLIENT-5339] [CLIENT-5348]
  • Add get_as_map() and get_as_ordered_map() to the CDT read builders, and single-value list_append / list_add to the nested CDT builder.
  • Create expression indexes from an AEL string, set indexes with on_set() and CTX.to_bytes(), and blob() indexes. [CLIENT-5221] [CLIENT-4318]
  • Accept collection, bit, HLL, string, and expression steps in background operations, let background tasks combine index filters with where(), and add expiry controls to the background write builders. [CLIENT-5575] [CLIENT-5579]
  • Let a DataSet with no set span the whole namespace. [CLIENT-5580]
  • Add tabular writes: dataset-scoped bins() with row() and rows().
  • Add the get_many() / put_many() window API and transparent read and write coalescing for async throughput. [CLIENT-5168]
  • Add first() / first_or_raise() query terminals, RecordStream.pop() / pop_or_raise(), and lazy stream() execution across the builders. [CLIENT-5024]
  • Add expire_record_at(datetime) and expire_record_after(timedelta). [CLIENT-4689]
  • Expose client metrics on Cluster: enable_metrics(), metrics_snapshot(), exporters, and the operational and usage tiers. [CLIENT-5036] [CLIENT-5205] [CLIENT-5527]
  • Configure Behavior and system settings from YAML or environment variables, select config profiles by the server-reported cluster name, and opt into strict validation with with_strict_config(). [CLIENT-5042] [CLIENT-5046] [CLIENT-5498]
  • Add SDK logging. [CLIENT-5008]
  • Identify the client on the wire through the user agent, and support setting app_id. [CLIENT-5060]
  • Run qualified batch operations in implicit transactions, tune do_in_transaction() conflict retries, keep an in-doubt transaction retryable after a failed commit, raise on an abandoned roll-forward, and add Txn.in_doubt and TxnState.COMMIT_FAILED. [CLIENT-4362] [CLIENT-5589] [CLIENT-4963] [CLIENT-5413] [CLIENT-5177]
  • Manage UDFs and indexes from a session or cluster (register_udf(), remove_udf(), list_udf(), create_index(), drop_index(), list_indexes()), and derive a session with different behavior through session_for().
  • Add cluster and node introspection: nodes(), get_node(), node_names(), server_version(), and the supports_* capability probes.
  • Add targeted exception subclasses, and surface server_message, exp_trace, sub_code, and to_exception() on RecordResult, with ErrorDetailVerbosity to control the detail. [CLIENT-5025] [CLIENT-4792] [CLIENT-4791]
  • Pass TLS protocols and ciphers through, make the CA file optional, support for_login_only, and add external-insecure credentials and tend and login timeouts. [CLIENT-5387]
  • Surface the batch sub-policy fields and the replica and read modes on batch operations, and make batch and query concurrency configurable. [CLIENT-5240] [CLIENT-5319]
  • Add SortedMap for key-ordered map bins, UDF calls in heterogeneous batches, and Exp.exclusive.
  • Re-export the native types callers use, including Key, ResultCode, SubCode, Filter, IndexType, ListOrderType, and MapOrder.
  • Support Python 3.15 and free-threaded 3.15t.

Improvements

  • Run AsyncPool loops on uvloop. [CLIENT-4987]
  • Deliver batch results in place. [CLIENT-5461]
  • Speed up batch chains: fold key-disjoint runs, reuse write policies across identical segments, and build results with less per-row overhead.
  • Resolve batch and point-write policies against each namespace's AP or SC mode, read from the partition map.
  • Push a final metrics snapshot when metrics are disabled or the cluster closes.
  • Add an AI coding agent entry point to the README and scrub the guides. [CLIENT-4583] [CLIENT-5282]

Bug Fixes

  • Fix client-side batch failure rows reporting success, and report code-less failure rows as CLIENT_ERROR.
  • Fix the SC durable-delete setting. [CLIENT-5218]
  • Fix the partition helper confusing a bound with a count. [CLIENT-5191]
  • Fix a query-builder path that bypassed Behavior.
  • Fix two info responses that returned unparsed wire data.
  • Fix a race in the routing TTL cache that could expose None to readers.
  • Keep a with_txn read inside the transaction on SC namespaces, and use read settings for single-key read-only operate calls.
  • Honor send_key on batch writes, and stop include_missing_keys surfacing filtered-out rows.
  • Fix an AsyncPool stall under uvloop on free-threaded Python. [CLIENT-4987]
  • Relax over-strict write-TTL validation. [CLIENT-4994]

Full Changelog: v0.9.0-alpha.5...v1.0.0