Introduction 

Raises

RecordNotFound.

# Get nonexistent record
try:
    client.get(keyTuple)
except ex.RecordNotFound as e:
    print("Error: {0} [{1}]".format(e.msg, e.code))
    # Error: 127.0.0.1:3000 AEROSPIKE_ERR_RECORD_NOT_FOUND [2]

# Get existing record
client.put(keyTuple, {'bin1': 4})
(key, meta, bins) = client.get(keyTuple)

print(key) # ('test', 'demo', None, bytearray(b'...'))
print(meta) # {'ttl': 2592000, 'gen': 1}
print(bins) # {'bin1': 4}

Changed in version 2.0.0.

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

Returns specific bins of a record.

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

Parameters

key (tuple) – a Key Tuple associated with the record.
bins (list) – a list of bin names to select from the record.
policy (dict) – optional Read Policies.

Returns

Raises

RecordNotFound.

# Record to select from
client.put(keyTuple, {'bin1': 4, 'bin2': 3})

# Only get bin1
(key, meta, bins) = client.select(keyTuple, ['bin1'])

# Similar output to get()
print(key) # ('test', 'demo', 'key', bytearray(b'...'))
print(meta) # {'ttl': 2592000, 'gen': 1}
print(bins) # {'bin1': 4}

# Get all bins
(key, meta, bins) = client.select(keyTuple, ['bin1', 'bin2'])
print(bins) # {'bin1': 4, 'bin2': 3}

# Get nonexistent bin
(key, meta, bins) = client.select(keyTuple, ['bin3'])
print(bins) # {}

Changed in version 2.0.0.

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 associated with the record.
val (int) – ttl in seconds, with 0 resolving to the default value in the server config.
meta (dict) – record metadata to be set. see Metadata Dictionary
policy (dict) – see Operate Policies.

Raises

a subclass of AerospikeError.

# Insert record and get its metadata
client.put(keyTuple, bins = {"bin1": 4})
(key, meta) = client.exists(keyTuple)
print(meta) # {'ttl': 2592000, 'gen': 1}

# Explicitly set TTL to 120
# and increment generation
client.touch(keyTuple, 120)

# Record metadata should be updated
(key, meta) = client.exists(keyTuple)
print(meta) # {'ttl': 120, 'gen': 2}

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) – contains the expected generation of the record in a key called "gen".
policy (dict) – see Remove Policies. May be passed as a keyword argument.

Raises

a subclass of AerospikeError.

# Insert a record
client.put(keyTuple, {"bin1": 4})

# Try to remove it with the wrong generation
try:
    client.remove(keyTuple, meta={'gen': 5}, policy={'gen': aerospike.POLICY_GEN_EQ})
except ex.AerospikeError as e:
    # Error: AEROSPIKE_ERR_RECORD_GENERATION [3]
    print("Error: {0} [{1}]".format(e.msg, e.code))

# Remove it ignoring generation
client.remove(keyTuple)

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

digest = client.get_key_digest("test", "demo", "key")
print(digest.hex())
# 3bd475bd0c73f210b67ea83793300eeae576285d

Deprecated since version 2.0.1: use the function aerospike.calc_digest() instead.

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) – record metadata to be set. See Metadata Dictionary.
policy (dict) – optional Write Policies.

Raises

a subclass of AerospikeError.

# Insert record
bins = {"bin1": 0, "bin2": 1}
client.put(keyTuple, bins)

# Remove bin1
client.remove_bin(keyTuple, ['bin1'])

# Only bin2 shold remain
(keyTuple, meta, bins) = client.get(keyTuple)
print(bins)
# {'bin2': 1}

Batch Operations

class aerospike.Client

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

keys (list) – a list of Key Tuple.
policy (dict) – see Batch Policies.

Returns

Raises

a ClientError if the batch is too big.

# Keys
keyTuples = [
    ('test', 'demo', '1'),
    ('test', 'demo', '2'),
    ('test', 'demo', '3'),
]
# Only insert two records with the first and second key
client.put(keyTuples[0], {'bin1': 'value'})
client.put(keyTuples[1], {'bin1': 'value'})

# Try to get records with all three keys
records = client.get_many(keyTuples)
# The third record tuple should have 'meta' and 'bins' set to none
# Because there is no third record
print(records[0])
print(records[1])
print(records[2])

# Expected output:
# (('test', 'demo', '1', bytearray(...)), {'ttl': 2592000, 'gen': 1}, {'bin1': 'value'})
# (('test', 'demo', '2', bytearray(...)), {'ttl': 2592000, 'gen': 1}, {'bin1': 'value'})
# (('test', 'demo', '3', bytearray(...)), None, None)

exists_many(keys[, policy: dict]) → [key, meta]

Batch-read metadata for multiple keys.

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

Parameters

keys (list) – a list of Key Tuple.
policy (dict) – see Batch Policies.

Returns

a list of (key, metadata) tuple for each record.

# Keys
# Only insert two records with the first and second key
keyTuples = [
    ('test', 'demo', '1'),
    ('test', 'demo', '2'),
    ('test', 'demo', '3'),
]
client.put(keyTuples[0], {'bin1': 'value'})
client.put(keyTuples[1], {'bin1': 'value'})

# Check for existence of records using all three keys
keyMetadata = client.exists_many(keyTuples)
print(keyMetadata[0])
print(keyMetadata[1])
print(keyMetadata[2])

# (('test', 'demo', '1', bytearray(...)), {'ttl': 2592000, 'gen': 1})
# (('test', 'demo', '2', bytearray(...)), {'ttl': 2592000, 'gen': 1})
# (('test', 'demo', '3', bytearray(...)), None)

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

Batch-read specific bins from multiple records.

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

Parameters

keys (list) – a list of Key Tuple to read from.
bins (list) – a list of bin names to read from the records.
policy (dict) – see Batch Policies.

Returns

# Insert 4 records with these keys
keyTuples = [
    ('test', 'demo', 1),
    ('test', 'demo', 2),
    ('test', 'demo', 3),
    ('test', 'demo', 4)
]
# Only records 1, 2, 4 have a bin called bin2
client.put(keyTuples[0], {'bin1': 20, 'bin2': 40})
client.put(keyTuples[1], {'bin1': 11, 'bin2': 50})
client.put(keyTuples[2], {'bin1': 50,             'bin3': 20})
client.put(keyTuples[3], {'bin1': 87, 'bin2': 76, 'bin3': 40})

# Get all 4 records and filter out every bin except bin2
records = client.select_many(keyTuples, ['bin2'])
for record in records:
    print(record)

# (('test', 'demo', 1, bytearray(...)), {'ttl': 2592000, 'gen': 1}, {'bin2': 40})
# (('test', 'demo', 2, bytearray(...)), {'ttl': 2592000, 'gen': 1}, {'bin2': 50})
# (('test', 'demo', 3, bytearray(...)), {'ttl': 2592000, 'gen': 1}, {})
# (('test', 'demo', 4, bytearray(...)), {'ttl': 2592000, 'gen': 1}, {'bin2': 76})

batch_get_ops(keys, ops, policy: dict) → [key, meta, bins]

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

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

Parameters

keys (list) – a list of Key Tuple.
ops (list) – a list of operations to apply.
policy (dict) – see Batch Policies.

Returns

Raises

a ClientError if the batch is too big.

