aerospike

`aerospike.Client` --- Client Class

Overview

The client connects through a seed node (the address of a single node) to an Aerospike database cluster. From the seed node, the client learns of the other nodes and establishes connections to them. It also gets the partition map of the cluster, which is how it knows where every record actually lives.

The client handles the connections, including re-establishing them ahead of executing an operation. It keeps track of changes to the cluster through a cluster-tending thread.

Client Architecture and Data Distribution.

Boilerplate Code For Examples

Assume every in-line example runs this code beforehand:

Warning

Only run example code on a brand new Aerospike server. This code deletes all records in the demo set!

Basic example:

# Write a record
client.put(keyTuple, {'name': 'John Doe', 'age': 32})

# Read a record
(key, meta, record) = client.get(keyTuple)

Methods

To create a new client, use aerospike.client.

Connection

connect([username, password])

If there is currently no connection to the cluster, connect to it. The optional username and password only apply when connecting to the Enterprise Edition of Aerospike.

param str username: a defined user with roles in the cluster. See admin_create_user.
param str password: the password will be hashed by the client using bcrypt.
raises: ~aerospike.exception.ClientError, for example when a connection cannot be established to a seed node (any single node in the cluster from which the client learns of the other nodes).

Note

Python client 5.0.0 and up will fail to connect to Aerospike server 4.8.x or older. If you see the error "-10, ‘Failed to connect’", please make sure you are using server 4.9 or later.

Security features article.

is_connected()

Tests the connections between the client and the nodes of the cluster. If the result is False, the client will require another call to ~aerospike.connect.

rtype: bool

2.0.0

close()

Close all connections to the cluster. It is recommended to explicitly call this method when the program is done communicating with the cluster.

You may call ~aerospike.Client.connect again after closing the connection.

Record Operations

put(key, bins: dict[, meta: dict[, policy: dict[, serializer=aerospike.SERIALIZER_NONE]]])

Create a new record, or remove / add bins to a record.

param tuple key: a aerospike_key_tuple associated with the record.
param dict bins: contains bin name-value pairs of the record.
param dict meta: record metadata to be set. see metadata_dict.
param dict policy: see aerospike_write_policies.
param serializer: override the serialization mode of the client with one of the aerospike_serialization_constants. To use a class-level, user-defined serialization function registered with aerospike.set_serializer, use aerospike.SERIALIZER_USER.
raises: a subclass of ~aerospike.exception.AerospikeError.

Example:

exists(key[, policy: dict]) -> (key, meta)

Check if a record with a given key exists in the cluster.

Returns the record's key and metadata in a tuple.

If the record does not exist, the tuple's metadata will be :pyNone.

param tuple key: a aerospike_key_tuple associated with the record.
param dict policy: see aerospike_read_policies.
rtype: tuple (key, meta)
raises: a subclass of ~aerospike.exception.AerospikeError.

2.0.3

get(key[, policy: dict]) -> (key, meta, bins)

Returns a record with a given key.

param tuple key: a aerospike_key_tuple associated with the record.
param dict policy: see aerospike_read_policies.
return: a aerospike_record_tuple.
raises: ~aerospike.exception.RecordNotFound.

2.0.0

select(key, bins: list[, policy: dict]) -> (key, meta, bins)

Returns specific bins of a record.

If a bin does not exist, it will not show up in the returned aerospike_record_tuple.

param tuple key: a aerospike_key_tuple associated with the record.
param list bins: a list of bin names to select from the record.
param dict policy: optional aerospike_read_policies.
return: a aerospike_record_tuple.
raises: ~aerospike.exception.RecordNotFound.

2.0.0

touch(key[, val=0[, meta: dict[, policy: dict]]])

Touch the given record, setting its time-to-live and incrementing its generation.

param tuple key: a aerospike_key_tuple associated with the record.
param int val: ttl in seconds, with 0 resolving to the default value in the server config.
param dict meta: record metadata to be set. see metadata_dict
param dict policy: see aerospike_operate_policies.
raises: a subclass of ~aerospike.exception.AerospikeError.

remove(key[meta: dict[, policy: dict]])

Remove a record matching the key from the cluster.

param tuple key: a aerospike_key_tuple associated with the record.
param dict meta: contains the expected generation of the record in a key called "gen".
param dict policy: see aerospike_remove_policies. May be passed as a keyword argument.
raises: a subclass of ~aerospike.exception.AerospikeError.

remove_bin(key, list[, meta: dict[, policy: dict]])

Remove a list of bins from a record with a given key. Equivalent to setting those bins to aerospike.null with a ~aerospike.put.

param tuple key: a aerospike_key_tuple associated with the record.
param list list: the bins names to be removed from the record.
param dict meta: record metadata to be set. See metadata_dict.
param dict policy: optional aerospike_write_policies.
raises: a subclass of ~aerospike.exception.AerospikeError.

single: Batch Operations

Batch Operations

get_many(keys[, policy: dict]) -> [(key, meta, bins)]

12.0.0 Use batch_read instead.

Batch-read multiple records, and return them as a list.

Any record that does not exist will have a :pyNone value for metadata and bins in the record tuple.

param list keys: a list of aerospike_key_tuple.
param dict policy: see aerospike_batch_policies.
return: a list of aerospike_record_tuple.
raises: a ~aerospike.exception.ClientError if the batch is too big.

exists_many(keys[, policy: dict]) -> [ (key, meta)]

12.0.0 Use batch_read instead.

Batch-read metadata for multiple keys.

Any record that does not exist will have a :pyNone value for metadata in their tuple.

param list keys: a list of aerospike_key_tuple.
param dict policy: see aerospike_batch_policies.
return: a list of (key, metadata) tuple for each record.

select_many(keys, bins: list[, policy: dict]) -> [(key, meta, bins), ...]}

12.0.0 Use batch_read instead.

Batch-read specific bins from multiple records.

Any record that does not exist will have a :pyNone value for metadata and bins in its tuple.

param list keys: a list of aerospike_key_tuple to read from.
param list bins: a list of bin names to read from the records.
param dict policy: see aerospike_batch_policies.
return: a list of aerospike_record_tuple.

batch_get_ops(keys, ops, policy: dict) -> [ (key, meta, bins)]

12.0.0 Use batch_operate instead.

Batch-read multiple records, and return them as a list.

Any record that does not exist will have a exception type value as metadata and :pyNone value as bins in the record tuple.

param list keys: a list of aerospike_key_tuple.
param list ops: a list of operations to apply.
param dict policy: see aerospike_batch_policies.
return: a list of aerospike_record_tuple.
raises: a ~aerospike.exception.ClientError if the batch is too big.

Note

The following batch methods will return a ~aerospike_helpers.batch.records.BatchRecords object with a result value of 0 if one of the following is true:

All transactions are successful.

One or more transactions failed because:

A record was filtered out by an expression

The record was not found

Otherwise:

If the Python client-layer's code throws an error, such as a connection error or parameter error, an exception will be raised.

If the underlying C client throws an error, the returned ~aerospike_helpers.batch.records.BatchRecords object will have a result value equal to an as_status error code. In this case, the ~aerospike_helpers.batch.records.BatchRecords object has a list of batch records called batch_records, and each batch record contains the result of that transaction.

batch_write(batch_records: BatchRecords, [policy_batch: dict]) -> BatchRecords

Write/read multiple records for specified batch keys in one batch call.

This method allows different sub-commands for each key in the batch. The resulting status and operated bins are set in batch_records.results and batch_records.record.

param BatchRecords batch_records: A BatchRecords object used to specify the operations to carry out.
param dict policy_batch: aerospike batch policy aerospike_batch_policies.
return: A reference to the batch_records argument of type BatchRecords <aerospike_helpers.batch.records>.
raises: A subclass of ~aerospike.exception.AerospikeError. See note above batch_write for details.

Note

Requires server version >= 6.0.0.

More information about the batch helpers aerospike_operation_helpers.batch

batch_read(keys: list, [bins: list], [policy_batch: dict]) -> BatchRecords

Read multiple records.

If a list of bin names is not provided, return all the bins for each record.

If a list of bin names is provided, return only these bins for the given list of records.

If an empty list of bin names is provided, only the metadata of each record will be returned. Each BatchRecord.record in BatchRecords.batch_records will only be a 2-tuple (key, meta).

param list keys: The key tuples of the records to fetch.
param list[str] bins: List of bin names to fetch for each record.
param dict policy_batch: See aerospike_batch_policies.
return: an instance of BatchRecords <aerospike_helpers.batch.records>.
raises: A subclass of ~aerospike.exception.AerospikeError. See note above batch_write for details.

Note

Requires server version >= 6.0.0.

batch_operate(keys: list, ops: list, [policy_batch: dict], [policy_batch_write: dict], [ttl: int]) -> BatchRecords

Perform the same read/write transactions on multiple keys.

Note

Prior to Python client 14.0.0, using the ~batch_operate() method with only read operations caused an error. This bug was fixed in version 14.0.0.

param list keys: The keys to operate on.
param list ops: List of operations to apply.
param dict policy_batch: See aerospike_batch_policies.
param dict policy_batch_write: See aerospike_batch_write_policies.
param int ttl: The time-to-live (expiration) of each record in seconds.
return: an instance of BatchRecords <aerospike_helpers.batch.records>.
raises: A subclass of ~aerospike.exception.AerospikeError. See note above batch_write for details.

Note

Requires server version >= 6.0.0.

