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.

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.

is_connected()

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

Return type

bool

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 or bytearray.

  • 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()

Record Tuple

record

The record tuple (key, meta: dict, bins) which is returned by various read operations.

  • key the Key Tuple.

  • meta a dict containing {'gen' : genration value, 'ttl': ttl value}.

  • bins a dict containing bin-name/bin-value pairs.

See also

Data Model: Record.

Operations

Record Operations

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

Write a record with a given key to the cluster.

Parameters
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
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
Returns

a Record Tuple. See Unicode Handling.

Raises

RecordNotFound.

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 when get() does not find the record. Code that used to check for meta != 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
Returns

a Record Tuple. See Unicode Handling.

Raises

RecordNotFound.

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 when select() does not find the record. Code that used to check for meta != 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
  • key (tuple) – a Key Tuple tuple associated with the record.

  • val (int) – the optional ttl in seconds, with 0 resolving to the default value in the server config.

  • meta (dict) – optional record metadata to be set.

  • policy (dict) – optional Operate Policies.

Raises

a subclass of AerospikeError.

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
  • key (tuple) – a Key Tuple associated with the record.

  • 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
  • ns (str) – the namespace in the aerospike cluster.

  • set (str) – the set name.

  • key (str or int) – the primary key identifier of the record within the set.

Returns

a RIPEMD-160 digest of the input tuple.

Return type

bytearray

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 a put().

Parameters
  • key (tuple) – a Key Tuple associated with the record.

  • list (list) – the bins names to be removed from the record.

  • meta (dict) – optional record metadata to be set, with field 'ttl' set to int number of seconds or one of the TTL Constants, and 'gen' set to int 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 a None value for metadata and bins in the record tuple.

Parameters
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 a None value for metadata in the result tuple.

Parameters
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 a None value for metadata and bins in the record tuple. The bins will be filtered as specified.

Parameters
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
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
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
  • key (tuple) – a Key Tuple tuple associated with the record.

  • 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 to int number of seconds or one of the TTL Constants, and 'gen' set to int 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
  • key (tuple) – a Key Tuple tuple associated with the record.

  • 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 to int number of seconds or one of the TTL Constants, and 'gen' set to int 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
  • key (tuple) – a Key Tuple tuple associated with the record.

  • bin (str) – the name of the bin.

  • offset (int or float) – the value by which to increment the value in bin.

  • meta (dict) – optional record metadata to be set, with field 'ttl' set to int number of seconds or one of the TTL Constants, and 'gen' set to int generation number to compare.

  • policy (dict) – optional Operate Policies. Note: the exists policy option may not be: aerospike.POLICY_EXISTS_CREATE_OR_REPLACE nor aerospike.POLICY_EXISTS_REPLACE

Raises

a subclass of 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
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 with OPERATOR_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
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 or None) in a namespace. A scan with a None set returns all the records in the namespace.

Parameters
  • namespace (str) – the namespace in the aerospike cluster.

  • set (str) – optional specified set name, otherwise the entire namespace will be scanned.

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 or None) in a namespace. A query with a None set returns records which are not in any named set. This is different than the meaning of a None set in a scan.

Parameters
  • namespace (str) – the namespace in the aerospike cluster.

  • set (str) – optional specified set name, otherwise the records which are not part of any set will be queried (Note: this is different from not providing the set in scan()).

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
  • module (str) – the UDF module to be deregistered from the cluster.

  • policy (dict) – currently timeout in milliseconds is the available policy.

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

list

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

str

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
  • key (tuple) – a Key Tuple associated with the record.

  • 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 (dict) – optional Apply Policies.

Returns

the value optionally returned by the UDF, one of str,int, float, bytearray, list, dict.

Raises

a subclass of AerospikeError.

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

int

Returns

a job ID that can be used with job_info() to check the status of the aerospike.JOB_SCAN.

Raises

a subclass of AerospikeError.

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

int

Returns

a job ID that can be used with job_info() to check the status of the aerospike.JOB_QUERY.

Raises

a subclass of AerospikeError.