# Insert records for 3 players and their scores
keyTuples = [("test", "demo", i) for i in range(1, 4)]
bins = [
    {"scores": [1, 4, 3, 10]},
    {"scores": [20, 1, 4, 28]},
    {"scores": [50, 20, 10, 20]},
]
for keyTuple, bin in zip(keyTuples, bins):
    client.put(keyTuple, bin)

# Get highest scores for each player
from aerospike_helpers.operations import list_operations
ops = [
    list_operations.list_get_by_rank("scores", -1, aerospike.LIST_RETURN_VALUE)
]
records = client.batch_get_ops(keyTuples, ops)

# Print results
for _, _, bins in records:
    print(bins)
# {'scores': 10}
# {'scores': 28}
# {'scores': 50}

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

All transactions are successful.

One or more transactions failed because:

A record was filtered out by an expression

The record was not found

Otherwise if one or more transactions failed, the BatchRecords object will have a result value equal to an as_status error code.

In any case, the BatchRecords object has a list of batch records called batch_records, and each batch record contains the result of that transaction.

batch_write(batch_records: BatchRecords[, policy_batch: dict]) → BatchRecords

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

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

Parameters

batch_records (BatchRecords) – A BatchRecords object used to specify the operations to carry out.
policy_batch (dict) – aerospike batch policy Batch Policies.

Returns

A reference to the batch_records argument of type BatchRecords.

Raises

A subclass of AerospikeError.

from aerospike_helpers.batch import records as br
from aerospike_helpers.operations import operations as op

# Keys
# Only insert two records with the first and second key
keyTuples = [
    ('test', 'demo', 'Robert'),
    ('test', 'demo', 'Daniel'),
    ('test', 'demo', 'Patrick'),
]
client.put(keyTuples[0], {'id': 100, 'balance': 400})
client.put(keyTuples[1], {'id': 101, 'balance': 200})
client.put(keyTuples[2], {'id': 102, 'balance': 300})

# Apply different operations to different keys
batchRecords = br.BatchRecords(
    [
        # Remove Robert from system
        br.Remove(
            key = keyTuples[0],
        ),
        # Modify Daniel's ID and balance
        br.Write(
            key = keyTuples[1],
            ops = [
                op.write("id", 200),
                op.write("balance", 100),
                op.read("id"),
            ],
        ),
        # Read Patrick's ID
        br.Read(
            key = keyTuples[2],
            ops=[
                op.read("id")
            ],
            policy=None
        ),
    ]
)

client.batch_write(batchRecords)

# batch_write modifies its BatchRecords argument.
# Results for each BatchRecord will be set in the result, record, and in_doubt fields.
for batchRecord in batchRecords.batch_records:
    print(batchRecord.result)
    print(batchRecord.record)
# Note how written bins return None if their values aren't read
# And removed records have an empty bins dictionary
# 0
# (('test', 'demo', 'Robert', bytearray(b'...')), {'ttl': 4294967295, 'gen': 0}, {})
# 0
# (('test', 'demo', 'Daniel', bytearray(b'...')), {'ttl': 2592000, 'gen': 2}, {'id': 200, 'balance': None})
# 0
# (('test', 'demo', 'Patrick', bytearray(b'...')), {'ttl': 2592000, 'gen': 1}, {'id': 102})

Note

Requires server version >= 6.0.0.

See also

More information about the batch helpers aerospike_helpers.batch package

batch_operate(keys: list, ops: list[, policy_batch: dict][, policy_batch_write: dict]) → BatchRecords

Perform the same read/write transactions on multiple keys.

Parameters

keys (list) – The keys to operate on.
ops (list) – List of operations to apply.
policy_batch (dict) – See Batch Policies.
policy_batch_write (dict) – See Batch Write Policies.

Returns

an instance of BatchRecords.

Raises

A subclass of AerospikeError.

from aerospike_helpers.operations import operations as op

# Insert 3 records
keys = [("test", "demo", f"employee{i}") for i in range(1, 4)]
bins = [
    {"id": 100, "balance": 200},
    {"id": 101, "balance": 400},
    {"id": 102, "balance": 300}
]
for key, bin in zip(keys, bins):
    client.put(key, bin)

# Increment ID by 100 and balance by 500 for all employees
# NOTE: batch_operate ops must include a write op
# get_batch_ops or get_many can be used for all read ops use cases.
ops = [
    op.increment("id", 100),
    op.increment("balance", 500),
    op.read("balance")
]

batchRecords = client.batch_operate(keys, ops)
print(batchRecords.result)
# 0

# Print each individual transaction's results
# and record if it was read from
for batchRecord in batchRecords.batch_records:
    print(f"{batchRecord.result}: {batchRecord.record}")
# 0: (('test', 'demo', 'employee1', bytearray(b'...')), {'ttl': 2592000, 'gen': 2}, {'id': None, 'balance': 700})
# 0: (('test', 'demo', 'employee2', bytearray(b'...')), {'ttl': 2592000, 'gen': 2}, {'id': None, 'balance': 900})
# 0: (('test', 'demo', 'employee3', bytearray(b'...')), {'ttl': 2592000, 'gen': 2}, {'id': None, 'balance': 800})

Note

Requires server version >= 6.0.0.

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

Apply UDF (user defined function) on multiple keys.

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) – See Batch Policies.
policy_batch_apply (dict) – See Batch Apply Policies.

Returns

an instance of BatchRecords.

Raises

A subclass of AerospikeError.

# Insert 3 records
keys = [("test", "demo", f"employee{i}") for i in range(1, 4)]
bins = [
    {"id": 100, "balance": 200},
    {"id": 101, "balance": 400},
    {"id": 102, "balance": 300}
]
for key, bin in zip(keys, bins):
    client.put(key, bin)

# Apply a user defined function (UDF) to a batch
# of records using batch_apply.
client.udf_put("batch_apply.lua")

args = ["balance", 0.5, 100]
batchRecords = client.batch_apply(keys, "batch_apply", "tax", args)

print(batchRecords.result)
# 0

for batchRecord in batchRecords.batch_records:
    print(f"{batchRecord.result}: {batchRecord.record}")
# 0: (('test', 'demo', 'employee1', bytearray(b'...')), {'ttl': 2592000, 'gen': 2}, {'SUCCESS': 0})
# 0: (('test', 'demo', 'employee2', bytearray(b'...')), {'ttl': 2592000, 'gen': 2}, {'SUCCESS': 100})
# 0: (('test', 'demo', 'employee3', bytearray(b'...')), {'ttl': 2592000, 'gen': 2}, {'SUCCESS': 50})

-- Deduct tax and fees from bin
function tax(record, binName, taxRate, fees)
    if aerospike:exists(record) then
        record[binName] = record[binName] * (1 - taxRate) - fees
        aerospike:update(record)
    else
        record[binName] = 0
        aerospike:create(record)
    end
    return record[binName]
end

Note

Requires server version >= 6.0.0.

batch_remove(keys: list[, policy_batch: dict][, policy_batch_remove: dict]) → BatchRecords

Note

Requires server version >= 6.0.0.

Remove multiple records by key.

Parameters

keys (list) – The keys to remove.
policy_batch (dict) – Optional aerospike batch policy Batch Policies.
policy_batch_remove (dict) – Optional aerospike batch remove policy Batch Remove Policies.

Returns