batch_apply(keys: list, module: str, function: str, args: list, [policy_batch: dict], [policy_batch_apply: dict]) -> BatchRecords

Apply UDF (user defined function) on multiple keys.

param list keys: The keys to operate on.
param str module: the name of the UDF module.
param str function: the name of the UDF to apply to the record identified by key.
param list args: the arguments to the UDF.
param dict policy_batch: See aerospike_batch_policies.
param dict policy_batch_apply: See aerospike_batch_apply_policies.
return: an instance of BatchRecords <aerospike_helpers.batch.records>.
raises: A subclass of ~aerospike.exception.AerospikeError. See note above batch_write for details.

Note

Requires server version >= 6.0.0.

batch_remove(keys: list, [policy_batch: dict], [policy_batch_remove: dict]) -> BatchRecords

Note

Requires server version >= 6.0.0.

Remove multiple records by key.

param list keys: The keys to remove.
param dict policy_batch: Optional aerospike batch policy aerospike_batch_policies.
param dict policy_batch_remove: Optional aerospike batch remove policy aerospike_batch_remove_policies.
return: an instance of BatchRecords <aerospike_helpers.batch.records>.
raises: A subclass of ~aerospike.exception.AerospikeError. See note above batch_write for details.

single: String Operations

String Operations

Note

Please see aerospike_helpers.operations.operations for the new way to use string operations.

append(key, bin, val[, meta: dict[, policy: dict]])

Append a string to the string value in bin.

param tuple key: a aerospike_key_tuple tuple associated with the record.
param str bin: the name of the bin.
param str val: the string to append to the bin value.
param dict meta: record metadata to be set. See metadata_dict.
param dict policy: optional aerospike_operate_policies.
raises: a subclass of ~aerospike.exception.AerospikeError.

client.put(keyTuple, {'bin1': 'Martin Luther King'})
client.append(keyTuple, 'bin1', ' jr.')
(_, _, bins) = client.get(keyTuple)
print(bins) # Martin Luther King jr.

prepend(key, bin, val[, meta: dict[, policy: dict]])

Prepend the string value in bin with the string val.

param tuple key: a aerospike_key_tuple tuple associated with the record.
param str bin: the name of the bin.
param str val: the string to prepend to the bin value.
param dict meta: record metadata to be set. See metadata_dict.
param dict policy: optional aerospike_operate_policies.
raises: a subclass of ~aerospike.exception.AerospikeError.

client.put(keyTuple, {'bin1': 'Freeman'})
client.prepend(keyTuple, 'bin1', ' Gordon ')
(_, _, bins) = client.get(keyTuple)
print(bins) # Gordon Freeman

single: Numeric Operations

Numeric Operations

Note

Please see aerospike_helpers.operations.operations for the new way to use numeric operations using the operate command.

increment(key, bin, offset[, meta: dict[, policy: dict]])

Increment the integer value in bin by the integer val.

param tuple key: a aerospike_key_tuple tuple associated with the record.
param str bin: the name of the bin.
param int offset: the value by which to increment the value in bin.
type offset: :pyint or :pyfloat
param dict meta: record metadata to be set. See metadata_dict.
param dict policy: optional aerospike_operate_policies. Note: the exists policy option may not be: aerospike.POLICY_EXISTS_CREATE_OR_REPLACE nor aerospike.POLICY_EXISTS_REPLACE
raises: a subclass of ~aerospike.exception.AerospikeError.

# Start with 100 lives
client.put(keyTuple, {'lives': 100})

# Gain health
client.increment(keyTuple, 'lives', 10)
(key, meta, bins) = client.get(keyTuple)
print(bins) # 110

# Take damage
client.increment(keyTuple, 'lives', -90)
(key, meta, bins) = client.get(keyTuple)
print(bins) # 20

single: List Operations

List Operations

Note

Please see aerospike_helpers.operations.list_operations for the new way to use list operations. Old style list operations are deprecated. The docs for old style list operations were removed in client 6.0.0. The code supporting these methods will be removed in a coming release.

single: Map Operations

Map Operations

Note

Please see aerospike_helpers.operations.map_operations for the new way to use map operations. Old style map operations are deprecated. The docs for old style map operations were removed in client 6.0.0. The code supporting these methods will be removed in a coming release.

single: Multi-Ops

Single-Record Transactions

operate(key, list: list[, meta: dict[, policy: dict]]) -> (key, meta, bins)

Performs an atomic transaction, with multiple bin operations, against a single record with a given key.

Starting with Aerospike server version 3.6.0, non-existent bins are not present in the returned aerospike_record_tuple. The returned record tuple will only contain one element per bin, even if multiple operations were performed on the bin. (In Aerospike server versions prior to 3.6.0, non-existent bins being read will have a :pyNone value. )

param tuple key: a aerospike_key_tuple associated with the record.
param list list: See aerospike_operation_helpers.operations.
param dict meta: record metadata to be set. See metadata_dict.
param dict policy: optional aerospike_operate_policies.
return: a aerospike_record_tuple.
raises: a subclass of ~aerospike.exception.AerospikeError.

Note

operate can now have multiple write operations on a single bin.

2.1.3

operate_ordered(key, list: list[, meta: dict[, policy: dict]]) -> (key, meta, bins)

Performs an atomic transaction, with multiple bin operations, against a single record with a given key. The results will be returned as a list of (bin-name, result) tuples. The order of the elements in the list will correspond to the order of the operations from the input parameters.

Write operations or read operations that fail will not return a (bin-name, result) tuple.

param tuple key: a aerospike_key_tuple associated with the record.
param list list: See aerospike_operation_helpers.operations.
param dict meta: record metadata to be set. See metadata_dict.
param dict policy: optional aerospike_operate_policies.
return: a aerospike_record_tuple.
raises: a subclass of ~aerospike.exception.AerospikeError.

2.1.3

single: User Defined Functions

User Defined Functions

udf_put(filename[, udf_type=aerospike.UDF_TYPE_LUA[, policy: dict]])

Register a UDF module with the cluster.

param str filename: the path to the UDF module to be registered with the cluster.
param int udf_type: aerospike.UDF_TYPE_LUA.
param dict policy: currently timeout in milliseconds is the available policy.
raises: a subclass of ~aerospike.exception.AerospikeError.

Note

To run this example, do not run the boilerplate code.

import aerospike

config = {
    'hosts': [ ('127.0.0.1', 3000)],
    'lua': { 'user_path': '/path/to/lua/user_path'}
}
client = aerospike.client(config)
# Register the UDF module and copy it to the Lua 'user_path'
client.udf_put('/path/to/my_module.lua')
client.close()

udf_remove(module[, policy: dict])

Remove a previously registered UDF module from the cluster.

param str module: the UDF module to be deregistered from the cluster.
param dict policy: currently timeout in milliseconds is the available policy.
raises: a subclass of ~aerospike.exception.AerospikeError.

client.udf_remove('my_module.lua')

udf_list([policy: dict]) -> []

Return the list of UDF modules registered with the cluster.

param dict policy: currently timeout in milliseconds is the available policy.
rtype: list
raises: a subclass of ~aerospike.exception.AerospikeError.

print(client.udf_list())
# [
#    {'content': bytearray(b''),
#    'hash': bytearray(b'195e39ceb51c110950bd'),
#    'name': 'my_udf1.lua',
#    'type': 0},
#    {'content': bytearray(b''),
#    'hash': bytearray(b'8a2528e8475271877b3b'),
#    'name': 'stream_udf.lua',
#    'type': 0}
# ]

udf_get(module: str[, language: int = aerospike.UDF_TYPE_LUA[, policy: dict]]) -> str

Return the content of a UDF module which is registered with the cluster.

param str module: the UDF module to read from the cluster.
param int language: aerospike.UDF_TYPE_LUA
param dict policy: currently timeout in milliseconds is the available policy.
rtype: str
raises: a subclass of ~aerospike.exception.AerospikeError.

apply(key, module, function, args[, policy: dict])

Apply a registered (see udf_put) record UDF to a particular record.

param tuple key: a aerospike_key_tuple associated with the record.
param str module: the name of the UDF module.
param str function: the name of the UDF to apply to the record identified by key.
param list args: the arguments to the UDF.
param dict policy: optional aerospike_apply_policies.
return: the value optionally returned by the UDF, one of str,int, float, bytearray, list, dict.
raises: a subclass of ~aerospike.exception.AerospikeError.

Record UDF and Developing Record UDFs.

scan_apply(ns, set, module, function[, args[, policy: dict[, options]]]) -> int

7.0.0 aerospike.Query should be used instead.

Initiate a scan and apply a record UDF to each record matched by the scan.

This method blocks until the scan is complete.

param str ns: the namespace in the aerospike cluster.
param str set: the set name. Should be :pyNone if the entire namespace is to be scanned.
param str module: the name of the UDF module.
param str function: the name of the UDF to apply to the records matched by the scan.
param list args: the arguments to the UDF.
param dict policy: optional aerospike_scan_policies.
param dict options: the aerospike_scan_options that will apply to the scan.
rtype: int
return: a job ID that can be used with job_info to check the status of the aerospike.JOB_SCAN.
raises: a subclass of ~aerospike.exception.AerospikeError.

query_apply(ns, set, predicate, module, function[, args[, policy: dict]]) -> int

Initiate a query and apply a record UDF to each record matched by the query.

This method blocks until the query is complete.