aerospike.job_info(job_id, module[, policy: dict]) dict

Return the status of a job running in the background.

Parameters
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, or info_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 output

Send 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

dict

Raises

a subclass of AerospikeError.

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
Return type

dict

Raises

a subclass of AerospikeError.

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, or info_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

str

Raises

a subclass of AerospikeError.

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

str

Raises

a subclass of AerospikeError.

Note

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

aerospike.info_random_node(command[, policy: dict]) str

Send an info command to a single random node.

Parameters
Return type

str

Raises

a subclass of AerospikeError.

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.

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,

Return type

int or None

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
  • 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_name (str) – the name of the index.

  • policy (dict) – optional Info Policies.

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
  • 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_name (str) – the name of the index.

  • policy (dict) – optional Info Policies.

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 and aerospike.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 and aerospike.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 and aerospike.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
  • 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_name (str) – the name of the index.

  • policy (dict) – optional Info Policies.

Raises

a subclass of AerospikeError.

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 (see aerospike.exception).

A user is validated by the client against the server whenever a connection is established through the use of a username and password (passwords hashed using bcrypt). When security is enabled, each operation is validated against the user's roles. Users are assigned roles, which are collections of 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()
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
Raises

one of the AdminError subclasses.

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

Add privileges to a role.

Parameters
Raises

one of the AdminError subclasses.

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

Remove privileges from a role.

Parameters
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
Returns

a Privilege Objects.

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
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
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 to put(), 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;

  • sleep_between_retries (int)
    Milliseconds to sleep between retries. Enter 0 to skip sleep.

    Default: 0
  • socket_timeout (int)
    Socket idle timeout in milliseconds when processing a database command.

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

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

    Default: 0
  • total_timeout (int)
    Total transaction timeout in milliseconds.

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

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

    Default: 1000
  • compress (bool)
    Compress client requests and server responses.

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

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

    Default: False
  • key
  • exists
  • gen
  • commit_level
  • durable_delete (bool)
    Perform durable delete

    Default: False
  • expressions list
    Compiled aerospike expressions aerospike_helpers used for filtering records within a transaction.

    Default: None

    Note

    Requires Aerospike server version >= 5.2.

Read Policies

policy

A dict of optional read policies, which are applicable to get(), 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
  • sleep_between_retries (int)
    Milliseconds to sleep between retries. Enter 0 to skip sleep.

    Default: 0
  • socket_timeout (int)
    Socket idle timeout in milliseconds when processing a database command.

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

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

    Default: 0
  • total_timeout (int)
    Total transaction timeout in milliseconds.

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

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

    Default: 1000
  • compress (bool)
    Compress client requests and server responses.

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

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

    Default: False
  • deserialize (bool)
    Should raw bytes representing a list or map be deserialized to a list or dictionary.
    Set to False for backup programs that just need access to raw bytes.
    Default: True
  • key
  • 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

    New in version 3.7.0.

  • replica

    Default: aerospike.POLICY_REPLICA_SEQUENCE
  • expressions list
    Compiled aerospike expressions aerospike_helpers used for filtering records within a transaction.

    Default: None

    Note

    Requires Aerospike server version >= 5.2.

Operate Policies

policy

A dict of optional operate policies, which are applicable to append(), 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;

  • sleep_between_retries (int)
    Milliseconds to sleep between retries. Enter 0 to skip sleep.

    Default: 0
  • socket_timeout (int)
    Socket idle timeout in milliseconds when processing a database command.

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

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

    Default: 0
  • total_timeout (int)
    Total transaction timeout in milliseconds.

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

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

    Default: 1000
  • compress (bool)
    Compress client requests and server responses.

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

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

    Default: False
  • key
  • gen
  • replica
  • commit_level
  • 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

    New in version 3.7.0.

  • exists
  • durable_delete (bool)
    Perform durable delete

    Default: False
  • expressions list
    Compiled aerospike expressions aerospike_helpers used for filtering records within a transaction.

    Default: None

    Note

    Requires Aerospike server version >= 5.2.