an instance of BatchRecords.

Raises

A subclass of AerospikeError.

# Insert 3 records
keys = [("test", "demo", f"employee{i}") for i in range(1, 4)]
bins = [
    {"id": 100, "balance": 200},
    {"id": 101, "balance": 400},
    {"id": 102, "balance": 300}
]
for key, bin in zip(keys, bins):
    client.put(key, bin)

batchRecords = client.batch_remove(keys)

# A result of 0 means success
print(batchRecords.result)
# 0
for batchRecord in batchRecords.batch_records:
    print(batchRecord.result)
    print(batchRecord.record)
# 0: (('test', 'demo', 'employee1', bytearray(b'...')), {'ttl': 4294967295, 'gen': 0}, {})
# 0: (('test', 'demo', 'employee2', bytearray(b'...')), {'ttl': 4294967295, 'gen': 0}, {})
# 0: (('test', 'demo', 'employee3', bytearray(b'...')), {'ttl': 4294967295, 'gen': 0}, {})

String Operations

class aerospike.Client

Note

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

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

Append a string to the string value in bin.

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 bin value.
meta (dict) – record metadata to be set. See Metadata Dictionary.
policy (dict) – optional Operate Policies.

Raises

a subclass of AerospikeError.

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

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

Prepend the string value in bin with the string val.

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 bin value.
meta (dict) – record metadata to be set. See Metadata Dictionary.
policy (dict) – optional Operate Policies.

Raises

a subclass of AerospikeError.

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

Numeric Operations

class aerospike.Client

Note

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

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

Increment the integer value in bin by the integer val.

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) – record metadata to be set. See Metadata Dictionary.
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.

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

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

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

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

class aerospike.Client

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

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

Starting with Aerospike server version 3.6.0, non-existent bins are not present in the returned 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

key (tuple) – a Key Tuple associated with the record.
list (list) – See aerospike_helpers.operations package.
meta (dict) – record metadata to be set. See Metadata Dictionary.
policy (dict) – optional Operate Policies.

Returns

Raises

a subclass of AerospikeError.

from aerospike_helpers.operations import operations

# Add name, update age, and return attributes
client.put(keyTuple, {'age': 25, 'career': 'delivery boy'})
ops = [
    operations.increment("age", 1000),
    operations.write("name", "J."),
    operations.prepend("name", "Phillip "),
    operations.append("name", " Fry"),
    operations.read("name"),
    operations.read("career"),
    operations.read("age")
]
(key, meta, bins) = client.operate(key, ops)

print(key) # ('test', 'demo', None, bytearray(b'...'))
# The generation should only increment once
# A transaction is *atomic*
print(meta) # {'ttl': 2592000, 'gen': 2}
print(bins) # Will display all bins selected by read operations
# {'name': 'Phillip J. Fry', 'career': 'delivery boy', 'age': 1025}

Note

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

Changed in version 2.1.3.

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

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

Parameters

key (tuple) – a Key Tuple associated with the record.
list (list) – See aerospike_helpers.operations package.
meta (dict) – record metadata to be set. See Metadata Dictionary.
policy (dict) – optional Operate Policies.

Returns

Raises

a subclass of AerospikeError.

from aerospike_helpers.operations import operations

# Add name, update age, and return attributes
client.put(keyTuple, {'age': 25, 'career': 'delivery boy'})
ops = [
    operations.increment("age", 1000),
    operations.write("name", "J."),
    operations.prepend("name", "Phillip "),
    operations.append("name", " Fry"),
    operations.read("name"),
    operations.read("career"),
    operations.read("age")
]
(key, meta, bins) = client.operate_ordered(keyTuple, ops)

# Same output for key and meta as operate()
# But read operations are outputted as bin-value pairs
print(bins)
# [('name': 'Phillip J. Fry'), ('career': 'delivery boy'), ('age': 1025)]

Changed in version 2.1.3.

User Defined Functions

class aerospike.Client

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

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

import aerospike

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

udf_remove(module[, policy: dict])

Remove a previously registered UDF module from the cluster.

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

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.

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

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

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

Parameters

module (str) – the UDF module to read from the cluster.
language (int) – aerospike.UDF_TYPE_LUA
policy (dict) – currently timeout in milliseconds is the available policy.

Return type

Raises

a subclass of AerospikeError.

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.

See also

Record UDF and Developing Record UDFs.

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 Policies.
options (dict) – the 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.

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

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

This method blocks until the query is complete.

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.

job_info(job_id, module[, policy: dict]) → dict

Return the status of a job running in the background.

The returned dict contains these keys:

"status": see Job Statuses for possible values.

"records_read": number of scanned records.

"progress_pct": progress percentage of the job

Parameters

job_id (int) – the job ID returned by scan_apply() or query_apply().
module – one of Job Constants.
policy – optional Info Policies.

Returns

dict

Raises

a subclass of AerospikeError.

scan_info(scan_id) → dict

Deprecated since version 1.0.50: Use job_info() instead.

Return the status of a scan running in the background.

The returned dict contains these keys:

"status": see Scan Constants for possible values.

"records_scanned": number of scanned records.

"progress_pct": progress percentage of the job

Parameters: scan_id (int) – the scan ID returned by scan_apply().
Returns: dict
Raises: a subclass of AerospikeError.

Info Operations

class aerospike.Client

get_node_names() → []

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

Returns: a list of node info dictionaries.
Raises: a subclass of AerospikeError.

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

Changed in version 6.0.0.

get_nodes() → []

Return the list of hosts present in a connected cluster.

Returns: a list of node address tuples.
Raises: a subclass of AerospikeError.

# Assuming two nodes
nodes = client.get_nodes()
print(nodes)
# [('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

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. See Info Command Reference.
host (str) – a node name. Example: ‘BCER199932C’
policy (dict) – optional Info Policies.

Return type

Raises

a subclass of AerospikeError.

Note

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

info_all(command[, policy: dict]]) → {}

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

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

Parameters

command (str) –
see Info Command Reference.
policy (dict) – optional Info Policies.

Return type

dict

Raises

a subclass of AerospikeError.

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

New in version 3.0.0.

info_random_node(command[, policy: dict]) → str

Send an info command to a single random node.

Parameters

command (str) –
the info command. See Info Command Reference.
policy (dict) – optional Info Policies.

Return type

Raises

a subclass of AerospikeError.

Changed in version 6.0.0.

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.

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

Parameters

command (str) –
the info command. See Info Command Reference.
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

xdr-set-filter Info Command Reference.

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

info(command[, hosts[, policy: dict]]) → {}

Deprecated since version 3.0.0: Use info_all() to send a request to the entire cluster.

Send an info command to all nodes in the cluster, and optionally filter responses to only include certain nodes.

Parameters

command (str) –
the info command. See Info Command Reference
hosts (list) – a list containing (address, port) tuples. If specified, only send the command to these hosts. Example: [('127.0.0.1', 3000)]
policy (dict) – optional Info Policies.

Return type

dict

Raises

a subclass of AerospikeError.

response = client.info(command)
client.close()
# {'BB9581F41290C00': (None, '127.0.0.1:3000\n'), 'BC3581F41290C00': (None, '127.0.0.1:3010\n')}

Note

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

Changed in version 3.0.0.

set_xdr_filter(data_center, namespace, expression_filter[, policy: dict]) → str

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

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