param str ns: the namespace in the aerospike cluster.
param str set: the set name. Should be :pyNone if you want to query records in the ns which are in no set.
param tuple predicate: the tuple produced by one of the aerospike.predicates methods.
param str module: the name of the UDF module.
param str function: the name of the UDF to apply to the records matched by the query.
param list args: the arguments to the UDF.
param dict policy: optional aerospike_write_policies.
rtype: int
return: a job ID that can be used with job_info to check the status of the aerospike.JOB_QUERY.
raises: a subclass of ~aerospike.exception.AerospikeError.

job_info(job_id, module[, policy: dict]) -> dict

Return the status of a job running in the background.

The returned dict contains these keys:

"status": see aerospike_job_constants_status for possible values.

"records_read": number of scanned records.

"progress_pct": progress percentage of the job

param int job_id: the job ID returned by scan_apply or query_apply.
param module: one of aerospike_job_constants.
param policy: optional aerospike_info_policies.
returns: dict
raises: a subclass of ~aerospike.exception.AerospikeError.

single: Info Operations

Info Operations

get_node_names() -> []

Return the list of hosts and node names present in a connected cluster.

return: a list of node info dictionaries.
raises: a subclass of ~aerospike.exception.AerospikeError.

# Assuming two nodes
nodes = client.get_node_names()
print(nodes)
# [{'address': '1.1.1.1', 'port': 3000, 'node_name': 'BCER199932C'}, {'address': '1.1.1.1', 'port': 3010, 'node_name': 'ADFFE7782CD'}]

6.0.0

get_nodes() -> []

Return the list of hosts present in a connected cluster.

return: a list of node address tuples.
raises: a subclass of ~aerospike.exception.AerospikeError.

# Assuming two nodes
nodes = client.get_nodes()
print(nodes)
# [('127.0.0.1', 3000), ('127.0.0.1', 3010)]

3.0.0

Warning

In versions < 3.0.0 get_nodes will not work when using TLS

info_single_node(command, host[, policy: dict]) -> str

Send an info command to a single node specified by host name.

param str command: the info command. See Info Command Reference.
param str host: a node name. Example: 'BCER199932C'
param dict policy: optional aerospike_info_policies.
rtype: str
raises: a subclass of ~aerospike.exception.AerospikeError.

Note

Use get_node_names as an easy way to get host IP to node name mappings.

info_all(command[, policy: dict]]) -> {}

Send an info command to all nodes in the cluster to which the client is connected.

If any of the individual requests fail, this will raise an exception.

param str command: see Info Command Reference.
param dict policy: optional aerospike_info_policies.
rtype: dict
raises: a subclass of ~aerospike.exception.AerospikeError.

response = client.info_all("namespaces")
print(response)
# {'BB9020011AC4202': (None, 'test\n')}

3.0.0

info_random_node(command, [policy: dict]) -> str

Send an info command to a single random node.

param str command: the info command. See Info Command Reference.
param dict policy: optional aerospike_info_policies.
rtype: str
raises: a subclass of ~aerospike.exception.AerospikeError.

6.0.0

set_xdr_filter(data_center, namespace, expression_filter[, policy: dict]) -> str

Set the cluster's xdr filter using an Aerospike expression.

The cluster's current filter can be removed by setting expression_filter to None.

param str data_center: The data center to apply the filter to.
param str namespace: The namespace to apply the filter to.
param AerospikeExpression expression_filter: The filter to set. See expressions at :pyaerospike_helpers.
param dict policy: optional aerospike_info_policies.
raises: a subclass of ~aerospike.exception.AerospikeError.

xdr-set-filter Info Command Reference.

5.0.0

Warning

Requires Aerospike server version >= 5.3.

get_expression_base64(expression) -> str

Get the base64 representation of a compiled aerospike expression.

See aerospike_operation_helpers.expressions for more details on expressions.

param AerospikeExpression expression: the compiled expression.
raises: a subclass of ~aerospike.exception.AerospikeError.

7.0.0

shm_key() -> int

Expose the value of the shm_key for this client if shared-memory cluster tending is enabled,

rtype: int or :pyNone

truncate(namespace, set, nanos[, policy: dict])

Remove all records in the namespace / set whose last updated time is older than the given time.

This method is many orders of magnitude faster than deleting records one at a time. See Truncate command reference.

This asynchronous server call may return before the truncation is complete. The user can still write new records after the server returns because new records will have last update times greater than the truncate cutoff (set at the time of truncate call)

param str namespace: The namespace to truncate.
param str set: The set to truncate. Pass in :pyNone to truncate a namespace instead.
param long nanos: A cutoff threshold where records last updated before the threshold will be removed. Units are in nanoseconds since the UNIX epoch (1970-01-01). A value of 0 indicates that all records in the set should be truncated regardless of update time. The value must not be in the future.
param dict policy: See aerospike_info_policies.
rtype: Status indicating the success of the operation.
raises: a subclass of ~aerospike.exception.AerospikeError.

Note

Requires Aerospike server version >= 3.12

single: Index Operations

Index Operations

index_string_create(ns, set, bin, name[, policy: dict])

Create a string index with index_name on the bin in the specified ns, set.

param str ns: the namespace in the aerospike cluster.
param str set: the set name.
param str bin: the name of bin the secondary index is built on.
param str name: the name of the index.
param dict policy: optional aerospike_info_policies.
raises: a subclass of ~aerospike.exception.AerospikeError.

index_integer_create(ns, set, bin, name[, policy])

Create an integer index with name on the bin in the specified ns, set.

param str ns: the namespace in the aerospike cluster.
param str set: the set name.
param str bin: the name of bin the secondary index is built on.
param str name: the name of the index.
param dict policy: optional aerospike_info_policies.
raises: a subclass of ~aerospike.exception.AerospikeError.

index_blob_create(ns, set, bin, name[, policy])

Create an blob index with index name name on the bin in the specified ns, set.

param str ns: the namespace in the aerospike cluster.
param str set: the set name.
param str bin: the name of the bin the secondary index is built on.
param str name: the name of the index.
param dict policy: optional aerospike_info_policies.
raises: a subclass of ~aerospike.exception.AerospikeError.

index_list_create(ns, set, bin, index_datatype, name[, policy: dict])

Create an index named name for numeric, string or GeoJSON values (as defined by index_datatype) on records of the specified ns, set whose bin is a list.

param str ns: the namespace in the aerospike cluster.
param str set: the set name.
param str bin: the name of bin the secondary index is built on.
param index_datatype: Possible values are aerospike.INDEX_STRING, aerospike.INDEX_NUMERIC, aerospike.INDEX_BLOB, and aerospike.INDEX_GEO2DSPHERE.
param str name: the name of the index.
param dict policy: optional aerospike_info_policies.
raises: a subclass of ~aerospike.exception.AerospikeError.

Note

Requires server version >= 3.8.0

index_map_keys_create(ns, set, bin, index_datatype, name[, policy: dict])

Create an index named name for numeric, string or GeoJSON values (as defined by index_datatype) on records of the specified ns, set whose bin is a map. The index will include the keys of the map.

param str ns: the namespace in the aerospike cluster.
param str set: the set name.
param str bin: the name of bin the secondary index is built on.
param index_datatype: Possible values are aerospike.INDEX_STRING, aerospike.INDEX_NUMERIC, aerospike.INDEX_BLOB, and aerospike.INDEX_GEO2DSPHERE.
param str name: the name of the index.
param dict policy: optional aerospike_info_policies.
raises: a subclass of ~aerospike.exception.AerospikeError.

Note

Requires server version >= 3.8.0

index_map_values_create(ns, set, bin, index_datatype, name[, policy: dict])

Create an index named name for numeric, string or GeoJSON values (as defined by index_datatype) on records of the specified ns, set whose bin is a map. The index will include the values of the map.

param str ns: the namespace in the aerospike cluster.
param str set: the set name.
param str bin: the name of bin the secondary index is built on.
param index_datatype: Possible values are aerospike.INDEX_STRING, aerospike.INDEX_NUMERIC, aerospike.INDEX_BLOB, and aerospike.INDEX_GEO2DSPHERE.
param str name: the name of the index.
param dict policy: optional aerospike_info_policies.
raises: a subclass of ~aerospike.exception.AerospikeError.

Note

Requires server version >= 3.8.0

import aerospike

client = aerospike.client({ 'hosts': [ ('127.0.0.1', 3000)]})

# assume the bin fav_movies in the set test.demo bin should contain
# a dict { (str) _title_ : (int) _times_viewed_ }
# create a secondary index for string values of test.demo records whose 'fav_movies' bin is a map
client.index_map_keys_create('test', 'demo', 'fav_movies', aerospike.INDEX_STRING, 'demo_fav_movies_titles_idx')
# create a secondary index for integer values of test.demo records whose 'fav_movies' bin is a map
client.index_map_values_create('test', 'demo', 'fav_movies', aerospike.INDEX_NUMERIC, 'demo_fav_movies_views_idx')
client.close()

index_geo2dsphere_create(ns, set, bin, name[, policy: dict])

Create a geospatial 2D spherical index with name on the bin in the specified ns, set.

param str ns: the namespace in the aerospike cluster.
param str set: the set name.
param str bin: the name of bin the secondary index is built on.
param str name: the name of the index.
param dict policy: optional aerospike_info_policies.
raises: a subclass of ~aerospike.exception.AerospikeError.

aerospike.GeoJSON, aerospike.predicates

Note

Requires server version >= 3.7.0

import aerospike

