Delete records

Applies to

• Aerospike Developer SDK preview (Java 21+ and Python 3.10+)
• Aerospike Database 6.0 or later unless a section states otherwise

Code examples

Examples assume a connected session from Connect to Aerospike. Each usage guide lists shared imports in a tabbed block near the top of the page; snippet blocks add imports only for types not already shown. The first code block in each section includes dataset setup; later blocks in that section reuse those values. When a page includes a Complete example section, that block is fully self-contained.

Learn how to delete records from Aerospike using the Developer SDK. This guide covers simple deletion, conditional deletes, and handling deletion of non-existent records.

Except where noted, snippets on this page use the imports below. A snippet lists additional import lines only when it needs a type not shown here. When this page includes a Complete example section, that block is fully self-contained with every import required to run it.

Java

import com.aerospike.client.sdk.DataSet;
import com.aerospike.client.sdk.Record;
import com.aerospike.client.sdk.RecordResult;
import com.aerospike.client.sdk.RecordStream;

import java.util.ArrayList;
import java.util.List;

Python

import time

from aerospike_sdk import DataSet, GenerationError

Delete a record

Use delete() to remove a record by its key:

Java

DataSet users = DataSet.of("test", "users");

session.delete(users.id("user-1"))
    .execute();

📖 API reference: DataSet.of(...) | DataSet.id(...) | Session.delete(Key) | ChainableQueryBuilder.execute()

Python

users = DataSet.of("test", "users")
await session.delete(key=users.id("user-1")).execute()

📖 API reference: DataSet.of() | DataSet.id() | Session.delete() | WriteSegmentBuilder.execute()

Check if delete succeeded

Use the delete result row to determine whether a record was actually deleted:

Java

DataSet users = DataSet.of("test", "users");

RecordStream deleteStream = session.delete(users.id("user-1")).execute();
boolean deleted = deleteStream.getFirst().map(RecordResult::asBoolean).orElse(false);

if (deleted) {
    System.out.println("Record deleted successfully");
} else {
    System.out.println("Record didn't exist");
}

📖 API reference: DataSet.id(...) | Session.delete(Key) | ChainableQueryBuilder.execute() | RecordStream.getFirst()

Python

users = DataSet.of("test", "users")
stream = await session.delete(key=users.id("user-1")).execute()
row = await stream.first()
deleted = row.as_bool() if row is not None else False
stream.close()

if deleted:
    print("Record deleted successfully")
else:
    print("Record didn't exist")

📖 API reference: DataSet.of() | DataSet.id() | Session.delete() | RecordResult.as_bool() | RecordStream.first() | RecordStream.close() | WriteSegmentBuilder.execute()

Conditional delete (generation check)

Delete only if the record hasn’t been modified since you last read it:

Java

// Additional imports for this example:
import com.aerospike.client.sdk.AerospikeException;

DataSet users = DataSet.of("test", "users");

// Read the record first
RecordStream readStream = session.query(users.id("user-1")).execute();
Record user = readStream.getFirstRecord();

// Delete only if generation matches
try {
    session.delete(users.id("user-1"))
        .ensureGenerationIs(user.generation)
        .execute();
    System.out.println("Deleted successfully");
} catch (GenerationException e) {
    System.out.println("Record was modified, delete aborted");
}

📖 API reference: DataSet.id(...) | Session.delete(Key) | Session.query(Key) | ChainableQueryBuilder.execute() | RecordStream.getFirstRecord() | AerospikeException

Python

users = DataSet.of("test", "users")
# Read the record first
stream = await session.query(users.id("user-1")).execute()
row = await stream.first_or_raise()
user = row.record_or_raise()
stream.close()

# Delete only if generation matches
try:
    await (
        session.delete(key=users.id("user-1"))
        .ensure_generation_is(user.generation)
        .execute()
    )
    print("Deleted successfully")
except GenerationError:
    print("Record was modified, delete aborted")

📖 API reference: DataSet.of() | DataSet.id() | Session.query() | Session.delete() | WriteSegmentBuilder.ensure_generation_is() | RecordResult.record_or_raise() | RecordStream.first_or_raise() | RecordStream.close() | QueryBuilder.execute() | WriteSegmentBuilder.execute()

Use case

Generation-based conditional delete is useful when you want to ensure you’re deleting the exact version of the record you read, preventing accidental deletion of updated data.

Delete only if exists

By default, deleting a non-existent record is a no-op. In Java, use exists() first if you need a hard failure when the record is missing. In Python, check existence first and then delete. Note in both cases it is possible for the record to have been deleted by another thread between the return of the exists() check and when the result is actioned. To avoid this race condition, either use a transaction or check if the resultCode on the RecordResult equals KEY_NOT_FOUND

Java

DataSet users = DataSet.of("test", "users");

// There is no deleteOnly() in the Java SDK; check existence first if you must fail when absent.
boolean existed = session.exists(users.id("user-1")).execute().getFirstBoolean().orElse(false);
if (!existed) {
    System.out.println("Record not found");
} else {
    session.delete(users.id("user-1")).execute().close();
    System.out.println("Record deleted");
}

