aerospike — Aerospike Client for Python

The Aerospike client enables you to build an application in Python with an Aerospike cluster as its database. The client manages the connections to the cluster and handles the transactions performed against it.

Data Model

At the top is the namespace, a container that has one set of policy rules for all its data, and is similar to the database concept in an RDBMS, only distributed across the cluster. A namespace is subdivided into sets, similar to tables.

Pairs of key-value data called bins make up records, similar to columns of a row in a standard RDBMS. Aerospike is schema-less, meaning that you do not need to define your bins in advance.

Records are uniquely identified by their key, and record metadata is contained in an in-memory primary index.

See also

Architecture Overview and Aerospike Data Model for more information about Aerospike.

aerospike.client(config)

Creates a new instance of the Client class. This client can connect() to the cluster and perform operations against it, such as put() and get() records.

This is a wrapper function which calls the constructor for the Client class. The client may also be constructed by calling the constructor directly.

Parameters:config (dict) –

the client’s configuration.

  • hosts a required list of (address, port, [tls-name]) tuples identifying a node (or multiple nodes) in the cluster. The client will connect to the first available node in the list, the seed node, and will learn about the cluster and partition map from it. If tls-name is specified, it must match the tls-name specified in the node’s server configuration file and match the server’s CA certificate. Note: use of TLS requires Aerospike Enterprise Edition
  • lua an optional dict containing the paths to two types of Lua modules
    • system_path the location of the system modules such as aerospike.lua (default: /usr/local/aerospike/lua)
    • user_path the location of the user’s record and stream UDFs . (default: ./)
  • policies a dict of policies
    • read A dictionary containing read policies. See Read Policies for available policy fields and values.
    • write A dictionary containing write policies. See Write Policies for available policy fields and values.
    • apply A dictionary containing apply policies. See Apply Policies for available policy fields and values.
    • operate A dictionary containing operate policies. See Operate Policies for available policy fields and values.
    • remove A dictionary containing remove policies. See Remove Policies for available policy fields and values.
    • query A dictionary containing query policies. See Query Policies for available policy fields and values.
    • scan A dictionary containing scan policies. See Scan Policies for available policy fields and values.
    • batch A dictionary containing batch policies. See Batch Policies for available policy fields and values.
    • total_timeout default connection timeout in milliseconds (Deprecated: set this the individual policy dictionaries)
    • auth_mode a value defining how to authenticate with the server such as aerospike.AUTH_INTERNAL .
    • login_timeout_ms An integer representing Node login timeout in milliseconds. Default: 5000.
    • key default key policy, with values such as aerospike.POLICY_KEY_DIGEST (Deprecated: set this individually in the ‘read’, ‘write’, ‘apply’, ‘operate’, ‘remove’ policy dictionaries)
    • exists default exists policy, with values such as aerospike.POLICY_EXISTS_CREATE (Deprecated: set in the ‘write’ policies dictionary)
    • max_retries a int representing the number of times to retry a transaction (Deprecated: set this the individual policy dictionaries)
    • replica default replica policy, with values such as aerospike.POLICY_REPLICA_MASTER (Deprecated: set this in one or all of the ‘read’, ‘write’, ‘apply’, ‘operate’, ‘remove’ policy dictionaries)
    • commit_level default commit level policy, with values such as aerospike.POLICY_COMMIT_LEVEL_ALL (Deprecated: set this as needed individually in the ‘write’, ‘apply’, ‘operate’, ‘remove’ policy dictionaries)
  • shm a dict with optional shared-memory cluster tending parameters. Shared-memory cluster tending is on if the dict is provided. If multiple clients are instantiated talking to the same cluster the shm cluster-tending should be used.
    • max_nodes maximum number of nodes allowed. Pad so new nodes can be added without configuration changes (default: 16)
    • max_namespaces similarly pad (default: 8)
    • takeover_threshold_sec take over tending if the cluster hasn’t been checked for this many seconds (default: 30)
    • shm_key
      explicitly set the shm key for this client.
      If use_shared_connection is not set, or set to False, the user must provide a value for this field in order for shared memory to work correctly.
      If , and only if, use_shared_connection is set to True, the key will be implicitly evaluated per unique hostname, and can be inspected with shm_key() .
      It is still possible to specify a key when using use_shared_connection = True.
      (default: 0xA8000000)
  • use_shared_connection bool indicating whether this instance should share its connection to the Aerospike cluster with other client instances in the same process. (default: False)
  • tls a dict of optional TLS configuration parameters. TLS usage requires Aerospike Enterprise Edition
    • enable a bool indicating whether tls should be enabled or not. Default: False
    • cafile str Path to a trusted CA certificate file. By default TLS will use system standard trusted CA certificates
    • capath str Path to a directory of trusted certificates. See the OpenSSL SSL_CTX_load_verify_locations manual page for more information about the format of the directory.
    • protocols Specifies enabled protocols. This format is the same as Apache’s SSLProtocol documented at https://httpd.apache.org/docs/current/mod/mod_ssl.html#sslprotocol . If not specified the client will use “-all +TLSv1.2”.
    • cipher_suite str Specifies enabled cipher suites. The format is the same as OpenSSL’s Cipher List Format documented at https://www.openssl.org/docs/manmaster/apps/ciphers.html .If not specified the OpenSSL default cipher suite described in the ciphers documentation will be used. If you are not sure what cipher suite to select this option is best left unspecified
    • keyfile str Path to the client’s key for mutual authentication. By default mutual authentication is disabled.
    • keyfile_pw str Decryption password for the client’s key for mutual authentication. By default the key is assumed not to be encrypted.
    • cert_blacklist str Path to a certificate blacklist file. The file should contain one line for each blacklisted certificate. Each line starts with the certificate serial number expressed in hex. Each entry may optionally specify the issuer name of the certificate (serial numbers are only required to be unique per issuer). Example records: 867EC87482B2 /C=US/ST=CA/O=Acme/OU=Engineering/CN=Test Chain CA E2D4B0E570F9EF8E885C065899886461
    • certfile str Path to the client’s certificate chain file for mutual authentication. By default mutual authentication is disabled.
    • crl_check bool Enable CRL checking for the certificate chain leaf certificate. An error occurs if a suitable CRL cannot be found. By default CRL checking is disabled.
    • crl_check_all bool Enable CRL checking for the entire certificate chain. An error occurs if a suitable CRL cannot be found. By default CRL checking is disabled.
    • log_session_info bool Log session information for each connection.
    • for_login_only bool Log session information for each connection. Use TLS connections only for login authentication. All other communication with the server will be done with non-TLS connections. Default: False (Use TLS connections for all communication with server.)
  • serialization an optional instance-level tuple() of (serializer, deserializer). Takes precedence over a class serializer registered with set_serializer().
  • thread_pool_size number of threads in the pool that is used in batch/scan/query commands (default: 16)
  • max_socket_idle Maximum socket idle time in seconds. Connection pools will discard sockets that have
    been idle longer than the maximum. The value is limited to 24 hours (86400). It’s important to set this value to a few seconds less than the server’s proto-fd-idle-ms (default 60000 milliseconds or 1 minute), so the client does not attempt to use a socket that has already been reaped by the server. Default: 0 seconds (disabled) for non-TLS connections, 55 seconds for TLS connections.
  • max_conns_per_node maximum number of pipeline connections allowed for each node
  • tend_interval polling interval in milliseconds for tending the cluster (default: 1000)
  • compression_threshold compress data for transmission if the object size is greater than a given number of bytes (default: 0, meaning ‘never compress’) (Deprecated, set this in the ‘write’ policy dictionary)
  • cluster_name only server nodes matching this name will be used when determining the cluster
  • rack_id
    An integer. Rack where this client instance resides.
    rack_aware and POLICY_REPLICA_PREFER_RACK and server rack configuration must also be set to enable this functionality.
    Default 0.
  • rack_aware
    Boolean. Track server rack data.
    This field is useful when directing read commands to the server node that contains the key and exists on the same rack as the client.
    This serves to lower cloud provider costs when nodes are distributed across different racks/data centers.
    rack_id and POLICY_REPLICA_PREFER_RACK and server rack configuration must also be set to enable this functionality.
    Default False
  • use_services_alternate
    Boolean. Flag to signify if “services-alternate” should be used instead of “services”
    Default False
