Aerospike Python SDK

A high-level, chainable API for the Aerospike database, built on top of the Aerospike Python Native Client.

Important

The Aerospike Python SDK supports only Aerospike Server 8.2.0 and later.

Quick Example

import asyncio
from aerospike_sdk import ClusterDefinition, DataSet, Behavior

async def main():
    async with ClusterDefinition("localhost", 3000).connect() as cluster:
        session = cluster.create_session(Behavior.DEFAULT)
        users = DataSet.of("test", "users")

        # One-time setup: index the bin the filter below queries on. A
        # .where() query no index can satisfy falls back to a full-set scan.
        await (
            session.index(users)
            .on_bin("age")
            .named("users_age_idx")
            .integer()
            .create()
        )

        # Write
        await (
            session.upsert(users.id(1))
            .put({"name": "Alice", "age": 30})
            .execute()
        )

        # Read
        stream = await session.query(users.id(1)).execute()
        result = await stream.first_or_raise()
        print(result.record.bins)  # {'name': 'Alice', 'age': 30}

        # Query with AEL filter
        stream = await (
            session.query(users)
            .where("$.age > 25")
            .execute()
        )
        async for result in stream:
            print(result.record.bins)
        stream.close()

asyncio.run(main())

from aerospike_sdk import DataSet, Behavior
from aerospike_sdk.sync import ClusterDefinition

with ClusterDefinition("localhost", 3000).connect() as cluster:
    session = cluster.create_session(Behavior.DEFAULT)
    users = DataSet.of("test", "users")

    # One-time setup: index the bin the filter below queries on. A .where()
    # query no index can satisfy falls back to a full-set scan.
    session.index(users).on_bin("age").named("users_age_idx").integer().create()

    # Write
    session.upsert(users.id(1)).put({"name": "Alice", "age": 30}).execute()

    # Read
    stream = session.query(users.id(1)).execute()
    result = stream.first_or_raise()
    print(result.record.bins)

    # Query with AEL filter
    stream = session.query(users).where("$.age > 25").execute()
    for result in stream:
        print(result.record.bins)
    stream.close()

Installation

pip install aerospike-sdk

Or install from source:

git clone https://github.com/aerospike/aerospike-client-python-sdk.git
cd aerospike-client-python-sdk
pip install -e ".[dev]"

Key Concepts

ClusterDefinition / Cluster

Entry point. Configure seeds, auth, and TLS on a ClusterDefinition, then connect() for a live Cluster that creates sessions and manages the connection lifecycle. (Async at the top level; the sync twins live under aerospike_sdk.sync.)

Session

Scoped to a Behavior (policy defaults for timeouts, consistency, etc.). All reads and writes go through a session.

DataSet

A namespace + set pair. Use DataSet.of("ns", "set") to create one, then .id(key) to produce keys.

Builders

Reads return a QueryBuilder, writes return a WriteSegmentBuilder. Chain methods, then call .execute().

Aerospike Expression Language (AEL)

Filter records with string expressions ("$.age > 18 and $.status == 'active'"), or build them in code with Exp. See the AEL guide.

Requirements

  • Python 3.11+ (the SDK supports every CPython version under upstream security support; the floor rises in minor releases as versions reach end-of-life)

  • Aerospike Server 8.2.0 or later; earlier servers are not supported

  • aerospike-client-python-native

Next Steps