📖 API reference: DataSet.id(...) | Session.delete(Key) | Session.exists(Key) | ChainableQueryBuilder.execute() | ChainableNoBinsBuilder.execute() | RecordStream.close()

Python

users = DataSet.of("test", "users")

stream = await session.exists(users.id("user-1")).execute()
row = await stream.first()
stream.close()

if row is None or not row.as_bool():
    print("Record not found")
    return

await session.delete(key=users.id("user-1")).execute()
print("Record deleted")

📖 API reference: DataSet.of() | DataSet.id() | Session.delete() | Session.exists() | RecordResult.as_bool() | RecordStream.first() | RecordStream.close() | WriteSegmentBuilder.execute()

Delete with durability options

For critical deletes, ensure durability. These can either be done on a per-call basis, or set on the session level via a Behavior.

Java

DataSet users = DataSet.of("test", "users");

// Use a durable session for important deletes
session.delete(users.id("important-record"))
    .withDurableDelete()
    .execute();

📖 API reference: DataSet.id(...) | Session.delete(Key) | ChainableQueryBuilder.execute()

Python

users = DataSet.of("test", "users")

# Use a durable session for important deletes
await session.delete(key=users.id("important-record")).durably_delete().execute()

📖 API reference: DataSet.id() | Session.delete() | WriteSegmentBuilder.execute()

📖 Learn more: Behaviors explains durability options.

Batch delete

For deleting multiple records efficiently, see Batch Operations.

Java

DataSet users = DataSet.of("test", "users");

// Quick preview - see Batch Operations for full details
RecordStream deleteStream = session.delete(users.ids("user-1", "user-2", "user-3")).execute();

📖 API reference: DataSet.ids(...) | Session.delete(List) | Session.delete(Key) | ChainableQueryBuilder.execute()

Python

users = DataSet.of("test", "users")

# Quick preview - see Batch Operations for full details
await (
    session.batch()
    .delete(users.id("user-1"))
    .delete(users.id("user-2"))
    .delete(users.id("user-3"))
    .execute()
)

📖 API reference: DataSet.id() | Session.batch() | BatchOperationBuilder.delete() | BatchOperationBuilder.execute()

Soft delete pattern

Instead of permanently deleting, mark records as deleted:

Java

DataSet users = DataSet.of("test", "users");

// Soft delete: mark as deleted instead of removing
session.update(users.id("user-1"))
    .bin("deleted").setTo(true)
    .bin("deleted_at").setTo(System.currentTimeMillis())
    .execute();

// When querying, filter out deleted records
RecordStream stream = session.query(users)
    .where("$.deleted == false")
    .execute();
List<Record> activeUsers = new ArrayList<>();
stream.forEach(result -> {
    if (result.isOk()) {
        activeUsers.add(result.recordOrThrow());
    }
});
// forEach is a terminal operation and closes the stream.

📖 API reference: DataSet.id(...) | Session.update(Key) | Session.query(DataSet) | ChainableOperationBuilder.bin(...) | ChainableQueryBuilder.where(...) | ChainableQueryBuilder.execute() | RecordStream.forEach(...) | RecordResult.isOk() | RecordResult.recordOrThrow()

Python

users = DataSet.of("test", "users")
# Soft delete: mark as deleted instead of removing
await (
    session.update(users.id("user-1"))
    .bin("deleted").set_to(True)
    .bin("deleted_at").set_to(time.time())
    .execute()
)

# When querying, filter out deleted records
stream = await session.query(users).where("$.deleted == false").execute()
active_users = []
async for row in stream:
    active_users.append(row.record_or_raise())
stream.close()

📖 API reference: DataSet.of() | DataSet.id() | Session.query() | Session.update() | QueryBuilder.where() | QueryBuilder.bin() | WriteSegmentBuilder.set_to() | WriteSegmentBuilder.bin() | RecordResult.record_or_raise() | RecordStream.close() | QueryBuilder.execute() | WriteSegmentBuilder.execute()

Delete with TTL (auto-expire)

Instead of explicit deletion, let records expire automatically. Note: do not decrease the expiration time on a record.

Java

// Additional imports for this example:
import java.time.Duration;

DataSet users = DataSet.of("test", "users");

// Set TTL to expire in 1 minute (deferred delete)
session.touch(users.id("user-1"))
    .expireRecordAfter(Duration.ofMinutes(1))
    .execute();

📖 API reference: DataSet.id(...) | Session.touch(Key) | ChainableQueryBuilder.execute()

Python

users = DataSet.of("test", "users")

# Set TTL to expire in 1 minute (deferred delete)
await (
    session.touch(users.id("user-1"))
    .expire_record_after_seconds(60)
    .execute()
)

📖 API reference: DataSet.id() | Session.touch() | WriteSegmentBuilder.expire_record_after_seconds() | WriteSegmentBuilder.execute()

Complete example

This example is self-contained—it lists every import needed to run standalone.

Java