client = aerospike.client({ 'hosts': [ ('127.0.0.1', 3000)]})
client.index_geo2dsphere_create('test', 'pads', 'loc', 'pads_loc_geo')
client.close()

index_remove(ns: str, name: str[, policy: dict])

Remove the index with name from the namespace.

param str ns: the namespace in the aerospike cluster.
param str name: the name of the index.
param dict policy: optional aerospike_info_policies.
raises: a subclass of ~aerospike.exception.AerospikeError.

get_cdtctx_base64(ctx: list) -> str

Get the base64 representation of aerospike CDT ctx.

See aerospike_operation_helpers.cdt_ctx for more details on CDT context.

param list ctx: Aerospike CDT context: generated by aerospike CDT ctx helper aerospike_helpers.
raises: a subclass of ~aerospike.exception.AerospikeError.

7.1.1

single: Admin Operations

Admin Operations

The admin methods implement the security features of the Enterprise Edition of Aerospike. These methods will raise a ~aerospike.exception.SecurityNotSupported when the client is connected to a Community Edition cluster (see aerospike.exception). A user is validated by the client against the server whenever a connection is established through the use of a username and password (passwords hashed using bcrypt). When security is enabled, each operation is validated against the user's roles. Users are assigned roles, which are collections of aerospike_privilege_dict.

import aerospike
from aerospike import exception as ex
import time

config = {'hosts': [('127.0.0.1', 3000)] }
client = aerospike.client(config).connect('ipji', 'life is good')

try:
    dev_privileges = [{'code': aerospike.PRIV_READ}, {'code': aerospike.PRIV_READ_WRITE}]
    client.admin_create_role('dev_role', dev_privileges)
    client.admin_grant_privileges('dev_role', [{'code': aerospike.PRIV_READ_WRITE_UDF}])
    client.admin_create_user('dev', 'you young whatchacallit... idiot', ['dev_role'])
    time.sleep(1)
    print(client.admin_query_user('dev'))
    print(admin_query_users())
except ex.AdminError as e:
    print("Error [{0}]: {1}".format(e.code, e.msg))
client.close()

Security features article.

admin_create_role(role, privileges[, policy: dict[, whitelist[, read_quota[, write_quota]]]])

Create a custom role containing a list of privileges, as well as an optional whitelist and quotas.

param str role: The name of the role.
param list privileges: A list of aerospike_privilege_dict.
param dict policy: See aerospike_admin_policies.
param list whitelist: A list of whitelist IP addresses that can contain wildcards, for example 10.1.2.0/24.
param int read_quota: Maximum reads per second limit. Pass in 0 for no limit.
param int write_quota: Maximum write per second limit, Pass in 0 for no limit.
raises: One of the ~aerospike.exception.AdminError subclasses.

admin_set_whitelist(role, whitelist[, policy: dict])

Add a whitelist to a role.

param str role: The name of the role.
param list whitelist: List of IP strings the role is allowed to connect to. Setting this to :pyNone will clear the whitelist for that role.
param dict policy: See aerospike_admin_policies.
raises: One of the ~aerospike.exception.AdminError subclasses.

admin_set_quotas(role[, read_quota[, write_quota[, policy: dict]]])

Add quotas to a role.

param str role: the name of the role.
param int read_quota: Maximum reads per second limit. Pass in 0 for no limit.
param int write_quota: Maximum write per second limit. Pass in 0 for no limit.
param dict policy: See aerospike_admin_policies.
raises: one of the ~aerospike.exception.AdminError subclasses.

admin_drop_role(role[, policy: dict])

Drop a custom role.

param str role: the name of the role.
param dict policy: See aerospike_admin_policies.
raises: one of the ~aerospike.exception.AdminError subclasses.

admin_grant_privileges(role, privileges[, policy: dict])

Add privileges to a role.

param str role: the name of the role.
param list privileges: a list of aerospike_privilege_dict.
param dict policy: See aerospike_admin_policies.
raises: one of the ~aerospike.exception.AdminError subclasses.

admin_revoke_privileges(role, privileges[, policy: dict])

Remove privileges from a role.

param str role: the name of the role.
param list privileges: a list of aerospike_privilege_dict.
param dict policy: See aerospike_admin_policies.
raises: one of the ~aerospike.exception.AdminError subclasses.

admin_get_role(role[, policy: dict]) -> {}

Get a dict of privileges, whitelist, and quotas associated with a role.

param str role: the name of the role.
param dict policy: See aerospike_admin_policies.
return: a aerospike_role_dict.
raises: one of the ~aerospike.exception.AdminError subclasses.

admin_get_roles([policy: dict]) -> {}

Get the names of all roles and their attributes.

param dict policy: See aerospike_admin_policies.
return: a dict of aerospike_role_dict keyed by role names.
raises: one of the ~aerospike.exception.AdminError subclasses.

admin_query_role(role[, policy: dict]) -> []

Get the list of privileges associated with a role.

param str role: the name of the role.
param dict policy: See aerospike_admin_policies.
return: a list of aerospike_privilege_dict.
raises: one of the ~aerospike.exception.AdminError subclasses.

admin_query_roles([policy: dict]) -> {}

Get all named roles and their privileges.

param dict policy: optional aerospike_admin_policies.
return: a dict of aerospike_privilege_dict keyed by role name.
raises: one of the ~aerospike.exception.AdminError subclasses.

admin_create_user(username, password, roles[, policy: dict])

Create a user and grant it roles.

param str username: the username to be added to the Aerospike cluster.
param str password: the password associated with the given username.
param list roles: the list of role names assigned to the user.
param dict policy: optional aerospike_admin_policies.
raises: one of the ~aerospike.exception.AdminError subclasses.

admin_drop_user(username[, policy: dict])

Drop the user with a specified username from the cluster.

param str username: the username to be dropped from the aerospike cluster.
param dict policy: optional aerospike_admin_policies.
raises: one of the ~aerospike.exception.AdminError subclasses.

admin_change_password(username, password[, policy: dict])

Change the password of a user.

This operation can only be performed by that same user.

param str username: the username of the user.
param str password: the password associated with the given username.
param dict policy: optional aerospike_admin_policies.
raises: one of the ~aerospike.exception.AdminError subclasses.

admin_set_password(username, password[, policy: dict])

Set the password of a user by a user administrator.

param str username: the username to be added to the aerospike cluster.
param str password: the password associated with the given username.
param dict policy: optional aerospike_admin_policies.
raises: one of the ~aerospike.exception.AdminError subclasses.

admin_grant_roles(username, roles[, policy: dict])

Add roles to a user.

param str username: the username of the user.
param list roles: a list of role names.
param dict policy: optional aerospike_admin_policies.
raises: one of the ~aerospike.exception.AdminError subclasses.

admin_revoke_roles(username, roles[, policy: dict])

Remove roles from a user.

param str username: the username to have the roles revoked.
param list roles: a list of role names.
param dict policy: optional aerospike_admin_policies.
raises: one of the ~aerospike.exception.AdminError subclasses.

admin_query_user_info (user: str[, policy: dict]) -> dict

Retrieve roles and other info for a given user.

param str user: the username of the user.
param dict policy: optional aerospike_admin_policies.
return: a dict of user data. See admin_user_dict.

admin_query_users_info ([policy: dict]) -> list

Retrieve roles and other info for all users.

param dict policy: optional aerospike_admin_policies.
return: a list of users' data. See admin_user_dict.

admin_query_user (username[, policy: dict]) -> []

12.0.0 admin_query_user_info should be used instead.

Return the list of roles granted to the specified user.

param str username: the username of the user.
param dict policy: optional aerospike_admin_policies.
return: a list of role names.
raises: one of the ~aerospike.exception.AdminError subclasses.

admin_query_users ([policy: dict]) -> {}

12.0.0 admin_query_users_info should be used instead.

Get the roles of all users.

param dict policy: optional aerospike_admin_policies.
return: a dict of roles keyed by username.
raises: one of the ~aerospike.exception.AdminError subclasses.

Metrics

enable_metrics(policy: Optional[aerospike_helpers.metrics.MetricsPolicy] = None)

Enable extended periodic cluster and node latency metrics.

param MetricsPolicy policy: Optional metrics policy
raises: ~aerospike.exception.AerospikeError or one of its subclasses.

disable_metrics()

Disable extended periodic cluster and node latency metrics.

raises: ~aerospike.exception.AerospikeError or one of its subclasses.

User Dictionary

The user dictionary has the following key-value pairs:

"read_info" (list[int]): list of read statistics. List may be :pyNone. Current statistics by offset are:

0: read quota in records per second

1: single record read transaction rate (TPS)

2: read scan/query record per second rate (RPS)

3: number of limitless read scans/queries

Future server releases may add additional statistics.

"write_info" (list[int]): list of write statistics. List may be :pyNone. Current statistics by offset are:

0: write quota in records per second

1: single record write transaction rate (TPS)

2: write scan/query record per second rate (RPS)

3: number of limitless write scans/queries

Future server releases may add additional statistics.

"conns_in_use" (int): number of currently open connections.

"roles" (list[str]): list of assigned role names.

Scan and Query Constructors

scan(namespace[, set]) -> Scan

7.0.0 aerospike.Query should be used instead.

Returns a aerospike.Scan object to scan all records in a namespace / set.

If set is omitted or set to :pyNone, the object returns all records in the namespace.