Returns:an instance of the aerospike.Client class.
import aerospike

# configure the client to first connect to a cluster node at 127.0.0.1
# the client will learn about the other nodes in the cluster from the
# seed node.
# in this configuration shared-memory cluster tending is turned on,
# which is appropriate for a multi-process context, such as a webserver
config = {
    'hosts':    [ ('127.0.0.1', 3000) ],
    'policies': {'read': {total_timeout': 1000}},
    'shm':      { }}
client = aerospike.client(config)

Changed in version 2.0.0.

import aerospike
import sys

# NOTE: Use of TLS Requires Aerospike Enterprise Server Version >= 3.11 and Python Client version 2.1.0 or greater
# To view Instructions for server configuration for TLS see https://www.aerospike.com/docs/guide/security/tls.html
tls_name = "some-server-tls-name"
tls_ip = "127.0.0.1"
tls_port = 4333

# If tls-name is specified, it must match the tls-name specified in the node’s server configuration file
# and match the server’s CA certificate.
tls_host_tuple = (tls_ip, tls_port, tls_name)
hosts = [tls_host_tuple]

# Example configuration which will use TLS with the specifed cafile
tls_config = {
    "cafile": "/path/to/cacert.pem",
    "enable": True
}

client = aerospike.client({
    "hosts": hosts,
    "tls": tls_config
})
try:
    client.connect()
except Exception as e:
    print(e)
    print("Failed to connect")
    sys.exit()

key = ('test', 'demo', 1)
client.put(key, {'aerospike': 'aerospike'})
print(client.get(key))
aerospike.null()

A type for distinguishing a server-side null from a Python None. Replaces the constant aerospike.null.

Returns:a type representing the server-side type as_null.

New in version 2.0.1.

aerospike.CDTWildcard()

A type representing a wildcard object. This type may only be used as a comparison value in operations. It may not be stored in the database.

Returns:a type representing a wildcard value.
import aerospike
from aerospike_helpers.operations import list_operations as list_ops

client = aerospike.client({'hosts': [('localhost', 3000)]}).connect()
key = 'test', 'demo', 1

#  get all values of the form [1, ...] from a list of lists.
#  For example if list is [[1, 2, 3], [2, 3, 4], [1, 'a']], this operation will match
#  [1, 2, 3] and [1, 'a']
operations = [list_ops.list_get_by_value('list_bin', [1, aerospike.CDTWildcard()], aerospike.LIST_RETURN_VALUE)]
_, _, bins = client.operate(key, operations)

New in version 3.5.0.

Note

This requires Aerospike Server 4.3.1.3 or greater

aerospike.CDTInfinite()

A type representing an infinte value. This type may only be used as a comparison value in operations. It may not be stored in the database.

Returns:a type representing an infinite value.
import aerospike
from aerospike_helpers.operations import list_operations as list_ops

client = aerospike.client({'hosts': [('localhost', 3000)]}).connect()
key = 'test', 'demo', 1

#  get all values of the form [1, ...] from a list of lists.
#  For example if list is [[1, 2, 3], [2, 3, 4], [1, 'a']], this operation will match
#  [1, 2, 3] and [1, 'a']
operations = [list_ops.list_get_by_value_range('list_bin', aerospike.LIST_RETURN_VALUE, [1],  [1, aerospike.CDTInfinite()])]
_, _, bins = client.operate(key, operations)

New in version 3.5.0.

Note

This requires Aerospike Server 4.3.1.3 or greater

aerospike.calc_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, int or bytearray) – the primary key identifier of the record within the set.
Returns:

a RIPEMD-160 digest of the input tuple.

Return type:

bytearray

import aerospike
import pprint

digest = aerospike.calc_digest("test", "demo", 1 )
pp.pprint(digest)

Serialization

Note

By default, the aerospike.Client maps the supported types int, str, float, bytearray, list, dict to matching aerospike server types (int, string, double, bytes, list, map). When an unsupported type is encountered, the module uses cPickle to serialize and deserialize the data, storing it into as_bytes of type ‘Python’ (AS_BYTES_PYTHON).

The functions set_serializer() and set_deserializer() allow for user-defined functions to handle serialization, instead. The serialized data is stored as ‘Generic’ as_bytes of type (AS_BYTES_BLOB). The serialization config param of aerospike.client() registers an instance-level pair of functions that handle serialization.

aerospike.set_serializer(callback)

Register a user-defined serializer available to all aerospike.Client instances.

Parameters:callback (callable) – the function to invoke for serialization.

See also

To use this function with put() the argument to serializer should be aerospike.SERIALIZER_USER.

import aerospike
import json

def my_serializer(val):
    return json.dumps(val)

aerospike.set_serializer(my_serializer)

New in version 1.0.39.

aerospike.set_deserializer(callback)

Register a user-defined deserializer available to all aerospike.Client instances. Once registered, all read methods (such as get()) will run bins containing ‘Generic’ as_bytes of type (AS_BYTES_BLOB) through this deserializer.

Parameters:callback (callable) – the function to invoke for deserialization.
aerospike.unset_serializers()

Deregister the user-defined de/serializer available from aerospike.Client instances.

New in version 1.0.53.

Note

Serialization Examples

The following example shows the three modes of serialization - built-in, class-level user functions, instance-level user functions:

from __future__ import print_function
import aerospike
import marshal
import json

def go_marshal(val):
    return marshal.dumps(val)

def demarshal(val):
    return marshal.loads(val)

def jsonize(val):
    return json.dumps(val)

def dejsonize(val):
    return json.loads(val)

aerospike.set_serializer(go_marshal)
aerospike.set_deserializer(demarshal)
config = {'hosts':[('127.0.0.1', 3000)]}
client = aerospike.client(config).connect()
config['serialization'] = (jsonize,dejsonize)
client2 = aerospike.client(config).connect()

for i in xrange(1, 4):
    try:
        client.remove(('test', 'demo', 'foo' + i))
    except:
        pass

bin_ = {'t': (1, 2, 3)} # tuple is an unsupported type
print("Use the built-in serialization (cPickle)")
client.put(('test','demo','foo1'), bin_)
(key, meta, bins) = client.get(('test','demo','foo1'))
print(bins)

print("Use the class-level user-defined serialization (marshal)")
client.put(('test','demo','foo2'), bin_, serializer=aerospike.SERIALIZER_USER)
(key, meta, bins) = client.get(('test','demo','foo2'))
print(bins)

print("Use the instance-level user-defined serialization (json)")
client2.put(('test','demo','foo3'), bin_, serializer=aerospike.SERIALIZER_USER)
# notice that json-encoding a tuple produces a list
(key, meta, bins) = client2.get(('test','demo','foo3'))
print(bins)
client.close()

The expected output is:

Use the built-in serialization (cPickle)
{'i': 321, 't': (1, 2, 3)}
Use the class-level user-defined serialization (marshal)
{'i': 321, 't': (1, 2, 3)}
Use the instance-level user-defined serialization (json)
{'i': 321, 't': [1, 2, 3]}

While AQL shows the records as having the following structure:

aql> select i,t from test.demo where PK='foo1'
+-----+----------------------------------------------+
| i   | t                                            |
+-----+----------------------------------------------+
| 321 | 28 49 31 0A 49 32 0A 49 33 0A 74 70 31 0A 2E |
+-----+----------------------------------------------+
1 row in set (0.000 secs)

aql> select i,t from test.demo where PK='foo2'
+-----+-------------------------------------------------------------+
| i   | t                                                           |
+-----+-------------------------------------------------------------+
| 321 | 28 03 00 00 00 69 01 00 00 00 69 02 00 00 00 69 03 00 00 00 |
+-----+-------------------------------------------------------------+
1 row in set (0.000 secs)

aql> select i,t from test.demo where PK='foo3'
+-----+----------------------------+
| i   | t                          |
+-----+----------------------------+
| 321 | 5B 31 2C 20 32 2C 20 33 5D |
+-----+----------------------------+
1 row in set (0.000 secs)

Logging

aerospike.set_log_handler(callback)

Set a user-defined function as the log handler for all aerospike objects. The callback is invoked whenever a log event passing the logging level threshold is encountered.

Parameters:callback (callable) – the function used as the logging handler.

Note

The callback function must have the five parameters (level, func, path, line, msg)

from __future__ import print_function
import aerospike

def as_logger(level, func, path, line, msg):
def as_logger(level, func, myfile, line, msg):
    print("**", myfile, line, func, ':: ', msg, "**")

aerospike.set_log_level(aerospike.LOG_LEVEL_DEBUG)
aerospike.set_log_handler(as_logger)
aerospike.set_log_level(log_level)

Declare the logging level threshold for the log handler.

Parameters:log_level (int) – one of the Log Level constant values.

Geospatial

aerospike.geodata([geo_data])

Helper for creating an instance of the GeoJSON class. Used to wrap a geospatial object, such as a point, polygon or circle.

Parameters:geo_data (dict) – a dict representing the geospatial data.
Returns:an instance of the aerospike.GeoJSON class.
import aerospike

# Create GeoJSON point using WGS84 coordinates.
latitude = 45.920278
longitude = 63.342222
loc = aerospike.geodata({'type': 'Point',
                         'coordinates': [longitude, latitude]})

New in version 1.0.54.

aerospike.geojson([geojson_str])

Helper for creating an instance of the GeoJSON class from a raw GeoJSON str.

Parameters:geojson_str (dict) – a str of raw GeoJSON.
Returns:an instance of the aerospike.GeoJSON class.
import aerospike

# Create GeoJSON point using WGS84 coordinates.
loc = aerospike.geojson('{"type": "Point", "coordinates": [-80.604333, 28.608389]}')

New in version 1.0.54.

Operators

Operators for the multi-ops method operate().

Note

Beginning in version 3.4.0, it is recommended to use the operation helpers module aerospike_helpers.operations package To create the arguments for the operate() and operate()

aerospike.OPERATOR_WRITE

Write a value into a bin

{
    "op" : aerospike.OPERATOR_WRITE,
    "bin": "name",
    "val": "Peanut"
}
aerospike.OPERATOR_APPEND

Append to a bin with str type data

{
    "op" : aerospike.OPERATOR_APPEND,
    "bin": "name",
    "val": "Mr. "
}
aerospike.OPERATOR_PREPEND

Prepend to a bin with str type data

{
    "op" : aerospike.OPERATOR_PREPEND,
    "bin": "name",
    "val": " Esq."
}
aerospike.OPERATOR_INCR

Increment a bin with int or float type data

{
    "op" : aerospike.OPERATOR_INCR,
    "bin": "age",
    "val": 1
}
aerospike.OPERATOR_READ

Read a specific bin

{
    "op" : aerospike.OPERATOR_READ,
    "bin": "name"
}
aerospike.OPERATOR_TOUCH

Touch a record, setting its TTL. May be combined with OPERATOR_READ

{
    "op" : aerospike.OPERATOR_TOUCH
}
aerospike.OP_LIST_APPEND

Append an element to a bin with list type data

{
    "op" : aerospike.OP_LIST_APPEND,
    "bin": "events",
    "val": 1234,
    "list_policy": {"write_flags": aerospike.LIST_WRITE_ADD_UNIQUE} # Optional, new in client 3.4.0
}

Changed in version 3.4.0.

aerospike.OP_LIST_APPEND_ITEMS

Extend a bin with list type data with a list of items

{
    "op" : aerospike.OP_LIST_APPEND_ITEMS,
    "bin": "events",
    "val": [ 123, 456 ],
    "list_policy": {"write_flags": aerospike.LIST_WRITE_ADD_UNIQUE} # Optional, new in client 3.4.0
}

Changed in version 3.4.0.

aerospike.OP_LIST_INSERT

Insert an element at a specified index of a bin with list type data

{
    "op" : aerospike.OP_LIST_INSERT,
    "bin": "events",
    "index": 2,
    "val": 1234,
    "list_policy": {"write_flags": aerospike.LIST_WRITE_ADD_UNIQUE} # Optional, new in client 3.4.0
}

Changed in version 3.4.0.

aerospike.OP_LIST_INSERT_ITEMS

Insert the items at a specified index of a bin with list type data

{
    "op" : aerospike.OP_LIST_INSERT_ITEMS,
    "bin": "events",
    "index": 2,
    "val": [ 123, 456 ]
    "list_policy": {"write_flags": aerospike.LIST_WRITE_ADD_UNIQUE} # Optional, new in client 3.4.0
}

Changed in version 3.4.0.

aerospike.OP_LIST_INCREMENT

Increment the value of an item at the given index in a list stored in the specified bin

{
    "op": aerospike.OP_LIST_INCREMENT,
    "bin": "bin_name",
    "index": 2,
    "val": 5,
    "list_policy": {"write_flags": aerospike.LIST_WRITE_ADD_UNIQUE} # Optional, new in client 3.4.0
}

Changed in version 3.4.0.

aerospike.OP_LIST_POP

Remove and return the element at a specified index of a bin with list type data

{
    "op" : aerospike.OP_LIST_POP, # removes and returns a value
    "bin": "events",
    "index": 2
}
aerospike.OP_LIST_POP_RANGE

Remove and return a list of elements at a specified index range of a bin with list type data

{
    "op" : aerospike.OP_LIST_POP_RANGE,
    "bin": "events",
    "index": 2,
    "val": 3 # remove and return 3 elements starting at index 2
}
aerospike.OP_LIST_REMOVE

Remove the element at a specified index of a bin with list type data

{
    "op" : aerospike.OP_LIST_REMOVE, # remove a value
    "bin": "events",
    "index": 2
}
aerospike.OP_LIST_REMOVE_RANGE

Remove a list of elements at a specified index range of a bin with list type data

{
    "op" : aerospike.OP_LIST_REMOVE_RANGE,
    "bin": "events",
    "index": 2,
    "val": 3 # remove 3 elements starting at index 2
}
aerospike.OP_LIST_CLEAR

Remove all the elements in a bin with list type data

 {
    "op" : aerospike.OP_LIST_CLEAR,
    "bin": "events"
}
aerospike.OP_LIST_SET

Set the element val in a specified index of a bin with list type data

{
    "op" : aerospike.OP_LIST_SET,
    "bin": "events",
    "index": 2,
    "val": "latest event at index 2" # set this value at index 2,
    "list_policy": {"write_flags": aerospike.LIST_WRITE_ADD_UNIQUE} # Optional, new in client 3.4.0
}

Changed in version 3.4.0.

aerospike.OP_LIST_GET

Get the element at a specified index of a bin with list type data

{
    "op" : aerospike.OP_LIST_GET,
    "bin": "events",
    "index": 2
}
aerospike.OP_LIST_GET_RANGE

Get the list of elements starting at a specified index of a bin with list type data

{
    "op" : aerospike.OP_LIST_GET_RANGE,
    "bin": "events",
    "index": 2,
    "val": 3 # get 3 elements starting at index 2
}
aerospike.OP_LIST_TRIM

Remove elements from a bin with list type data which are not within the range starting at a given index plus val

{
    "op" : aerospike.OP_LIST_TRIM,
    "bin": "events",
    "index": 2,
    "val": 3 # remove all elements not in the range between index 2 and index 2 + 3
}
aerospike.OP_LIST_SIZE

Count the number of elements in a bin with list type data

{
    "op" : aerospike.OP_LIST_SIZE,
    "bin": "events" # gets the size of a list contained in the bin
}
aerospike.OP_LIST_GET_BY_INDEX

Get the item at the specified index from a list bin. Server selects list item identified by index and returns selected data specified by return_type.

{
    "op" : aerospike.OP_LIST_GET_BY_INDEX,
    "bin": "events",
    "index": 2, # Index of the item to fetch
    "return_type": aerospike.LIST_RETURN_VALUE
}

New in version 3.4.0.

aerospike.OP_LIST_GET_BY_INDEX_RANGE

Server selects count list items starting at specified index and returns selected data specified by return_type. if count is omitted, the server returns all items from index to the end of list.

If inverted is set to True, return all items outside of the specified range.

{
    "op" : aerospike.OP_LIST_GET_BY_INDEX_RANGE,
    "bin": "events",
    "index": 2, # Beginning index of range,
    "count": 2, # Optional Count.
    "return_type": aerospike.LIST_RETURN_VALUE,
    "inverted": False # Optional.
}

New in version 3.4.0.

aerospike.OP_LIST_GET_BY_RANK

Server selects list item identified by rank and returns selected data specified by return_type.

{
    "op" : aerospike.OP_LIST_GET_BY_RANK,
    "bin": "events",
    "rank": 2, # Rank of the item to fetch
    "return_type": aerospike.LIST_RETURN_VALUE
}

New in version 3.4.0.

aerospike.OP_LIST_GET_BY_RANK_RANGE

Server selects count list items starting at specified rank and returns selected data specified by return_type. If count is not specified, the server returns items starting at the specified rank to the last ranked item.

If inverted is set to True, return all items outside of the specified range.

{
    "op" : aerospike.OP_LIST_GET_BY_RANK_RANGE,
    "bin": "events",
    "rank": 2, # Rank of the item to fetch
    "count": 3,
    "return_type": aerospike.LIST_RETURN_VALUE,
    "inverted": False # Optional, defaults to False
}

New in version 3.4.0.

aerospike.OP_LIST_GET_BY_VALUE

Server selects list items identified by val and returns selected data specified by return_type.

{
    "op" : aerospike.OP_LIST_GET_BY_VALUE,
    "bin": "events",
    "val": 5,
    "return_type": aerospike.LIST_RETURN_COUNT
}

New in version 3.4.0.

aerospike.OP_LIST_GET_BY_VALUE_LIST

Server selects list items contained in by value_list and returns selected data specified by return_type.

If inverted is set to True, returns items not included in value_list

{
    "op" : aerospike.OP_LIST_GET_BY_VALUE_LIST,
    "bin": "events",
    "value_list": [5, 6, 7],
    "return_type": aerospike.LIST_RETURN_COUNT,
    "inverted": False # Optional, defaults to False
}

New in version 3.4.0.

aerospike.OP_LIST_GET_BY_VALUE_RANGE

Create list get by value range operation. Server selects list items identified by value range (begin inclusive, end exclusive). If value_begin is not present the range is less than value_end. If value_end is not specified, the range is greater than or equal to value_begin.

If inverted is set to True, returns items not included in the specified range.

{
    "op" : aerospike.OP_LIST_GET_BY_VALUE_RANGE,
    "bin": "events",
    "value_begin": 3, # Optional
    "value_end": 6, Optional
    "return_type": aerospike.LIST_RETURN_VALUE,
    "inverted": False # Optional, defaults to False
}

New in version 3.4.0.

aerospike.OP_LIST_REMOVE_BY_INDEX

Remove and return the item at the specified index from a list bin. Server selects list item identified by index and returns selected data specified by return_type.

{
    "op" : aerospike.OP_LIST_REMOVE_BY_INDEX,
    "bin": "events",
    "index": 2, # Index of the item to fetch
    "return_type": aerospike.LIST_RETURN_VALUE
}

New in version 3.4.0.

aerospike.OP_LIST_REMOVE_BY_INDEX_RANGE

Server remove count list items starting at specified index and returns selected data specified by return_type. if count is omitted, the server removes and returns all items from index to the end of list.

If inverted is set to True, remove and return all items outside of the specified range.

{
    "op" : aerospike.OP_LIST_REMOVE_BY_INDEX_RANGE,
    "bin": "events",
    "index": 2, # Beginning index of range,
    "count": 2, # Optional Count.
    "return_type": aerospike.LIST_RETURN_VALUE,
    "inverted": False # Optional.
}

New in version 3.4.0.

aerospike.OP_LIST_REMOVE_BY_RANK

Server removes and returns list item identified by rank and returns selected data specified by return_type.

{
    "op" : aerospike.OP_LIST_REMOVE_BY_RANK,
    "bin": "events",
    "rank": 2, # Rank of the item to fetch
    "return_type": aerospike.LIST_RETURN_VALUE
}

New in version 3.4.0.

aerospike.OP_LIST_REMOVE_BY_RANK_RANGE

Server removes and returns count list items starting at specified rank and returns selected data specified by return_type. If count is not specified, the server removes and returns items starting at the specified rank to the last ranked item.

If inverted is set to True, removes return all items outside of the specified range.

{
    "op" : aerospike.OP_LIST_REMOVE_BY_RANK_RANGE,
    "bin": "events",
    "rank": 2, # Rank of the item to fetch
    "count": 3,
    "return_type": aerospike.LIST_RETURN_VALUE,
    "inverted": False # Optional, defaults to False
}

New in version 3.4.0.

aerospike.OP_LIST_REMOVE_BY_VALUE

Server removes and returns list items identified by val and returns selected data specified by return_type.

If inverted is set to True, removes and returns list items with a value not equal to val.

{
    "op" : aerospike.OP_LIST_REMOVE_BY_VALUE,
    "bin": "events",
    "val": 5,
    "return_type": aerospike.LIST_RETURN_COUNT,
    "inverted", # Optional, defaults to False
}

New in version 3.4.0.

aerospike.OP_LIST_REMOVE_BY_VALUE_LIST

Server removes and returns list items contained in by value_list and returns selected data specified by return_type.

If inverted is set to True, removes and returns items not included in value_list

{
    "op" : aerospike.OP_LIST_REMOVE_BY_VALUE_LIST,
    "bin": "events",
    "value_list": [5, 6, 7],
    "return_type": aerospike.LIST_RETURN_COUNT,
    "inverted": False # Optional, defaults to False
}

New in version 3.4.0.

aerospike.OP_LIST_REMOVE_BY_VALUE_RANGE

Create list remove by value range operation. Server removes and returns list items identified by value range (begin inclusive, end exclusive). If value_begin is not present the range is less than value_end. If value_end is not specified, the range is greater than or equal to value_begin.

If inverted is set to True, removes and returns items not included in the specified range.

{
    "op" : aerospike.OP_LIST_REMOVE_BY_VALUE_RANGE,
    "bin": "events",
    "value_begin": 3, # Optional
    "value_end": 6, Optional
    "return_type": aerospike.LIST_RETURN_VALUE,
    "inverted": False # Optional, defaults to False
}

New in version 3.4.0.

aerospike.OP_LIST_SET_ORDER

Assign an ordering to the specified list bin. list_order should be one of aerospike.LIST_ORDERED, aerospike.LIST_UNORDERED.

{
    "op": aerospike.OP_LIST_SET_ORDER,
    "list_order": aerospike.LIST_ORDERED,
    "bin": "events"
}

New in version 3.4.0.

aerospike.OP_LIST_SORT

Perform a sort operation on the bin. sort_flags, if provided, can be one of: aerospike.LIST_SORT_DROP_DUPLICATES indicating that duplicate elements should be removed from the sorted list.

{
    'op': aerospike.OP_LIST_SORT,
    'sort_flags': aerospike.LIST_SORT_DROP_DUPLICATES, # Optional flags or'd together specifying behavior
    'bin': self.test_bin
}

New in version 3.4.0.

aerospike.OP_MAP_SET_POLICY

Set the policy for a map bin. The policy controls the write mode and the ordering of the map entries.

{
    "op" : aerospike.OP_MAP_SET_POLICY,
    "bin": "scores",
    "map_policy": {"map_write_mode": Aeorspike.MAP_UPDATE, "map_order": Aerospike.MAP_KEY_VALUE_ORDERED}
}
aerospike.OP_MAP_PUT

Put a key/value pair into a map. Operator accepts an optional map_policy dictionary (see OP_MAP_SET_POLICY for an example)

{
    "op" : aerospike.OP_MAP_PUT,
    "bin": "my_map",
    "key": "age",
    "val": 97
}
OP_MAP_PUT_ITEMS. Operator accepts an optional map_policy dictionary (see OP_MAP_SET_POLICY for an example)

Put a dictionary of key/value pairs into a map.

{
    "op" : aerospike.OP_MAP_PUT_ITEMS,
    "bin": "my_map",
    "val": {"name": "bubba", "occupation": "dancer"}
}
OP_MAP_INCREMENT. Operator accepts an optional map_policy dictionary (see OP_MAP_SET_POLICY for an example)

Increment the value of map entry by the given “val” argument.

{
    "op" : aerospike.OP_MAP_INCREMENT,
    "bin": "my_map",
    "key": "age",
    "val": 1
}
OP_MAP_DECREMENT. Operator accepts an optional map_policy dictionary (see OP_MAP_SET_POLICY for an example)

Decrement the value of map entry by the given “val” argument.

{
    "op" : aerospike.OP_MAP_DECREMENT,
    "bin": "my_map",
    "key": "age",
    "val": 1
}
aerospike.OP_MAP_SIZE

Return the number of entries in the given map bin.

{
    "op" : aerospike.OP_MAP_SIZE,
    "bin": "my_map"
}
aerospike.OP_MAP_CLEAR

Remove all entries from the given map bin.

{
    "op" : aerospike.OP_MAP_CLEAR,
    "bin": "my_map"
}

Note that if “return_type” is not specified in the parameters for a map operation, the default is aerospike.MAP_RETURN_NONE

aerospike.OP_MAP_REMOVE_BY_KEY

Remove the first entry from the map bin that matches the given key.

{
    "op" : aerospike.OP_MAP_REMOVE_BY_KEY,
    "bin": "my_map",
    "key": "age",
    "return_type": aerospike.MAP_RETURN_VALUE
}
aerospike.OP_MAP_REMOVE_BY_KEY_LIST

Remove the entries from the map bin that match the list of given keys. If inverted is set to True, remove all items except those in the list of keys.

{
    "op" : aerospike.OP_MAP_REMOVE_BY_KEY_LIST,
    "bin": "my_map",
    "val": ["name", "rank", "serial"],
    "inverted": False #Optional
}
aerospike.OP_MAP_REMOVE_BY_KEY_RANGE

Remove the entries from the map bin that have keys which fall between the given “key” (inclusive) and “val” (exclusive). If inverted is set to True, remove all items outside of the specified range.

{
    "op" : aerospike.OP_MAP_REMOVE_BY_KEY_RANGE,
    "bin": "my_map",
    "key": "i",
    "val": "j",
    "return_type": aerospike.MAP_RETURN_KEY_VALUE,
    "inverted": False # Optional
}
aerospike.OP_MAP_REMOVE_BY_VALUE

Remove the entry or entries from the map bin that have values which match the given “val” parameter. If inverted is set to True, remove all items with a value other than val

{
    "op" : aerospike.OP_MAP_REMOVE_BY_VALUE,
    "bin": "my_map",
    "val": 97,
    "return_type": aerospike.MAP_RETURN_KEY
    "inverted": False #optional
}
aerospike.OP_MAP_REMOVE_BY_VALUE_LIST

Remove the entries from the map bin that have values which match the list of values given in the “val” parameter. If inverted is set to True, remove all items with values not contained in the list of values.

{
    "op" : aerospike.OP_MAP_REMOVE_BY_VALUE_LIST,
    "bin": "my_map",
    "val": [97, 98, 99],
    "return_type": aerospike.MAP_RETURN_KEY,
    "inverted": False # Optional
}
aerospike.OP_MAP_REMOVE_BY_VALUE_RANGE

Remove the entries from the map bin that have values starting with the given “val” parameter (inclusive) up to the given “range” parameter (exclusive). If inverted is set to True, remove all items outside of the specified range.

{
    "op" : aerospike.OP_MAP_REMOVE_BY_VALUE_RANGE,
    "bin": "my_map",
    "val": 97,
    "range": 100,
    "return_type": aerospike.MAP_RETURN_KEY,
    "inverted": False # Optional
}
aerospike.OP_MAP_REMOVE_BY_INDEX

Remove the entry from the map bin at the given “index” location.

{
    "op" : aerospike.OP_MAP_REMOVE_BY_INDEX,
    "bin": "my_map",
    "index": 0,
    "return_type": aerospike.MAP_RETURN_KEY_VALUE
}
aerospike.OP_MAP_REMOVE_BY_INDEX_RANGE

Remove the entries from the map bin starting at the given “index” location and removing “range” items. If inverted is set to True, remove all items outside of the specified range.

{
    "op" : aerospike.OP_MAP_REMOVE_BY_INDEX_RANGE,
    "bin": "my_map",
    "index": 0,
    "val": 2,
    "return_type": aerospike.MAP_RETURN_KEY_VALUE,
    "inverted": False # Optional
}
aerospike.OP_MAP_REMOVE_BY_RANK

Remove the first entry from the map bin that has a value with a rank matching the given “index”.

{
    "op" : aerospike.OP_MAP_REMOVE_BY_RANK,
    "bin": "my_map",
    "index": 10
}
aerospike.OP_MAP_REMOVE_BY_RANK_RANGE

Remove the entries from the map bin that have values with a rank starting at the given “index” and removing “range” items. If inverted is set to True, remove all items outside of the specified range.

{
    "op" : aerospike.OP_MAP_REMOVE_BY_RANK_RANGE,
    "bin": "my_map",
    "index": 10,
    "val": 2,
    "return_type": aerospike.MAP_RETURN_KEY_VALUE,
    "inverted": False # Optional
}
aerospike.OP_MAP_GET_BY_KEY

Return the entry from the map bin that which has a key that matches the given “key” parameter.

{
    "op" : aerospike.OP_MAP_GET_BY_KEY,
    "bin": "my_map",
    "key": "age",
    "return_type": aerospike.MAP_RETURN_KEY_VALUE
}
aerospike.OP_MAP_GET_BY_KEY_RANGE

Return the entries from the map bin that have keys which fall between the given “key” (inclusive) and “val” (exclusive). If inverted is set to True, return all items outside of the specified range.

{
    "op" : aerospike.OP_MAP_GET_BY_KEY_RANGE,
    "bin": "my_map",
    "key": "i",
    "range": "j",
    "return_type": aerospike.MAP_RETURN_KEY_VALUE
    "inverted": False # Optional
}
aerospike.OP_MAP_GET_BY_VALUE

Return the entry or entries from the map bin that have values which match the given “val” parameter. If inverted is set to True, return all items with a value not equal to the given “val” parameter.

{
    "op" : aerospike.OP_MAP_GET_BY_VALUE,
    "bin": "my_map",
    "val": 97,
    "return_type": aerospike.MAP_RETURN_KEY
}
aerospike.OP_MAP_GET_BY_VALUE_RANGE

Return the entries from the map bin that have values starting with the given “val” parameter (inclusive) up to the given “range” parameter (exclusive). If inverted is set to True, return all items outside of the specified range.

{
    "op" : aerospike.OP_MAP_GET_BY_VALUE_RANGE,
    "bin": "my_map",
    "val": 97,
    "range": 100,
    "return_type": aerospike.MAP_RETURN_KEY,
    "inverted": False # Optional
}
aerospike.OP_MAP_GET_BY_INDEX

Return the entry from the map bin at the given “index” location.

{
    "op" : aerospike.OP_MAP_GET_BY_INDEX,
    "bin": "my_map",
    "index": 0,
    "return_type": aerospike.MAP_RETURN_KEY_VALUE
}
aerospike.OP_MAP_GET_BY_INDEX_RANGE

Return the entries from the map bin starting at the given “index” location and returning “range” items. If inverted is set to True, return all items outside of the specified range.

{
    "op" : aerospike.OP_MAP_GET_BY_INDEX_RANGE,
    "bin": "my_map",
    "index": 0,
    "val": 2,
    "return_type": aerospike.MAP_RETURN_KEY_VALUE,
    "inverted": False # Optional
}
aerospike.OP_MAP_GET_BY_RANK

Return the first entry from the map bin that has a value with a rank matching the given “index”.

{
    "op" : aerospike.OP_MAP_GET_BY_RANK,
    "bin": "my_map",
    "index": 10
}
aerospike.OP_MAP_GET_BY_RANK_RANGE

Return the entries from the map bin that have values with a rank starting at the given “index” and removing “range” items. If inverted is set to True, return all items outside of the specified range.

{
    "op" : aerospike.OP_MAP_GET_BY_RANK_RANGE,
    "bin": "my_map",
    "index": 10,
    "val": 2,
    "return_type": aerospike.MAP_RETURN_KEY_VALUE,
    "inverted": False # Optional
}

Changed in version 2.0.4.

Policies

Commit Level Policy Options

Specifies the number of replicas required to be successfully committed before returning success in a write operation to provide the desired consistency guarantee.

aerospike.POLICY_COMMIT_LEVEL_ALL

Return succcess only after successfully committing all replicas

aerospike.POLICY_COMMIT_LEVEL_MASTER

Return succcess after successfully committing the master replica

AP Read Mode Policy Options

Read policy for AP (availability) namespaces.

New in version 3.7.0.

aerospike.POLICY_READ_MODE_AP_ONE

Involve single node in the read operation.

New in version 3.7.0.

aerospike.POLICY_READ_MODE_AP_ALL

Involve all duplicates in the read operation.

New in version 3.7.0.

SC Read Mode Policy Options

Read policy for SC (strong consistency) namespaces.

New in version 3.7.0.

aerospike.POLICY_READ_MODE_SC_SESSION

Ensures this client will only see an increasing sequence of record versions. Server only reads from master. This is the default.

New in version 3.7.0.

aerospike.POLICY_READ_MODE_SC_LINEARIZE

Ensures ALL clients will only see an increasing sequence of record versions. Server only reads from master.

New in version 3.7.0.

aerospike.POLICY_READ_MODE_SC_ALLOW_REPLICA

Server may read from master or any full (non-migrating) replica. Increasing sequence of record versions is not guaranteed.

New in version 3.7.0.

aerospike.POLICY_READ_MODE_SC_ALLOW_UNAVAILABLE

Server may read from master or any full (non-migrating) replica or from unavailable partitions. Increasing sequence of record versions is not guaranteed.

New in version 3.7.0.

Existence Policy Options

Specifies the behavior for writing the record depending whether or not it exists.

aerospike.POLICY_EXISTS_CREATE

Create a record, ONLY if it doesn’t exist

aerospike.POLICY_EXISTS_CREATE_OR_REPLACE

Completely replace a record if it exists, otherwise create it

aerospike.POLICY_EXISTS_IGNORE

Write the record, regardless of existence. (i.e. create or update)

aerospike.POLICY_EXISTS_REPLACE

Completely replace a record, ONLY if it exists

aerospike.POLICY_EXISTS_UPDATE

Update a record, ONLY if it exists

Generation Policy Options

Specifies the behavior of record modifications with regard to the generation value.

aerospike.POLICY_GEN_IGNORE

Write a record, regardless of generation

aerospike.POLICY_GEN_EQ

Write a record, ONLY if generations are equal

aerospike.POLICY_GEN_GT

Write a record, ONLY if local generation is greater-than remote generation

Key Policy Options

Specifies the behavior for whether keys or digests should be sent to the cluster.

aerospike.POLICY_KEY_DIGEST

Calculate the digest on the client-side and send it to the server

aerospike.POLICY_KEY_SEND

Send the key in addition to the digest. This policy causes a write operation to store the key on the server

Replica Options

Specifies which partition replica to read from.

aerospike.POLICY_REPLICA_SEQUENCE

Always try node containing master partition first. If connection fails and retry_on_timeout is true, try node containing prole partition. Currently restricted to master and one prole.

aerospike.POLICY_REPLICA_MASTER

Read from the partition master replica node

aerospike.POLICY_REPLICA_ANY

Distribute reads across nodes containing key’s master and replicated partition in round-robin fashion. Currently restricted to master and one prole.

aerospike.POLICY_REPLICA_PREFER_RACK
Try node on the same rack as the client first. If there are no nodes on the same rack, use POLICY_REPLICA_SEQUENCE instead.

rack_aware and rack_id must be set in the config argument of the client constructor in order to enable this functionality

Retry Policy Options

Specifies the behavior of failed operations.

aerospike.POLICY_RETRY_NONE

Only attempt an operation once

aerospike.POLICY_RETRY_ONCE

If an operation fails, attempt the operation one more time

Auth Mode Constants

Specifies the type of authentication to be used when communicating with the server

aerospike.AUTH_INTERNAL

Use internal authentication only. Hashed password is stored on the server. Do not send clear password. This is the default.

aerospike.AUTH_EXTERNAL

Use external authentication (like LDAP). Specific external authentication is configured on server. If TLS defined, send clear password on node login via TLS. Throw exception if TLS is not defined.

aerospike.AUTH_EXTERNAL_INSECURE

Use external authentication (like LDAP). Specific external authentication is configured on server. Send clear password on node login whether or not TLS is defined. This mode should only be used for testing purposes because it is not secure authentication.

Scan Constants

aerospike.SCAN_PRIORITY_AUTO
aerospike.SCAN_PRIORITY_HIGH
aerospike.SCAN_PRIORITY_LOW
aerospike.SCAN_PRIORITY_MEDIUM
aerospike.SCAN_STATUS_ABORTED

Deprecated since version 1.0.50: used by scan_info()

aerospike.SCAN_STATUS_COMPLETED

Deprecated since version 1.0.50: used by scan_info()

aerospike.SCAN_STATUS_INPROGRESS

Deprecated since version 1.0.50: used by scan_info()

aerospike.SCAN_STATUS_UNDEF

Deprecated since version 1.0.50: used by scan_info()

New in version 1.0.39.

Job Constants

aerospike.JOB_SCAN

Scan job type argument for the module parameter of job_info()

aerospike.JOB_QUERY

Query job type argument for the module parameter of job_info()

aerospike.JOB_STATUS_UNDEF
aerospike.JOB_STATUS_INPROGRESS
aerospike.JOB_STATUS_COMPLETED

New in version 1.0.50.

Serialization Constants

aerospike.SERIALIZER_PYTHON

Use the cPickle serializer to handle unsupported types (default)

aerospike.SERIALIZER_USER

Use a user-defined serializer to handle unsupported types. Must have been registered for the aerospike class or configured for the Client object

aerospike.SERIALIZER_NONE

Do not serialize bins whose data type is unsupported

New in version 1.0.47.

Miscellaneous

aerospike.__version__

A str containing the module’s version.

New in version 1.0.54.

aerospike.null

A value for distinguishing a server-side null from a Python None .

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

aerospike.UDF_TYPE_LUA
aerospike.INDEX_STRING

An index whose values are of the aerospike string data type

aerospike.INDEX_NUMERIC

An index whose values are of the aerospike integer data type

aerospike.INDEX_GEO2DSPHERE

An index whose values are of the aerospike GetJSON data type

See also

Data Types.

aerospike.INDEX_TYPE_LIST

Index a bin whose contents is an aerospike list

aerospike.INDEX_TYPE_MAPKEYS

Index the keys of a bin whose contents is an aerospike map

aerospike.INDEX_TYPE_MAPVALUES

Index the values of a bin whose contents is an aerospike map

Log Level

aerospike.LOG_LEVEL_TRACE
aerospike.LOG_LEVEL_DEBUG
aerospike.LOG_LEVEL_INFO
aerospike.LOG_LEVEL_WARN
aerospike.LOG_LEVEL_ERROR
aerospike.LOG_LEVEL_OFF

Privileges

Permission codes define the type of permission granted for a user’s role.

aerospike.PRIV_READ

The user is granted read access.

aerospike.PRIV_WRITE

The user is granted write access.

aerospike.PRIV_READ_WRITE

The user is granted read and write access.

aerospike.PRIV_READ_WRITE_UDF

The user is granted read and write access, and the ability to invoke UDFs.

aerospike.PRIV_SYS_ADMIN

The user is granted the ability to perform system administration operations. Global scope only.

aerospike.PRIV_USER_ADMIN

The user is granted the ability to perform user administration operations. Global scope only.

aerospike.PRIV_DATA_ADMIN

User can perform systems administration functions on a database that do not involve user administration. Examples include setting dynamic server configuration. Global scope only.

Map Return Types

Return types used by various map operations

aerospike.MAP_RETURN_NONE

Do not return any value.

aerospike.MAP_RETURN_INDEX

Return key index order.

aerospike.MAP_RETURN_REVERSE_INDEX

Return reverse key order.

aerospike.MAP_RETURN_RANK

Return value order.

aerospike.MAP_RETURN_REVERSE_RANK

Return reserve value order.

aerospike.MAP_RETURN_COUNT

Return count of items selected.

aerospike.MAP_RETURN_KEY

Return key for single key read and key list for range read.

aerospike.MAP_RETURN_VALUE

Return value for single key read and value list for range read.

aerospike.MAP_RETURN_KEY_VALUE

Return key/value items. Note that key/value pairs will be returned as a list of tuples (i.e. [(key1, value1), (key2, value2)])

List Return Types

Return types used by various map operations

aerospike.LIST_RETURN_NONE

Do not return any value.

aerospike.LIST_RETURN_INDEX

Return key index order.

aerospike.LIST_RETURN_REVERSE_INDEX

Return reverse key order.

aerospike.LIST_RETURN_RANK

Return value order.

aerospike.LIST_RETURN_REVERSE_RANK

Return reserve value order.

aerospike.LIST_RETURN_COUNT

Return count of items selected.

aerospike.LIST_RETURN_VALUE

Return value for single key read and value list for range read.

Regex Flag Values

Flags used for the predexp.string_regex function

aerospike.REGEX_NONE

Use default behavior.

aerospike.REGEX_ICASE

Do not differentiate case.

aerospike.REGEX_EXTENDED

Use POSIX Extended Regular Expression syntax when interpreting regex.

aerospike.REGEX_NOSUB

Do not report position of matches.

aerospike.REGEX_NEWLINE

Match-any-character operators don’t match a newline.