Apply Policies

policy

A dict of optional apply policies, which are applicable to apply().

  • max_retries (int)
    Maximum number of retries before aborting the current transaction. The initial attempt is not counted as a retry.

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

    Default: 0

    Warning

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

  • sleep_between_retries (int)
    Milliseconds to sleep between retries. Enter 0 to skip sleep.

    Default: 0
  • socket_timeout (int)
    Socket idle timeout in milliseconds when processing a database command.

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

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

    Default: 0
  • total_timeout (int)
    Total transaction timeout in milliseconds.

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

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

    Default: 1000
  • compress (bool)
    Compress client requests and server responses.

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

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

    Default: False
  • key
  • replica
  • gen
  • commit_level
  • durable_delete (bool)
    Perform durable delete

    Default: False
  • expressions list
    Compiled aerospike expressions aerospike_helpers used for filtering records within a transaction.

    Default: None

    Note

    Requires Aerospike server version >= 5.2.

Remove Policies

policy

A dict of optional remove policies, which are applicable to remove().

  • max_retries (int)
    Maximum number of retries before aborting the current transaction. The initial attempt is not counted as a retry.

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

    Default: 0

    Warning

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

  • sleep_between_retries (int)
    Milliseconds to sleep between retries. Enter 0 to skip sleep.
    Default: 0
  • socket_timeout (int)
    Socket idle timeout in milliseconds when processing a database command.

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

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

    Default: 0
  • total_timeout (int)
    Total transaction timeout in milliseconds.

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

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

    Default: 1000
  • compress (bool)
    Compress client requests and server responses.

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

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

    Default: False
  • key
  • commit_level
  • gen
  • durable_delete (bool)
    Perform durable delete

    Default: False

    Note

    Requires Enterprise server version >= 3.10

  • replica

    Default: aerospike.POLICY_REPLICA_SEQUENCE
  • expressions list
    Compiled aerospike expressions aerospike_helpers used for filtering records within a transaction.

    Default: None

    Note

    Requires Aerospike server version >= 5.2.

Batch Policies

policy

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

  • max_retries (int)
    Maximum number of retries before aborting the current transaction. The initial attempt is not counted as a retry.

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

    Default: 2
  • sleep_between_retries (int)
    Milliseconds to sleep between retries. Enter 0 to skip sleep.

    Default: 0
  • socket_timeout (int)
    Socket idle timeout in milliseconds when processing a database command.

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

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

    Default: 0
  • total_timeout (int)
    Total transaction timeout in milliseconds.

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

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

    Default: 1000
  • compress (bool)
    Compress client requests and server responses.

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

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

    Default: False
  • read_mode_ap
    One of the 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

    New in version 3.7.0.

  • replica
  • concurrent (bool)
    Determine if batch commands to each server are run in parallel threads.

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

    Default True
  • 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
  • deserialize (bool)
    Should raw bytes be deserialized to as_list or as_map. Set to False for backup programs that just need access to raw bytes.

    Default: True
  • expressions list
    Compiled aerospike expressions aerospike_helpers used for filtering records within a transaction.

    Default: None

    Note

    Requires Aerospike server version >= 5.2.

Batch Write Policies

policy

A dict of optional batch write policies, which are applicable to batch_write(), batch_operate() and Write.

Batch Apply Policies

policy

A dict of optional batch apply policies, which are applicable to batch_apply(), and Apply.

Batch Remove Policies

policy

A dict of optional batch remove policies, which are applicable to batch_remove(), and Remove.

Batch Read Policies

policy

A dict of optional batch read policies, which are applicable to Read.

Info Policies

policy

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

  • timeout (int)
    Read timeout in milliseconds

Admin Policies

policy

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

  • timeout (int)
    Admin operation timeout in milliseconds

List Policies

policy

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

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 of map_write_mode or map_write_flags should be provided. map_write_mode should be used for Aerospike Server versions < 4.3.0 and map_write_flags should be used for Aerospike server versions greater than or equal to 4.3.0 .

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

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

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)

  • 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)