Parameters

data_center (str) – The data center to apply the filter to.
namespace (str) – The namespace to apply the filter to.
expression_filter (AerospikeExpression) – The filter to set. See expressions at aerospike_helpers.
policy (dict) – optional Info Policies.

Raises

a subclass of AerospikeError.

See also

Changed in version 5.0.0.

Warning

Requires Aerospike server version >= 5.3.

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.
Raises: a subclass of AerospikeError.

from aerospike_helpers import expressions as exp

# Compile expression
expr = exp.Eq(exp.IntBin("bin1"), 6).compile()

base64 = client.get_expression_base64(expr)
print(base64)
# kwGTUQKkYmluMQY=

Changed in version 7.0.0.

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

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

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

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

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

Parameters

namespace (str) – The namespace to truncate.
set (str) – The set to truncate. Pass in None to truncate a namespace instead.
nanos (long) – A cutoff threshold where records last updated before the threshold will be removed. Units are in nanoseconds since the UNIX epoch (1970-01-01). A value of 0 indicates that all records in the set should be truncated regardless of update time. The value must not be in the future.
policy (dict) – See Info Policies.

Return type

Status indicating the success of the operation.

Raises

a subclass of AerospikeError.

Note

Requires Aerospike server version >= 3.12

import time

client.put(("test", "demo", "key1"), {"bin": 4})

time.sleep(1)
# Take threshold time
current_time = time.time()
time.sleep(1)

client.put(("test", "demo", "key2"), {"bin": 5})

threshold_ns = int(current_time * 10**9)
# Remove all items in set `demo` created before threshold time
# Record using key1 should be removed
client.truncate('test', 'demo', threshold_ns)

# Remove all items in namespace
# client.truncate('test', None, 0)

Index Operations

class aerospike.Client

