Repository navigation
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-native1.0.0, the renamed native client, in place ofaerospike-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().ClientandSyncClientare no longer public, the deprecated connection entry points are removed, andAsyncPoolcallbacks receive aCluster. [CLIENT-5127] [CLIENT-5053] - Return an awaitable context manager from
ClusterDefinition.connect(), soasync with ClusterDefinition(...).connect() as cluster:works directly. - Drop the
Syncprefix from the synchronous classes and export them only fromaerospike_sdk.sync:Session,TransactionalSession,QueryBuilder,RecordStream,IndexBuilder, andInfoCommands. - Rename
ClusterDefinition.validate_cluster_name_is()tocluster_name()andwith_ip_map()toip_map(), and replace the TLS builder (with_tls_config_of(),TlsBuilder) with keyword arguments onwith_tls_config(). - Accept only positional targets on session verbs: a
DataSet, aKey,Keyvarargs, or aList[Key]. Thekey=,dataset=,namespace=,set_name=, andkey_value=keywords are removed, andsession.index()takes aDataSet. - Replace
begin_transaction(),transaction_session(), andget_current_transaction()withtransaction()andcurrent_transaction(), and removeSession.batch(),Session.client, andTransactionalSession.rollback()(useabort()). Build batches by chaining verbs on the session. - Return
TxnStatusfromcommit()andabort(), replacingCommitStatusandAbortStatus. - Remove the query builder's raw-policy escape hatches (
with_policy(),with_read_policy(),base_policy(),replica()), along withmax_records()(uselimit()),filter_expression()(usewhere()),expected_duration(),with_index_context(), and the background-task methods (use the background builders). Each operation accepts onewhere(). - Remove
respond_all_keys; useinclude_missing_keys. [CLIENT-5026] - Rename the background builders'
index_filters()tofilter(), which takes one index filter. - Rename the index builder's
numeric()tointeger(), which createsINTEGERindexes. [CLIENT-4361] - Remove the flat
Behaviorshortcuts (total_timeout,socket_timeout,max_retries,retry_delay,send_key) fromBehaviorandderive_with_changes(); set them throughSettingsscopes. Public config dataclasses andQueryHintare keyword-only, andQueryHint.bin_nameis removed. - Remove
increment_by()from the write builders (useadd()),OperationResult.get_long()andget_double()(useget_int()andget_float()), andExp.device_size()andExp.memory_size(). - Remove the AEL parser exports (
parse_ael,parse_ael_with_index,parse_ctx,ParseResult,AelParseException),Index,IndexContext,RegexFlag, andOnError.IndexTypeEnumis replaced byIndexType, andMaxErrorRatebyMaxErrorRateError. - Make the
RecordStream.from_*construction factories private. - Raise SDK
AerospikeErrorsubclasses from query streams instead of raw native-client exceptions, and default error messages to the result code description. [CLIENT-5492] - Raise
RecordNotFoundErrorfromor_raiseterminals, and refuse operations on a transaction that has already committed or aborted. - Turn on
list_createpadding 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_nodeson 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, theExp.string_*family, andCREATE_ONLY/UPDATE_ONLYstring 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, andcollect_values_as_expression_read. [CLIENT-5564] - Add
list_jointo the query, operate, and nested CDT builders, and the bit base64-encode operation and expression. [CLIENT-5339] [CLIENT-5348] - Add
get_as_map()andget_as_ordered_map()to the CDT read builders, and single-valuelist_append/list_addto the nested CDT builder. - Create expression indexes from an AEL string, set indexes with
on_set()andCTX.to_bytes(), andblob()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
DataSetwith no set span the whole namespace. [CLIENT-5580] - Add tabular writes: dataset-scoped
bins()withrow()androws(). - 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 lazystream()execution across the builders. [CLIENT-5024] - Add
expire_record_at(datetime)andexpire_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
Behaviorand system settings from YAML or environment variables, select config profiles by the server-reported cluster name, and opt into strict validation withwith_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 addTxn.in_doubtandTxnState.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 throughsession_for(). - Add cluster and node introspection:
nodes(),get_node(),node_names(),server_version(), and thesupports_*capability probes. - Add targeted exception subclasses, and surface
server_message,exp_trace,sub_code, andto_exception()onRecordResult, withErrorDetailVerbosityto 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
SortedMapfor key-ordered map bins, UDF calls in heterogeneous batches, andExp.exclusive. - Re-export the native types callers use, including
Key,ResultCode,SubCode,Filter,IndexType,ListOrderType, andMapOrder. - Support Python 3.15 and free-threaded 3.15t.
Improvements
- Run
AsyncPoolloops 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
Noneto readers. - Keep a
with_txnread inside the transaction on SC namespaces, and use read settings for single-key read-only operate calls. - Honor
send_keyon batch writes, and stopinclude_missing_keyssurfacing filtered-out rows. - Fix an
AsyncPoolstall 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