param str namespace: the namespace in the aerospike cluster.
param str set: optional specified set name, otherwise the entire namespace will be scanned.
return: an :pyaerospike.Scan class.

query(namespace[, set]) -> Query

Return a aerospike.Query object to be used for executing queries over a specified set in a namespace.

See aerospike.Query for more details.

param str namespace: the namespace in the aerospike cluster.
param str set: optional specified set name, otherwise the records which are not part of any set will be queried (Note: this is different from not providing the set in scan).
return: an :pyaerospike.Query class.

single: Other Methods

Tuples

Key Tuple

key

The key tuple, which is sent and returned by various operations, has the structure

(namespace, set, primary key[, digest])

namespace (str)

Name of the namespace.

This must be preconfigured on the cluster.

set (str)

Name of the set.

The set be created automatically if it does not exist.

primary key (str, int or bytearray)

The value by which the client-side application identifies the record.

digest

The record's RIPEMD-160 digest.

The first three parts of the tuple get hashed through RIPEMD-160, and the digest used by the clients and cluster nodes to locate the record. A key tuple is also valid if it has the digest part filled and the primary key part set to :pyNone.

The following code example shows:

How to use the key tuple in a put operation

How to fetch the key tuple in a get operation
import aerospike

# NOTE: change this to your Aerospike server's seed node address
seedNode = ('127.0.0.1', 3000)
config = config = {'hosts': [seedNode]}
client = aerospike.client(config)

# The key tuple comprises the following:
namespaceName = 'test'
setName = 'setname'
primaryKeyName = 'pkname'
keyTuple = (namespaceName, setName, primaryKeyName)

# Insert a record
recordBins = {'bin1':0, 'bin2':1}
client.put(keyTuple, recordBins)

# Now fetch that record
(key, meta, bins) = client.get(keyTuple)

# The key should be in the second format
# Notice how there is no primary key
# and there is the record's digest
print(key)

# Expected output:
# ('test', 'setname', None, bytearray(b'b\xc7[\xbb\xa4K\xe2\x9al\xd12!&\xbf<\xd9\xf9\x1bPo'))

# Cleanup
client.remove(keyTuple)
client.close()
Data Model: Keys and Digests.

Record Tuple

record

The record tuple which is returned by various read operations. It has the structure:

(key, meta, bins)

key (tuple)

See aerospike_key_tuple.
meta (dict)
Contains record metadata with the following key-value pairs:
- gen (int)
  
  Generation value
- ttl (int)
  
  Time-to-live value
bins (dict)

Contains bin-name/bin-value pairs.

We reuse the code example in the key-tuple section and print the meta and bins values that were returned from ~aerospike.Client.get():

import aerospike

# NOTE: change this to your Aerospike server's seed node address
seedNode = ('127.0.0.1', 3000)
config = {'hosts': [seedNode]}
client = aerospike.client(config)

namespaceName = 'test'
setName = 'setname'
primaryKeyName = 'pkname'
keyTuple = (namespaceName, setName, primaryKeyName)

# Insert a record
recordBins = {'bin1':0, 'bin2':1}
client.put(keyTuple, recordBins)

# Now fetch that record
(key, meta, bins) = client.get(keyTuple)

# Generation is 1 because this is the first time we wrote the record
print(meta)

# Expected output:
# {'ttl': 2592000, 'gen': 1}

# The bin-value pairs we inserted
print(bins)
{'bin1': 0, 'bin2': 1}

client.remove(keyTuple)
client.close()

Data Model: Record.

Metadata Dictionary

The metadata dictionary has the following key-value pairs:

"ttl" (int): record time to live in seconds. See TTL_CONSTANTS for possible special values.

"gen" (int): record generation

Policies

Write Policies

policy

A dict of optional write policies, which are applicable to ~Client.put, ~Client.query_apply. ~Client.remove_bin.

max_retries (int)

Maximum number of retries before aborting the current transaction. The initial attempt is not counted as a retry.

If max_retries is exceeded, the transaction will return error AEROSPIKE_ERR_TIMEOUT.

Default: 0

Warning

Database writes that are not idempotent (such as "add") should not be retried because the write operation may be performed multiple times if the client timed out previous transaction attempts. It's important to use a distinct write policy for non-idempotent writes, which sets max_retries = 0;
sleep_between_retries (int)

Milliseconds to sleep between retries. Enter 0 to skip sleep.

Default: 0
socket_timeout (int)

Socket idle timeout in milliseconds when processing a database command.

If socket_timeout is not 0 and the socket has been idle for at least socket_timeout, both max_retries and total_timeout are checked. If max_retries and total_timeout are not exceeded, the transaction is retried.

If both socket_timeout and total_timeout are non-zero and socket_timeout > total_timeout, then socket_timeout will be set to total_timeout. If socket_timeout is 0, there will be no socket idle limit.

Default: 30000
total_timeout (int)

Total transaction timeout in milliseconds.

The total_timeout is tracked on the client and sent to the server along with the transaction in the wire protocol. The client will most likely timeout first, but the server also has the capability to timeout the transaction.

If total_timeout is not 0 and total_timeout is reached before the transaction completes, the transaction will return error AEROSPIKE_ERR_TIMEOUT. If total_timeout is 0, there will be no total time limit.

Default: 1000
compress (bool)

Compress client requests and server responses.

Use zlib compression on write or batch read commands when the command buffer size is greater than 128 bytes. In addition, tell the server to compress it's response on read commands. The server response compression threshold is also 128 bytes.

This option will increase cpu and memory usage (for extra compressed buffers), but decrease the size of data sent over the network.

Default: False
key

One of the POLICY_KEY values such as aerospike.POLICY_KEY_DIGEST

Default: aerospike.POLICY_KEY_DIGEST
exists

One of the POLICY_EXISTS values such as aerospike.POLICY_EXISTS_CREATE

Default: aerospike.POLICY_EXISTS_IGNORE
ttl
The default time-to-live (expiration) of the record in seconds. This field will only be used if the write transaction:
1. Doesn't contain a metadata dictionary with a ttl value.
2. Contains a metadata dictionary with a ttl value set to aerospike.TTL_CLIENT_DEFAULT.
There are also special values that can be set for this option. See TTL_CONSTANTS.
gen

One of the POLICY_GEN values such as aerospike.POLICY_GEN_IGNORE

Default: aerospike.POLICY_GEN_IGNORE
commit_level

One of the POLICY_COMMIT_LEVEL values such as aerospike.POLICY_COMMIT_LEVEL_ALL

Default: aerospike.POLICY_COMMIT_LEVEL_ALL
durable_delete (bool)

Perform durable delete

Default: False
expressions list

Compiled aerospike expressions aerospike_helpers used for filtering records within a transaction.

Default: None

Note

Requires Aerospike server version >= 5.2.
compression_threshold (int)

Compress data for transmission if the object size is greater than a given number of bytes.

Default: 0, meaning 'never compress'
replica

Algorithm used to determine target node. One of the POLICY_REPLICA values.

Default: aerospike.POLICY_REPLICA_SEQUENCE

Read Policies

policy

A dict of optional read policies, which are applicable to ~Client.get, ~Client.exists, ~Client.select.

max_retries (int)

Maximum number of retries before aborting the current transaction. The initial attempt is not counted as a retry.

If max_retries is exceeded, the transaction will return error AEROSPIKE_ERR_TIMEOUT.

Default: 2
sleep_between_retries (int)

Milliseconds to sleep between retries. Enter 0 to skip sleep.

Default: 0
socket_timeout (int)

Socket idle timeout in milliseconds when processing a database command.

If socket_timeout is not 0 and the socket has been idle for at least socket_timeout, both max_retries and total_timeout are checked. If max_retries and total_timeout are not exceeded, the transaction is retried.

If both socket_timeout and total_timeout are non-zero and socket_timeout > total_timeout, then socket_timeout will be set to total_timeout. If socket_timeout is 0, there will be no socket idle limit.

Default: 30000
total_timeout (int)

Total transaction timeout in milliseconds.

The total_timeout is tracked on the client and sent to the server along with the transaction in the wire protocol. The client will most likely timeout first, but the server also has the capability to timeout the transaction.

If total_timeout is not 0 and total_timeout is reached before the transaction completes, the transaction will return error AEROSPIKE_ERR_TIMEOUT. If total_timeout is 0, there will be no total time limit.

Default: 1000
compress (bool)

Compress client requests and server responses.

Use zlib compression on write or batch read commands when the command buffer size is greater than 128 bytes. In addition, tell the server to compress it's response on read commands. The server response compression threshold is also 128 bytes.

This option will increase cpu and memory usage (for extra compressed buffers), but decrease the size of data sent over the network.

Default: False
deserialize (bool)

Should raw bytes representing a list or map be deserialized to a list or dictionary.
Set to False for backup programs that just need access to raw bytes.
Default: True
key

One of the POLICY_KEY values such as aerospike.POLICY_KEY_DIGEST

Default: aerospike.POLICY_KEY_DIGEST
read_mode_ap

One of the POLICY_READ_MODE_AP values such as aerospike.AS_POLICY_READ_MODE_AP_ONE

Default: aerospike.AS_POLICY_READ_MODE_AP_ONE

3.7.0
read_mode_sc

One of the POLICY_READ_MODE_SC values such as aerospike.POLICY_READ_MODE_SC_SESSION

Default: aerospike.POLICY_READ_MODE_SC_SESSION

