Skip to main content

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 TypeOperationDescription
Allop_putUpsert (create or update) a bin. Also called write.
Allop_getRead a bin. Also called read.
Allop_touchIncrease the generation counter for a record.
Allop_deleteRemove a record from the database. Generates a tombstone when you use the durable delete policy.
Integer
Float
op_addAdd (or subtract) a value. Used to implement counters. Also called increment.
Stringop_append
op_prepend
Modify a string.
ListFor a list of all List Operations, see Collection Data Types: Lists.
MapFor a list of all Map Operations, see Collection Data Types: Maps.
Blob/ BytesFor a list of all Blob/Byte Operations, see Data Types: Blob/Bytes.
HLLFor a list of all HyperLogLog Operations, see Data Types: HyperLogLog.
GeoFor 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 it is recommended that 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..

References

See these topics for language-specific examples: