Transaction operations
Aerospike records contain one or more Bins of potentially different data types. Nested Lists and Maps, also called collection data types (or CDTs) may be combined to implement a complex data structure as a document. To service these potentially-complex documents of data, every Aerospike client provides the following method:
operate
Combines multiple operations on a single record into a transaction. Operations include the bin read and write operations, and any operation on a data type, which is stored in a bin. Examples are add on integer bins, HLL operations on HyperLogLog bins, bitwise operations on Blob (Bytes) bins, or the large API of operations on list and map bins.
One of the arguments to the operate
method is an ordered list of bin operations to execute. The syntax used by Aerospike clients varies by programming language. Unlike a record get
operation, which returns an Aerospike record, operate returns output from each sub-operation per bin. This is useful to confirm transaction processing and to troubleshoot logic that results in unexpected transaction success or failures.
Each operate
call results in an ACID-compliant transaction consisting of one or more ordered bin operations on the record. This operation is a single atomic transaction that is processed by Aerospike under a record lock with isolation and durability. By comparison, every record operation results in an atomic transaction consisting of a single operation.
The following is the comprehensive list of bin operations that can be part of a transaction using operate. The table below contains either the operations or a link to the comprehensive list of operations for each data type.
Data Type | Operation | Description |
---|---|---|
All | op_put | Upsert (create or update) a bin. Also called write . |
All | op_get | Read a bin. Also called read . |
All | op_touch | Increase the generation counter for a record. |
All | op_delete | Remove a record from the database. Generates a tombstone when you use the durable delete policy. |
Integer Float | op_add | Add (or subtract) a value. Used to implement counters. Also called increment . |
String | op_append op_prepend | Modify a string. |
List | For a list of all List Operations, see Collection Data Types: Lists. | |
Map | For a list of all Map Operations, see Collection Data Types: Maps. | |
Blob/ Bytes | For a list of all Blob/Byte Operations, see Data Types: Blob/Bytes. | |
HLL | For a list of all HyperLogLog Operations, see Data Types: HyperLogLog. | |
Geo | For a list of all Geospatial Operations, see Data Types: Geospatial. |
As of Aerospike version 5.6, Aerospike operation expressions can be applied to any transaction operation mentioned above.
Filtering Transactions
A transaction can be conditionally applied, based on the result of a filter expression. If the filter expression evaluates to true, the transaction will execute. Older versions starting with Aerospike 4.7 can apply a predicate filter to the transaction.
Support for predicate filters is planned for removal in Aerospike 5.8, so We recommend that you filter expressions (added in version 5.2) be used in their place.
Code example of a transaction operation
The following Python example performs read and update bin operations on a record. The syntax differs per Aerospike client, based on the needs of the operating system.
# The following is the primary key of a record
#
# key = (namespace_name, set_name, user_key)
#
# The following is the Aerospike record associated with that key.
#
# bins = {
# 'l': [ "qwertyuiop", 1, bytearray("asd;as[d'as;d", "utf-8") ],
# 'm': { "key": "asd';q;'1';" },
# 'i': 1234,
# 'f': 3.14159265359,
# 's': '!@#@#$QSDAsd;as'
# }
ops = [
operations.increment('i', 1)
operations.read('i')
operations.append('s', 'foobarbaz')
operations.read('s')
]
client.operate(key, ops)
# Expected result:
# i is now 1235
# s is now !@#@#$QSDAsd;asfoobarbaz
Usage notes
All read and write operations on records accept policy parameters: Max Retries and Total Timeout.
Write operations take an optional time-to-live (TTL) parameter which specifies how long the record can live before Aerospike automatically expires it and removes it from the primary index. For more details on the interaction between TTL and eviction, see Managing Storage Capacity.
A transaction’s constituent operations may accept or require additional policy parameters. For additional details about those parameters, refer to the API reference for the client and operation you are using..
Server responses
Some types of write operations do not return results
by default, which can make it difficult to determine the correct result offset.
To ensure that every write operation returns a result, set the
WritePolicy.respondAllOps
field to true
.
ClientPolicy clientPolicy = new ClientPolicy();
clientPolicy.WritePolicyDefault.respondAllOps = true;
References
See these topics for language-specific examples: