aerospike
The client connects through a seed node (the address of a single node) to an Aerospike database cluster. From the seed node, the client learns of the other nodes and establishes connections to them. It also gets the partition map of the cluster, which is how it knows where every record actually lives.
The client handles the connections, including re-establishing them ahead of executing an operation. It keeps track of changes to the cluster through a cluster-tending thread.
Assume every in-line example runs this code beforehand:
Warning
Only run example code on a brand new Aerospike server. This code deletes all records in the demo
set!
Basic example:
# Write a record
client.put(keyTuple, {'name': 'John Doe', 'age': 32})
# Read a record
(key, meta, record) = client.get(keyTuple)
To create a new client, use aerospike.client
.
connect([username, password])
If there is currently no connection to the cluster, connect to it. The optional username and password only apply when connecting to the Enterprise Edition of Aerospike.
- param str username
a defined user with roles in the cluster. See
admin_create_user
.- param str password
the password will be hashed by the client using bcrypt.
- raises
~aerospike.exception.ClientError
, for example when a connection cannot be established to a seed node (any single node in the cluster from which the client learns of the other nodes).
Note
Python client 5.0.0 and up will fail to connect to Aerospike server 4.8.x or older. If you see the error "-10, ‘Failed to connect’", please make sure you are using server 4.9 or later.
is_connected()
Tests the connections between the client and the nodes of the cluster. If the result is False
, the client will require another call to ~aerospike.connect
.
- rtype
bool
2.0.0
close()
Close all connections to the cluster. It is recommended to explicitly call this method when the program is done communicating with the cluster.
You may call ~aerospike.Client.connect
again after closing the connection.
put(key, bins: dict[, meta: dict[, policy: dict[, serializer=aerospike.SERIALIZER_NONE]]])
Create a new record, or remove / add bins to a record.
- param tuple key
a
aerospike_key_tuple
associated with the record.- param dict bins
contains bin name-value pairs of the record.
- param dict meta
record metadata to be set. see
metadata_dict
.- param dict policy
see
aerospike_write_policies
.- param serializer
override the serialization mode of the client with one of the
aerospike_serialization_constants
. To use a class-level, user-defined serialization function registered withaerospike.set_serializer
, useaerospike.SERIALIZER_USER
.- raises
a subclass of
~aerospike.exception.AerospikeError
.
Example:
exists(key[, policy: dict]) -> (key, meta)
Check if a record with a given key exists in the cluster.
Returns the record's key and metadata in a tuple.
If the record does not exist, the tuple's metadata will be :pyNone
.
- param tuple key
a
aerospike_key_tuple
associated with the record.- param dict policy
see
aerospike_read_policies
.- rtype
tuple (key, meta)
- raises
a subclass of
~aerospike.exception.AerospikeError
.
2.0.3
get(key[, policy: dict]) -> (key, meta, bins)
Returns a record with a given key.
- param tuple key
a
aerospike_key_tuple
associated with the record.- param dict policy
see
aerospike_read_policies
.- return
a
aerospike_record_tuple
.- raises
~aerospike.exception.RecordNotFound
.
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 aerospike_record_tuple
.
- param tuple key
a
aerospike_key_tuple
associated with the record.- param list bins
a list of bin names to select from the record.
- param dict policy
optional
aerospike_read_policies
.- return
a
aerospike_record_tuple
.- raises
~aerospike.exception.RecordNotFound
.
2.0.0
touch(key[, val=0[, meta: dict[, policy: dict]]])
Touch the given record, setting its time-to-live and incrementing its generation.
- param tuple key
a
aerospike_key_tuple
associated with the record.- param int val
ttl in seconds, with
0
resolving to the default value in the server config.- param dict meta
record metadata to be set. see
metadata_dict
- param dict policy
see
aerospike_operate_policies
.- raises
a subclass of
~aerospike.exception.AerospikeError
.
remove(key[meta: dict[, policy: dict]])
Remove a record matching the key from the cluster.
- param tuple key
a
aerospike_key_tuple
associated with the record.- param dict meta
contains the expected generation of the record in a key called
"gen"
.- param dict policy
see
aerospike_remove_policies
. May be passed as a keyword argument.- raises
a subclass of
~aerospike.exception.AerospikeError
.
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 ~aerospike.put
.
- param tuple key
a
aerospike_key_tuple
associated with the record.- param list list
the bins names to be removed from the record.
- param dict meta
record metadata to be set. See
metadata_dict
.- param dict policy
optional
aerospike_write_policies
.- raises
a subclass of
~aerospike.exception.AerospikeError
.
single: Batch Operations
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 :pyNone
value for metadata and bins in the record tuple.
- param list keys
a list of
aerospike_key_tuple
.- param dict policy
see
aerospike_batch_policies
.- return
a
list
ofaerospike_record_tuple
.- raises
a
~aerospike.exception.ClientError
if the batch is too big.
12.0.0 Use batch_read
instead.
exists_many(keys[, policy: dict]) -> [ (key, meta)]
Batch-read metadata for multiple keys.
Any record that does not exist will have a :pyNone
value for metadata in their tuple.
- param list keys
a list of
aerospike_key_tuple
.- param dict policy
see
aerospike_batch_policies
.- return
a
list
of (key, metadata)tuple
for each record.
12.0.0 Use batch_read
instead.
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 :pyNone
value for metadata and bins in its tuple.
- param list keys
a list of
aerospike_key_tuple
to read from.- param list bins
a list of bin names to read from the records.
- param dict policy
see
aerospike_batch_policies
.- return
a
list
ofaerospike_record_tuple
.
12.0.0 Use batch_read
instead.
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 :pyNone
value as bins in the record tuple.
- param list keys
a list of
aerospike_key_tuple
.- param list ops
a list of operations to apply.
- param dict policy
see
aerospike_batch_policies
.- return
a
list
ofaerospike_record_tuple
.- raises
a
~aerospike.exception.ClientError
if the batch is too big.
12.0.0 Use batch_operate
instead.
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
.
- param BatchRecords batch_records
A
BatchRecords
object used to specify the operations to carry out.- param dict policy_batch
aerospike batch policy
aerospike_batch_policies
.- return
A reference to the batch_records argument of type
BatchRecords <aerospike_helpers.batch.records>
.- raises
A subclass of
~aerospike.exception.AerospikeError
.
Note
Requires server version >= 6.0.0.
More information about the batch helpers aerospike_operation_helpers.batch
batch_read(keys: list, [bins: list], [policy_batch: dict]) -> BatchRecords
Read multiple records.
If a list of bin names is not provided, return all the bins for each record.
If a list of bin names is provided, return only these bins for the given list of records.
If an empty list of bin names is provided, only the metadata of each record will be returned. Each BatchRecord.record
in BatchRecords.batch_records
will only be a 2-tuple (key, meta)
.
- param list keys
The key tuples of the records to fetch.
- param list[str] bins
List of bin names to fetch for each record.
- param dict policy_batch
See
aerospike_batch_policies
.- return
an instance of
BatchRecords <aerospike_helpers.batch.records>
.- raises
A subclass of
~aerospike.exception.AerospikeError
.
Note
Requires server version >= 6.0.0.
batch_operate(keys: list, ops: list, [policy_batch: dict], [policy_batch_write: dict], [ttl: int]) -> BatchRecords
Perform the same read/write transactions on multiple keys.
- param list keys
The keys to operate on.
- param list ops
List of operations to apply.
- param dict policy_batch
See
aerospike_batch_policies
.- param dict policy_batch_write
See
aerospike_batch_write_policies
.- param int ttl
The time-to-live (expiration) of each record in seconds.
- return
an instance of
BatchRecords <aerospike_helpers.batch.records>
.- raises
A subclass of
~aerospike.exception.AerospikeError
.
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.
- param list keys
The keys to operate on.
- param str module
the name of the UDF module.
- param str function
the name of the UDF to apply to the record identified by key.
- param list args
the arguments to the UDF.
- param dict policy_batch
See
aerospike_batch_policies
.- param dict policy_batch_apply
See
aerospike_batch_apply_policies
.- return
an instance of
BatchRecords <aerospike_helpers.batch.records>
.- raises
A subclass of
~aerospike.exception.AerospikeError
.
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.
- param list keys
The keys to remove.
- param dict policy_batch
Optional aerospike batch policy
aerospike_batch_policies
.- param dict policy_batch_remove
Optional aerospike batch remove policy
aerospike_batch_remove_policies
.- return
an instance of
BatchRecords <aerospike_helpers.batch.records>
.- raises
A subclass of
~aerospike.exception.AerospikeError
.
single: String Operations
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.
- param tuple key
a
aerospike_key_tuple
tuple associated with the record.- param str bin
the name of the bin.
- param str val
the string to append to the bin value.
- param dict meta
record metadata to be set. See
metadata_dict
.- param dict policy
optional
aerospike_operate_policies
.- raises
a subclass of
~aerospike.exception.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.
- param tuple key
a
aerospike_key_tuple
tuple associated with the record.- param str bin
the name of the bin.
- param str val
the string to prepend to the bin value.
- param dict meta
record metadata to be set. See
metadata_dict
.- param dict policy
optional
aerospike_operate_policies
.- raises
a subclass of
~aerospike.exception.AerospikeError
.
client.put(keyTuple, {'bin1': 'Freeman'})
client.prepend(keyTuple, 'bin1', ' Gordon ')
(_, _, bins) = client.get(keyTuple)
print(bins) # Gordon Freeman
single: Numeric Operations
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.
- param tuple key
a
aerospike_key_tuple
tuple associated with the record.- param str bin
the name of the bin.
- param int offset
the value by which to increment the value in bin.
- type offset
:py
int
or :pyfloat
- param dict meta
record metadata to be set. See
metadata_dict
.- param dict policy
optional
aerospike_operate_policies
. Note: theexists
policy option may not be:aerospike.POLICY_EXISTS_CREATE_OR_REPLACE
noraerospike.POLICY_EXISTS_REPLACE
- raises
a subclass of
~aerospike.exception.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
single: 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.single: 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: Multi-Ops
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 aerospike_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 :pyNone
value. )
- param tuple key
a
aerospike_key_tuple
associated with the record.- param list list
See
aerospike_operation_helpers.operations
.- param dict meta
record metadata to be set. See
metadata_dict
.- param dict policy
optional
aerospike_operate_policies
.- return
a
aerospike_record_tuple
.- raises
a subclass of
~aerospike.exception.AerospikeError
.
Note
operate
can now have multiple write operations on a single bin.
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.
Write operations or read operations that fail will not return a (bin-name, result)
tuple.
- param tuple key
a
aerospike_key_tuple
associated with the record.- param list list
See
aerospike_operation_helpers.operations
.- param dict meta
record metadata to be set. See
metadata_dict
.- param dict policy
optional
aerospike_operate_policies
.- return
a
aerospike_record_tuple
.- raises
a subclass of
~aerospike.exception.AerospikeError
.
2.1.3
single: User Defined Functions
udf_put(filename[, udf_type=aerospike.UDF_TYPE_LUA[, policy: dict]])
Register a UDF module with the cluster.
- param str filename
the path to the UDF module to be registered with the cluster.
- param int udf_type
aerospike.UDF_TYPE_LUA
.- param dict policy
currently timeout in milliseconds is the available policy.
- raises
a subclass of
~aerospike.exception.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)
# 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.
- param str module
the UDF module to be deregistered from the cluster.
- param dict policy
currently timeout in milliseconds is the available policy.
- raises
a subclass of
~aerospike.exception.AerospikeError
.
client.udf_remove('my_module.lua')
udf_list([policy: dict]) -> []
Return the list of UDF modules registered with the cluster.
- param dict policy
currently timeout in milliseconds is the available policy.
- rtype
list
- raises
a subclass of
~aerospike.exception.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.
- param str module
the UDF module to read from the cluster.
- param int language
aerospike.UDF_TYPE_LUA
- param dict policy
currently timeout in milliseconds is the available policy.
- rtype
str
- raises
a subclass of
~aerospike.exception.AerospikeError
.
apply(key, module, function, args[, policy: dict])
Apply a registered (see udf_put
) record UDF to a particular record.
- param tuple key
a
aerospike_key_tuple
associated with the record.- param str module
the name of the UDF module.
- param str function
the name of the UDF to apply to the record identified by key.
- param list args
the arguments to the UDF.
- param dict policy
optional
aerospike_apply_policies
.- return
the value optionally returned by the UDF, one of
str
,int
,float
,bytearray
,list
,dict
.- raises
a subclass of
~aerospike.exception.AerospikeError
.
scan_apply(ns, set, module, function[, args[, policy: dict[, options]]]) -> int
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.
- param str ns
the namespace in the aerospike cluster.
- param str set
the set name. Should be :py
None
if the entire namespace is to be scanned.- param str module
the name of the UDF module.
- param str function
the name of the UDF to apply to the records matched by the scan.
- param list args
the arguments to the UDF.
- param dict policy
optional
aerospike_scan_policies
.- param dict options
the
aerospike_scan_options
that will apply to the scan.- rtype
int
- return
a job ID that can be used with
job_info
to check the status of theaerospike.JOB_SCAN
.- raises
a subclass of
~aerospike.exception.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.
- param str ns
the namespace in the aerospike cluster.
- param str set
the set name. Should be :py
None
if you want to query records in the ns which are in no set.- param tuple predicate
the tuple produced by one of the
aerospike.predicates
methods.- param str module
the name of the UDF module.
- param str function
the name of the UDF to apply to the records matched by the query.
- param list args
the arguments to the UDF.
- param dict policy
optional
aerospike_write_policies
.- rtype
int
- return
a job ID that can be used with
job_info
to check the status of theaerospike.JOB_QUERY
.- raises
a subclass of
~aerospike.exception.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"
: seeaerospike_job_constants_status
for possible values."records_read"
: number of scanned records."progress_pct"
: progress percentage of the job
- param int job_id
the job ID returned by
scan_apply
orquery_apply
.- param module
one of
aerospike_job_constants
.- param policy
optional
aerospike_info_policies
.- returns
dict
- raises
a subclass of
~aerospike.exception.AerospikeError
.
single: Info Operations
get_node_names() -> []
Return the list of hosts and node names present in a connected cluster.
- return
a
list
of node info dictionaries.- raises
a subclass of
~aerospike.exception.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'}]
6.0.0
get_nodes() -> []
Return the list of hosts present in a connected cluster.
- return
a
list
of node address tuples.- raises
a subclass of
~aerospike.exception.AerospikeError
.
# Assuming two nodes
nodes = client.get_nodes()
print(nodes)
# [('127.0.0.1', 3000), ('127.0.0.1', 3010)]
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.
- param str command
the info command. See Info Command Reference.
- param str host
a node name. Example: 'BCER199932C'
- param dict policy
optional
aerospike_info_policies
.- rtype
str
- raises
a subclass of
~aerospike.exception.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.
- param str command
- param dict policy
optional
aerospike_info_policies
.- rtype
dict
- raises
a subclass of
~aerospike.exception.AerospikeError
.
response = client.info_all("namespaces")
print(response)
# {'BB9020011AC4202': (None, 'test\n')}
3.0.0
info_random_node(command, [policy: dict]) -> str
Send an info command to a single random node.
- param str command
the info command. See Info Command Reference.
- param dict policy
optional
aerospike_info_policies
.- rtype
str
- raises
a subclass of
~aerospike.exception.AerospikeError
.
6.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.
- param str data_center
The data center to apply the filter to.
- param str namespace
The namespace to apply the filter to.
- param AerospikeExpression expression_filter
The filter to set. See expressions at :py
aerospike_helpers
.- param dict policy
optional
aerospike_info_policies
.- raises
a subclass of
~aerospike.exception.AerospikeError
.
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_operation_helpers.expressions
for more details on expressions.
- param AerospikeExpression expression
the compiled expression.
- raises
a subclass of
~aerospike.exception.AerospikeError
.
7.0.0
shm_key() -> int
Expose the value of the shm_key for this client if shared-memory cluster tending is enabled,
- rtype
int
or :pyNone
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)
- param str namespace
The namespace to truncate.
- param str set
The set to truncate. Pass in :py
None
to truncate a namespace instead.- param long nanos
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 of0
indicates that all records in the set should be truncated regardless of update time. The value must not be in the future.- param dict policy
See
aerospike_info_policies
.- rtype
Status indicating the success of the operation.
- raises
a subclass of
~aerospike.exception.AerospikeError
.
Note
Requires Aerospike server version >= 3.12
single: Index Operations
index_string_create(ns, set, bin, name[, policy: dict])
Create a string index with index_name on the bin in the specified ns, set.
- param str ns
the namespace in the aerospike cluster.
- param str set
the set name.
- param str bin
the name of bin the secondary index is built on.
- param str name
the name of the index.
- param dict policy
optional
aerospike_info_policies
.- raises
a subclass of
~aerospike.exception.AerospikeError
.
index_integer_create(ns, set, bin, name[, policy])
Create an integer index with name on the bin in the specified ns, set.
- param str ns
the namespace in the aerospike cluster.
- param str set
the set name.
- param str bin
the name of bin the secondary index is built on.
- param str name
the name of the index.
- param dict policy
optional
aerospike_info_policies
.- raises
a subclass of
~aerospike.exception.AerospikeError
.
index_blob_create(ns, set, bin, name[, policy])
Create an blob index with index name name on the bin in the specified ns, set.
- param str ns
the namespace in the aerospike cluster.
- param str set
the set name.
- param str bin
the name of the bin the secondary index is built on.
- param str name
the name of the index.
- param dict policy
optional
aerospike_info_policies
.- raises
a subclass of
~aerospike.exception.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.
- param str ns
the namespace in the aerospike cluster.
- param str set
the set name.
- param str bin
the name of bin the secondary index is built on.
- param index_datatype
Possible values are
aerospike.INDEX_STRING
,aerospike.INDEX_NUMERIC
,aerospike.INDEX_BLOB
, andaerospike.INDEX_GEO2DSPHERE
.- param str name
the name of the index.
- param dict policy
optional
aerospike_info_policies
.- raises
a subclass of
~aerospike.exception.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.
- param str ns
the namespace in the aerospike cluster.
- param str set
the set name.
- param str bin
the name of bin the secondary index is built on.
- param index_datatype
Possible values are
aerospike.INDEX_STRING
,aerospike.INDEX_NUMERIC
,aerospike.INDEX_BLOB
, andaerospike.INDEX_GEO2DSPHERE
.- param str name
the name of the index.
- param dict policy
optional
aerospike_info_policies
.- raises
a subclass of
~aerospike.exception.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.
- param str ns
the namespace in the aerospike cluster.
- param str set
the set name.
- param str bin
the name of bin the secondary index is built on.
- param index_datatype
Possible values are
aerospike.INDEX_STRING
,aerospike.INDEX_NUMERIC
,aerospike.INDEX_BLOB
, andaerospike.INDEX_GEO2DSPHERE
.- param str name
the name of the index.
- param dict policy
optional
aerospike_info_policies
.- raises
a subclass of
~aerospike.exception.AerospikeError
.
Note
Requires server version >= 3.8.0
import aerospike
client = aerospike.client({ 'hosts': [ ('127.0.0.1', 3000)]})
# 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.
- param str ns
the namespace in the aerospike cluster.
- param str set
the set name.
- param str bin
the name of bin the secondary index is built on.
- param str name
the name of the index.
- param dict policy
optional
aerospike_info_policies
.- raises
a subclass of
~aerospike.exception.AerospikeError
.
aerospike.GeoJSON
, aerospike.predicates
Note
Requires server version >= 3.7.0
import aerospike
client = aerospike.client({ 'hosts': [ ('127.0.0.1', 3000)]})
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.
- param str ns
the namespace in the aerospike cluster.
- param str name
the name of the index.
- param dict policy
optional
aerospike_info_policies
.- raises
a subclass of
~aerospike.exception.AerospikeError
.
get_cdtctx_base64(ctx: list) -> str
Get the base64 representation of aerospike CDT ctx.
See aerospike_operation_helpers.cdt_ctx
for more details on CDT context.
- param list ctx
Aerospike CDT context: generated by aerospike CDT ctx helper
aerospike_helpers
.- raises
a subclass of
~aerospike.exception.AerospikeError
.
7.1.1
single: Admin Operations
The admin methods implement the security features of the Enterprise Edition of Aerospike. These methods will raise a ~aerospike.exception.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 aerospike_privilege_dict
.
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()
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.
- param str role
The name of the role.
- param list privileges
A list of
aerospike_privilege_dict
.- param dict policy
See
aerospike_admin_policies
.- param list whitelist
A list of whitelist IP addresses that can contain wildcards, for example
10.1.2.0/24
.- param int read_quota
Maximum reads per second limit. Pass in
0
for no limit.- param int write_quota
Maximum write per second limit, Pass in
0
for no limit.- raises
One of the
~aerospike.exception.AdminError
subclasses.
admin_set_whitelist(role, whitelist[, policy: dict])
Add a whitelist to a role.
- param str role
The name of the role.
- param list whitelist
List of IP strings the role is allowed to connect to. Setting this to :py
None
will clear the whitelist for that role.- param dict policy
See
aerospike_admin_policies
.- raises
One of the
~aerospike.exception.AdminError
subclasses.
admin_set_quotas(role[, read_quota[, write_quota[, policy: dict]]])
Add quotas to a role.
- param str role
the name of the role.
- param int read_quota
Maximum reads per second limit. Pass in
0
for no limit.- param int write_quota
Maximum write per second limit. Pass in
0
for no limit.- param dict policy
See
aerospike_admin_policies
.- raises
one of the
~aerospike.exception.AdminError
subclasses.
admin_drop_role(role[, policy: dict])
Drop a custom role.
- param str role
the name of the role.
- param dict policy
See
aerospike_admin_policies
.- raises
one of the
~aerospike.exception.AdminError
subclasses.
admin_grant_privileges(role, privileges[, policy: dict])
Add privileges to a role.
- param str role
the name of the role.
- param list privileges
a list of
aerospike_privilege_dict
.- param dict policy
See
aerospike_admin_policies
.- raises
one of the
~aerospike.exception.AdminError
subclasses.
admin_revoke_privileges(role, privileges[, policy: dict])
Remove privileges from a role.
- param str role
the name of the role.
- param list privileges
a list of
aerospike_privilege_dict
.- param dict policy
See
aerospike_admin_policies
.- raises
one of the
~aerospike.exception.AdminError
subclasses.
admin_get_role(role[, policy: dict]) -> {}
Get a dict
of privileges, whitelist, and quotas associated with a role.
- param str role
the name of the role.
- param dict policy
See
aerospike_admin_policies
.- return
a
aerospike_role_dict
.- raises
one of the
~aerospike.exception.AdminError
subclasses.
admin_get_roles([policy: dict]) -> {}
Get the names of all roles and their attributes.
- param dict policy
See
aerospike_admin_policies
.- return
a
dict
ofaerospike_role_dict
keyed by role names.- raises
one of the
~aerospike.exception.AdminError
subclasses.
admin_query_role(role[, policy: dict]) -> []
Get the list
of privileges associated with a role.
- param str role
the name of the role.
- param dict policy
See
aerospike_admin_policies
.- return
a
list
ofaerospike_privilege_dict
.- raises
one of the
~aerospike.exception.AdminError
subclasses.
admin_query_roles([policy: dict]) -> {}
Get all named roles and their privileges.
- param dict policy
optional
aerospike_admin_policies
.- return
a
dict
ofaerospike_privilege_dict
keyed by role name.- raises
one of the
~aerospike.exception.AdminError
subclasses.
admin_create_user(username, password, roles[, policy: dict])
Create a user and grant it roles.
- param str username
the username to be added to the Aerospike cluster.
- param str password
the password associated with the given username.
- param list roles
the list of role names assigned to the user.
- param dict policy
optional
aerospike_admin_policies
.- raises
one of the
~aerospike.exception.AdminError
subclasses.
admin_drop_user(username[, policy: dict])
Drop the user with a specified username from the cluster.
- param str username
the username to be dropped from the aerospike cluster.
- param dict policy
optional
aerospike_admin_policies
.- raises
one of the
~aerospike.exception.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.
- param str username
the username of the user.
- param str password
the password associated with the given username.
- param dict policy
optional
aerospike_admin_policies
.- raises
one of the
~aerospike.exception.AdminError
subclasses.
admin_set_password(username, password[, policy: dict])
Set the password of a user by a user administrator.
- param str username
the username to be added to the aerospike cluster.
- param str password
the password associated with the given username.
- param dict policy
optional
aerospike_admin_policies
.- raises
one of the
~aerospike.exception.AdminError
subclasses.
admin_grant_roles(username, roles[, policy: dict])
Add roles to a user.
- param str username
the username of the user.
- param list roles
a list of role names.
- param dict policy
optional
aerospike_admin_policies
.- raises
one of the
~aerospike.exception.AdminError
subclasses.
admin_revoke_roles(username, roles[, policy: dict])
Remove roles from a user.
- param str username
the username to have the roles revoked.
- param list roles
a list of role names.
- param dict policy
optional
aerospike_admin_policies
.- raises
one of the
~aerospike.exception.AdminError
subclasses.
admin_query_user_info (user: str[, policy: dict]) -> dict
Retrieve roles and other info for a given user.
- param str user
the username of the user.
- param dict policy
optional
aerospike_admin_policies
.- return
a
dict
of user data. Seeadmin_user_dict
.
admin_query_users_info ([policy: dict]) -> list
Retrieve roles and other info for all users.
- param dict policy
optional
aerospike_admin_policies
.- return
a
list
of users' data. Seeadmin_user_dict
.
admin_query_user (username[, policy: dict]) -> []
Return the list of roles granted to the specified user.
- param str username
the username of the user.
- param dict policy
optional
aerospike_admin_policies
.- return
a
list
of role names.- raises
one of the
~aerospike.exception.AdminError
subclasses.
12.0.0 admin_query_user_info
should be used instead.
admin_query_users ([policy: dict]) -> {}
Get the roles of all users.
- param dict policy
optional
aerospike_admin_policies
.- return
a
dict
of roles keyed by username.- raises
one of the
~aerospike.exception.AdminError
subclasses.
12.0.0 admin_query_users_info
should be used instead.
enable_metrics(policy: Optional[aerospike_helpers.metrics.MetricsPolicy] = None)
Enable extended periodic cluster and node latency metrics.
- param MetricsPolicy policy
Optional metrics policy
- raises
~aerospike.exception.AerospikeError
or one of its subclasses.
disable_metrics()
Disable extended periodic cluster and node latency metrics.
- raises
~aerospike.exception.AerospikeError
or one of its subclasses.
The user dictionary has the following key-value pairs:
"read_info"
(list[int]
): list of read statistics. List may be :pyNone
. Current statistics by offset are:
- 0: read quota in records per second
- 1: single record read transaction rate (TPS)
- 2: read scan/query record per second rate (RPS)
- 3: number of limitless read scans/queries
Future server releases may add additional statistics.
"write_info"
(list[int]
): list of write statistics. List may be :pyNone
. Current statistics by offset are:
- 0: write quota in records per second
- 1: single record write transaction rate (TPS)
- 2: write scan/query record per second rate (RPS)
- 3: number of limitless write scans/queries
Future server releases may add additional statistics.
"conns_in_use"
(int
): number of currently open connections."roles"
(list[str]
): list of assigned role names.
scan(namespace[, set]) -> Scan
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 :pyNone
, the object returns all records in the namespace.
- param str namespace
the namespace in the aerospike cluster.
- param str set
optional specified set name, otherwise the entire namespace will be scanned.
- return
an :py
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
for more details.
- param str namespace
the namespace in the aerospike cluster.
- param str set
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
).- return
an :py
aerospike.Query
class.
single: Other Methods
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
orbytearray
)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 :py
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) # 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()
record
The record tuple which is returned by various read operations. It has the structure:
(key, meta, bins)
- key (
tuple
) See
aerospike_key_tuple
.
- key (
- meta (
dict
) Contains record metadata with the following key-value pairs:
- gen (
int
) Generation value
- gen (
- ttl (
int
) Time-to-live value
- ttl (
- meta (
- bins (
dict
) Contains bin-name/bin-value pairs.
- bins (
We reuse the code example in the key-tuple section and print the meta
and bins
values that were returned from ~aerospike.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) 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()
The metadata dictionary has the following key-value pairs:
"ttl"
(int
): record time to live in seconds. SeeTTL_CONSTANTS
for possible special values."gen"
(int
): record generation
policy
A dict
of optional write policies, which are applicable to ~Client.put
, ~Client.query_apply
. ~Client.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 errorAEROSPIKE_ERR_TIMEOUT
.
Default:0
Warning
Database writes that are not idempotent (such as "add") should not be retried because the write operation may be performed multiple times if the client timed out previous transaction attempts. It's important to use a distinct write policy for non-idempotent writes, which sets max_retries = 0;
- max_retries (
- sleep_between_retries (
int
) - Milliseconds to sleep between retries. Enter
0
to skip sleep.
Default:0
- sleep_between_retries (
- socket_timeout (
int
) - Socket idle timeout in milliseconds when processing a database command.
If socket_timeout is not0
and the socket has been idle for at least socket_timeout, both max_retries and total_timeout are checked. If max_retries and total_timeout are not exceeded, the transaction is retried.
If bothsocket_timeout
andtotal_timeout
are non-zero andsocket_timeout
>total_timeout
, thensocket_timeout
will be set tototal_timeout
. Ifsocket_timeout
is0
, there will be no socket idle limit.
Default:30000
- socket_timeout (
- total_timeout (
int
) - Total transaction timeout in milliseconds.
The total_timeout is tracked on the client and sent to the server along with the transaction in the wire protocol. The client will most likely timeout first, but the server also has the capability to timeout the transaction.
Iftotal_timeout
is not0
andtotal_timeout
is reached before the transaction completes, the transaction will return errorAEROSPIKE_ERR_TIMEOUT
. Iftotal_timeout
is0
, there will be no total time limit.
Default:1000
- total_timeout (
- compress (
bool
) - Compress client requests and server responses.
Use zlib compression on write or batch read commands when the command buffer size is greater than 128 bytes. In addition, tell the server to compress it's response on read commands. The server response compression threshold is also 128 bytes.
This option will increase cpu and memory usage (for extra compressed buffers), but decrease the size of data sent over the network.
Default:False
- compress (
- key
- One of the
POLICY_KEY
values such asaerospike.POLICY_KEY_DIGEST
Default:aerospike.POLICY_KEY_DIGEST
- exists
- One of the
POLICY_EXISTS
values such asaerospike.POLICY_EXISTS_CREATE
Default:aerospike.POLICY_EXISTS_IGNORE
- ttl
The default time-to-live (expiration) of the record in seconds. This field will only be used if the write transaction:
- Doesn't contain a metadata dictionary with a
ttl
value. - Contains a metadata dictionary with a
ttl
value set toaerospike.TTL_CLIENT_DEFAULT
.
There are also special values that can be set for this option. See
TTL_CONSTANTS
.- Doesn't contain a metadata dictionary with a
- gen
- One of the
POLICY_GEN
values such asaerospike.POLICY_GEN_IGNORE
Default:aerospike.POLICY_GEN_IGNORE
- commit_level
- One of the
POLICY_COMMIT_LEVEL
values such asaerospike.POLICY_COMMIT_LEVEL_ALL
Default:aerospike.POLICY_COMMIT_LEVEL_ALL
- durable_delete (
bool
) - Perform durable delete
Default:False
- durable_delete (
- expressions
list
- Compiled aerospike expressions
aerospike_helpers
used for filtering records within a transaction.
Default: NoneNote
Requires Aerospike server version >= 5.2.
- expressions
- compression_threshold (
int
) Compress data for transmission if the object size is greater than a given number of bytes.
Default:
0
, meaning 'never compress'
- compression_threshold (
- replica
Algorithm used to determine target node. One of the
POLICY_REPLICA
values.Default:
aerospike.POLICY_REPLICA_SEQUENCE
policy
A dict
of optional read policies, which are applicable to ~Client.get
, ~Client.exists
, ~Client.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 errorAEROSPIKE_ERR_TIMEOUT
.
Default:2
- max_retries (
- sleep_between_retries (
int
) - Milliseconds to sleep between retries. Enter
0
to skip sleep.
Default:0
- sleep_between_retries (
- socket_timeout (
int
) - Socket idle timeout in milliseconds when processing a database command.
If socket_timeout is not0
and the socket has been idle for at least socket_timeout, both max_retries and total_timeout are checked. If max_retries and total_timeout are not exceeded, the transaction is retried.
If bothsocket_timeout
andtotal_timeout
are non-zero andsocket_timeout
>total_timeout
, thensocket_timeout
will be set tototal_timeout
. Ifsocket_timeout
is0
, there will be no socket idle limit.
Default:30000
- socket_timeout (
- total_timeout (
int
) - Total transaction timeout in milliseconds.
The total_timeout is tracked on the client and sent to the server along with the transaction in the wire protocol. The client will most likely timeout first, but the server also has the capability to timeout the transaction.
Iftotal_timeout
is not0
andtotal_timeout
is reached before the transaction completes, the transaction will return errorAEROSPIKE_ERR_TIMEOUT
. Iftotal_timeout
is0
, there will be no total time limit.
Default:1000
- total_timeout (
- compress (
bool
) - Compress client requests and server responses.
Use zlib compression on write or batch read commands when the command buffer size is greater than 128 bytes. In addition, tell the server to compress it's response on read commands. The server response compression threshold is also 128 bytes.
This option will increase cpu and memory usage (for extra compressed buffers), but decrease the size of data sent over the network.
Default:False
- compress (
- deserialize (
bool
) - Should raw bytes representing a list or map be deserialized to a list or dictionary.
Set to False for backup programs that just need access to raw bytes.
Default:True
- deserialize (
- key
- One of the
POLICY_KEY
values such asaerospike.POLICY_KEY_DIGEST
Default:aerospike.POLICY_KEY_DIGEST
- read_mode_ap
- One of the
POLICY_READ_MODE_AP
values such asaerospike.AS_POLICY_READ_MODE_AP_ONE
Default:aerospike.AS_POLICY_READ_MODE_AP_ONE
3.7.0
- read_mode_sc
- One of the
POLICY_READ_MODE_SC
values such asaerospike.POLICY_READ_MODE_SC_SESSION
Default:aerospike.POLICY_READ_MODE_SC_SESSION
3.7.0
- read_touch_ttl_percent
Determine how record TTL (time to live) is affected on reads. When enabled, the server can efficiently operate as a read-based LRU cache where the least recently used records are expired. The value is expressed as a percentage of the TTL sent on the most recent write such that a read within this interval of the record’s end of life will generate a touch.
For example, if the most recent write had a TTL of 10 hours and
"read_touch_ttl_percent"
is set to 80, the next read within 8 hours of the record's end of life (equivalent to 2 hours after the most recent write) will result in a touch, resetting the TTL to another 10 hours.Values:
0
: Use server config default-read-touch-ttl-pct for the record's namespace/set.-1
: Do not reset record TTL on reads.1
-100
: Reset record TTL on reads when within this percentage of the most recent write TTL.
Default:
0
Note
Requires Aerospike server version >= 7.1.
- replica
- One of the
POLICY_REPLICA
values such asaerospike.POLICY_REPLICA_MASTER
Default:aerospike.POLICY_REPLICA_SEQUENCE
- expressions
list
- Compiled aerospike expressions
aerospike_helpers
used for filtering records within a transaction.
Default: NoneNote
Requires Aerospike server version >= 5.2.
- expressions
policy
A dict
of optional operate policies, which are applicable to ~Client.append
, ~Client.prepend
, ~Client.increment
, ~Client.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 errorAEROSPIKE_ERR_TIMEOUT
.
Default:0
Warning
Database writes that are not idempotent (such as "add") should not be retried because the write operation may be performed multiple times if the client timed out previous transaction attempts. It's important to use a distinct write policy for non-idempotent writes, which sets max_retries = 0;
- max_retries (
- sleep_between_retries (
int
) - Milliseconds to sleep between retries. Enter
0
to skip sleep.
Default:0
- sleep_between_retries (
- socket_timeout (
int
) - Socket idle timeout in milliseconds when processing a database command.
If socket_timeout is not0
and the socket has been idle for at least socket_timeout, both max_retries and total_timeout are checked. If max_retries and total_timeout are not exceeded, the transaction is retried.
If bothsocket_timeout
andtotal_timeout
are non-zero andsocket_timeout
>total_timeout
, thensocket_timeout
will be set tototal_timeout
. Ifsocket_timeout
is0
, there will be no socket idle limit.
Default:30000
- socket_timeout (
- total_timeout (
int
) - Total transaction timeout in milliseconds.
The total_timeout is tracked on the client and sent to the server along with the transaction in the wire protocol. The client will most likely timeout first, but the server also has the capability to timeout the transaction.
Iftotal_timeout
is not0
andtotal_timeout
is reached before the transaction completes, the transaction will return errorAEROSPIKE_ERR_TIMEOUT
. Iftotal_timeout
is0
, there will be no total time limit.
Default:1000
- total_timeout (
- compress (
bool
) - Compress client requests and server responses.
Use zlib compression on write or batch read commands when the command buffer size is greater than 128 bytes. In addition, tell the server to compress it's response on read commands. The server response compression threshold is also 128 bytes.
This option will increase cpu and memory usage (for extra compressed buffers), but decrease the size of data sent over the network.
Default:False
- compress (
- key
- One of the
POLICY_KEY
values such asaerospike.POLICY_KEY_DIGEST
Default:aerospike.POLICY_KEY_DIGEST
- gen
- One of the
POLICY_GEN
values such asaerospike.POLICY_GEN_IGNORE
Default:aerospike.POLICY_GEN_IGNORE
- ttl (
int
) The default time-to-live (expiration) of the record in seconds. This field will only be used if an operate transaction contains a write operation and either:
- Doesn't contain a metadata dictionary with a
ttl
value. - Contains a metadata dictionary with a
ttl
value set toaerospike.TTL_CLIENT_DEFAULT
.
There are also special values that can be set for this option. See
TTL_CONSTANTS
.- Doesn't contain a metadata dictionary with a
- ttl (
- read_touch_ttl_percent
Determine how record TTL (time to live) is affected on reads. When enabled, the server can efficiently operate as a read-based LRU cache where the least recently used records are expired. The value is expressed as a percentage of the TTL sent on the most recent write such that a read within this interval of the record’s end of life will generate a touch.
For example, if the most recent write had a TTL of 10 hours and
"read_touch_ttl_percent"
is set to 80, the next read within 8 hours of the record's end of life (equivalent to 2 hours after the most recent write) will result in a touch, resetting the TTL to another 10 hours.Values:
0
: Use server config default-read-touch-ttl-pct for the record's namespace/set.-1
: Do not reset record TTL on reads.1
-100
: Reset record TTL on reads when within this percentage of the most recent write TTL.
Default:
0
Note
Requires Aerospike server version >= 7.1.
- replica
- One of the
POLICY_REPLICA
values such asaerospike.POLICY_REPLICA_MASTER
Default:aerospike.POLICY_REPLICA_SEQUENCE
- commit_level
- One of the
POLICY_COMMIT_LEVEL
values such asaerospike.POLICY_COMMIT_LEVEL_ALL
Default:aerospike.POLICY_COMMIT_LEVEL_ALL
- read_mode_ap
- One of the
POLICY_READ_MODE_AP
values such asaerospike.AS_POLICY_READ_MODE_AP_ONE
Default:aerospike.AS_POLICY_READ_MODE_AP_ONE
3.7.0
- read_mode_sc
- One of the
POLICY_READ_MODE_SC
values such asaerospike.POLICY_READ_MODE_SC_SESSION
Default:aerospike.POLICY_READ_MODE_SC_SESSION
3.7.0
- exists
- One of the
POLICY_EXISTS
values such asaerospike.POLICY_EXISTS_CREATE
Default:aerospike.POLICY_EXISTS_IGNORE
- durable_delete (
bool
) - Perform durable delete
Default:False
- durable_delete (
- deserialize
bool
- Should raw bytes representing a list or map be deserialized to a Python list or map. Set to false for backup programs that just need access to raw bytes.
Default: :pyTrue
- deserialize
- expressions
list
- Compiled aerospike expressions
aerospike_helpers
used for filtering records within a transaction.
Default: NoneNote
Requires Aerospike server version >= 5.2.
- expressions
policy
A dict
of optional apply policies, which are applicable to ~Client.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 errorAEROSPIKE_ERR_TIMEOUT
.
Default:0
Warning
Database writes that are not idempotent (such as "add") should not be retried because the write operation may be performed multiple times if the client timed out previous transaction attempts. It's important to use a distinct write policy for non-idempotent writes, which sets max_retries = 0;
- max_retries (
- sleep_between_retries (
int
) - Milliseconds to sleep between retries. Enter
0
to skip sleep.
Default:0
- sleep_between_retries (
- socket_timeout (
int
) - Socket idle timeout in milliseconds when processing a database command.
If socket_timeout is not0
and the socket has been idle for at least socket_timeout, both max_retries and total_timeout are checked. If max_retries and total_timeout are not exceeded, the transaction is retried.
If bothsocket_timeout
andtotal_timeout
are non-zero andsocket_timeout
>total_timeout
, thensocket_timeout
will be set tototal_timeout
. Ifsocket_timeout
is0
, there will be no socket idle limit.
Default:30000
- socket_timeout (
- total_timeout (
int
) - Total transaction timeout in milliseconds.
The total_timeout is tracked on the client and sent to the server along with the transaction in the wire protocol. The client will most likely timeout first, but the server also has the capability to timeout the transaction.
Iftotal_timeout
is not0
andtotal_timeout
is reached before the transaction completes, the transaction will return errorAEROSPIKE_ERR_TIMEOUT
. Iftotal_timeout
is0
, there will be no total time limit.
Default:1000
- total_timeout (
- compress (
bool
) - Compress client requests and server responses.
Use zlib compression on write or batch read commands when the command buffer size is greater than 128 bytes. In addition, tell the server to compress it's response on read commands. The server response compression threshold is also 128 bytes.
This option will increase cpu and memory usage (for extra compressed buffers), but decrease the size of data sent over the network.
Default:False
- compress (
- key
- One of the
POLICY_KEY
values such asaerospike.POLICY_KEY_DIGEST
Default:aerospike.POLICY_KEY_DIGEST
- replica
- One of the
POLICY_REPLICA
values such asaerospike.POLICY_REPLICA_MASTER
Default:aerospike.POLICY_REPLICA_SEQUENCE
- commit_level
- One of the
POLICY_COMMIT_LEVEL
values such asaerospike.POLICY_COMMIT_LEVEL_ALL
Default:aerospike.POLICY_COMMIT_LEVEL_ALL
- ttl (
int
) The default time-to-live (expiration) of the record in seconds. This field will only be used if an apply transaction doesn't have an apply policy with a
ttl
value that overrides this field.There are also special values that can be set for this field. See
TTL_CONSTANTS
.
- ttl (
- durable_delete (
bool
) - Perform durable delete
Default:False
- durable_delete (
- expressions
list
- Compiled aerospike expressions
aerospike_helpers
used for filtering records within a transaction.
Default: NoneNote
Requires Aerospike server version >= 5.2.
- expressions
policy
A dict
of optional remove policies, which are applicable to ~Client.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 errorAEROSPIKE_ERR_TIMEOUT
.
Default:0
Warning
Database writes that are not idempotent (such as "add") should not be retried because the write operation may be performed multiple times if the client timed out previous transaction attempts. It's important to use a distinct write policy for non-idempotent writes, which sets max_retries = 0;
- max_retries (
- sleep_between_retries (
int
) - Milliseconds to sleep between retries. Enter
0
to skip sleep.
Default:0
- sleep_between_retries (
- socket_timeout (
int
) - Socket idle timeout in milliseconds when processing a database command.
If socket_timeout is not0
and the socket has been idle for at least socket_timeout, both max_retries and total_timeout are checked. If max_retries and total_timeout are not exceeded, the transaction is retried.
If bothsocket_timeout
andtotal_timeout
are non-zero andsocket_timeout
>total_timeout
, thensocket_timeout
will be set tototal_timeout
. Ifsocket_timeout
is0
, there will be no socket idle limit.
Default:30000
- socket_timeout (
- total_timeout (
int
) - Total transaction timeout in milliseconds.
The total_timeout is tracked on the client and sent to the server along with the transaction in the wire protocol. The client will most likely timeout first, but the server also has the capability to timeout the transaction.
Iftotal_timeout
is not0
andtotal_timeout
is reached before the transaction completes, the transaction will return errorAEROSPIKE_ERR_TIMEOUT
. Iftotal_timeout
is0
, there will be no total time limit.
Default:1000
- total_timeout (
- compress (
bool
) - Compress client requests and server responses.
Use zlib compression on write or batch read commands when the command buffer size is greater than 128 bytes. In addition, tell the server to compress it's response on read commands. The server response compression threshold is also 128 bytes.
This option will increase cpu and memory usage (for extra compressed buffers), but decrease the size of data sent over the network.
Default:False
- compress (
- key
- One of the
POLICY_KEY
values such asaerospike.POLICY_KEY_DIGEST
Default:aerospike.POLICY_KEY_DIGEST
- commit_level
- One of the
POLICY_COMMIT_LEVEL
values such asaerospike.POLICY_COMMIT_LEVEL_ALL
Default:aerospike.POLICY_COMMIT_LEVEL_ALL
- gen
- One of the
POLICY_GEN
values such asaerospike.POLICY_GEN_IGNORE
Default:aerospike.POLICY_GEN_IGNORE
- generation (
int
) - The generation of the record. This value is limited to a 16-bit unsigned integer.
- generation (
- durable_delete (
bool
) - Perform durable delete
Default:False
Note
Requires Enterprise server version >= 3.10
- durable_delete (
- replica
- One of the
POLICY_REPLICA
values such asaerospike.POLICY_REPLICA_MASTER
Default:aerospike.POLICY_REPLICA_SEQUENCE
- expressions
list
- Compiled aerospike expressions
aerospike_helpers
used for filtering records within a transaction.
Default: NoneNote
Requires Aerospike server version >= 5.2.
- expressions
policy
A dict
of optional batch policies, which are applicable to ~aerospike.get_many
, ~aerospike.exists_many
and ~aerospike.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 errorAEROSPIKE_ERR_TIMEOUT
.
Default:2
- max_retries (
- sleep_between_retries (
int
) - Milliseconds to sleep between retries. Enter
0
to skip sleep.
Default:0
- sleep_between_retries (
- socket_timeout (
int
) - Socket idle timeout in milliseconds when processing a database command.
If socket_timeout is not0
and the socket has been idle for at least socket_timeout, both max_retries and total_timeout are checked. If max_retries and total_timeout are not exceeded, the transaction is retried.
If bothsocket_timeout
andtotal_timeout
are non-zero andsocket_timeout
>total_timeout
, thensocket_timeout
will be set tototal_timeout
. Ifsocket_timeout
is0
, there will be no socket idle limit.
Default:30000
- socket_timeout (
- total_timeout (
int
) - Total transaction timeout in milliseconds.
The total_timeout is tracked on the client and sent to the server along with the transaction in the wire protocol. The client will most likely timeout first, but the server also has the capability to timeout the transaction.
Iftotal_timeout
is not0
andtotal_timeout
is reached before the transaction completes, the transaction will return errorAEROSPIKE_ERR_TIMEOUT
. Iftotal_timeout
is0
, there will be no total time limit.
Default:1000
- total_timeout (
- compress (
bool
) - Compress client requests and server responses.
Use zlib compression on write or batch read commands when the command buffer size is greater than 128 bytes. In addition, tell the server to compress it's response on read commands. The server response compression threshold is also 128 bytes.
This option will increase cpu and memory usage (for extra compressed buffers), but decrease the size of data sent over the network.
Default:False
- compress (
- read_mode_ap
- One of the
POLICY_READ_MODE_AP
values such asaerospike.AS_POLICY_READ_MODE_AP_ONE
Default:aerospike.AS_POLICY_READ_MODE_AP_ONE
3.7.0
- read_mode_sc
- One of the
POLICY_READ_MODE_SC
values such asaerospike.POLICY_READ_MODE_SC_SESSION
Default:aerospike.POLICY_READ_MODE_SC_SESSION
3.7.0
- read_touch_ttl_percent
Determine how record TTL (time to live) is affected on reads. When enabled, the server can efficiently operate as a read-based LRU cache where the least recently used records are expired. The value is expressed as a percentage of the TTL sent on the most recent write such that a read within this interval of the record’s end of life will generate a touch.
For example, if the most recent write had a TTL of 10 hours and
"read_touch_ttl_percent"
is set to 80, the next read within 8 hours of the record's end of life (equivalent to 2 hours after the most recent write) will result in a touch, resetting the TTL to another 10 hours.Values:
0
: Use server config default-read-touch-ttl-pct for the record's namespace/set.-1
: Do not reset record TTL on reads.1
-100
: Reset record TTL on reads when within this percentage of the most recent write TTL.
Default:
0
Note
Requires Aerospike server version >= 7.1.
- replica
- One of the
POLICY_REPLICA
values such asaerospike.POLICY_REPLICA_MASTER
Default:aerospike.POLICY_REPLICA_SEQUENCE
- concurrent (
bool
) - Determine if batch commands to each server are run in parallel threads.
DefaultFalse
- concurrent (
- allow_inline (
bool
) - Allow batch to be processed immediately in the server's receiving thread when the server deems it to be appropriate. If False, the batch will always be processed in separate transaction threads. This field is only relevant for the new batch index protocol.
DefaultTrue
- allow_inline (
- 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
- allow_inline_ssd (
- deserialize (
bool
) - Should raw bytes be deserialized to as_list or as_map. Set to False for backup programs that just need access to raw bytes.
Default:True
- deserialize (
- expressions
list
- Compiled aerospike expressions
aerospike_helpers
used for filtering records within a transaction.
Default: NoneNote
Requires Aerospike server version >= 5.2.
- expressions
- 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 areAEROSPIKE_ERR_RECORD_NOT_FOUND
andAEROSPIKE_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
- respond_all_keys
policy
A dict
of optional batch write policies, which are applicable to ~aerospike.batch_write
, ~aerospike.batch_operate
and Write <aerospike_helpers.batch.records>
.
- key
- One of the
POLICY_KEY
values such asaerospike.POLICY_KEY_DIGEST
Default:aerospike.POLICY_KEY_DIGEST
- commit_level
- One of the
POLICY_COMMIT_LEVEL
values such asaerospike.POLICY_COMMIT_LEVEL_ALL
Default:aerospike.POLICY_COMMIT_LEVEL_ALL
- gen
- One of the
POLICY_GEN
values such asaerospike.POLICY_GEN_IGNORE
Default:aerospike.POLICY_GEN_IGNORE
- exists
- One of the
POLICY_EXISTS
values such asaerospike.POLICY_EXISTS_CREATE
Default:aerospike.POLICY_EXISTS_IGNORE
- durable_delete (
bool
) - Perform durable delete
Default:False
- durable_delete (
- expressions
list
- Compiled aerospike expressions
aerospike_helpers
used for filtering records within a transaction.
Default: None
- expressions
- ttl
int
- The time-to-live (expiration) in seconds to apply to every record in the batch. This field will only be used if:
- A
~aerospike.Client.batch_write
call contains a~aerospike_helpers.batch.records.Write
that:- Doesn't contain a metadata dictionary with a
ttl
value. - Contains a metadata dictionary with a
ttl
value set toaerospike.TTL_CLIENT_DEFAULT
.
- Doesn't contain a metadata dictionary with a
- A
~aerospike.Client.batch_operate
call:- Doesn't pass in a ttl argument.
- Passes in aerospike.TTL_CLIENT_DEFAULT to the ttl parameter.
There are also special values that can be set for this field. See
TTL_CONSTANTS
.Default:
0
- A
- ttl
policy
A dict
of optional batch apply policies, which are applicable to ~aerospike.batch_apply
, and Apply <aerospike_helpers.batch.records>
.
- key
- One of the
POLICY_KEY
values such asaerospike.POLICY_KEY_DIGEST
Default:aerospike.POLICY_KEY_DIGEST
- commit_level
- One of the
POLICY_COMMIT_LEVEL
values such asaerospike.POLICY_COMMIT_LEVEL_ALL
Default:aerospike.POLICY_COMMIT_LEVEL_ALL
- ttl int
- Time to live (expiration) of the record in seconds.
SeeTTL_CONSTANTS
for possible special values.
Note that the TTL value will be employed ONLY on write/update calls.
Default:0
- durable_delete
bool
- If the transaction results in a record deletion, leave a tombstone for the record. This prevents deleted records from reappearing after node failures. Valid for Aerospike Server Enterprise Edition only.
Default: :pyFalse
(do not tombstone deleted records).
- durable_delete
- expressions
list
- Compiled aerospike expressions
aerospike_helpers
used for filtering records within a transaction.
Default: None
- expressions
policy
A dict
of optional batch remove policies, which are applicable to ~aerospike.batch_remove
, and Remove <aerospike_helpers.batch.records>
.
- key
- One of the
POLICY_KEY
values such asaerospike.POLICY_KEY_DIGEST
Default:aerospike.POLICY_KEY_DIGEST
- commit_level
- One of the
POLICY_COMMIT_LEVEL
values such asaerospike.POLICY_COMMIT_LEVEL_ALL
Default:aerospike.POLICY_COMMIT_LEVEL_ALL
- gen
- One of the
POLICY_GEN
values such asaerospike.POLICY_GEN_IGNORE
Default:aerospike.POLICY_GEN_IGNORE
- generation int
- Generation of the record.
Default: 0
- durable_delete (
bool
) - Perform durable delete
Default:False
- durable_delete (
- expressions
list
- Compiled aerospike expressions
aerospike_helpers
used for filtering records within a transaction.
Default: None
- expressions
policy
A dict
of optional batch read policies, which are applicable to Read <aerospike_helpers.batch.records>
.
- read_mode_ap
- One of the
POLICY_READ_MODE_AP
values such asaerospike.AS_POLICY_READ_MODE_AP_ONE
Default:aerospike.AS_POLICY_READ_MODE_AP_ONE
- read_mode_sc
- One of the
POLICY_READ_MODE_SC
values such asaerospike.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
- expressions
- read_touch_ttl_percent
Determine how record TTL (time to live) is affected on reads. When enabled, the server can efficiently operate as a read-based LRU cache where the least recently used records are expired. The value is expressed as a percentage of the TTL sent on the most recent write such that a read within this interval of the record’s end of life will generate a touch.
For example, if the most recent write had a TTL of 10 hours and
"read_touch_ttl_percent"
is set to 80, the next read within 8 hours of the record's end of life (equivalent to 2 hours after the most recent write) will result in a touch, resetting the TTL to another 10 hours.Values:
0
: Use server config default-read-touch-ttl-pct for the record's namespace/set.-1
: Do not reset record TTL on reads.1
-100
: Reset record TTL on reads when within this percentage of the most recent write TTL.
Default:
0
Note
Requires Aerospike server version >= 7.1.
policy
A dict
of optional info policies, which are applicable to ~aerospike.info_all
, ~aerospike.info_single_node
, ~aerospike.info_random_node
and index operations.
- timeout (
int
) - Read timeout in milliseconds
- timeout (
policy
A dict
of optional admin policies, which are applicable to admin (security) operations.
- timeout (
int
) - Admin operation timeout in milliseconds
- timeout (
policy
A dict
of optional list policies, which are applicable to list operations.
- write_flags
- Write flags for the operation.
One of theaerospike_list_write_flag
values such asaerospike.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 ofaerospike_list_order
, such asaerospike.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 }
policy
A dict
of optional map policies, which are applicable to map operations.
- map_write_flags
- Write flags for the map operation.
One of theaerospike_map_write_flag
values such asaerospike.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 ofaerospike_map_order
, such asaerospike.MAP_KEY_ORDERED
Default:aerospike.MAP_UNORDERED
- persist_index (
bool
) - If :py
True
, persist map index. A map index improves lookup performance,
but requires more storage. A map index can be created for a top-level
ordered map only. Nested and unordered map indexes are not supported.
- persist_index (
Example:
# Server >= 4.3.0
map_policy = {
'map_order': aerospike.MAP_UNORDERED,
'map_write_flags': aerospike.MAP_WRITE_FLAGS_CREATE_ONLY
}
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 theaerospike_bitwise_write_flag
values such asaerospike.BIT_WRITE_DEFAULT
Default:aerospike.BIT_WRITE_DEFAULT
Example:
bit_policy = {
'bit_write_flags': aerospike.BIT_WRITE_UPDATE_ONLY
}
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 theaerospike_hll_write_flags
values such asaerospike.HLL_WRITE_DEFAULT
Default:aerospike.HLL_WRITE_DEFAULT
Example:
HLL_policy = {
'flags': aerospike.HLL_WRITE_UPDATE_ONLY
}
Role
A dict
describing attributes associated with a specific role:
"privileges"
: alist
ofaerospike_privilege_dict
."whitelist"
: alist
of IP address strings."read_quota"
: aint
representing the allowed read transactions per second."write_quota"
: aint
representing the allowed write transactions per second.
privilege
A dict
describing a privilege and where it applies to:
"code"
: one of theaerospike_privileges
values"ns"
: optionalstr
specifying the namespace where the privilege applies.If not specified, the privilege applies globally.
"set"
: optionalstr
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_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"
: Optionalint
signifying which partition to start at.Default:
0
(the first partition)"count"
: Optionalint
signifying how many partitions to process.Default:
4096
(all partitions)"digest"
: Optionaldict
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"
: Optionaldict
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, False, 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"
:bool
represents the overall retry status of this partition query. (i.e. Does this query/scan need to be retried?)"done"
:bool
represents whether all partitions were finished.
In addition, the dictionary contains keys of the partition IDs (int
), and each partition ID is mapped to a tuple containing the status details of a partition.
That tuple has the following values in this order:
id
:int
represents a partition ID numberinit
: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, False, bytearray([0]*20), 0)...
# }
partition_status = query.get_partitions_status()
policy = {
"partition_filter": {
"partition_status": partition_status,
"begin": 0,
"count": 4096
},
}