3.7.0
read_touch_ttl_percent
Determine how record TTL (time to live) is affected on reads. When enabled, the server can efficiently operate as a read-based LRU cache where the least recently used records are expired. The value is expressed as a percentage of the TTL sent on the most recent write such that a read within this interval of the record’s end of life will generate a touch.

For example, if the most recent write had a TTL of 10 hours and "read_touch_ttl_percent" is set to 80, the next read within 8 hours of the record's end of life (equivalent to 2 hours after the most recent write) will result in a touch, resetting the TTL to another 10 hours.

Values:
- 0 : Use server config default-read-touch-ttl-pct for the record's namespace/set.
- -1 : Do not reset record TTL on reads.
- 1 - 100 : Reset record TTL on reads when within this percentage of the most recent write TTL.
Default: 0

Note

Requires Aerospike server version >= 7.1.
replica

One of the POLICY_REPLICA values such as aerospike.POLICY_REPLICA_MASTER

Default: aerospike.POLICY_REPLICA_SEQUENCE
expressions list

Compiled aerospike expressions aerospike_helpers used for filtering records within a transaction.

Default: None

Note

Requires Aerospike server version >= 5.2.

Operate Policies

policy

A dict of optional operate policies, which are applicable to ~Client.append, ~Client.prepend, ~Client.increment, ~Client.operate, and atomic list and map operations.

max_retries (int)

Maximum number of retries before aborting the current transaction. The initial attempt is not counted as a retry.

If max_retries is exceeded, the transaction will return error AEROSPIKE_ERR_TIMEOUT.

Default: 0

Warning

Database writes that are not idempotent (such as "add") should not be retried because the write operation may be performed multiple times if the client timed out previous transaction attempts. It's important to use a distinct write policy for non-idempotent writes, which sets max_retries = 0;
sleep_between_retries (int)

Milliseconds to sleep between retries. Enter 0 to skip sleep.

Default: 0
socket_timeout (int)

Socket idle timeout in milliseconds when processing a database command.

If socket_timeout is not 0 and the socket has been idle for at least socket_timeout, both max_retries and total_timeout are checked. If max_retries and total_timeout are not exceeded, the transaction is retried.

If both socket_timeout and total_timeout are non-zero and socket_timeout > total_timeout, then socket_timeout will be set to total_timeout. If socket_timeout is 0, there will be no socket idle limit.

Default: 30000
total_timeout (int)

Total transaction timeout in milliseconds.

The total_timeout is tracked on the client and sent to the server along with the transaction in the wire protocol. The client will most likely timeout first, but the server also has the capability to timeout the transaction.

If total_timeout is not 0 and total_timeout is reached before the transaction completes, the transaction will return error AEROSPIKE_ERR_TIMEOUT. If total_timeout is 0, there will be no total time limit.

Default: 1000
compress (bool)

Compress client requests and server responses.

Use zlib compression on write or batch read commands when the command buffer size is greater than 128 bytes. In addition, tell the server to compress it's response on read commands. The server response compression threshold is also 128 bytes.

This option will increase cpu and memory usage (for extra compressed buffers), but decrease the size of data sent over the network.

Default: False
key

One of the POLICY_KEY values such as aerospike.POLICY_KEY_DIGEST

Default: aerospike.POLICY_KEY_DIGEST
gen

One of the POLICY_GEN values such as aerospike.POLICY_GEN_IGNORE

Default: aerospike.POLICY_GEN_IGNORE
ttl (int)
The default time-to-live (expiration) of the record in seconds. This field will only be used if an operate transaction contains a write operation and either:
1. Doesn't contain a metadata dictionary with a ttl value.
2. Contains a metadata dictionary with a ttl value set to aerospike.TTL_CLIENT_DEFAULT.
There are also special values that can be set for this option. See TTL_CONSTANTS.
read_touch_ttl_percent
Determine how record TTL (time to live) is affected on reads. When enabled, the server can efficiently operate as a read-based LRU cache where the least recently used records are expired. The value is expressed as a percentage of the TTL sent on the most recent write such that a read within this interval of the record’s end of life will generate a touch.

For example, if the most recent write had a TTL of 10 hours and "read_touch_ttl_percent" is set to 80, the next read within 8 hours of the record's end of life (equivalent to 2 hours after the most recent write) will result in a touch, resetting the TTL to another 10 hours.

Values:
- 0 : Use server config default-read-touch-ttl-pct for the record's namespace/set.
- -1 : Do not reset record TTL on reads.
- 1 - 100 : Reset record TTL on reads when within this percentage of the most recent write TTL.
Default: 0

Note

Requires Aerospike server version >= 7.1.
replica

One of the POLICY_REPLICA values such as aerospike.POLICY_REPLICA_MASTER

Default: aerospike.POLICY_REPLICA_SEQUENCE
commit_level

One of the POLICY_COMMIT_LEVEL values such as aerospike.POLICY_COMMIT_LEVEL_ALL

Default: aerospike.POLICY_COMMIT_LEVEL_ALL
read_mode_ap

One of the POLICY_READ_MODE_AP values such as aerospike.AS_POLICY_READ_MODE_AP_ONE

Default: aerospike.AS_POLICY_READ_MODE_AP_ONE

3.7.0
read_mode_sc

One of the POLICY_READ_MODE_SC values such as aerospike.POLICY_READ_MODE_SC_SESSION

Default: aerospike.POLICY_READ_MODE_SC_SESSION

3.7.0
exists

One of the POLICY_EXISTS values such as aerospike.POLICY_EXISTS_CREATE

Default: aerospike.POLICY_EXISTS_IGNORE
durable_delete (bool)

Perform durable delete

Default: False
deserialize bool

Should raw bytes representing a list or map be deserialized to a Python list or map. Set to false for backup programs that just need access to raw bytes.

Default: :pyTrue
expressions list

Compiled aerospike expressions aerospike_helpers used for filtering records within a transaction.

Default: None

Note

Requires Aerospike server version >= 5.2.

Apply Policies

policy

A dict of optional apply policies, which are applicable to ~Client.apply.

max_retries (int)

Maximum number of retries before aborting the current transaction. The initial attempt is not counted as a retry.

If max_retries is exceeded, the transaction will return error AEROSPIKE_ERR_TIMEOUT.

Default: 0

Warning

Database writes that are not idempotent (such as "add") should not be retried because the write operation may be performed multiple times if the client timed out previous transaction attempts. It's important to use a distinct write policy for non-idempotent writes, which sets max_retries = 0;
sleep_between_retries (int)

Milliseconds to sleep between retries. Enter 0 to skip sleep.

Default: 0
socket_timeout (int)

Socket idle timeout in milliseconds when processing a database command.

If socket_timeout is not 0 and the socket has been idle for at least socket_timeout, both max_retries and total_timeout are checked. If max_retries and total_timeout are not exceeded, the transaction is retried.

If both socket_timeout and total_timeout are non-zero and socket_timeout > total_timeout, then socket_timeout will be set to total_timeout. If socket_timeout is 0, there will be no socket idle limit.

Default: 30000
total_timeout (int)

Total transaction timeout in milliseconds.

The total_timeout is tracked on the client and sent to the server along with the transaction in the wire protocol. The client will most likely timeout first, but the server also has the capability to timeout the transaction.

If total_timeout is not 0 and total_timeout is reached before the transaction completes, the transaction will return error AEROSPIKE_ERR_TIMEOUT. If total_timeout is 0, there will be no total time limit.

Default: 1000
compress (bool)

Compress client requests and server responses.

Use zlib compression on write or batch read commands when the command buffer size is greater than 128 bytes. In addition, tell the server to compress it's response on read commands. The server response compression threshold is also 128 bytes.

This option will increase cpu and memory usage (for extra compressed buffers), but decrease the size of data sent over the network.

Default: False
key

One of the POLICY_KEY values such as aerospike.POLICY_KEY_DIGEST

Default: aerospike.POLICY_KEY_DIGEST
replica

One of the POLICY_REPLICA values such as aerospike.POLICY_REPLICA_MASTER

Default: aerospike.POLICY_REPLICA_SEQUENCE
commit_level

One of the POLICY_COMMIT_LEVEL values such as aerospike.POLICY_COMMIT_LEVEL_ALL

Default: aerospike.POLICY_COMMIT_LEVEL_ALL
ttl (int)

The default time-to-live (expiration) of the record in seconds. This field will only be used if an apply transaction doesn't have an apply policy with a ttl value that overrides this field.

There are also special values that can be set for this field. See TTL_CONSTANTS.
durable_delete (bool)

Perform durable delete

Default: False
expressions list

Compiled aerospike expressions aerospike_helpers used for filtering records within a transaction.

Default: None

Note

Requires Aerospike server version >= 5.2.

Remove Policies

policy

A dict of optional remove policies, which are applicable to ~Client.remove.

max_retries (int)

Maximum number of retries before aborting the current transaction. The initial attempt is not counted as a retry.

If max_retries is exceeded, the transaction will return error AEROSPIKE_ERR_TIMEOUT.

Default: 0

Warning

Database writes that are not idempotent (such as "add") should not be retried because the write operation may be performed multiple times if the client timed out previous transaction attempts. It's important to use a distinct write policy for non-idempotent writes, which sets max_retries = 0;
sleep_between_retries (int)

Milliseconds to sleep between retries. Enter 0 to skip sleep.
Default: 0
socket_timeout (int)

Socket idle timeout in milliseconds when processing a database command.