import com.aerospike.client.sdk.Cluster;
import com.aerospike.client.sdk.ClusterDefinition;
import com.aerospike.client.sdk.DataSet;
import com.aerospike.client.sdk.Record;
import com.aerospike.client.sdk.RecordResult;
import com.aerospike.client.sdk.RecordStream;
import com.aerospike.client.sdk.Session;
import com.aerospike.client.sdk.policy.Behavior;

public class DeleteRecordsExample {
    public static void main(String[] args) {
        try (Cluster cluster = new ClusterDefinition("localhost", 3000).connect()) {
            Session session = cluster.createSession(Behavior.DEFAULT);
            DataSet users = DataSet.of("test", "users");
            String deleteKey = "delete-example-user";
            String conditionalKey = "delete-example-conditional";

            // Cleanup so the example is repeatable.
            session.delete(users.id(deleteKey)).execute().close();
            session.delete(users.id(conditionalKey)).execute().close();

            // Create a test record
            session.insert(users)
                .bins("name")
                .id(deleteKey).values("Test User")
                .execute();

            // Simple delete
            RecordStream deletedStream = session.delete(users.id(deleteKey)).execute();
            boolean deleted = deletedStream.getFirst().map(RecordResult::asBoolean).orElse(false);
            System.out.println("Deleted: " + deleted);

            // Try to delete again (returns false)
            RecordStream secondDeletedStream = session.delete(users.id(deleteKey)).execute();
            deleted = secondDeletedStream.getFirst().map(RecordResult::asBoolean).orElse(false);
            secondDeletedStream.close();
            System.out.println("Second delete: " + deleted);

            // Conditional delete example
            session.insert(users)
                .bins("name")
                .id(conditionalKey).values("Conditional User")
                .execute();

            RecordStream rs = session.query(users.id(conditionalKey)).execute();
            Record record = rs.getFirstRecord();

            session.delete(users.id(conditionalKey))
                .ensureGenerationIs(record.generation)
                .execute();
            System.out.println("Conditional delete succeeded");
        }
    }
}

📖 API reference: ClusterDefinition(String,int) | ClusterDefinition.connect() | Cluster.createSession(Behavior) | Cluster.close() | DataSet.of(...) | Session.insert(DataSet) | Session.delete(Key) | Session.query(Key) | OperationObjectBuilder.bins(...) | IdValuesBuilder.id(...) | IdValuesRowBuilder.values(...) | ChainableQueryBuilder.execute() | ChainableNoBinsBuilder.execute() | RecordStream.getFirstRecord() | RecordStream.getFirst() | RecordStream.close()

Python

import asyncio
from aerospike_sdk import Behavior, DataSet, Client


async def main():
    async with Client("localhost:3000") as client:
        session = client.create_session(Behavior.DEFAULT)
        users = DataSet.of("test", "users")
        delete_key = users.id("delete-example-user")
        conditional_key = users.id("delete-example-conditional")

        # Cleanup so the example is repeatable.
        stream = await session.delete(key=delete_key).execute()
        stream.close()
        stream = await session.delete(key=conditional_key).execute()
        stream.close()

        # Create a test record
        await session.insert(key=delete_key).put(
            {"name": "Test User"}
        ).execute()

        # Simple delete
        stream = await session.delete(key=delete_key).execute()
        row = await stream.first()
        deleted = row.as_bool() if row is not None else False
        stream.close()
        print(f"Deleted: {deleted}")

        # Try to delete again (returns False)
        stream = await session.delete(key=delete_key).execute()
        row = await stream.first()
        deleted = row.as_bool() if row is not None else False
        stream.close()
        print(f"Second delete: {deleted}")

        # Conditional delete example
        await session.insert(key=conditional_key).put(
            {"name": "Conditional User"}
        ).execute()

        stream = await session.query(conditional_key).execute()
        row = await stream.first_or_raise()
        record = row.record_or_raise()
        stream.close()

        await (
            session.delete(key=conditional_key)
            .ensure_generation_is(record.generation)
            .execute()
        )
        print("Conditional delete succeeded")

if __name__ == "__main__":
    asyncio.run(main())

📖 API reference: Client | Client.create_session() | DataSet.of() | DataSet.id() | Behavior.DEFAULT | Session.query() | Session.insert() | Session.delete() | WriteSegmentBuilder.put() | WriteSegmentBuilder.ensure_generation_is() | RecordResult.record_or_raise() | RecordResult.as_bool() | RecordStream.first() | RecordStream.first_or_raise() | RecordStream.close() | QueryBuilder.execute() | WriteSegmentBuilder.execute()

API reference summary

Method	Description	Link
delete()	Delete a record by key	Java · Python
.ensureGenerationIs(gen) / .ensure_generation_is(gen)	Conditional delete	—
(No deleteOnly / delete_only in either SDK)	Use exists() then delete(), or inspect the delete result	—

Next steps

Batch Operations

Delete multiple records efficiently.

Batch Operations →

Query Records

Find records to delete with DSL queries.

Query Records →

Error Handling

Handle deletion errors gracefully.

Error Handling →