Skip to content

Bin operations

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

Jump to the Code block for a combined complete example.

Description

Demonstrates single record operations in an Aerospike database.

Setup

Boilerplate

The following examples leverage the following boilerplate to initialize the Aerospike module and connect to a server before executing a single record operations.

const Aerospike = await import("aerospike");
const op = Aerospike.operations;
const map = Aerospike.maps;
// Set hosts to your server's address and port
const config = { hosts: "YOUR_HOST_ADDRESS:YOUR_PORT" };
// Creates a key with the namespace "sandbox", set "ufodata", and user key 5001
const key = new Aerospike.Key("sandbox", "ufodata", 5001);
// Establishes a connection to the server
const client = await Aerospike.connect(config);

The record structure:

+------+----------+----------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------+
| PK | occurred | reported | posted | report | location |
+------+----------+----------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------+
| 5001 | 20220531 | 20220601 | 20220601 | MAP('{"shape":["circle", "flash", "disc"], "summary":"Large flying disc flashed in the sky above the student union. Craziest thing I've ever seen!", "city":"Ann Arbor", "state":"Michigan", "duration":"5 minutes"}') | GeoJSON('{"type":"Point","coordinates":[42.2808,83.743]}') |
+------+----------+----------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------+

Operations

Use the Aerospike Client API to perform separate operations on one or multiple bins in a record within a single transaction. This feature performs an atomic modification then returns the result. The table below shows some of the bin operations available for operate transactions.

Operations for List, Map, String, Blob/Bytes, Geospatial, and HyperLogLog data types see Scalar data types.

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.
Integer
Float
op_addAdd (or subtract) a value. Used to implement counters. Also called increment.
Stringop_append
op_prepend
Modify a string. For Unicode-aware transforms, see String operations (Database 8.2.0 and later).

Single operation

All of the operations in the table above, along with CDT, Blob/Bytes, Geospatial, HyperLogLog, and String operations (Database 8.2.0 and later), can be executed as a single operation with the operate method.

The following example creates a map policy for a KEY_ORDERED map, then applies that policy to the report bin. A KEY_ORDERED map provides faster access than the default UNORDERED map.

// Create map policy with ordering set to KEY_ORDERED
const mapPolicy = new Aerospike.MapPolicy({ order: map.order.KEY_ORDERED });
// Create the ops
const ops = [map.setPolicy("report", mapPolicy)];
// Apply the map policy
await client.operate(key, ops);

Multiple Operations

Multiple operations can be combined in a single transaction when one or more bins need to be updated or read.

The following example inserts the posted bin with value 20220602, updates the city inside the report bin to "Ypsilanti", and reads the report bin in a single transaction.

// Create the ops
const ops = [
op.write("posted", 20220602),
map.put("report", "city", "Ypsilanti"),
op.read("report"),
];
// Update the record
const record = await client.operate(key, ops);
// Do something
console.info("Record: %o", record.bins);

List operations

Aerospike.lists builds list operations for operate(). The following example appends 20220602 to the sightings list bin and trims the list to its five most recent entries. The append creates the bin if it does not exist.

const list = Aerospike.lists;
const ops = [
// Add the newest entry to the end of the list
list.append("sightings", 20220602),
// Keep only the last five entries
list.trim("sightings", -5, 5),
];
await client.operate(key, ops);

list.trim(bin, index, count) keeps count elements starting at index and removes the rest. A negative index counts back from the end of the list. For every list operation, see List operations.

Returning from operate()

operate() resolves to a record whose bins hold the results of the operations that return a value:

  • A write operation returns no value, and its bin isn’t included in bins.
  • A list or map modify operation returns a value that depends on the operation. For example, list.append() returns the list’s new size and list.trim() returns the number of elements removed.
  • A read operation returns the bin’s value.

See Bitwise operations, List operations, Map operations, String operations, HyperLogLog (HLL) operations, and Expressions for more information about return values.

Each bin name holds one result. If more than one operation in the call returns a result for the same bin, bins holds only the last one. To get a bin’s value both before and after you modify it, read the earlier value with a read expression under a different name:

const exp = Aerospike.exp;
const ops = [
// Read posted under the name "before"
exp.operations.read("before", exp.binInt("posted"), 0),
op.incr("posted", 1),
op.read("posted"),
];
const record = await client.operate(key, ops);
console.info("Before: %d, after: %d", record.bins.before, record.bins.posted);

Code block

Expand this section for a single code block to create a command operation
const Aerospike = await import("aerospike");
const op = Aerospike.operations;
const map = Aerospike.maps;
// Set hosts to your server's address and port
const config = { hosts: "YOUR_HOST_ADDRESS:YOUR_PORT" };
// Creates a key with the namespace "sandbox", set "ufodata", and user key 5001
const key = new Aerospike.Key("sandbox", "ufodata", 5001);
// Establishes a connection to the server
const client = await Aerospike.connect(config);
// Create the ops
const ops = [
op.write("posted", 20220602),
map.put("report", "city", "Ypsilanti"),
op.read("report"),
];
// Update the record
const record = await client.operate(key, ops);
await client.close();