If socket_timeout is not 0 and the socket has been idle for at least socket_timeout, both max_retries and total_timeout are checked. If max_retries and total_timeout are not exceeded, the transaction is retried.

If both socket_timeout and total_timeout are non-zero and socket_timeout > total_timeout, then socket_timeout will be set to total_timeout. If socket_timeout is 0, there will be no socket idle limit.

Default: 30000
total_timeout (int)

Total transaction timeout in milliseconds.

The total_timeout is tracked on the client and sent to the server along with the transaction in the wire protocol. The client will most likely timeout first, but the server also has the capability to timeout the transaction.

If total_timeout is not 0 and total_timeout is reached before the transaction completes, the transaction will return error AEROSPIKE_ERR_TIMEOUT. If total_timeout is 0, there will be no total time limit.

Default: 1000
compress (bool)

Compress client requests and server responses.

Use zlib compression on write or batch read commands when the command buffer size is greater than 128 bytes. In addition, tell the server to compress it's response on read commands. The server response compression threshold is also 128 bytes.

This option will increase cpu and memory usage (for extra compressed buffers), but decrease the size of data sent over the network.

Default: False
key

One of the POLICY_KEY values such as aerospike.POLICY_KEY_DIGEST

Default: aerospike.POLICY_KEY_DIGEST
commit_level

One of the POLICY_COMMIT_LEVEL values such as aerospike.POLICY_COMMIT_LEVEL_ALL

Default: aerospike.POLICY_COMMIT_LEVEL_ALL
gen

One of the POLICY_GEN values such as aerospike.POLICY_GEN_IGNORE

Default: aerospike.POLICY_GEN_IGNORE
generation (int)

The generation of the record. This value is limited to a 16-bit unsigned integer.
durable_delete (bool)

Perform durable delete

Default: False

Note

Requires Enterprise server version >= 3.10
replica

One of the POLICY_REPLICA values such as aerospike.POLICY_REPLICA_MASTER

Default: aerospike.POLICY_REPLICA_SEQUENCE
expressions list

Compiled aerospike expressions aerospike_helpers used for filtering records within a transaction.

Default: None

Note

Requires Aerospike server version >= 5.2.

Batch Policies

policy

A dict of optional batch policies, which are applicable to ~aerospike.get_many, ~aerospike.exists_many and ~aerospike.select_many.

max_retries (int)

Maximum number of retries before aborting the current transaction. The initial attempt is not counted as a retry.

If max_retries is exceeded, the transaction will return error AEROSPIKE_ERR_TIMEOUT.

Default: 2
sleep_between_retries (int)

Milliseconds to sleep between retries. Enter 0 to skip sleep.

Default: 0
socket_timeout (int)

Socket idle timeout in milliseconds when processing a database command.

If socket_timeout is not 0 and the socket has been idle for at least socket_timeout, both max_retries and total_timeout are checked. If max_retries and total_timeout are not exceeded, the transaction is retried.

If both socket_timeout and total_timeout are non-zero and socket_timeout > total_timeout, then socket_timeout will be set to total_timeout. If socket_timeout is 0, there will be no socket idle limit.

Default: 30000
total_timeout (int)

Total transaction timeout in milliseconds.

The total_timeout is tracked on the client and sent to the server along with the transaction in the wire protocol. The client will most likely timeout first, but the server also has the capability to timeout the transaction.

If total_timeout is not 0 and total_timeout is reached before the transaction completes, the transaction will return error AEROSPIKE_ERR_TIMEOUT. If total_timeout is 0, there will be no total time limit.

Default: 1000
compress (bool)

Compress client requests and server responses.

Use zlib compression on write or batch read commands when the command buffer size is greater than 128 bytes. In addition, tell the server to compress it's response on read commands. The server response compression threshold is also 128 bytes.

This option will increase cpu and memory usage (for extra compressed buffers), but decrease the size of data sent over the network.

Default: False
read_mode_ap

One of the POLICY_READ_MODE_AP values such as aerospike.AS_POLICY_READ_MODE_AP_ONE

Default: aerospike.AS_POLICY_READ_MODE_AP_ONE

3.7.0
read_mode_sc

One of the POLICY_READ_MODE_SC values such as aerospike.POLICY_READ_MODE_SC_SESSION

Default: aerospike.POLICY_READ_MODE_SC_SESSION

3.7.0
read_touch_ttl_percent
Determine how record TTL (time to live) is affected on reads. When enabled, the server can efficiently operate as a read-based LRU cache where the least recently used records are expired. The value is expressed as a percentage of the TTL sent on the most recent write such that a read within this interval of the record’s end of life will generate a touch.

For example, if the most recent write had a TTL of 10 hours and "read_touch_ttl_percent" is set to 80, the next read within 8 hours of the record's end of life (equivalent to 2 hours after the most recent write) will result in a touch, resetting the TTL to another 10 hours.

Values:
- 0 : Use server config default-read-touch-ttl-pct for the record's namespace/set.
- -1 : Do not reset record TTL on reads.
- 1 - 100 : Reset record TTL on reads when within this percentage of the most recent write TTL.
Default: 0

Note

Requires Aerospike server version >= 7.1.
replica

One of the POLICY_REPLICA values such as aerospike.POLICY_REPLICA_MASTER

Default: aerospike.POLICY_REPLICA_SEQUENCE
concurrent (bool)

Determine if batch commands to each server are run in parallel threads.

Default False
allow_inline (bool)

Allow batch to be processed immediately in the server's receiving thread when the server deems it to be appropriate. If False, the batch will always be processed in separate transaction threads. This field is only relevant for the new batch index protocol.

Default True
allow_inline_ssd (bool)

Allow batch to be processed immediately in the server's receiving thread for SSD namespaces. If false, the batch will always be processed in separate service threads. Server versions < 6.0 ignore this field.

Inline processing can introduce the possibility of unfairness because the server can process the entire batch before moving onto the next command.

Default: False
deserialize (bool)

Should raw bytes be deserialized to as_list or as_map. Set to False for backup programs that just need access to raw bytes.

Default: True
expressions list

Compiled aerospike expressions aerospike_helpers used for filtering records within a transaction.

Default: None

Note

Requires Aerospike server version >= 5.2.
respond_all_keys bool

Should all batch keys be attempted regardless of errors. This field is used on both the client and server. The client handles node specific errors and the server handles key specific errors.

If True, every batch key is attempted regardless of previous key specific errors. Node specific errors such as timeouts stop keys to that node, but keys directed at other nodes will continue to be processed.

If False, the server will stop the batch to its node on most key specific errors. The exceptions are AEROSPIKE_ERR_RECORD_NOT_FOUND and AEROSPIKE_FILTERED_OUT which never stop the batch. The client will stop the entire batch on node specific errors for sync commands that are run in sequence (concurrent == false). The client will not stop the entire batch for async commands or sync commands run in parallel.

Server versions < 6.0 do not support this field and treat this value as false for key specific errors.

Default: True

Batch Write Policies

policy

A dict of optional batch write policies, which are applicable to ~aerospike.batch_write, ~aerospike.batch_operate and Write <aerospike_helpers.batch.records>.

key

One of the POLICY_KEY values such as aerospike.POLICY_KEY_DIGEST

Default: aerospike.POLICY_KEY_DIGEST
commit_level

One of the POLICY_COMMIT_LEVEL values such as aerospike.POLICY_COMMIT_LEVEL_ALL

Default: aerospike.POLICY_COMMIT_LEVEL_ALL
gen

One of the POLICY_GEN values such as aerospike.POLICY_GEN_IGNORE

Default: aerospike.POLICY_GEN_IGNORE
exists

One of the POLICY_EXISTS values such as aerospike.POLICY_EXISTS_CREATE

Default: aerospike.POLICY_EXISTS_IGNORE
durable_delete (bool)

Perform durable delete

Default: False
expressions list

Compiled aerospike expressions aerospike_helpers used for filtering records within a transaction.

Default: None
ttl int
The time-to-live (expiration) in seconds to apply to every record in the batch. This field will only be used if:
1. A ~aerospike.Client.batch_write call contains a ~aerospike_helpers.batch.records.Write that:
  1. Doesn't contain a metadata dictionary with a ttl value.
  2. Contains a metadata dictionary with a ttl value set to aerospike.TTL_CLIENT_DEFAULT.
2. A ~aerospike.Client.batch_operate call:
  1. Doesn't pass in a ttl argument.
  2. Passes in aerospike.TTL_CLIENT_DEFAULT to the ttl parameter.
There are also special values that can be set for this field. See TTL_CONSTANTS.

Default: 0

Batch Apply Policies

policy

A dict of optional batch apply policies, which are applicable to ~aerospike.batch_apply, and Apply <aerospike_helpers.batch.records>.

key

One of the POLICY_KEY values such as aerospike.POLICY_KEY_DIGEST

Default: aerospike.POLICY_KEY_DIGEST
commit_level

One of the POLICY_COMMIT_LEVEL values such as aerospike.POLICY_COMMIT_LEVEL_ALL

Default: aerospike.POLICY_COMMIT_LEVEL_ALL
ttl int

Time to live (expiration) of the record in seconds.

See TTL_CONSTANTS for possible special values.

Note that the TTL value will be employed ONLY on write/update calls.

Default: 0
durable_delete bool

If the transaction results in a record deletion, leave a tombstone for the record. This prevents deleted records from reappearing after node failures. Valid for Aerospike Server Enterprise Edition only.

Default: :pyFalse (do not tombstone deleted records).
expressions list

