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 >= 3.10.0 Supports predicate expressions for record operations see
predexp
. Requires server version >= 4.7.0.import aerospike from aerospike import predexp 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]) preds = [ # check that the record has a value < 2 bin 'name' predexp.integer_bin("number"), predexp.integer_value(2), predexp.integer_less(), ] records = [] for i in range(3): try: records.append(client.get(keys[i], policy={"predexp": 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 >= 3.10.0 Supports predicate expressions for batch operations see
predexp
. Requires server version >= 4.7.0import aerospike from aerospike import predexp 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]) preds = [ # check that the record has a value less than 2 in bin 'name' predexp.integer_bin("number"), predexp.integer_value(2), predexp.integer_less(), ] records = client.get_many(keys, policy={"predexp": preds}) 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.
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 >= 3.10.0 Supports predicate expressions for transactions, see
predexp
. Requires server version >= 4.7.0.import aerospike from aerospike import predexp 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)] preds = [ # check that the record has value 'Kim' in bin 'name' predexp.string_bin("name"), predexp.string_value("Kim"), predexp.string_equal(), ] # 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={"predexp": preds}) 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'. preds = [ # check that the record has value 'John' in bin 'name' predexp.string_bin("name"), predexp.string_value("John"), predexp.string_equal(), ] client.operate(key, ops, policy={"predexp": preds}) 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 ¶
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 >= 3.10.0 Supports predicate expressions for apply, scan_apply, and query_apply see
predexp
. Requires server version 4.7.0.import aerospike from aerospike import predexp 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]) preds = [ # check that the record has value < 2 or == 3 in bin 'name' predexp.integer_bin("number"), predexp.integer_value(2), predexp.integer_less(), predexp.integer_bin("number"), predexp.integer_value(3), predexp.integer_equal(), predexp.predexp_or(2), ] policy = {"predexp": preds} 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 ¶
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 (expression) – 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.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
) - 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 (
- predexp
list
- A list of
aerospike.predexp
used as a predicate filter for record, bin, batch, and record UDF operations.Default: None
- predexp
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'}
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)
☃