Best practices

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

This guide provides optimization techniques for the Aerospike Python client, including:

Shared client instances
Connection pool limits
Policy reuse
Circuit breaker settings
Logging for operational visibility

Enable client log

Each client instance runs a background cluster tend thread that periodically polls all nodes for cluster status. This thread generates log messages that reflect node additions and removals and any errors when retrieving node status, peers, partition maps, and racks. Enable logging to receive these messages during troubleshooting.

See Configure logging.

Each client instance spawns a maintenance thread that periodically makes info requests to all server nodes for cluster status. Multiple client instances create additional load on the server. Use one client instance per cluster in an application and share that instance across application threads or workers.

Set maximum connections

Set max_conns_per_node in the client configuration to the maximum number of synchronous connections allowed per server node (default 100). The number of connections used per node depends on concurrent commands in progress plus sub-commands used for parallel multi-node commands (batch and query). A request fails if the maximum number of connections would be exceeded.

Set min_conns_per_node to preallocate connections and avoid latency from creating new connections after idle periods. See Policies and the connection tuning guide for details.

User-defined key

By default, the user-defined key is not stored on the server. The client converts it to a hash digest that identifies the record. If the user-defined key must persist on the server, use one of the following methods:

Set 'key': aerospike.POLICY_KEY_SEND in the write policy. The key is sent to the server for storage on writes and returned on multi-record queries.
Explicitly store and retrieve the user-defined key in a bin.

See Create records for an example.

Replace mode

When a command creates or replaces all record bins, use replace mode to increase performance. The server then does not have to read the old record before updating. Do not use replace mode when updating a subset of bins.

import aerospike

write_policy = {'exists': aerospike.POLICY_EXISTS_REPLACE}
client.put(key, bins, policy=write_policy)

See Update records for available exists actions.

Policy reuse

Each database command accepts an optional policy argument. If a group of commands uses the same policy, reuse the policy dictionary instead of creating a new one for each command.

Set policy defaults in the client configuration and pass only the fields that differ per command:

import aerospike

config = {
    'hosts': [('127.0.0.1', 3000)],
    'policies': {
        'read': {'total_timeout': 1000},
        'write': {'total_timeout': 2000, 'max_retries': 2},
    },
}

client = aerospike.client(config).connect()
client.get(key)  # uses read policy defaults from config

When a policy must differ from the default for a single command, copy the base policy and modify the copy so parallel commands are not affected by shared mutations.

Circuit breaker

Use client-side backoff to prevent overwhelming a node during error bursts. Configure max_error_rate and error_rate_window in the client configuration. When the error threshold is reached, the client raises aerospike.exception.MaxErrorRateExceeded for commands to that node.

See Policies — Backoff behavior and the circuit breaker tutorial.

Use operate for multiple bin updates

Use client.operate() to batch multiple operations on the same record in a single round trip instead of issuing separate read and write commands.

See Bin operations.

Close the client

Call client.close() when the application shuts down to release connections and stop the cluster tend thread. After closing, create a new client or call client.connect() before executing further commands.