Compiled aerospike expressions aerospike_helpers used for filtering records within a transaction.

Default: None

Batch Remove Policies

policy

A dict of optional batch remove policies, which are applicable to ~aerospike.batch_remove, and Remove <aerospike_helpers.batch.records>.

key

One of the POLICY_KEY values such as aerospike.POLICY_KEY_DIGEST

Default: aerospike.POLICY_KEY_DIGEST
commit_level

One of the POLICY_COMMIT_LEVEL values such as aerospike.POLICY_COMMIT_LEVEL_ALL

Default: aerospike.POLICY_COMMIT_LEVEL_ALL
gen

One of the POLICY_GEN values such as aerospike.POLICY_GEN_IGNORE

Default: aerospike.POLICY_GEN_IGNORE
generation int

Generation of the record.

Default: 0
durable_delete (bool)

Perform durable delete

Default: False
expressions list

Compiled aerospike expressions aerospike_helpers used for filtering records within a transaction.

Default: None

Batch Read Policies

policy

A dict of optional batch read policies, which are applicable to Read <aerospike_helpers.batch.records>.

read_mode_ap

One of the POLICY_READ_MODE_AP values such as aerospike.AS_POLICY_READ_MODE_AP_ONE

Default: aerospike.AS_POLICY_READ_MODE_AP_ONE
read_mode_sc

One of the POLICY_READ_MODE_SC values such as aerospike.POLICY_READ_MODE_SC_SESSION

Default: aerospike.POLICY_READ_MODE_SC_SESSION
expressions list

Compiled aerospike expressions aerospike_helpers used for filtering records within a transaction.

Default: None
read_touch_ttl_percent
Determine how record TTL (time to live) is affected on reads. When enabled, the server can efficiently operate as a read-based LRU cache where the least recently used records are expired. The value is expressed as a percentage of the TTL sent on the most recent write such that a read within this interval of the record’s end of life will generate a touch.

For example, if the most recent write had a TTL of 10 hours and "read_touch_ttl_percent" is set to 80, the next read within 8 hours of the record's end of life (equivalent to 2 hours after the most recent write) will result in a touch, resetting the TTL to another 10 hours.

Values:
- 0 : Use server config default-read-touch-ttl-pct for the record's namespace/set.
- -1 : Do not reset record TTL on reads.
- 1 - 100 : Reset record TTL on reads when within this percentage of the most recent write TTL.
Default: 0

Note

Requires Aerospike server version >= 7.1.

Info Policies

policy

A dict of optional info policies, which are applicable to ~aerospike.info_all, ~aerospike.info_single_node, ~aerospike.info_random_node and index operations.

timeout (int)

Read timeout in milliseconds

Admin Policies

policy

A dict of optional admin policies, which are applicable to admin (security) operations.

timeout (int)

Admin operation timeout in milliseconds

List Policies

policy

A dict of optional list policies, which are applicable to list operations.

write_flags

Write flags for the operation.
One of the aerospike_list_write_flag values such as aerospike.LIST_WRITE_DEFAULT

Default: aerospike.LIST_WRITE_DEFAULT

Values should be or'd together:
aerospike.LIST_WRITE_ADD_UNIQUE | aerospike.LIST_WRITE_INSERT_BOUNDED
list_order

Ordering to maintain for the list.
One of aerospike_list_order, such as aerospike.LIST_ORDERED

Default: aerospike.LIST_UNORDERED

Example:

list_policy = {
    "write_flags": aerospike.LIST_WRITE_ADD_UNIQUE | aerospike.LIST_WRITE_INSERT_BOUNDED,
    "list_order": aerospike.LIST_ORDERED
}

Map Policies

policy

A dict of optional map policies, which are applicable to map operations.

map_write_flags

Write flags for the map operation.
One of the aerospike_map_write_flag values such as aerospike.MAP_WRITE_FLAGS_DEFAULT

Default: aerospike.MAP_WRITE_FLAGS_DEFAULT

Values should be or'd together:
aerospike.LIST_WRITE_ADD_UNIQUE | aerospike.LIST_WRITE_INSERT_BOUNDED

Note

This is only valid for Aerospike Server versions >= 4.3.0.
map_order

Ordering to maintain for the map entries.
One of aerospike_map_order, such as aerospike.MAP_KEY_ORDERED

Default: aerospike.MAP_UNORDERED
persist_index (bool)

If :pyTrue, persist map index. A map index improves lookup performance,
but requires more storage. A map index can be created for a top-level
ordered map only. Nested and unordered map indexes are not supported.

Default: :pyFalse

Example:

# Server >= 4.3.0
map_policy = {
    'map_order': aerospike.MAP_UNORDERED,
    'map_write_flags': aerospike.MAP_WRITE_FLAGS_CREATE_ONLY
}

Bit Policies

policy

A dict of optional bit policies, which are applicable to bitwise operations.

Note

Requires server version >= 4.6.0

bit_write_flags

Write flags for the bit operation.
One of the aerospike_bitwise_write_flag values such as aerospike.BIT_WRITE_DEFAULT

Default: aerospike.BIT_WRITE_DEFAULT

Example:

bit_policy = {
    'bit_write_flags': aerospike.BIT_WRITE_UPDATE_ONLY
}

HyperLogLog Policies

policy

A dict of optional HyperLogLog policies, which are applicable to bit operations.

Note

Requires server version >= 4.9.0

flags

Write flags for the HLL operation.
One of the aerospike_hll_write_flags values such as aerospike.HLL_WRITE_DEFAULT

Default: aerospike.HLL_WRITE_DEFAULT

Example:

HLL_policy = {
    'flags': aerospike.HLL_WRITE_UPDATE_ONLY
}

Misc

Role Objects

Role

A dict describing attributes associated with a specific role:

"privileges": a list of aerospike_privilege_dict.
"whitelist": a list of IP address strings.
"read_quota": a int representing the allowed read transactions per second.
"write_quota": a int representing the allowed write transactions per second.

Privilege Objects

privilege

A dict describing a privilege and where it applies to:

"code": one of the aerospike_privileges values
"ns": optional str specifying the namespace where the privilege applies.

If not specified, the privilege applies globally.
"set": optional str specifying the set within the namespace where the privilege applies.

If not specified, the privilege applies to the entire namespace.

Example:

{'code': aerospike.PRIV_READ, 'ns': 'test', 'set': 'demo'}

Partition Objects

partition_filter

A dict of partition information used by the client to perform partition queries or scans. Useful for resuming terminated queries and querying particular partitions or records.

"begin": Optional int signifying which partition to start at.

Default: 0 (the first partition)
"count": Optional int signifying how many partitions to process.

Default: 4096 (all partitions)
"digest": Optional dict containing the keys "init" and "value" signifying whether the digest has been calculated, and the digest value.
- "init": bool Whether the digest has been calculated.
- "value": bytearray The bytearray value of the digest, should be 20 characters long.
Default: {} (will start from first record in partition)
"partition_status": Optional dict containing partition_status tuples. These can be used to resume a query/scan.

Default: {} (all partitions)

Default: {} (All partitions will be queried/scanned).

# Example of a query policy using partition_filter.

# partition_status is most easily used to resume a query
# and can be obtained by calling Query.get_partitions_status()
partition_status = {
    0: {0, False, False, bytearray([0]*20)}...
}

policy = {
    "partition_filter": {
        "partition_status": partition_status,
        "begin": 0,
        "count": 4096
    },
}

partition_status

Note

Requires Aerospike server version >= 6.0.

A dict of partition status information used by the client to set the partition status of a partition query or scan.

This is useful for resuming either of those.

The dictionary contains these key-value pairs:

"retry": bool represents the overall retry status of this partition query. (i.e. Does this query/scan need to be retried?)
"done": bool represents whether all partitions were finished.

In addition, the dictionary contains keys of the partition IDs (int), and each partition ID is mapped to a tuple containing the status details of a partition.

That tuple has the following values in this order:

id: int represents a partition ID number
init: bool represents whether the digest being queried was calculated.
retry: bool represents whether this partition should be retried.
digest: bytearray represents the digest of the record being queried.

Should be 20 characters long.
bval: int is used in conjunction with "digest" to determine the last record received by a partition query.

Default: {} (All partitions will be queried).

# Example of a query policy using partition_status.

# Here is the form of partition_status.
# partition_status = {
#     0: (0, False, False, bytearray([0]*20), 0)...
# }
partition_status = query.get_partitions_status()

policy = {
    "partition_filter": {
        "partition_status": partition_status,
        "begin": 0,
        "count": 4096
    },
}

Files

client.rst

Latest commit

History

client.rst

File metadata and controls

aerospike.Client --- Client Class

Overview

Boilerplate Code For Examples

Methods

Connection

Record Operations

Batch Operations

String Operations

Numeric Operations

List Operations

Map Operations

Single-Record Transactions

User Defined Functions

Info Operations

Index Operations

Admin Operations

Metrics

User Dictionary

Scan and Query Constructors

Tuples

Key Tuple

Record Tuple

Metadata Dictionary

Policies

Write Policies

Read Policies

Operate Policies

Apply Policies

Remove Policies

Batch Policies

Batch Write Policies

Batch Apply Policies

Batch Remove Policies

Batch Read Policies

Info Policies

Admin Policies

List Policies

Map Policies

Bit Policies

HyperLogLog Policies

Misc

Role Objects

Privilege Objects

Partition Objects

`aerospike.Client` --- Client Class