index_string_create(ns, set, bin, 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.
name (str) – the name of the index.
policy (dict) – optional Info Policies.

Raises

a subclass of AerospikeError.

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

Create an integer index with 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.
name (str) – the name of the index.
policy (dict) – optional Info Policies.

Raises

a subclass of AerospikeError.

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

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

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.
name (str) – the name of the index.
policy (dict) – optional Info Policies.

Raises

a subclass of AerospikeError.

Note

Requires server version >= 3.8.0

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

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

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.
name (str) – the name of the index.
policy (dict) – optional Info Policies.

Raises

a subclass of AerospikeError.

Note

Requires server version >= 3.8.0

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

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

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

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

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

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

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

Remove the index with name from the namespace.

Parameters

ns (str) – the namespace in the aerospike cluster.
name (str) – the name of the index.
policy (dict) – optional Info Policies.

Raises

a subclass of AerospikeError.

get_cdtctx_base64(ctx: list) → str

Get the base64 representation of aerospike CDT ctx.

See aerospike_helpers.cdt_ctx module for more details on CDT context.

Parameters: ctx (list) – Aerospike CDT context: generated by aerospike CDT ctx helper aerospike_helpers.
Raises: a subclass of AerospikeError.

import aerospike
from aerospike_helpers import cdt_ctx

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

ctxs = [cdt_ctx.cdt_ctx_list_index(0)]
ctxs_base64 = client.get_cdtctx_base64(ctxs)
print("Base64 encoding of ctxs:", ctxs_base64)

client.close()

Changed in version 7.1.1.

Admin Operations

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

See also

Security features article.

class aerospike.Client

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

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

Parameters

role (str) – The name of the role.
privileges (list) – A list of Privilege Objects.
policy (dict) – See 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 0 for no limit.
write_quota (int) – Maximum write per second limit, Pass in 0 for no limit.

Raises

One of the AdminError subclasses.

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

Add a 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 this to None will clear the whitelist for that role.
policy (dict) – See Admin Policies.

Raises

One of the AdminError subclasses.

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 0 for no limit.
write_quota (int) – Maximum write per second limit. Pass in 0 for no limit.
policy (dict) – See Admin Policies.

Raises

one of the AdminError subclasses.

admin_drop_role(role[, policy: dict])

Drop a custom role.

Parameters

role (str) – the name of the role.
policy (dict) – See Admin Policies.

Raises

one of the AdminError subclasses.

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

Add privileges to a role.

Parameters

role (str) – the name of the role.
privileges (list) – a list of Privilege Objects.
policy (dict) – See Admin Policies.

Raises

one of the AdminError subclasses.

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

Remove privileges from a role.

Parameters

role (str) – the name of the role.
privileges (list) – a list of Privilege Objects.
policy (dict) – See Admin Policies.

Raises

one of the AdminError subclasses.

admin_get_role(role[, policy: dict]) → {}

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

Parameters

role (str) – the name of the role.
policy (dict) – See Admin Policies.

Returns

a Role Objects.

Raises

one of the AdminError subclasses.

admin_get_roles([policy: dict]) → {}

Get the names of all roles and their attributes.

Parameters: policy (dict) – See Admin Policies.
Returns: a dict of Role Objects keyed by role names.
Raises: one of the AdminError subclasses.

admin_query_role(role[, policy: dict]) → []

Get the list of privileges associated with a role.

Parameters

role (str) – the name of the role.
policy (dict) – See Admin Policies.

Returns

a list of Privilege Objects.

Raises

one of the AdminError subclasses.

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.

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

Create a user 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.

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.

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

Change the password of a user.

This operation can only be performed by that same user.

Parameters

username (str) – the username of the user.
password (str) – the password associated with the given username.
policy (dict) – optional Admin Policies.

Raises

one of the AdminError subclasses.

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

Set the password of a user 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.

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

Add roles to a user.

Parameters

username (str) – the username of the user.
roles (list) – a list of role names.
policy (dict) – optional Admin Policies.

Raises

one of the AdminError subclasses.

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

Remove roles from a user.

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.

admin_query_user(username[, policy: dict]) → []

Return the list of roles granted to the specified user.

Parameters

username (str) – the username of the user.
policy (dict) – optional Admin Policies.

Returns

a list of role names.

Raises

one of the AdminError subclasses.

admin_query_users([policy: dict]) → {}

Get the roles of all users.

Parameters: policy (dict) – optional Admin Policies.
Returns: a dict of roles keyed by username.
Raises: one of the AdminError subclasses.

Scan and Query Constructors

class aerospike.Client

scan(namespace[, set]) → Scan

Deprecated since version 7.0.0: aerospike.Query should be used instead.

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

If set is omitted or set to None, the object returns all 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.

query(namespace[, set]) → Query

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

See aerospike.Query — Query Class for more details.

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.

Tuples

Key Tuple

key

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

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

namespace (str)
Name of the namespace.

This must be preconfigured on the cluster.

set (str)
Name of the set.

The set be created automatically if it does not exist.

primary key (str, int or bytearray)
The value by which the client-side application identifies the record.

digest
The record’s RIPEMD-160 digest.

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

The following code example shows:

How to use the key tuple in a put operation

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

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

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

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

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

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

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

# Cleanup
client.remove(keyTuple)
client.close()
See also

Data Model: Keys and Digests.

Record Tuple

record

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

(key, meta, bins)

key (tuple)
See Key Tuple.
meta (dict)
Contains record metadata with the following key-value pairs:
- gen (int)
  Generation value
- ttl (int)
  Time-to-live value
bins (dict)
Contains bin-name/bin-value pairs.

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

import aerospike

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

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

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

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

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

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

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

client.remove(keyTuple)
client.close()

See also

Data Model: Record.

Metadata Dictionary

The metadata dictionary has the following key-value pairs:

"ttl" (int): record time to live in seconds. See TTL Constants.

"gen" (int): record generation

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: 30000
total_timeout (int)

Total transaction timeout in milliseconds.

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

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

Default: 1000
compress (bool)

Compress client requests and server responses.

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

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

Default: False
key

One of the Key Policy Options values such as aerospike.POLICY_KEY_DIGEST

Default: aerospike.POLICY_KEY_DIGEST
exists

One of the Existence Policy Options values such as aerospike.POLICY_EXISTS_CREATE

Default: aerospike.POLICY_EXISTS_IGNORE
gen

One of the Generation Policy Options values such as aerospike.POLICY_GEN_IGNORE

Default: aerospike.POLICY_GEN_IGNORE
commit_level

One of the Commit Level Policy Options values such as aerospike.POLICY_COMMIT_LEVEL_ALL

Default: aerospike.POLICY_COMMIT_LEVEL_ALL
durable_delete (bool)

Perform durable delete

Default: False
expressions list

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

Default: None

Note

Requires Aerospike server version >= 5.2.
compression_threshold (int)
Compress data for transmission if the object size is greater than a given number of bytes.

Default: 0, meaning ‘never compress’

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: 30000
total_timeout (int)

Total transaction timeout in milliseconds.

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

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

Default: 1000
compress (bool)

Compress client requests and server responses.

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

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

Default: False
deserialize (bool)

Should raw bytes representing a list or map be deserialized to a list or dictionary.

Set to False for backup programs that just need access to raw bytes.

Default: True
key

One of the Key Policy Options values such as aerospike.POLICY_KEY_DIGEST

Default: aerospike.POLICY_KEY_DIGEST
read_mode_ap

One of the AP Read Mode Policy Options values such as aerospike.AS_POLICY_READ_MODE_AP_ONE

Default: aerospike.AS_POLICY_READ_MODE_AP_ONE

New in version 3.7.0.
read_mode_sc

One of the SC Read Mode Policy Options values such as aerospike.POLICY_READ_MODE_SC_SESSION

Default: aerospike.POLICY_READ_MODE_SC_SESSION

New in version 3.7.0.
replica

One of the Replica Options values such as aerospike.POLICY_REPLICA_MASTER

Default: aerospike.POLICY_REPLICA_SEQUENCE
expressions list

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

Default: 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: 30000
total_timeout (int)

Total transaction timeout in milliseconds.

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

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

Default: 1000
compress (bool)

Compress client requests and server responses.

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

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

Default: False
key

One of the Key Policy Options values such as aerospike.POLICY_KEY_DIGEST

Default: aerospike.POLICY_KEY_DIGEST
gen

One of the Generation Policy Options values such as aerospike.POLICY_GEN_IGNORE

Default: aerospike.POLICY_GEN_IGNORE
replica

One of the Replica Options values such as aerospike.POLICY_REPLICA_MASTER

Default: aerospike.POLICY_REPLICA_SEQUENCE
commit_level

One of the Commit Level Policy Options values such as aerospike.POLICY_COMMIT_LEVEL_ALL

Default: aerospike.POLICY_COMMIT_LEVEL_ALL
read_mode_ap

One of the AP Read Mode Policy Options values such as aerospike.AS_POLICY_READ_MODE_AP_ONE

Default: aerospike.AS_POLICY_READ_MODE_AP_ONE

New in version 3.7.0.
read_mode_sc

One of the SC Read Mode Policy Options values such as aerospike.POLICY_READ_MODE_SC_SESSION

Default: aerospike.POLICY_READ_MODE_SC_SESSION

New in version 3.7.0.
exists

One of the Existence Policy Options values such as aerospike.POLICY_EXISTS_CREATE

Default: aerospike.POLICY_EXISTS_IGNORE
durable_delete (bool)

Perform durable 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: 30000
total_timeout (int)

Total transaction timeout in milliseconds.

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

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

Default: 1000
compress (bool)

Compress client requests and server responses.

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

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

Default: False
key

One of the Key Policy Options values such as aerospike.POLICY_KEY_DIGEST

Default: aerospike.POLICY_KEY_DIGEST
replica

One of the Replica Options values such as aerospike.POLICY_REPLICA_MASTER

Default: aerospike.POLICY_REPLICA_SEQUENCE
gen

One of the Generation Policy Options values such as aerospike.POLICY_GEN_IGNORE

Default: aerospike.POLICY_GEN_IGNORE
commit_level

One of the Commit Level Policy Options values such as aerospike.POLICY_COMMIT_LEVEL_ALL

Default: aerospike.POLICY_COMMIT_LEVEL_ALL
durable_delete (bool)

Perform durable 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: 30000
total_timeout (int)

Total transaction timeout in milliseconds.

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

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

Default: 1000
compress (bool)

Compress client requests and server responses.

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

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

Default: False
key

One of the Key Policy Options values such as aerospike.POLICY_KEY_DIGEST

Default: aerospike.POLICY_KEY_DIGEST
commit_level

One of the Commit Level Policy Options values such as aerospike.POLICY_COMMIT_LEVEL_ALL

Default: aerospike.POLICY_COMMIT_LEVEL_ALL
gen

One of the Generation Policy Options values such as aerospike.POLICY_GEN_IGNORE

Default: aerospike.POLICY_GEN_IGNORE
durable_delete (bool)

Perform durable delete

Default: False

Note

Requires Enterprise server version >= 3.10
replica

One of the Replica Options values such as aerospike.POLICY_REPLICA_MASTER

Default: aerospike.POLICY_REPLICA_SEQUENCE
expressions list

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

Default: 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: 30000
total_timeout (int)

Total transaction timeout in milliseconds.

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

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

Default: 1000
compress (bool)

Compress client requests and server responses.

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

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

Default: False
read_mode_ap

One of the AP Read Mode Policy Options values such as aerospike.AS_POLICY_READ_MODE_AP_ONE

Default: aerospike.AS_POLICY_READ_MODE_AP_ONE

New in version 3.7.0.
read_mode_sc

One of the SC Read Mode Policy Options values such as aerospike.POLICY_READ_MODE_SC_SESSION

Default: aerospike.POLICY_READ_MODE_SC_SESSION

New in version 3.7.0.
replica

One of the Replica Options values such as aerospike.POLICY_REPLICA_MASTER

Default: aerospike.POLICY_REPLICA_SEQUENCE
concurrent (bool)

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

Default False
allow_inline (bool)

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

Default True
allow_inline_ssd (bool)
Allow batch to be processed immediately in the server’s receiving thread for SSD namespaces. If false, the batch will always be processed in separate service threads. Server versions < 6.0 ignore this field.

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

Default: False
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.
respond_all_keys bool
Should all batch keys be attempted regardless of errors. This field is used on both the client and server. The client handles node specific errors and the server handles key specific errors.

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

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

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

Default: True

Batch Write Policies

policy

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

key

One of the Key Policy Options values such as aerospike.POLICY_KEY_DIGEST

Default: aerospike.POLICY_KEY_DIGEST
commit_level

One of the Commit Level Policy Options values such as aerospike.POLICY_COMMIT_LEVEL_ALL

Default: aerospike.POLICY_COMMIT_LEVEL_ALL
gen

One of the Generation Policy Options values such as aerospike.POLICY_GEN_IGNORE

Default: aerospike.POLICY_GEN_IGNORE
exists

One of the Existence Policy Options values such as aerospike.POLICY_EXISTS_CREATE

Default: aerospike.POLICY_EXISTS_IGNORE
durable_delete (bool)

Perform durable delete

Default: False
expressions list

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

Default: None
ttl int

The time-to-live (expiration) in seconds to apply to every record in the batch.

The ttl must be a 32-bit unsigned integer, or a ParamError will be raised.

Default: 0

Batch Apply Policies

policy

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

key

One of the Key Policy Options values such as aerospike.POLICY_KEY_DIGEST

Default: aerospike.POLICY_KEY_DIGEST
commit_level

One of the Commit Level Policy Options values such as aerospike.POLICY_COMMIT_LEVEL_ALL

Default: aerospike.POLICY_COMMIT_LEVEL_ALL
ttl int

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

0 which means that the

record will adopt the default TTL value from the namespace.

0xFFFFFFFF (also, -1 in a signed 32 bit int)

which means that the record

will get an internal “void_time” of zero, and thus will never expire.

0xFFFFFFFE (also, -2 in a signed 32 bit int)

which means that the record

ttl will not change when the record is updated.

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

Default: 0
expressions list

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

Default: None

Batch Remove Policies

policy

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

key

One of the Key Policy Options values such as aerospike.POLICY_KEY_DIGEST

Default: aerospike.POLICY_KEY_DIGEST
commit_level

One of the Commit Level Policy Options values such as aerospike.POLICY_COMMIT_LEVEL_ALL

Default: aerospike.POLICY_COMMIT_LEVEL_ALL
gen

One of the Generation Policy Options values such as aerospike.POLICY_GEN_IGNORE

Default: aerospike.POLICY_GEN_IGNORE
generation int

Generation of the record.

Default: 0
durable_delete (bool)

Perform durable delete

Default: False
expressions list

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

Default: None

Batch Read Policies

policy

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

read_mode_ap

One of the AP Read Mode Policy Options values such as aerospike.AS_POLICY_READ_MODE_AP_ONE

Default: aerospike.AS_POLICY_READ_MODE_AP_ONE
read_mode_sc

One of the SC Read Mode Policy Options values such as aerospike.POLICY_READ_MODE_SC_SESSION

Default: aerospike.POLICY_READ_MODE_SC_SESSION
expressions list

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

Default: None

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.

write_flags

Write flags for the operation.

One of the List Write Flags values such as aerospike.LIST_WRITE_DEFAULT

Default: aerospike.LIST_WRITE_DEFAULT

Values should be or’d together:

aerospike.LIST_WRITE_ADD_UNIQUE | aerospike.LIST_WRITE_INSERT_BOUNDED
list_order

Ordering to maintain for the list.

One of List Order, such as aerospike.LIST_ORDERED

Default: aerospike.LIST_UNORDERED

Example:

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

Map Policies

policy

A dict of optional map policies, which are applicable to map operations. Only one 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 .

map_write_mode

Write mode for the map operation.

One of the Map Write Mode values such as aerospike.MAP_UPDATE

Default: aerospike.MAP_UPDATE

Note

This should only be used for Server version < 4.3.0.
map_write_flags

Write flags for the map operation.

One of the Map Write Flag values such as aerospike.MAP_WRITE_FLAGS_DEFAULT

Default: aerospike.MAP_WRITE_FLAGS_DEFAULT

Values should be or’d together:

aerospike.LIST_WRITE_ADD_UNIQUE | aerospike.LIST_WRITE_INSERT_BOUNDED

Note

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

Ordering to maintain for the map entries.

One of Map Order, such as aerospike.MAP_KEY_ORDERED

Default: aerospike.MAP_UNORDERED

Example:

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

# Server < 4.3.0
map_policy = {
    'map_order': aerospike.MAP_UNORDERED,
    'map_write_mode': aerospike.MAP_CREATE_ONLY
}

Bit Policies

policy

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

Note

Requires server version >= 4.6.0

bit_write_flags

Write flags for the bit operation.

One of the Bitwise Write Flags values such as aerospike.BIT_WRITE_DEFAULT

Default: aerospike.BIT_WRITE_DEFAULT

Example:

bit_policy = {
    'bit_write_flags': aerospike.BIT_WRITE_UPDATE_ONLY
}

HyperLogLog Policies

policy

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

Note

Requires server version >= 4.9.0

flags

Write flags for the HLL operation.

One of the HyperLogLog Write Flags values such as aerospike.HLL_WRITE_DEFAULT

Default: aerospike.HLL_WRITE_DEFAULT

Example:

HLL_policy = {
    'flags': aerospike.HLL_WRITE_UPDATE_ONLY
}

Misc

Role Objects

Role

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.

Privilege Objects

privilege

A dict describing a privilege and where it applies to:

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

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

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

Example:

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

Partition Objects

partition_filter

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

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

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

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

Default: {} (all partitions)

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

# Example of a query policy using partition_filter.

# partition_status is most easily used to resume a query
# and can be obtained by calling Query.get_partitions_status()
partition_status = {
    0: {0, False, 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 partition query or scan.

This is useful for resuming either of those.

The dictionary contains these key-value pairs:

"retry": str represents the overall retry status of this partition query. (i.e. Does this query/scan need to be retried?)

This maps to a boolean value.
"done": str represents whether all partitions were finished.

This maps to a boolean value.

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

Each partition ID has a dictionary with the following keys:

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

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

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

# Example of a query policy using partition_status.

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

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

`aerospike.Scan` — Scan Class

Deprecated since version 7.0.0: aerospike.Query should be used instead.

Overview

The Scan object is used to return all the records in a specified set (which can be omitted or None). A Scan with a None set returns all the records in the namespace.

The scan is invoked using foreach(), results(), or execute_background(). The bins returned can be filtered using select().

See also

Scans and Managing Scans.

Methods

class aerospike.Scan

Deprecated since version 7.0.0: aerospike.Query should be used instead.

select(bin1[, bin2[, bin3..]]): Set a filter on the record bins resulting from results() or foreach(). If a selected bin does not exist in a record it will not appear in the bins portion of that record tuple.

apply(module, function[, arguments])

Apply a record UDF to each record found by the scan UDF.

Parameters

module (str) – the name of the Lua module.
function (str) – the name of the Lua function within the module.
arguments (list) – optional arguments to pass to the function. NOTE: these arguments must be types supported by Aerospike See: supported data types. If you need to use an unsupported type, (e.g. set or tuple) you can use a serializer such as pickle first.

Returns

one of the supported types, int, str, float (double), list, dict (map), bytearray (bytes), bool.

See also

Developing Record UDFs

add_ops(ops)

Add a list of write ops to the scan. When used with Scan.execute_background() the scan will perform the write ops on any records found. If no predicate is attached to the scan it will apply ops to all the records in the specified set. See aerospike_helpers for available ops.

Parameters: ops – list A list of write operations generated by the aerospike_helpers e.g. list_operations, map_operations, etc.

Note

Requires server version >= 4.7.0.

import aerospike
from aerospike_helpers.operations import list_operations
from aerospike_helpers.operations import operations
scan = client.scan('test', 'demo')

ops =  [
    operations.append(test_bin, 'val_to_append'),
    list_operations.list_remove_by_index(test_bin, list_index_to_remove, aerospike.LIST_RETURN_NONE)
]
scan.add_ops(ops)

id = scan.execute_background()
client.close()

For a more comprehensive example, see using a list of write ops with Query.execute_background() .

results([policy[, nodename]]) -> list of (key, meta, bins)

Buffer the records resulting from the scan, and return them as a list of records.

Parameters

policy (dict) – optional Policies.
nodename (str) – optional Node ID of node used to limit the scan to a single node.

Returns

import aerospike
import pprint

pp = pprint.PrettyPrinter(indent=2)
config = { 'hosts': [ ('127.0.0.1',3000)]}
client = aerospike.client(config).connect()

client.put(('test','test','key1'), {'id':1,'a':1},
    policy={'key':aerospike.POLICY_KEY_SEND})
client.put(('test','test','key2'), {'id':2,'b':2},
    policy={'key':aerospike.POLICY_KEY_SEND})

scan = client.scan('test', 'test')
scan.select('id','a','zzz')
res = scan.results()
pp.pprint(res)
client.close()

Note

We expect to see:

[ ( ( 'test',
      'test',
      u'key2',
      bytearray(b'\xb2\x18\n\xd4\xce\xd8\xba:\x96s\xf5\x9ba\xf1j\xa7t\xeem\x01')),
    { 'gen': 52, 'ttl': 2592000},
    { 'id': 2}),
  ( ( 'test',
      'test',
      u'key1',
      bytearray(b'\x1cJ\xce\xa7\xd4Vj\xef+\xdf@W\xa5\xd8o\x8d:\xc9\xf4\xde')),
    { 'gen': 52, 'ttl': 2592000},
    { 'a': 1, 'id': 1})]

Note

As of client 7.0.0 and with server >= 6.0 results and the scan policy “partition_filter” see Partition Objects can be used to specify which partitions/records results will scan. See the example below.

# This is an example of scaning partitions 1000 - 1003.
import aerospike


scan = client.scan("test", "demo")

policy = {
    "partition_filter": {
        "begin": 1000,
        "count": 4
    },
}

# NOTE that these will only be non 0 if there are records in partitions 1000 - 1003
# results will be the records in partitions 1000 - 1003
results = scan.results(policy=policy)

foreach(callback[, policy[, options[, nodename]]])

Invoke the callback function for each of the records streaming back from the scan.

Parameters

callback (callable) – the function to invoke for each record.
policy (dict) – optional Policies.
options (dict) – the Options that will apply to the scan.
nodename (str) – optional Node ID of node used to limit the scan to a single node.

Note

A Record Tuple is passed as the argument to the callback function. If the scan is using the “partition_filter” scan policy the callback will receive two arguments The first is a int representing partition id, the second is the same Record Tuple as a normal callback.

import aerospike
import pprint

pp = pprint.PrettyPrinter(indent=2)
config = { 'hosts': [ ('127.0.0.1',3000)]}
client = aerospike.client(config).connect()

client.put(('test','test','key1'), {'id':1,'a':1},
    policy={'key':aerospike.POLICY_KEY_SEND})
client.put(('test','test','key2'), {'id':2,'b':2},
    policy={'key':aerospike.POLICY_KEY_SEND})

def show_key(record):
    key, meta, bins = record
    print(key)

scan = client.scan('test', 'test')
scan_opts = {
  'concurrent': True,
  'nobins': True
}
scan.foreach(show_key, options=scan_opts)
client.close()

Note

We expect to see:

('test', 'test', u'key2', bytearray(b'\xb2\x18\n\xd4\xce\xd8\xba:\x96s\xf5\x9ba\xf1j\xa7t\xeem\x01'))
('test', 'test', u'key1', bytearray(b'\x1cJ\xce\xa7\xd4Vj\xef+\xdf@W\xa5\xd8o\x8d:\xc9\xf4\xde'))

Note

To stop the stream return False from the callback function.

import aerospike

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

def limit(lim, result):
    c = [0] # integers are immutable so a list (mutable) is used for the counter
    def key_add(record):
        key, metadata, bins = record
        if c[0] < lim:
            result.append(key)
            c[0] = c[0] + 1
        else:
            return False
    return key_add

scan = client.scan('test','user')
keys = []
scan.foreach(limit(100, keys))
print(len(keys)) # this will be 100 if the number of matching records > 100
client.close()

Note

As of client 7.0.0 and with server >= 6.0 foreach and the scan policy “partition_filter” see Partition Objects can be used to specify which partitions/records foreach will scan. See the example below.

# This is an example of scaning partitions 1000 - 1003.
import aerospike


partitions = []

def callback(part_id, input_tuple):
    print(part_id)
    partitions.append(part_id)

scan = client.scan("test", "demo")

policy = {
    "partition_filter": {
        "begin": 1000,
        "count": 4
    },
}

scan.foreach(callback, policy)


# NOTE that these will only be non 0 if there are records in partitions 1000 - 1003
# should be 4
print(len(partitions))

# should be [1000, 1001, 1002, 1003]
print(partitions)

execute_background([policy])

Execute a record UDF on records found by the scan in the background. This method returns before the scan has completed. A UDF can be added to the scan with Scan.apply().

Parameters: policy (dict) – optional Write Policies.
Returns: a job ID that can be used with aerospike.job_info() to track the status of the aerospike.JOB_SCAN, as it runs in the background.

Note

Python client version 3.10.0 implemented scan execute_background.

import aerospike
from aerospike import exception as ex
import sys
import time

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.AerospikeError 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])

    scan = client.scan("test", "demo")
    scan.apply("my_udf", "my_udf", ["number", 10])
    job_id = scan.execute_background()

    # wait for job to finish
    while True:
        response = client.job_info(job_id, aerospike.JOB_SCAN)
        if response["status"] != aerospike.JOB_STATUS_INPROGRESS:
            break
        time.sleep(0.25)

    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()
# 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': 12}),
#   (('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

paginate()

Makes a scan instance a paginated scan. Call this if you are using the “max_records” scan policy and you need to scan data in pages.

Note

Calling .paginate() on a scan instance causes it to save its partition state. This can be retrieved later using .get_partitions_status(). This can also be done using the partition_filter policy.

# scan 3 pages of 1000 records each.

import aerospike

pages = 3
page_size = 1000
policy = {"max_records": 1000}

scan = client.scan('test', 'demo')

scan.paginate()

# NOTE: The number of pages queried and records returned per page can differ
# if record counts are small or unbalanced across nodes.
for page in range(pages):
    records = scan.results(policy=policy)

    print("got page: " + str(page))

    if scan.is_done():
        print("all done")
        break

# This id can be used to paginate queries.

is_done()

If using scan pagination, did the previous paginated or partition_filter scan using this scan instance return all records?

Returns: A bool signifying whether this paginated scan instance has returned all records.

import aerospike

policy = {"max_records": 1000}

scan = client.scan('test', 'demo')

scan.paginate()

records = scan.results(policy=policy)

if scan.is_done():
    print("all done")

# This id can be used to monitor the progress of a paginated scan.

get_partitions_status()

Get this scan instance’s partition status. That is which partitions have been queried and which have not. The returned value is a dict with partition id, int, as keys and tuple as values. If the scan instance is not tracking its partitions, the returned dict will be empty.

Note

A scan instance must have had .paginate() called on it in order retrieve its partition status. If .paginate() was not called, the scan instance will not save partition status.

Returns: a tuple of form (id: int, init: class`bool`, done: class`bool`, digest: bytearray). See Partition Objects for more information.

# This is an example of resuming a scan using partition status.
import aerospike


for i in range(15):
    key = ("test", "demo", i)
    bins = {"id": i}
    client.put(key, bins)

records = []
resumed_records = []

def callback(input_tuple):
    record, _, _ = input_tuple

    if len(records) == 5:
        return False

    records.append(record)

scan = client.scan("test", "demo")
scan.paginate()

scan.foreach(callback)

# The first scan should stop after 5 records.
assert len(records) == 5

partition_status = scan.get_partitions_status()

def resume_callback(part_id, input_tuple):
    record, _, _ = input_tuple
    resumed_records.append(record)

scan_resume = client.scan("test", "demo")

policy = {
    "partition_filter": {
        "partition_status": partition_status
    },
}

scan_resume.foreach(resume_callback, policy)

# should be 15
total_records = len(records) + len(resumed_records)
print(total_records)

# cleanup
for i in range(15):
    key = ("test", "demo", i)
    client.remove(key)

Policies

policy

A dict of optional scan policies which are applicable to Scan.results() and Scan.foreach(). See Policies.

max_retries int

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

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

Default: 0

Warning

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

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

Default: 0
socket_timeout int

Socket idle timeout in milliseconds when processing a database command.

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

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

Default: 30000.
total_timeout int

Total transaction timeout in milliseconds.

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

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

Default: 0
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
fail_on_cluster_change bool

Deprecated in 6.0.0. No longer has any effect..

Abort the scan if the cluster is not in a stable state. Only used for server versions < 4.9.

Default: False
durable_delete bool

Perform durable delete (requires Enterprise server version >= 3.10)

If the transaction results in a record deletion, leave a tombstone for the record.

Default: False
records_per_second int

Limit the scan to process records at records_per_second.

Requires server version >= 4.7.0.

Default: 0 (no limit).
expressions list

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

Default: None

Note

Requires Aerospike server version >= 5.2.
max_records int

Approximate number of records to return to client.

This number is divided by the number of nodes involved in the scan.

The actual number of records returned may be less than max_records if node record counts are small and unbalanced across nodes.

Default: 0 (No Limit).

Note

Requires Aerospike server version >= 6.0
partition_filter dict

A dictionary of partition information used by the client

to perform partiton scans. Useful for resuming terminated scans and

scaning particular partitons/records.

See Partition Objects for more information.

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

Options

options

A dict of optional scan options which are applicable to Scan.foreach().

priority

Deprecated in 6.0.0. Scan priority will be removed in a coming release.

Scan priority has been replaced by the records_per_second policy see Policies.
nobins bool

Whether to return the bins portion of the Record Tuple.

Default False.
concurrent bool

Whether to run the scan concurrently on all nodes of the cluster.

Default False.
percent int

Deprecated in version 6.0.0, will be removed in a coming release.

No longer available with server 5.6+.

Use scan policy max_records instead.

Percentage of records to return from the scan.

Default 100.

New in version 1.0.39.

`aerospike.Query` — Query Class

Overview

Constructing A Query

The query object is used for executing queries over a secondary index of a specified set. It can be created by calling aerospike.Client.query().

A query without a secondary index filter will apply to all records in the namespace, similar to a Scan.

Otherwise, the query can optionally be assigned one of the secondary index filters in aerospike.predicates to filter out records using their bin values. These secondary index filters are applied to the query using where(). In this case, if the set is initialized to None, then the query will only apply to records without a set.

Note

The secondary index filters in aerospike.predicates are not the same as the deprecated predicate expressions. For more details, read this guide.

Writing Using Query

If a list of write operations is added to the query with add_ops(), they will be applied to each record processed by the query. See available write operations at aerospike_helpers.operations.

Query Aggregations

A stream UDF may be applied with apply(). It will aggregate results out of the records streaming back from the query.

Getting Results From Query

The returned bins can be filtered by using select().

Finally, the query is invoked using one of these methods:

foreach()
results()
execute_background()

See also

Queries and Managing Queries.

Fields

class aerospike.Query

max_records (int)

Approximate number of records to return to client.

This number is divided by the number of nodes involved in the scan. The actual number of records returned may be less than max_records if node record counts are small and unbalanced across nodes.

Default: 0 (no limit)

Note

Requires server version >= 6.0.0

records_per_second (int)

Limit the scan to process records at records_per_second. Requires server version >= 6.0.0

Default: 0 (no limit)

ttl (int)

The time-to-live (expiration) of the record in seconds.

There are also special values that can be set in the record TTL:

0 (TTL_NAMESPACE_DEFAULT)
Which means that the record will adopt the default TTL value from the namespace.

0xFFFFFFFF (TTL_NEVER_EXPIRE)
(also, -1 in a signed 32 bit int) Which means that the record will never expire.

0xFFFFFFFE (TTL_DONT_UPDATE)
(also, -2 in a signed 32 bit int) Which means that the record ttl will not change when the record is updated.

Note

Note that the TTL value will be employed ONLY on background query writes.

Requires server version >= 6.0.0

Default: 0 (record will adopt the default TTL value from the namespace)

Methods

Assume this boilerplate code is run before all examples below:

import aerospike
import sys
from aerospike import exception as ex

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

# Create a client and connect it to the cluster
try:
    client = aerospike.client(config).connect()
    client.truncate('test', "demo", 0)
except ex.ClientError as e:
    print("Error: {0} [{1}]".format(e.msg, e.code))
    sys.exit(1)

# Remove old indices
try:
    client.index_remove("test", "scoreIndex")
    client.index_remove("test", "eloIndex")
except ex.AerospikeError as e:
    # Ignore if no indices found
    pass

# Insert 4 records
keyTuples = [("test", "demo", f"player{i}") for i in range(4)]
bins = [
    {"score": 100, "elo": 1400},
    {"score": 20, "elo": 1500},
    {"score": 10, "elo": 1100},
    {"score": 200, "elo": 900}
]
for keyTuple, bin in zip(keyTuples, bins):
    client.put(keyTuple, bin)

query = client.query('test', 'demo')

# Queries require a secondary index for each bin name
client.index_integer_create("test", "demo", "score", "scoreIndex")
client.index_integer_create("test", "demo", "elo", "eloIndex")

class aerospike.Query

select(bin1[, bin2[, bin3..]])

Set a filter on the record bins resulting from results() or foreach().

If a selected bin does not exist in a record it will not appear in the bins portion of that record tuple.

where(predicate[, ctx])

Set a where predicate for the query.

You can only assign at most one predicate to the query. If this function isn’t called, the query will behave similar to aerospike.Scan.

Parameters

predicate (tuple) – the tuple produced by either equals() or between().
ctx (list) – the list produced by one of the aerospike_helpers.cdt_ctx methods.

results([,policy [, options]]) -> list of (key, meta, bins)

Buffer the records resulting from the query, and return them as a list of records.

Parameters

policy (dict) – optional Policies.
options (dict) – optional Options.

Returns