Client Class — Client
¶
Client
¶
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.
See also
Example:
# import the module
import aerospike
from aerospike import exception as ex
import sys
# Configure the client
config = {
'hosts': [ ('127.0.0.1', 3000) ]
}
# Optionally set policies for various method types
write_policies = {'total_timeout': 2000, 'max_retries': 0}
read_policies = {'total_timeout': 1500, 'max_retries': 1}
policies = {'write': write_policies, 'read': read_policies}
config['policies'] = policies
# Create a client and connect it to the cluster
try:
client = aerospike.client(config).connect()
except ex.ClientError as e:
print("Error: {0} [{1}]".format(e.msg, e.code))
sys.exit(1)
# Records are addressable via a tuple of (namespace, set, primary key)
key = ('test', 'demo', 'foo')
try:
# Write a record
client.put(key, {
'name': 'John Doe',
'age': 32
})
except ex.RecordError as e:
print("Error: {0} [{1}]".format(e.msg, e.code))
# Read a record
(key, meta, record) = client.get(key)
# Close the connection to the Aerospike cluster
client.close()
Connection¶
- class aerospike.Client¶
- connect([username, password])¶
Connect to the cluster. The optional username and password only apply when connecting to the Enterprise Edition of Aerospike.
- Parameters
username (str) – a defined user with roles in the cluster. See
admin_create_user()
.password (str) – the password will be hashed by the client using bcrypt.
- Raises
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.
See also
- 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 toconnect()
.- Return type
Changed in version 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.
Key Tuple¶
- key
The key tuple, which is sent and returned by various operations, has the structure
(namespace, set, primary key[, the record's RIPEMD-160 digest])
namespace the
str
name of the namespace, which must be preconfigured on the cluster.set the
str
name of the set. Will be created automatically if it does not exist.primary key the value by which the client-side application identifies the record, which can be of type
str
,int
orbytearray
.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
None
.>>> client = aerospike.client(config).connect() >>> client.put(('test','demo','oof'), {'id':0, 'a':1}) >>> (key, meta, bins) = client.get(('test','demo','oof')) >>> key ('test', 'demo', None, bytearray(b'\ti\xcb\xb9\xb6V#V\xecI#\xealu\x05\x00H\x98\xe4=')) >>> (key2, meta2, bins2) = client.get(key) >>> bins2 {'a': 1, 'id': 0} >>> client.close()See also
Record Tuple¶
- record
The record tuple
(key, meta: dict, bins)
which is returned by various read operations.See also
Operations¶
Record Operations¶
- aerospike.put(key, bins: dict[, meta: dict[, policy: dict[, serializer]]])¶
Write a record with a given key to the cluster.
- Parameters
meta (dict) – optional record metadata to be set, with field
'ttl'
set toint
number of seconds or one of the TTL Constants, and'gen'
set toint
generation number to compare.policy (dict) – optional Write Policies.
serializer – optionally override the serialization mode of the client with one of the Serialization Constants. To use a class-level user-defined serialization function registered with
aerospike.set_serializer()
useaerospike.SERIALIZER_USER
.- Raises
a subclass of
AerospikeError
.import aerospike from aerospike import exception as ex config = { 'hosts': [ ('127.0.0.1', 3000) ], 'total_timeout': 1500 } client = aerospike.client(config).connect() try: key = ('test', 'demo', 1) bins = { 'l': [ "qwertyuiop", 1, bytearray("asd;as[d'as;d", "utf-8") ], 'm': { "key": "asd';q;'1';" }, 'i': 1234, 'f': 3.14159265359, 's': '!@#@#$QSDAsd;as' } client.put(key, bins, policy={'key': aerospike.POLICY_KEY_SEND}, meta={'ttl':180}) # adding a bin client.put(key, {'smiley': u"\ud83d\ude04"}) # removing a bin client.put(key, {'i': aerospike.null()}) except ex.AerospikeError as e: print("Error: {0} [{1}]".format(e.msg, e.code)) sys.exit(1) finally: client.close()Note
Version >= 5.0.0 Supports aerrospike expressions for record operations see aerospike_helpers.expressions package. Requires server version >= 5.2.0.
import aerospike from aerospike_helpers import expressions as exp from aerospike import exception as ex import sys config = {"hosts": [("127.0.0.1", 3000)]} client = aerospike.client(config).connect() try: keys = [("test", "demo", 1), ("test", "demo", 2), ("test", "demo", 3)] records = [{"number": 1}, {"number": 2}, {"number": 3}] for i in range(3): client.put(keys[i], records[i]) # check that the record has a value < 2 bin 'name' expr = exp.LT(exp.IntBin("number"), 2).compile() records = [] for i in range(3): try: records.append(client.get(keys[i], policy={"expressions": preds})) except ex.FilteredOut as e: print("Error: {0} [{1}]".format(e.msg, e.code)) print(records) except ex.AerospikeError as e: print("Error: {0} [{1}]".format(e.msg, e.code)) sys.exit(1) finally: client.close() # the get only returns records that match the preds # otherwise, an error is returned # EXPECTED OUTPUT: # Error: 127.0.0.1:3000 AEROSPIKE_FILTERED_OUT [27] # Error: 127.0.0.1:3000 AEROSPIKE_FILTERED_OUT [27] # [(('test', 'demo', 1, bytearray(b'\xb7\xf4\xb88\x89\xe2\xdag\xdeh>\x1d\xf6\x91\x9a\x1e\xac\xc4F\xc8')), {'gen': 8, 'ttl': 2592000}, {'charges': [10, 20, 14], 'name': 'John', 'number': 1})]Note
Using Generation Policy
The generation policy allows a record to be written only when the generation is a specific value. In the following example, we only want to write the record if no change has occurred since
exists()
was called.import aerospike from aerospike import exception as ex import sys config = { 'hosts': [ ('127.0.0.1',3000)]} client = aerospike.client(config).connect() try: (key, meta) = client.exists(('test','test','key1')) print(meta) print('============') client.put(('test','test','key1'), {'id':1,'a':2}, meta={'gen': 33}, policy={'gen':aerospike.POLICY_GEN_EQ}) print('Record written.') except ex.RecordGenerationError: print("put() failed due to generation policy mismatch") except ex.AerospikeError as e: print("Error: {0} [{1}]".format(e.msg, e.code)) client.close()
- aerospike.exists(key[, policy: dict]) -> (key, meta)¶
Check if a record with a given key exists in the cluster and return the record as a tuple consisting of key and meta. If the record does not exist the meta data will be
None
.
- Parameters
policy (dict) – optional Read Policies.
- Return type
tuple (key, meta)
- Raises
a subclass of
AerospikeError
.import aerospike from aerospike import exception as ex import sys config = { 'hosts': [('127.0.0.1', 3000)] } client = aerospike.client(config).connect() try: # assuming a record with such a key exists in the cluster key = ('test', 'demo', 1) (key, meta) = client.exists(key) print(key) print('--------------------------') print(meta) except ex.RecordNotFound: print("Record not found:", key) except ex.AerospikeError as e: print("Error: {0} [{1}]".format(e.msg, e.code)) sys.exit(1) finally: client.close()Changed in version 2.0.3.
- aerospike.get(key[, policy: dict]) -> (key, meta, bins)¶
Read a record with a given key, and return the record as a tuple consisting of key, meta and bins.
- Parameters
policy (dict) – optional Read Policies.
- Returns
a Record Tuple. See Unicode Handling.
- Raises
import aerospike from aerospike import exception as ex import sys config = {'hosts': [('127.0.0.1', 3000)]} client = aerospike.client(config).connect() try: # assuming a record with such a key exists in the cluster key = ('test', 'demo', 1) (key, meta, bins) = client.get(key) print(key) print('--------------------------') print(meta) print('--------------------------') print(bins) except ex.RecordNotFound: print("Record not found:", key) except ex.AerospikeError as e: print("Error: {0} [{1}]".format(e.msg, e.code)) sys.exit(1) finally: client.close()Warning
The client has been changed to raise a
RecordNotFound
exception whenget()
does not find the record. Code that used to check formeta != None
should be modified.Changed in version 2.0.0.
- aerospike.select(key, bins: list[, policy: dict]) -> (key, meta, bins)¶
Read a record with a given key, and return the record as a tuple consisting of key, meta and bins, with the specified bins projected. Prior to Aerospike server 3.6.0, if a selected bin does not exist its value will be
None
. Starting with 3.6.0, if a bin does not exist it will not be present in the returned Record Tuple.
- Parameters
bins (list) – a list of bin names to select from the record.
policy (dict) – optional Read Policies.
- Returns
a Record Tuple. See Unicode Handling.
- Raises
import aerospike from aerospike import exception as ex import sys config = { 'hosts': [('127.0.0.1', 3000)] } client = aerospike.client(config).connect() try: # assuming a record with such a key exists in the cluster key = ('test', 'demo', 1) (key, meta, bins) = client.select(key, ['name']) print("name: ", bins.get('name')) except ex.RecordNotFound: print("Record not found:", key) except ex.AerospikeError as e: print("Error: {0} [{1}]".format(e.msg, e.code)) sys.exit(1) finally: client.close()Warning
The client has been changed to raise a
RecordNotFound
exception whenselect()
does not find the record. Code that used to check formeta != None
should be modified.Changed in version 2.0.0.
- aerospike.touch(key[, val=0[, meta: dict[, policy: dict]]])¶
Touch the given record, setting its time-to-live and incrementing its generation.
- Parameters
- Raises
a subclass of
AerospikeError
.See also
import aerospike config = { 'hosts': [('127.0.0.1', 3000)] } client = aerospike.client(config).connect() key = ('test', 'demo', 1) client.touch(key, 120, policy={'total_timeout': 100}) client.close()
- aerospike.remove(key[meta: dict[, policy: dict]])¶
Remove a record matching the key from the cluster.
- Parameters
meta (dict) – Optional dictonary allowing a user to specify the expected generation of the record.
policy (dict) – optional Remove Policies. May be passed as a keyword argument.
- Raises
a subclass of
AerospikeError
.import aerospike config = { 'hosts': [('127.0.0.1', 3000)] } client = aerospike.client(config).connect() key = ('test', 'demo', 1) client.remove(key, meta={'gen': 5}, policy={'gen': aerospike.POLICY_GEN_EQ}) client.close()
- aerospike.get_key_digest(ns, set, key) bytearray ¶
Calculate the digest of a particular key. See: Key Tuple.
- Parameters
- Returns
a RIPEMD-160 digest of the input tuple.
- Return type
import aerospike import pprint pp = pprint.PrettyPrinter(indent=2) config = { 'hosts': [('127.0.0.1', 3000)] } client = aerospike.client(config).connect() digest = client.get_key_digest("test", "demo", 1 ) pp.pprint(digest) key = ('test', 'demo', None, digest) (key, meta, bins) = client.get(key) pp.pprint(bins) client.close()Deprecated since version 2.0.1: use the function
aerospike.calc_digest()
instead.Removing a Bin
- aerospike.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 aput()
.
- Parameters
list (list) – the bins names to be removed from the record.
meta (dict) – optional record metadata to be set, with field
'ttl'
set toint
number of seconds or one of the TTL Constants, and'gen'
set toint
generation number to compare.policy (dict) – optional Write Policies.
- Raises
a subclass of
AerospikeError
.import aerospike config = { 'hosts': [('127.0.0.1', 3000)] } client = aerospike.client(config).connect() key = ('test', 'demo', 1) meta = { 'ttl': 3600 } client.remove_bin(key, ['name', 'age'], meta, {'retry': aerospike.POLICY_RETRY_ONCE}) client.close()
Batch Operations¶
- aerospike.get_many(keys[, policy: dict]) [key, meta, bins] ¶
Batch-read multiple records, and return them as a
list
. Any record that does not exist will have aNone
value for metadata and bins in the record tuple.
- Parameters
policy (dict) – optional Batch Policies.
- Returns
a
list
of Record Tuple.- Raises
a
ClientError
if the batch is too big.See also
More information about the Batch Index interface new to Aerospike server >= 3.6.0.
import aerospike from aerospike import exception as ex import sys config = { 'hosts': [('127.0.0.1', 3000)] } client = aerospike.client(config).connect() try: # assume the fourth key has no matching record keys = [ ('test', 'demo', '1'), ('test', 'demo', '2'), ('test', 'demo', '3'), ('test', 'demo', '4') ] records = client.get_many(keys) print(records) except ex.AerospikeError as e: print("Error: {0} [{1}]".format(e.msg, e.code)) sys.exit(1) finally: client.close()Note
We expect to see something like:
[ (('test', 'demo', '1', bytearray(b'ev\xb4\x88\x8c\xcf\x92\x9c \x0bo\xbd\x90\xd0\x9d\xf3\xf6\xd1\x0c\xf3')), {'gen': 1, 'ttl': 2592000}, {'age': 1, 'name': u'Name1'}), (('test', 'demo', '2', bytearray(b'n\xcd7p\x88\xdcF\xe1\xd6\x0e\x05\xfb\xcbs\xa68I\xf0T\xfd')), {'gen': 1, 'ttl': 2592000}, {'age': 2, 'name': u'Name2'}), (('test', 'demo', '3', bytearray(b'\x9f\xf2\xe3\xf3\xc0\xc1\xc3q\xb5$n\xf8\xccV\xa9\xed\xd91a\x86')), {'gen': 1, 'ttl': 2592000}, {'age': 3, 'name': u'Name3'}), (('test', 'demo', '4', bytearray(b'\x8eu\x19\xbe\xe0(\xda ^\xfa\x8ca\x93s\xe8\xb3%\xa8]\x8b')), None, None) ]Note
Version >= 5.0.0 Supports aerrospike expressions for batch operations see aerospike_helpers.expressions package. Requires server version >= 5.2.0.
import aerospike from aerospike_helpers import expressions as exp from aerospike import exception as ex import sys config = {"hosts": [("127.0.0.1", 3000)]} client = aerospike.client(config).connect() try: keys = [("test", "demo", 1), ("test", "demo", 2), ("test", "demo", 3)] records = [{"number": 1}, {"number": 2}, {"number": 3}] for i in range(3): client.put(keys[i], records[i]) # check that the record has a value less than 2 in bin 'name' expr = exp.LT(exp.IntBin("number"), 2).compile() records = client.get_many(keys, policy={"expressions": expr}) print(records) except ex.AerospikeError as e: print("Error: {0} [{1}]".format(e.msg, e.code)) sys.exit(1) finally: client.close() # the get_many only returns the records that matched the preds # EXPECTED OUTPUT: # [ # (('test', 'demo', 1, bytearray(b'\xb7\xf4\xb88\x89\xe2\xdag\xdeh>\x1d\xf6\x91\x9a\x1e\xac\xc4F\xc8')), {'gen': 8, 'ttl': 2592000}, {'charges': [10, 20, 14], 'name': 'John', 'number': 1}), # (('test', 'demo', 2, bytearray(b'\xaejQ_7\xdeJ\xda\xccD\x96\xe2\xda\x1f\xea\x84\x8c:\x92p')), None, None), # ('test', 'demo', 3, bytearray(b'\xb1\xa5`g\xf6\xd4\xa8\xa4D9\xd3\xafb\xbf\xf8ha\x01\x94\xcd')), None, None) # ]Warning
The return type changed to
list
starting with version 1.0.50.
- aerospike.exists_many(keys[, policy: dict]) [key, meta] ¶
Batch-read metadata for multiple keys, and return it as a
list
. Any record that does not exist will have aNone
value for metadata in the result tuple.
- Parameters
policy (dict) – optional Batch Policies.
- Returns
a
list
of (key, metadata) tuple.See also
More information about the Batch Index interface new to Aerospike server >= 3.6.0.
import aerospike from aerospike import exception as ex import sys config = { 'hosts': [('127.0.0.1', 3000)] } client = aerospike.client(config).connect() try: # assume the fourth key has no matching record keys = [ ('test', 'demo', '1'), ('test', 'demo', '2'), ('test', 'demo', '3'), ('test', 'demo', '4') ] records = client.exists_many(keys) print(records) except ex.AerospikeError as e: print("Error: {0} [{1}]".format(e.msg, e.code)) sys.exit(1) finally: client.close()Note
We expect to see something like:
[ (('test', 'demo', '1', bytearray(b'ev\xb4\x88\x8c\xcf\x92\x9c \x0bo\xbd\x90\xd0\x9d\xf3\xf6\xd1\x0c\xf3')), {'gen': 2, 'ttl': 2592000}), (('test', 'demo', '2', bytearray(b'n\xcd7p\x88\xdcF\xe1\xd6\x0e\x05\xfb\xcbs\xa68I\xf0T\xfd')), {'gen': 7, 'ttl': 1337}), (('test', 'demo', '3', bytearray(b'\x9f\xf2\xe3\xf3\xc0\xc1\xc3q\xb5$n\xf8\xccV\xa9\xed\xd91a\x86')), {'gen': 9, 'ttl': 543}), (('test', 'demo', '4', bytearray(b'\x8eu\x19\xbe\xe0(\xda ^\xfa\x8ca\x93s\xe8\xb3%\xa8]\x8b')), None) ]Warning
The return type changed to
list
starting with version 1.0.50.
- aerospike.select_many(keys, bins: list[, policy: dict]) [(key, meta, bins), ...]} ¶
Batch-read multiple records, and return them as a
list
. Any record that does not exist will have aNone
value for metadata and bins in the record tuple. The bins will be filtered as specified.
- Parameters
bins (list) – the bin names to select from the matching records.
policy (dict) – optional Batch Policies.
- Returns
a
list
of Record Tuple.See also
More information about the Batch Index interface new to Aerospike server >= 3.6.0.
import aerospike from aerospike import exception as ex import sys config = { 'hosts': [('127.0.0.1', 3000)] } client = aerospike.client(config).connect() try: # assume the fourth key has no matching record keys = [ ('test', 'demo', None, bytearray(b'ev\xb4\x88\x8c\xcf\x92\x9c \x0bo\xbd\x90\xd0\x9d\xf3\xf6\xd1\x0c\xf3'), ('test', 'demo', None, bytearray(b'n\xcd7p\x88\xdcF\xe1\xd6\x0e\x05\xfb\xcbs\xa68I\xf0T\xfd'), ('test', 'demo', None, bytearray(b'\x9f\xf2\xe3\xf3\xc0\xc1\xc3q\xb5$n\xf8\xccV\xa9\xed\xd91a\x86'), ('test', 'demo', None, bytearray(b'\x8eu\x19\xbe\xe0(\xda ^\xfa\x8ca\x93s\xe8\xb3%\xa8]\x8b') ] records = client.select_many(keys, [u'name']) print(records) except ex.AerospikeError as e: print("Error: {0} [{1}]".format(e.msg, e.code)) sys.exit(1) finally: client.close()Note
We expect to see something like:
[ (('test', 'demo', None, bytearray(b'ev\xb4\x88\x8c\xcf\x92\x9c \x0bo\xbd\x90\xd0\x9d\xf3\xf6\xd1\x0c\xf3'), {'gen': 1, 'ttl': 2592000}, {'name': u'Name1'}), (('test', 'demo', None, bytearray(b'n\xcd7p\x88\xdcF\xe1\xd6\x0e\x05\xfb\xcbs\xa68I\xf0T\xfd'), {'gen': 1, 'ttl': 2592000}, {'name': u'Name2'}), (('test', 'demo', None, bytearray(b'\x9f\xf2\xe3\xf3\xc0\xc1\xc3q\xb5$n\xf8\xccV\xa9\xed\xd91a\x86'), {'gen': 1, 'ttl': 2592000}, {'name': u'Name3'}), (('test', 'demo', None, bytearray(b'\x8eu\x19\xbe\xe0(\xda ^\xfa\x8ca\x93s\xe8\xb3%\xa8]\x8b'), None, None) ]Warning
The return type changed to
list
starting with version 1.0.50.
- aerospike.batch_write(batch_records: BatchRecords[, policy: dict]) BatchRecords ¶
Note
Requires server version >= 6.0.0.
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 records and status are set in batch_records record and result fields.
Note
batch_write modifies the batch_records parameter.
- Parameters
batch_records (BatchRecords) – A BatchRecords object used to specify the operations to carry out.
policy (dict) – Optional aerospike batch policy Batch Policies.
- Returns
A reference to the batch_records argument of type
BatchRecords
.- Raises
A subclass of
AerospikeError
.See also
More information about the batch helpers aerospike_helpers.batch package
See also
More information about the Batch Index
import aerospike from aerospike import exception as ex from aerospike_helpers.batch import records as br import aerospike_helpers.expressions as exp from aerospike_helpers.operations import operations as op import sys config = { 'hosts': [('127.0.0.1', 3000)] } client = aerospike.client(config).connect() # Apply different operations to different keys # using batch_write. w_batch_record = br.BatchRecords( [ br.Remove( key=(namespace, set, 1), policy={} ), br.Write( key=(namespace, set, 100), ops=[ op.write("id", 100), op.write("balance", 100), op.read("id"), op.read("id"), ], policy={"expressions": exp.GT(exp.IntBin("balance"), 2000).compile()} ), br.Read( key=(namespace, set, 333), ops=[ op.read("id") ], policy=None ), ] ) try: # batch_write modifies its BatchRecords argument. # Results for each BatchRecord will be set in their result, # record, and in_doubt fields. client.batch_write(w_batch_record) for batch_record in w_batch_record.batch_records: print(batch_record.result) print(batch_record.record) except ex.AerospikeError as e: print("Error: {0} [{1}]".format(e.msg, e.code)) sys.exit(1) finally: client.close()
- aerospike.batch_operate(keys: list, ops: list[, policy_batch: dict][, policy_batch_write: dict]) BatchRecords ¶
Note
Requires server version >= 6.0.0.
Perform the same read/write operations on multiple keys.
- Parameters
keys (list) – The keys to operate on.
ops (list) – List of operations to apply.
policy_batch (dict) – Optional aerospike batch policy Batch Policies.
policy_batch_write (dict) – Optional aerospike batch write policy Batch Write Policies.
- Returns
an instance of
BatchRecords
.- Raises
A subclass of
AerospikeError
.See also
More information about the Batch Index
import aerospike from aerospike import exception as ex from aerospike_helpers.batch import records as br import aerospike_helpers.expressions as exp from aerospike_helpers.operations import operations as op import sys config = { 'hosts': [('127.0.0.1', 3000)] } client = aerospike.client(config).connect() # Batch add 10 to the bin "balance" and read it if it's over # 1000 NOTE: batch_operate ops must include a write op # get_batch_ops or get_many can be used for all read ops use cases. expr = exp.GT(exp.IntBin("balance"), 1000).compile() ops = [ op.increment("balance", 10), op.read("balance") ] policy_batch = {"expressions": expr} try: res = client.batch_operate(keys, ops, policy_batch) except ex.AerospikeError as e: print("Error: {0} [{1}]".format(e.msg, e.code)) client.close() sys.exit(1) # res is an instance of BatchRecords # the field, batch_records, contains a BatchRecord instance # for each key used by the batch_operate call. # the field, results, is 0 if all batch subtransactions completed succesfully # or the only failures are FILTERED_OUT or RECORD_NOT_FOUND. # Otherwise its value corresponds to an as_status error code and signifies that # one or more of the batch subtransactions failed. Each BatchRecord instance # also has a results field that signifies the status of that batch subtransaction. if res.result == 0: # BatchRecord 100 should have a result code of 27 meaning it was filtered out by an expression. print("BatchRecord 100 result: {result}".format(result=res.batch_records[100].result)) # BatchRecord 100 should, record be None. print("BatchRecord 100 record: {record}".format(record=res.batch_records[100].record)) # BatchRecord 101 should have a result code of 0 meaning it succeeded. print("BatchRecord 101 result: {result}".format(result=res.batch_records[101].result)) # BatchRecord 101, record should be populated. print("BatchRecord 101 record: {record}".format(record=res.batch_records[101].record)) else: # Some batch sub transaction failed. print("res result: {result}".format(result=res.result)) client.close()
- aerospike.batch_apply(keys: list, module: str, function: str, args: list[, policy_batch: dict][, policy_batch_apply: dict]) BatchRecords ¶
Note
Requires server version >= 6.0.0.
Apply UDF (user defined function) on multiple keys.
- Parameters
keys (list) – The keys to operate on.
module (str) – the name of the UDF module.
function (str) – the name of the UDF to apply to the record identified by key.
args (list) – the arguments to the UDF.
policy_batch (dict) – Optional aerospike batch policy Batch Policies.
policy_batch_apply (dict) – Optional aerospike batch apply policy Batch Apply Policies.
- Returns
an instance of
BatchRecords
.- Raises
A subclass of
AerospikeError
.See also
More information about the Batch Index
import aerospike from aerospike import exception as ex import sys config = { 'hosts': [('127.0.0.1', 3000)] } client = aerospike.client(config).connect() keys = [(namespace, set, i) for i in range(10)] # Apply a user defined function (UDF) to a batch # of records using batch_apply. module = "test_record_udf" path_to_module = "/path/to/test_record_udf.lua" function = "bin_udf_operation_integer" args = ["balance", 10, 5] client.udf_put(path_to_module) try: # This should add 15 to each balance bin. res = client.batch_apply(keys, module, function, args) except ex.AerospikeError as e: print("Error: {0} [{1}]".format(e.msg, e.code)) client.close() sys.exit(1) print("res result: {result}".format(result=res.result)) for batch_record in res.batch_records: print(batch_record.result) print(batch_record.record) client.close() # bin_udf_operation_integer lua # --[[UDF which performs arithmetic operation on bin containing # integer value. # --]] # function bin_udf_operation_integer(record, bin_name, x, y) # record[bin_name] = (record[bin_name] + x) + y # if aerospike:exists(record) then # aerospike:update(record) # else # aerospike:create(record) # end # return record[bin_name] # end
- aerospike.batch_remove(keys: list[, policy_batch: dict][, policy_batch_remove: dict]) BatchRecords ¶
Note
Requires server version >= 6.0.0.
Remove multiple records by key.
- Parameters
keys (list) – The keys to remove.
policy_batch (dict) – Optional aerospike batch policy Batch Policies.
policy_batch_remove (dict) – Optional aerospike batch remove policy Batch Remove Policies.
- Returns
an instance of
BatchRecords
.- Raises
A subclass of
AerospikeError
.See also
More information about the Batch Index
import aerospike from aerospike import exception as ex import sys config = { 'hosts': [('127.0.0.1', 3000)] } client = aerospike.client(config).connect() keys = [(namespace, set, i) for i in range(10)] # Delete the records using batch_remove try: res = client.batch_remove(keys) except ex.AerospikeError as e: print("Error: {0} [{1}]".format(e.msg, e.code)) client.close() sys.exit(1) # Should be 0 signifying success. print("BatchRecords result: {result}".format(result=res.result)) client.close()
String Operations¶
Note
Please see
aerospike_helpers.operations.operations
for the new way to use string operations.
- aerospike.append(key, bin, val[, meta: dict[, policy: dict]])¶
Append the string val to the string value in bin.
- Parameters
bin (str) – the name of the bin.
val (str) – the string to append to the value of bin.
meta (dict) – optional record metadata to be set, with field
'ttl'
set toint
number of seconds or one of the TTL Constants, and'gen'
set toint
generation number to compare.policy (dict) – optional Operate Policies.
- Raises
a subclass of
AerospikeError
.import aerospike from aerospike import exception as ex import sys config = { 'hosts': [('127.0.0.1', 3000)] } client = aerospike.client(config).connect() try: key = ('test', 'demo', 1) client.append(key, 'name', ' jr.', policy={'total_timeout': 1200}) except ex.AerospikeError as e: print("Error: {0} [{1}]".format(e.msg, e.code)) sys.exit(1) finally: client.close()
- aerospike.prepend(key, bin, val[, meta: dict[, policy: dict]])¶
Prepend the string value in bin with the string val.
- Parameters
bin (str) – the name of the bin.
val (str) – the string to prepend to the value of bin.
meta (dict) – optional record metadata to be set, with field
'ttl'
set toint
number of seconds or one of the TTL Constants, and'gen'
set toint
generation number to compare.policy (dict) – optional Operate Policies.
- Raises
a subclass of
AerospikeError
.import aerospike from aerospike import exception as ex import sys config = { 'hosts': [('127.0.0.1', 3000)] } client = aerospike.client(config).connect() try: key = ('test', 'demo', 1) client.prepend(key, 'name', 'Dr. ', policy={'total_timeout': 1200}) except ex.AerospikeError as e: print("Error: {0} [{1}]".format(e.msg, e.code)) sys.exit(1) finally: client.close()
Numeric Operations¶
Note
Please see
aerospike_helpers.operations.operations
for the new way to use numeric operations using the operate command.
- aerospike.increment(key, bin, offset[, meta: dict[, policy: dict]])¶
Increment the integer value in bin by the integer val.
- Parameters
bin (str) – the name of the bin.
offset (
int
orfloat
) – the value by which to increment the value in bin.meta (dict) – optional record metadata to be set, with field
'ttl'
set toint
number of seconds or one of the TTL Constants, and'gen'
set toint
generation number to compare.policy (dict) – optional Operate Policies. Note: the
exists
policy option may not be:aerospike.POLICY_EXISTS_CREATE_OR_REPLACE
noraerospike.POLICY_EXISTS_REPLACE
- Raises
a subclass of
AerospikeError
.import aerospike from aerospike import exception as ex import sys config = { 'hosts': [('127.0.0.1', 3000)] } client = aerospike.client(config).connect() try: client.put(('test', 'cats', 'mr. peppy'), {'breed':'persian'}, policy={'exists': aerospike.POLICY_EXISTS_CREATE_OR_REPLACE}) (key, meta, bins) = client.get(('test', 'cats', 'mr. peppy')) print("Before:", bins, "\n") client.increment(key, 'lives', -1) (key, meta, bins) = client.get(key) print("After:", bins, "\n") client.increment(key, 'lives', -1) (key, meta, bins) = client.get(key) print("Poor Kitty:", bins, "\n") print(bins) except ex.AerospikeError as e: print("Error: {0} [{1}]".format(e.msg, e.code)) sys.exit(1) finally: client.close()
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.
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-Record Transactions¶
- aerospike.operate(key, operations: 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 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
None
value. )
- Parameters
operations (list) – a
list
of one or more bin operations, each structured as thedict
{'bin': bin name, 'op': aerospike.OPERATOR_* [, 'val': value]}
. See aerospike_helpers.operations package.meta (dict) – optional record metadata to be set, with field
'ttl'
set toint
number of seconds or one of the TTL Constants, and'gen'
set toint
generation number to compare.policy (dict) – optional Operate Policies.
- Returns
a Record Tuple. See Unicode Handling.
- Raises
a subclass of
AerospikeError
.Note
Version >= 5.0.0 Supports aerrospike expressions for transactions see aerospike_helpers.expressions package. Requires server version >= 5.2.0.
import aerospike from aerospike_helpers import expressions as exp from aerospike_helpers.operations import list_operations, operations from aerospike import exception as ex import sys config = {"hosts": [("127.0.0.1", 3000)]} client = aerospike.client(config).connect() try: unique_id = 1 key = ("test", "demo", unique_id) client.put(key, {"name": "John", "charges": [10, 20, 14]}) ops = [list_operations.list_append("charges", 25)] # check that the record has value 'Kim' in bin 'name' expr = exp.Eq(exp.StrBin("name"), "Kim").compile() # Because the record's name bin is 'John' and not 'Kim', # client.operate() will fail with AEROSPIKE_FILTERED_OUT and the # operations will not be applied. try: client.operate(key, ops, policy={"expressions": expr}) except ex.FilteredOut as e: print("Error: {0} [{1}]".format(e.msg, e.code)) record = client.get(key) print(record) # This client.operate() will succeed because the name bin is 'John'. # check that the record has value 'John' in bin 'name' expr = exp.Eq(exp.StrBin("name"), "John").compile() client.operate(key, ops, policy={"expressions": expr}) record = client.get(key) print(record) except ex.AerospikeError as e: print("Error: {0} [{1}]".format(e.msg, e.code)) sys.exit(1) finally: client.close() # Error: 127.0.0.1:3000 AEROSPIKE_FILTERED_OUT [27] # (('test', 'demo', None, bytearray(b'\xb7\xf4\xb88\x89\xe2\xdag\xdeh>\x1d\xf6\x91\x9a\x1e\xac\xc4F\xc8')), {'ttl': 2592000, 'gen': 23}, {'number': 1, 'name': 'John', 'charges': [10, 20, 14]}) # (('test', 'demo', None, bytearray(b'\xb7\xf4\xb88\x89\xe2\xdag\xdeh>\x1d\xf6\x91\x9a\x1e\xac\xc4F\xc8')), {'ttl': 2592000, 'gen': 24}, {'number': 1, 'name': 'John', 'charges': [10, 20, 14, 25]})Note
In version 2.1.3 the return format of certain bin entries for this method, only in cases when a map operation specifying a return_type is used, has changed. Bin entries for map operations using “return_type” of aerospike.MAP_RETURN_KEY_VALUE will now return a bin value of a list of keys and corresponding values, rather than a list of key/value tuples. See the following code block for details.
# pre 2.1.3 formatting of key/value bin value [('key1', 'val1'), ('key2', 'val2'), ('key3', 'val3')] # >= 2.1.3 formatting ['key1', 'val1', 'key2', 'val2', 'key3', 'val3']Note
operate()
can now have multiple write operations on a single bin.import aerospike from aerospike_helpers.operations import operations as op_helpers from aerospike import exception as ex import sys config = { 'hosts': [('127.0.0.1', 3000)] } client = aerospike.client(config).connect() try: key = ('test', 'demo', 1) client.put(key, {'age': 25, 'career': 'delivery boy'}) ops = [ op_helpers.increment("age", 1000), op_helpers.write("name", "J."), op_helpers.prepend("name", "Phillip "), op_helpers.append("name", " Fry"), op_helpers.read("name"), op_helpers.read("career"), op_helpers.read("age") ] (key, meta, bins) = client.operate(key, ops, {'ttl':360}, {'total_timeout':500}) print(key) print('--------------------------') print(meta) print('--------------------------') print(bins) # will display all bins selected by OPERATOR_READ operations except ex.AerospikeError as e: print("Error: {0} [{1}]".format(e.msg, e.code)) sys.exit(1) finally: client.close()Note
OPERATOR_TOUCH
should only ever combine withOPERATOR_READ
, for example to implement LRU expiry on the records of a set.Warning
Having val associated with
OPERATOR_TOUCH
is deprecated. Use the meta ttl field instead.import aerospike from aerospike import exception as ex import sys config = { 'hosts': [('127.0.0.1', 3000)] } client = aerospike.client(config).connect() try: key = ('test', 'demo', 1) ops = [ { "op" : aerospike.OPERATOR_TOUCH, }, { "op" : aerospike.OPERATOR_READ, "bin": "name" } ] (key, meta, bins) = client.operate(key, ops, {'ttl':1800}) print("Touched the record for {0}, extending its ttl by 30m".format(bins)) except ex.AerospikeError as e: print("Error: {0} [{1}]".format(e.msg, e.code)) sys.exit(1) finally: client.close()Changed in version 2.1.3.
- aerospike.operate_ordered(key, operations: 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.
- Parameters
operations (list) – a
list
of one or more bin operations, each structured as thedict
{'bin': bin name, 'op': aerospike.OPERATOR_* [, 'val': value]}
. See aerospike_helpers.operations package.meta (dict) – optional record metadata to be set, with field
'ttl'
set toint
number of seconds or one of the TTL Constants, and'gen'
set toint
generation number to compare.policy (dict) – optional Operate Policies.
- Returns
a Record Tuple. See Unicode Handling.
- Raises
a subclass of
AerospikeError
.Note
In version 2.1.3 the return format of bin entries for this method, only in cases when a map operation specifying a return_type is used, has changed. Map operations using “return_type” of aerospike.MAP_RETURN_KEY_VALUE will now return a bin value of a list of keys and corresponding values, rather than a list of key/value tuples. See the following code block for details. In addition, some operations which did not return a value in versions <= 2.1.2 will now return a response.
# pre 2.1.3 formatting of key/value bin value [('key1', 'val1'), ('key2', 'val2'), ('key3', 'val3')] # >= 2.1.3 formatting ['key1', 'val1', 'key2', 'val2', 'key3', 'val3']import aerospike from aerospike import exception as ex from aerospike_helpers.operations import operations as op_helpers import sys config = { 'hosts': [('127.0.0.1', 3000)] } client = aerospike.client(config).connect() try: key = ('test', 'demo', 1) policy = { 'total_timeout': 1000, 'key': aerospike.POLICY_KEY_SEND, 'commit_level': aerospike.POLICY_COMMIT_LEVEL_MASTER } llist = [ op_helpers.append("name", "aa"), op_helpers.read("name"), op_helpers.increment("age", 3), op_helpers.read("age") ] client.operate_ordered(key, llist, {}, policy) except ex.AerospikeError as e: print("Error: {0} [{1}]".format(e.msg, e.code)) sys.exit(1) finally: client.close()Changed in version 2.1.3.
Scan and Query¶
- aerospike.scan(namespace[, set]) Scan ¶
Deprecated since version 7.0.0:
aerospike.Query
should be used instead.Return a
aerospike.Scan
object to be used for executing scans over a specified set (which can be omitted orNone
) in a namespace. A scan with aNone
set returns all the records in the namespace.
- Parameters
- Returns
an
aerospike.Scan
class.
- aerospike.query(namespace[, set]) Query ¶
Return a
aerospike.Query
object to be used for executing queries over a specified set (which can be omitted orNone
) in a namespace. A query with aNone
set returns records which are not in any named set. This is different than the meaning of aNone
set in a scan.
- Parameters
- Returns
an
aerospike.Query
class.
User Defined Functions¶
- aerospike.udf_put(filename[, udf_type=aerospike.UDF_TYPE_LUA[, policy: dict]])¶
Register a UDF module with the cluster.
- Parameters
filename (str) – the path to the UDF module to be registered with the cluster.
udf_type (int) –
aerospike.UDF_TYPE_LUA
.policy (dict) – currently timeout in milliseconds is the available policy.
- Raises
a subclass of
AerospikeError
.Note
Register the UDF module and copy it to the Lua ‘user_path’, a directory that should contain a copy of the modules registered with the cluster.
config = { 'hosts': [ ('127.0.0.1', 3000)], 'lua': { 'user_path': '/path/to/lua/user_path'}} client = aerospike.client(config).connect() client.udf_put('/path/to/my_module.lua') client.close()
- aerospike.udf_remove(module[, policy: dict])¶
Remove a previously registered UDF module from the cluster.
- Parameters
- Raises
a subclass of
AerospikeError
.client.udf_remove('my_module.lua')
- aerospike.udf_list([policy: dict]) [] ¶
Return the list of UDF modules registered with the cluster.
- Parameters
policy (dict) – currently timeout in milliseconds is the available policy.
- Return type
- Raises
a subclass of
AerospikeError
.import aerospike config = {'hosts': [('127.0.0.1', 3000)] } client = aerospike.client(config).connect() print(client.udf_list()) client.close()Note
We expect to see something like:
[{'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}, {'content': bytearray(b''), 'hash': bytearray(b'362ea79c8b64857701c2'), 'name': 'aggregate_udf.lua', 'type': 0}, {'content': bytearray(b''), 'hash': bytearray(b'635f47081431379baa4b'), 'name': 'module.lua', 'type': 0}]
- aerospike.udf_get(module[, language=aerospike.UDF_TYPE_LUA[, policy: dict]]) str ¶
Return the content of a UDF module which is registered with the cluster.
- Parameters
module (str) – the UDF module to read from the cluster.
udf_type (int) –
aerospike.UDF_TYPE_LUA
policy (dict) – currently timeout in milliseconds is the available policy.
- Return type
- Raises
a subclass of
AerospikeError
.
- aerospike.apply(key, module, function, args[, policy: dict])¶
Apply a registered (see
udf_put()
) record UDF to a particular record.
- Parameters
- Returns
the value optionally returned by the UDF, one of
str
,int
,float
,bytearray
,list
,dict
.- Raises
a subclass of
AerospikeError
.See also
Note
Version >= 5.0.0 Supports aerrospike expressions for apply, scan_apply, and query_apply see aerospike_helpers.expressions package. Requires server version >= 5.2.0.
import aerospike from aerospike_helpers import expressions as exp from aerospike import exception as ex import sys config = {"hosts": [("127.0.0.1", 3000)]} client = aerospike.client(config).connect() # register udf try: client.udf_put("/path/to/my_udf.lua") except ex.FilteredOut as e: print("Error: {0} [{1}]".format(e.msg, e.code)) client.close() sys.exit(1) # put records and apply udf try: keys = [("test", "demo", 1), ("test", "demo", 2), ("test", "demo", 3)] records = [{"number": 1}, {"number": 2}, {"number": 3}] for i in range(3): client.put(keys[i], records[i]) # check that the record has value < 2 or == 3 in bin 'number' expr = exp.Or( exp.LT(exp.IntBin("number"), 2), exp.Eq(exp.IntBin("number"), 3) ).compile() policy = {"expressions": expr} client.scan_apply("test", None, "my_udf", "my_udf", ["number", 10], policy) records = client.get_many(keys) print(records) except ex.AerospikeError as e: print("Error: {0} [{1}]".format(e.msg, e.code)) sys.exit(1) finally: client.close() # the udf has only modified the records that matched the preds # EXPECTED OUTPUT: # [ # (('test', 'demo', 1, bytearray(b'\xb7\xf4\xb88\x89\xe2\xdag\xdeh>\x1d\xf6\x91\x9a\x1e\xac\xc4F\xc8')), {'gen': 2, 'ttl': 2591999}, {'number': 11}), # (('test', 'demo', 2, bytearray(b'\xaejQ_7\xdeJ\xda\xccD\x96\xe2\xda\x1f\xea\x84\x8c:\x92p')), {'gen': 12, 'ttl': 2591999}, {'number': 2}), # (('test', 'demo', 3, bytearray(b'\xb1\xa5`g\xf6\xd4\xa8\xa4D9\xd3\xafb\xbf\xf8ha\x01\x94\xcd')), {'gen': 13, 'ttl': 2591999}, {'number': 13}) # ]# contents of my_udf.lua function my_udf(rec, bin, offset) info("my transform: %s", tostring(record.digest(rec))) rec[bin] = rec[bin] + offset aerospike:update(rec) end
- aerospike.scan_apply(ns, set, module, function[, args[, policy: dict[, options]]]) int ¶
Deprecated since version 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.
- Parameters
ns (str) – the namespace in the aerospike cluster.
set (str) – the set name. Should be
None
if the entire namespace is to be scanned.module (str) – the name of the UDF module.
function (str) – the name of the UDF to apply to the records matched by the scan.
args (list) – the arguments to the UDF.
policy (dict) – optional Scan Policies.
options (dict) – the Scan Options that will apply to the scan.
- Return type
- Returns
a job ID that can be used with
job_info()
to check the status of theaerospike.JOB_SCAN
.- Raises
a subclass of
AerospikeError
.See also
- aerospike.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 completed.
- Parameters
ns (str) – the namespace in the aerospike cluster.
set (str) – the set name. Should be
None
if you want to query records in the ns which are in no set.predicate (tuple) – the tuple produced by one of the
aerospike.predicates
methods.module (str) – the name of the UDF module.
function (str) – the name of the UDF to apply to the records matched by the query.
args (list) – the arguments to the UDF.
policy (dict) – optional Write Policies.
- Return type
- Returns
a job ID that can be used with
job_info()
to check the status of theaerospike.JOB_QUERY
.- Raises
a subclass of
AerospikeError
.See also
- aerospike.job_info(job_id, module[, policy: dict]) dict ¶
Return the status of a job running in the background.
- Parameters
job_id (int) – the job ID returned by
scan_apply()
andquery_apply()
.module – one of Job Constants.
- Returns
a
dict
with keys status, records_read, and progress_pct. The value of status is one of Job Statuses.- Raises
a subclass of
AerospikeError
.import aerospike from aerospike import exception as ex import time config = {'hosts': [ ('127.0.0.1', 3000)]} client = aerospike.client(config).connect() try: # run the UDF 'add_val' in Lua module 'simple' on the records of test.demo job_id = client.scan_apply('test', 'demo', 'simple', 'add_val', ['age', 1]) while True: time.sleep(0.25) response = client.job_info(job_id, aerospike.JOB_SCAN) if response['status'] == aerospike.JOB_STATUS_COMPLETED: break print("Job ", str(job_id), " completed") print("Progress percentage : ", response['progress_pct']) print("Number of scanned records : ", response['records_read']) except ex.AerospikeError as e: print("Error: {0} [{1}]".format(e.msg, e.code)) client.close()
- aerospike.scan_info(scan_id) dict ¶
Return the status of a scan running in the background.
- Parameters
scan_id (int) – the scan ID returned by
scan_apply()
.- Returns
a
dict
with keys status, records_scanned, and progress_pct. The value of status is one of Job Statuses.- Raises
a subclass of
AerospikeError
.Deprecated since version 1.0.50: Use
job_info()
instead.import aerospike from aerospike import exception as ex config = {'hosts': [ ('127.0.0.1', 3000)]} client = aerospike.client(config).connect() try: scan_id = client.scan_apply('test', 'demo', 'simple', 'add_val', ['age', 1]) while True: response = client.scan_info(scan_id) if response['status'] == aerospike.SCAN_STATUS_COMPLETED or \ response['status'] == aerospike.SCAN_STATUS_ABORTED: break if response['status'] == aerospike.SCAN_STATUS_COMPLETED: print("Background scan successful") print("Progress percentage : ", response['progress_pct']) print("Number of scanned records : ", response['records_scanned']) print("Background scan status : ", "SCAN_STATUS_COMPLETED") else: print("Scan_apply failed") except ex.AerospikeError as e: print("Error: {0} [{1}]".format(e.msg, e.code)) client.close()
Info Operations¶
- aerospike.get_node_names() [] ¶
Return the list of hosts present in a connected cluster including node names.
- Returns
a
list
of node info dictionaries.- Raises
a subclass of
AerospikeError
.import aerospike config = {'hosts': [('127.0.0.1', 3000)] } client = aerospike.client(config).connect() nodes = client.get_node_names() print(nodes) client.close()Note
We expect to see something like:
[{'address': '1.1.1.1', 'port': 3000, 'node_name': 'BCER199932C'}, {'address': '1.1.1.1', 'port': 3010, 'node_name': 'ADFFE7782CD'}]Changed in version 6.0.0.
- aerospike.get_nodes() [] ¶
Return the list of hosts present in a connected cluster.
- Returns
a
list
of node address tuples.- Raises
a subclass of
AerospikeError
.import aerospike config = {'hosts': [('127.0.0.1', 3000)] } client = aerospike.client(config).connect() nodes = client.get_nodes() print(nodes) client.close()Note
We expect to see something like:
[('127.0.0.1', 3000), ('127.0.0.1', 3010)]Changed in version 3.0.0.
Warning
In versions < 3.0.0
get_nodes
will not work when using TLS
- aerospike.info(command[, hosts[, policy: dict]]) {} ¶
Deprecated since version 3.0.0: Use
info_single_node()
to send a request to a single node, orinfo_all()
to send a request to the entire cluster. Sending requests to specific nodes can be better handled with a simple Python function such as:def info_to_host_list(client, request, hosts, policy=None): output = {} for host in hosts: try: response = client.info_node(request, host, policy) output[host] = response except Exception as e: # Handle the error gracefully here output[host] = e return outputSend an info command to all nodes in the cluster and filter responses to only include nodes specified in a hosts list.
- Parameters
command (str) – the info command.
hosts (list) – a
list
containing an address, port tuple. Example:[('127.0.0.1', 3000)]
policy (dict) – optional Info Policies.
- Return type
- Raises
a subclass of
AerospikeError
.See also
import aerospike config = {'hosts': [('127.0.0.1', 3000)] } client = aerospike.client(config).connect() response = client.info(command) client.close()Note
We expect to see something like:
{'BB9581F41290C00': (None, '127.0.0.1:3000\n'), 'BC3581F41290C00': (None, '127.0.0.1:3010\n')}Changed in version 3.0.0.
- aerospike.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.
- Parameters
command (str) – the info command.
policy (dict) – optional Info Policies.
- Return type
- Raises
a subclass of
AerospikeError
.See also
import aerospike config = {'hosts': [('127.0.0.1', 3000)] } client = aerospike.client(config).connect() response = client.info_all(command) client.close()Note
We expect to see something like:
{'BB9581F41290C00': (None, '127.0.0.1:3000\n'), 'BC3581F41290C00': (None, '127.0.0.1:3010\n')}New in version 3.0.0.
- aerospike.info_node(command, host[, policy: dict]) str ¶
Deprecated since version 6.0.0: Use
info_single_node()
to send a request to a single node, orinfo_all()
to send a request to the entire cluster.Send an info command to a single node specified by host.
- Parameters
command (str) – the info command.
host (tuple) – a tuple containing an address, port , optional tls-name . Example:
('127.0.0.1', 3000)
or when using TLS('127.0.0.1', 4333, 'server-tls-name')
. In order to send an info request when TLS is enabled, the tls-name must be present.policy (dict) – optional Info Policies.
- Return type
- Raises
a subclass of
AerospikeError
.See also
Changed in version 3.0.0.
Warning
for client versions < 3.0.0
info_node
will not work when using TLS
- aerospike.info_single_node(command, host[, policy: dict]) str ¶
Send an info command to a single node specified by host name.
- Parameters
command (str) – the info command.
host (tuple) – a
str
containing a node name. Example: ‘BCER199932C’policy (dict) – optional Info Policies.
- Return type
- Raises
a subclass of
AerospikeError
.Note
Use
get_node_names()
as an easy way to get host IP to node name mappings.See also
- aerospike.info_random_node(command[, policy: dict]) str ¶
Send an info command to a single random node.
- Parameters
command (str) – the info command.
policy (dict) – optional Info Policies.
- Return type
- Raises
a subclass of
AerospikeError
.See also
Changed in version 6.0.0.
- aerospike.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.
- Parameters
data_center (str) – The data center to apply the filter to.
namespace (str) – The namespace to apply the filter to.
expression_filter (AerospikeExpression) – The filter to set. See expressions at
aerospike_helpers
.policy (dict) – optional Info Policies.
- Raises
a subclass of
AerospikeError
.See also
Changed in version 5.0.0.
Warning
Requires Aerospike server version >= 5.3.
- aerospike.get_expression_base64(expression) str ¶
Get the base64 representation of a compiled aerospike expression. See aerospike_helpers.expressions package for more details on expressions.
- Parameters
expression (AerospikeExpression) – The compiled expression whose base64 representation will be returned. See expressions at aerospike_helpers.expressions package.
- Raises
a subclass of
AerospikeError
.# This is an example of getting the base64 representation of an aerospike expression. import aerospike from aerospike_helpers import expressions as exp # Compile expression expr = exp.Eq(exp.IntBin("bin1"), 6).compile() # Get base64 b64 = client.get_expression_base64(expr) # Expected output: "kwGTUQKkYmluMQY=" print(b64)Changed in version 7.0.0.
- aerospike.shm_key() int ¶
Expose the value of the shm_key for this client if shared-memory cluster tending is enabled,
- aerospike.truncate(namespace, set, nanos[, policy: dict])¶
Remove records in specified namespace/set efficiently. This method is many orders of magnitude faster than deleting records one at a time. See Truncate command reference.
Note
Requires Aerospike Server versions >= 3.12
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)
- Parameters
namespace (str) – The namespace on which the truncation operation should be performed.
set (str) – The set to truncate. Pass in
None
to indicate that all records in the namespace should be truncated.nanos (long) – A cutoff threshold indicating that records last updated before the threshold will be removed.Units are in nanoseconds since 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.policy (dict) – Optional Info Policies
- Return type
Status indicating the success of the operation.
- Raises
a subclass of
AerospikeError
.import aerospike import time client = aerospike.client({'hosts': [('localhost', 3000)]}).connect() # Store 10 items in the database for i in range(10): key = ('test', 'truncate', i) record = {'item': i} client.put(key, record) time.sleep(2) current_time = time.time() # Convert the current time to nanoseconds since epoch threshold_ns = int(current_time * 10 ** 9) time.sleep(2) # Make sure some time passes before next round of additions # Store another 10 items into the database for i in range(10, 20): key = ('test', 'truncate', i) record = {'item': i} client.put(key, record) # Store a record in the 'test' namespace without a set key = ('test', None, 'no set') record = ({'item': 'no set'}) client.put(key, record) # Remove all items created before the threshold time # The first 10 records we added will be removed by this call. # The second 10 will remain. client.truncate('test', 'truncate', threshold_ns) # Remove all records from test/truncate. # After this the record with key ('test', None, 'no set') still exists client.truncate('test', 'truncate', 0) # Remove all records from the test namespace client.truncate('test', None, 0) client.close()
Index Operations¶
- aerospike.index_string_create(ns, set, bin, index_name[, policy: dict])¶
Create a string index with index_name on the bin in the specified ns, set.
- Parameters
- Raises
a subclass of
AerospikeError
.
- aerospike.index_integer_create(ns, set, bin, index_name[, policy])¶
Create an integer index with index_name on the bin in the specified ns, set.
- Parameters
- Raises
a subclass of
AerospikeError
.
- aerospike.index_list_create(ns, set, bin, index_datatype, index_name[, policy: dict])¶
Create an index named index_name for numeric, string or GeoJSON values (as defined by index_datatype) on records of the specified ns, set whose bin is a list.
- Parameters
ns (str) – the namespace in the aerospike cluster.
set (str) – the set name.
bin (str) – the name of bin the secondary index is built on.
index_datatype – Possible values are
aerospike.INDEX_STRING
,aerospike.INDEX_NUMERIC
andaerospike.INDEX_GEO2DSPHERE
.index_name (str) – the name of the index.
policy (dict) – optional Info Policies.
- Raises
a subclass of
AerospikeError
.Note
Requires server version >= 3.8.0
- aerospike.index_map_keys_create(ns, set, bin, index_datatype, index_name[, policy: dict])¶
Create an index named index_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.
- Parameters
ns (str) – the namespace in the aerospike cluster.
set (str) – the set name.
bin (str) – the name of bin the secondary index is built on.
index_datatype – Possible values are
aerospike.INDEX_STRING
,aerospike.INDEX_NUMERIC
andaerospike.INDEX_GEO2DSPHERE
.index_name (str) – the name of the index.
policy (dict) – optional Info Policies.
- Raises
a subclass of
AerospikeError
.Note
Requires server version >= 3.8.0
- aerospike.index_map_values_create(ns, set, bin, index_datatype, index_name[, policy: dict])¶
Create an index named index_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.
- Parameters
ns (str) – the namespace in the aerospike cluster.
set (str) – the set name.
bin (str) – the name of bin the secondary index is built on.
index_datatype – Possible values are
aerospike.INDEX_STRING
,aerospike.INDEX_NUMERIC
andaerospike.INDEX_GEO2DSPHERE
.index_name (str) – the name of the index.
policy (dict) – optional Info Policies.
- Raises
a subclass of
AerospikeError
.Note
Requires server version >= 3.8.0
import aerospike client = aerospike.client({ 'hosts': [ ('127.0.0.1', 3000)]}).connect() # 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()
- aerospike.index_geo2dsphere_create(ns, set, bin, index_name[, policy: dict])¶
Create a geospatial 2D spherical index with index_name on the bin in the specified ns, set.
- Parameters
- Raises
a subclass of
AerospikeError
.See also
Note
Requires server version >= 3.7.0
import aerospike client = aerospike.client({ 'hosts': [ ('127.0.0.1', 3000)]}).connect() client.index_geo2dsphere_create('test', 'pads', 'loc', 'pads_loc_geo') client.close()
- aerospike.index_remove(ns, index_name[, policy: dict])¶
Remove the index with index_name from the namespace.
- Parameters
ns (str) – the namespace in the aerospike cluster.
index_name (str) – the name of the index.
policy (dict) – optional Info Policies.
- Raises
a subclass of
AerospikeError
.
Admin Operations¶
Note
The admin methods implement the security features of the Enterprise Edition of Aerospike. These methods will raise a
SecurityNotSupported
when the client is connected to a Community Edition cluster (seeaerospike.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 Privilege Objects.
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()See also
- aerospike.admin_create_role(role, privileges[, policy: dict[, whitelist[, read_quota[, write_quota]]]])¶
Create a custom, named role containing a
list
of privileges, optional whitelist, and quotas.
- Parameters
role (str) – The name of the role.
privileges (list) – A list of Privilege Objects.
policy (dict) – Optional Admin Policies.
whitelist (list) – A list of whitelist IP addresses that can contain wildcards, for example 10.1.2.0/24.
read_quota (int) – Maximum reads per second limit, pass in zero for no limit.
write_quota (int) – Maximum write per second limit, pass in zero for no limit.
- Raises
One of the
AdminError
subclasses.
- aerospike.admin_set_whitelist(role, whitelist[, policy: dict])¶
Add whitelist to a role.
- Parameters
role (str) – The name of the role.
whitelist (list) – List of IP strings the role is allowed to connect to. Setting whitlist to None will clear the whitelist for that role.
policy (dict) – Optional Admin Policies.
- Raises
One of the
AdminError
subclasses.
- aerospike.admin_set_quotas(role[, read_quota[, write_quota[, policy: dict]]])¶
Add quotas to a role.
- Parameters
role (str) – the name of the role.
read_quota (int) – Maximum reads per second limit, pass in zero for no limit.
write_quota (int) – Maximum write per second limit, pass in zero for no limit.
policy (dict) – optional Admin Policies.
- Raises
one of the
AdminError
subclasses.
- aerospike.admin_drop_role(role[, policy: dict])¶
Drop a custom role.
- Parameters
role (str) – the name of the role.
policy (dict) – optional Admin Policies.
- Raises
one of the
AdminError
subclasses.
- aerospike.admin_grant_privileges(role, privileges[, policy: dict])¶
Add privileges to a role.
- Parameters
role (str) – the name of the role.
privileges (list) – a list of Privilege Objects.
policy (dict) – optional Admin Policies.
- Raises
one of the
AdminError
subclasses.
- aerospike.admin_revoke_privileges(role, privileges[, policy: dict])¶
Remove privileges from a role.
- Parameters
role (str) – the name of the role.
privileges (list) – a list of Privilege Objects.
policy (dict) – optional Admin Policies.
- Raises
one of the
AdminError
subclasses.
- aerospike.admin_get_role(role[, policy: dict]) [] ¶
Get the
dict
of privileges, whitelist, and quotas associated with a role.
- Parameters
role (str) – the name of the role.
policy (dict) – optional Admin Policies.
- Returns
- Raises
one of the
AdminError
subclasses.
- aerospike.admin_get_roles([policy: dict]) {} ¶
Get all named roles and their attributes.
- Parameters
policy (dict) – optional Admin Policies.
- Returns
a
dict
of Privilege Objects keyed by role name.- Raises
one of the
AdminError
subclasses.
- aerospike.admin_query_role(role[, policy: dict]) [] ¶
Get the
list
of privileges associated with a role.
- Parameters
role (str) – the name of the role.
policy (dict) – optional Admin Policies.
- Returns
a
list
of Privilege Objects.- Raises
one of the
AdminError
subclasses.
- aerospike.admin_query_roles([policy: dict]) {} ¶
Get all named roles and their privileges.
- Parameters
policy (dict) – optional Admin Policies.
- Returns
a
dict
of Privilege Objects keyed by role name.- Raises
one of the
AdminError
subclasses.
- aerospike.admin_create_user(username, password, roles[, policy: dict])¶
Create a user with a specified username and grant it roles.
- Parameters
username (str) – the username to be added to the aerospike cluster.
password (str) – the password associated with the given username.
roles (list) – the list of role names assigned to the user.
policy (dict) – optional Admin Policies.
- Raises
one of the
AdminError
subclasses.
- aerospike.admin_drop_user(username[, policy: dict])¶
Drop the user with a specified username from the cluster.
- Parameters
username (str) – the username to be dropped from the aerospike cluster.
policy (dict) – optional Admin Policies.
- Raises
one of the
AdminError
subclasses.
- aerospike.admin_change_password(username, password[, policy: dict])¶
Change the password of the user username. This operation can only be performed by that same user.
- Parameters
username (str) – the username.
password (str) – the password associated with the given username.
policy (dict) – optional Admin Policies.
- Raises
one of the
AdminError
subclasses.
- aerospike.admin_set_password(username, password[, policy: dict])¶
Set the password of the user username by a user administrator.
- Parameters
username (str) – the username to be added to the aerospike cluster.
password (str) – the password associated with the given username.
policy (dict) – optional Admin Policies.
- Raises
one of the
AdminError
subclasses.
- aerospike.admin_grant_roles(username, roles[, policy: dict])¶
Add roles to the user username.
- Parameters
username (str) – the username to be granted the roles.
roles (list) – a list of role names.
policy (dict) – optional Admin Policies.
- Raises
one of the
AdminError
subclasses.
- aerospike.admin_revoke_roles(username, roles[, policy: dict])¶
Remove roles from the user username.
- Parameters
username (str) – the username to have the roles revoked.
roles (list) – a list of role names.
policy (dict) – optional Admin Policies.
- Raises
one of the
AdminError
subclasses.
- aerospike.admin_query_user(username[, policy: dict]) [] ¶
Return the list of roles granted to the specified user username.
- Parameters
username (str) – the username to query for.
policy (dict) – optional Admin Policies.
- Returns
a
list
of role names.- Raises
one of the
AdminError
subclasses.
- aerospike.admin_query_users([policy: dict]) {} ¶
Return the
dict
of users, with their roles keyed by username.
- Parameters
policy (dict) – optional Admin Policies.
- Returns
a
dict
of roles keyed by username.- Raises
one of the
AdminError
subclasses.
Policies¶
Write Policies¶
- policy
A
dict
of optional write policies, which are applicable toput()
,query_apply()
.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;
- max_retries (
- sleep_between_retries (
int
) - Milliseconds to sleep between retries. Enter
0
to skip sleep.Default:0
- sleep_between_retries (
- 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 bothsocket_timeout
andtotal_timeout
are non-zero andsocket_timeout
>total_timeout
, thensocket_timeout
will be set tototal_timeout
. Ifsocket_timeout
is0
, there will be no socket idle limit.Default:0
- socket_timeout (
- 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 not0
andtotal_timeout
is reached before the transaction completes, the transaction will return errorAEROSPIKE_ERR_TIMEOUT
. Iftotal_timeout
is0
, there will be no total time limit.Default:1000
- total_timeout (
- 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
- compress (
- key
- One of the Key Policy Options values such as
aerospike.POLICY_KEY_DIGEST
Default:aerospike.POLICY_KEY_DIGEST
- exists
- One of the Existence Policy Options values such as
aerospike.POLICY_EXISTS_CREATE
Default:aerospike.POLICY_EXISTS_IGNORE
- gen
- One of the Generation Policy Options values such as
aerospike.POLICY_GEN_IGNORE
Default:aerospike.POLICY_GEN_IGNORE
- commit_level
- One of the Commit Level Policy Options values such as
aerospike.POLICY_COMMIT_LEVEL_ALL
Default:aerospike.POLICY_COMMIT_LEVEL_ALL
- durable_delete (
bool
) - Perform durable deleteDefault:
False
- durable_delete (
- expressions
list
- Compiled aerospike expressions
aerospike_helpers
used for filtering records within a transaction.Default: NoneNote
Requires Aerospike server version >= 5.2.
- expressions
Read Policies¶
- policy
A
dict
of optional read policies, which are applicable toget()
,exists()
,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
- max_retries (
- sleep_between_retries (
int
) - Milliseconds to sleep between retries. Enter
0
to skip sleep.Default:0
- sleep_between_retries (
- 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 bothsocket_timeout
andtotal_timeout
are non-zero andsocket_timeout
>total_timeout
, thensocket_timeout
will be set tototal_timeout
. Ifsocket_timeout
is0
, there will be no socket idle limit.Default:0
- socket_timeout (
- 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 not0
andtotal_timeout
is reached before the transaction completes, the transaction will return errorAEROSPIKE_ERR_TIMEOUT
. Iftotal_timeout
is0
, there will be no total time limit.Default:1000
- total_timeout (
- 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
- compress (
- 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
- deserialize (
- key
- One of the Key Policy Options values such as
aerospike.POLICY_KEY_DIGEST
Default:aerospike.POLICY_KEY_DIGEST
- read_mode_ap
- One of the AP Read Mode Policy Options values such as
aerospike.AS_POLICY_READ_MODE_AP_ONE
Default:aerospike.AS_POLICY_READ_MODE_AP_ONE
New in version 3.7.0.
- read_mode_sc
- One of the SC Read Mode Policy Options values such as
aerospike.POLICY_READ_MODE_SC_SESSION
New in version 3.7.0.
- replica
- One of the Replica Options 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: NoneNote
Requires Aerospike server version >= 5.2.
- expressions
Operate Policies¶
- policy
A
dict
of optional operate policies, which are applicable toappend()
,prepend()
,increment()
,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;
- max_retries (
- sleep_between_retries (
int
) - Milliseconds to sleep between retries. Enter
0
to skip sleep.Default:0
- sleep_between_retries (
- 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 bothsocket_timeout
andtotal_timeout
are non-zero andsocket_timeout
>total_timeout
, thensocket_timeout
will be set tototal_timeout
. Ifsocket_timeout
is0
, there will be no socket idle limit.Default:0
- socket_timeout (
- 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 not0
andtotal_timeout
is reached before the transaction completes, the transaction will return errorAEROSPIKE_ERR_TIMEOUT
. Iftotal_timeout
is0
, there will be no total time limit.Default:1000
- total_timeout (
- 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
- compress (
- key
- One of the Key Policy Options values such as
aerospike.POLICY_KEY_DIGEST
Default:aerospike.POLICY_KEY_DIGEST
- gen
- One of the Generation Policy Options values such as
aerospike.POLICY_GEN_IGNORE
Default:aerospike.POLICY_GEN_IGNORE
- replica
- One of the Replica Options values such as
aerospike.POLICY_REPLICA_MASTER
Default:aerospike.POLICY_REPLICA_SEQUENCE
- commit_level
- One of the Commit Level Policy Options values such as
aerospike.POLICY_COMMIT_LEVEL_ALL
Default:aerospike.POLICY_COMMIT_LEVEL_ALL
- read_mode_ap
- One of the AP Read Mode Policy Options values such as
aerospike.AS_POLICY_READ_MODE_AP_ONE
Default:aerospike.AS_POLICY_READ_MODE_AP_ONE
New in version 3.7.0.
- read_mode_sc
- One of the SC Read Mode Policy Options values such as
aerospike.POLICY_READ_MODE_SC_SESSION
New in version 3.7.0.
- exists
- One of the Existence Policy Options values such as
aerospike.POLICY_EXISTS_CREATE
Default:aerospike.POLICY_EXISTS_IGNORE
- durable_delete (
bool
) - Perform durable deleteDefault:
False
- durable_delete (
- expressions
list
- Compiled aerospike expressions
aerospike_helpers
used for filtering records within a transaction.Default: NoneNote
Requires Aerospike server version >= 5.2.
- expressions
Apply Policies¶
- policy
A
dict
of optional apply policies, which are applicable toapply()
.- 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;
- max_retries (
- sleep_between_retries (
int
) - Milliseconds to sleep between retries. Enter
0
to skip sleep.Default:0
- sleep_between_retries (
- 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 bothsocket_timeout
andtotal_timeout
are non-zero andsocket_timeout
>total_timeout
, thensocket_timeout
will be set tototal_timeout
. Ifsocket_timeout
is0
, there will be no socket idle limit.Default:0
- socket_timeout (
- 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 not0
andtotal_timeout
is reached before the transaction completes, the transaction will return errorAEROSPIKE_ERR_TIMEOUT
. Iftotal_timeout
is0
, there will be no total time limit.Default:1000
- total_timeout (
- 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
- compress (
- key
- One of the Key Policy Options values such as
aerospike.POLICY_KEY_DIGEST
Default:aerospike.POLICY_KEY_DIGEST
- replica
- One of the Replica Options values such as
aerospike.POLICY_REPLICA_MASTER
Default:aerospike.POLICY_REPLICA_SEQUENCE
- gen
- One of the Generation Policy Options values such as
aerospike.POLICY_GEN_IGNORE
Default:aerospike.POLICY_GEN_IGNORE
- commit_level
- One of the Commit Level Policy Options values such as
aerospike.POLICY_COMMIT_LEVEL_ALL
Default:aerospike.POLICY_COMMIT_LEVEL_ALL
- durable_delete (
bool
) - Perform durable deleteDefault:
False
- durable_delete (
- expressions
list
- Compiled aerospike expressions
aerospike_helpers
used for filtering records within a transaction.Default: NoneNote
Requires Aerospike server version >= 5.2.
- expressions
Remove Policies¶
- policy
A
dict
of optional remove policies, which are applicable toremove()
.- 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;
- max_retries (
- sleep_between_retries (
int
) - Milliseconds to sleep between retries. Enter
0
to skip sleep.Default:0
- sleep_between_retries (
- 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 bothsocket_timeout
andtotal_timeout
are non-zero andsocket_timeout
>total_timeout
, thensocket_timeout
will be set tototal_timeout
. Ifsocket_timeout
is0
, there will be no socket idle limit.Default:0
- socket_timeout (
- 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 not0
andtotal_timeout
is reached before the transaction completes, the transaction will return errorAEROSPIKE_ERR_TIMEOUT
. Iftotal_timeout
is0
, there will be no total time limit.Default:1000
- total_timeout (
- 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
- compress (
- key
- One of the Key Policy Options values such as
aerospike.POLICY_KEY_DIGEST
Default:aerospike.POLICY_KEY_DIGEST
- commit_level
- One of the Commit Level Policy Options values such as
aerospike.POLICY_COMMIT_LEVEL_ALL
Default:aerospike.POLICY_COMMIT_LEVEL_ALL
- gen
- One of the Generation Policy Options values such as
aerospike.POLICY_GEN_IGNORE
Default:aerospike.POLICY_GEN_IGNORE
- durable_delete (
bool
) - Perform durable deleteDefault:
False
Note
Requires Enterprise server version >= 3.10
- durable_delete (
- replica
- One of the Replica Options 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: NoneNote
Requires Aerospike server version >= 5.2.
- expressions
Batch Policies¶
- policy
A
dict
of optional batch policies, which are applicable toget_many()
,exists_many()
andselect_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
- max_retries (
- sleep_between_retries (
int
) - Milliseconds to sleep between retries. Enter
0
to skip sleep.Default:0
- sleep_between_retries (
- 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 bothsocket_timeout
andtotal_timeout
are non-zero andsocket_timeout
>total_timeout
, thensocket_timeout
will be set tototal_timeout
. Ifsocket_timeout
is0
, there will be no socket idle limit.Default:0
- socket_timeout (
- 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 not0
andtotal_timeout
is reached before the transaction completes, the transaction will return errorAEROSPIKE_ERR_TIMEOUT
. Iftotal_timeout
is0
, there will be no total time limit.Default:1000
- total_timeout (
- 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
- compress (
- read_mode_ap
- One of the AP Read Mode Policy Options values such as
aerospike.AS_POLICY_READ_MODE_AP_ONE
Default:aerospike.AS_POLICY_READ_MODE_AP_ONE
New in version 3.7.0.
- read_mode_sc
- One of the SC Read Mode Policy Options values such as
aerospike.POLICY_READ_MODE_SC_SESSION
New in version 3.7.0.
- replica
- One of the Replica Options 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
- concurrent (
- 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 (
- send_set_name (
bool
) - .. deprecated:: in client version 7.0.0, the client ignores this policy and always sends set name to the server.Send set name field to server for every key in the batch for batch index protocol. This is only necessary when authentication is enabled and security roles are defined on a per set basis.Default:
False
- send_set_name (
- 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
- deserialize (
- expressions
list
- Compiled aerospike expressions
aerospike_helpers
used for filtering records within a transaction.Default: NoneNote
Requires Aerospike server version >= 5.2.
- expressions
Batch Write Policies¶
- policy
A
dict
of optional batch write policies, which are applicable tobatch_write()
,batch_operate()
andWrite
.- key
- One of the Key Policy Options values such as
aerospike.POLICY_KEY_DIGEST
Default:aerospike.POLICY_KEY_DIGEST
- commit_level
- One of the Commit Level Policy Options values such as
aerospike.POLICY_COMMIT_LEVEL_ALL
Default:aerospike.POLICY_COMMIT_LEVEL_ALL
- gen
- One of the Generation Policy Options values such as
aerospike.POLICY_GEN_IGNORE
Default:aerospike.POLICY_GEN_IGNORE
- exists
- One of the Existence Policy Options values such as
aerospike.POLICY_EXISTS_CREATE
Default:aerospike.POLICY_EXISTS_IGNORE
- durable_delete (
bool
) - Perform durable deleteDefault:
False
- durable_delete (
- expressions
list
- Compiled aerospike expressions
aerospike_helpers
used for filtering records within a transaction.Default: None
- expressions
Batch Apply Policies¶
- policy
A
dict
of optional batch apply policies, which are applicable tobatch_apply()
, andApply
.- key
- One of the Key Policy Options values such as
aerospike.POLICY_KEY_DIGEST
Default:aerospike.POLICY_KEY_DIGEST
- commit_level
- One of the Commit Level Policy Options 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.0 which means that therecord will adopt the default TTL value from the namespace.0xFFFFFFFF (also, -1 in a signed 32 bit int)which means that the recordwill get an internal “void_time” of zero, and thus will never expire.0xFFFFFFFE (also, -2 in a signed 32 bit int)which means that the recordttl will not change when the record is updated.Note that the TTL value will be employed ONLY on write/update calls.Default: 0
- expressions
list
- Compiled aerospike expressions
aerospike_helpers
used for filtering records within a transaction.Default: None
- expressions
Batch Remove Policies¶
- policy
A
dict
of optional batch remove policies, which are applicable tobatch_remove()
, andRemove
.- key
- One of the Key Policy Options values such as
aerospike.POLICY_KEY_DIGEST
Default:aerospike.POLICY_KEY_DIGEST
- commit_level
- One of the Commit Level Policy Options values such as
aerospike.POLICY_COMMIT_LEVEL_ALL
Default:aerospike.POLICY_COMMIT_LEVEL_ALL
- gen
- One of the Generation Policy Options 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 deleteDefault:
False
- durable_delete (
- expressions
list
- Compiled aerospike expressions
aerospike_helpers
used for filtering records within a transaction.Default: None
- expressions
Batch Read Policies¶
- policy
A
dict
of optional batch read policies, which are applicable toRead
.- read_mode_ap
- One of the AP Read Mode Policy Options values such as
aerospike.AS_POLICY_READ_MODE_AP_ONE
Default:aerospike.AS_POLICY_READ_MODE_AP_ONE
- read_mode_sc
- One of the SC Read Mode Policy Options values such as
aerospike.POLICY_READ_MODE_SC_SESSION
- expressions
list
- Compiled aerospike expressions
aerospike_helpers
used for filtering records within a transaction.Default: None
- expressions
Info Policies¶
- policy
A
dict
of optional info policies, which are applicable toinfo_all()
,info_single_node()
,info_random_node()
and index operations.- timeout (
int
) - Read timeout in milliseconds
- timeout (
Admin Policies¶
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 List Write Flags 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 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. Only one ofmap_write_mode
ormap_write_flags
should be provided.map_write_mode
should be used for Aerospike Server versions < 4.3.0 andmap_write_flags
should be used for Aerospike server versions greater than or equal to 4.3.0 .- map_write_mode
- Write mode for the map operation.One of the Map Write Mode values such as
aerospike.MAP_UPDATE
Default:aerospike.MAP_UPDATE
Note
This should only be used for Server version < 4.3.0.
- map_write_flags
- Write flags for the map operation.One of the 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 Map Order, such as
aerospike.MAP_KEY_ORDERED
Default:aerospike.MAP_UNORDERED
Example:
# Server >= 4.3.0 map_policy = { 'map_order': aerospike.MAP_UNORDERED, 'map_write_flags': aerospike.MAP_WRITE_FLAGS_CREATE_ONLY } # Server < 4.3.0 map_policy = { 'map_order': aerospike.MAP_UNORDERED, 'map_write_mode': aerospike.MAP_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 Bitwise Write Flags 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 HyperLogLog 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 Dictionary
A
dict
describing attributes associated with a specific role.privileges A list of Privilege Objects.
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.
Example:
{'code': aerospike.PRIV_READ, 'ns': 'test', 'set': 'demo'}
Privilege Objects¶
- privilege
A
dict
describing a privilege associated with a specific role.code one of the Privileges values such as
aerospike.PRIV_READ
ns optional namespace, to which the privilege applies, otherwise the privilege applies globally.
set optional set within the ns, to which the privilege applies, otherwise 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 partiton queries/scans. Useful for resuming terminated queries and querying particular partitons/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.# Example digest dict.
digest = {"init": True, "value": bytearray([0]*20)}
Default: {} (will start from first record in partition)
- digest Optional
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, Flase, 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 query/scan during a partition query/scan. Useful for resuming partition query/scans.partition_status is a dictionary with keys “retry” str, “done” str, and a variable amount of id int keys. “retry” corresponds to the overall partition query retry status and maps to a bool. i.e. Does this query/scan need to be retried? “done” represents whether all partitions were finished and maps to a bool. the id keys, called “id” in this documentation correspond to a partition id. “id“‘s value is another dictionary containing status details about that partition. See those values below.
id
int
Represents the 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
Used in conjunction with digest in order to determine the last record recieved by a partition query.
# Example of a query policy using partition_status. # Assume "query" is a valid aerospike Query instance. # partition_status is most easily used to resume a query # and can be obtained by calling Query.get_partitions_status() # Here is the form of partition_status. # partition_status = { # 0: (0, False, Flase, bytearray([0]*20), 0)... # } partition_status = query.get_partitions_status() policy = { "partition_filter": { "partition_status": partition_status, "begin": 0, "count": 4096 }, }
Default:
{}
(All partitions will be queried).
Unicode Handling¶
Both str
and unicode values are converted by the
client into UTF-8 encoded strings for storage on the aerospike server.
Read methods such as get()
,
query()
, scan()
and
operate()
will return that data as UTF-8 encoded
str
values. To get a unicode you will need to manually decode.
Warning
Prior to release 1.0.43 read operations always returned strings as unicode.
>>> client.put(key, { 'name': 'Dr. Zeta Alphabeta', 'age': 47})
>>> (key, meta, record) = client.get(key)
>>> type(record['name'])
<type 'str'>
>>> record['name']
'Dr. Zeta Alphabeta'
>>> client.put(key, { 'name': unichr(0x2603), 'age': 21})
>>> (key, meta, record) = client.get(key)
>>> type(record['name'])
<type 'str'>
>>> record['name']
'\xe2\x98\x83'
>>> print(record['name'])
☃
>>> name = record['name'].decode('utf-8')
>>> type(name)
<type 'unicode'>
>>> name
u'\u2603'
>>> print(name)
☃