Bin operations

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, Blob/Bytes, Geospatial, and HyperLogLog data types can be found here.

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.
Integer Float	op_add	Add (or subtract) a value. Used to implement counters. Also called increment.
String	op_append op_prepend	Modify a string.

Note

Operations are performed in user defined order.

Single operation

All of the operations in the table above, along with CDT, Blob/Bytes, Geospatial, and HyperLogLog operations, 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);

Returning from operate()

It’s important to understand how the operate method returns data, since operate accepts a variety of operations and deals with both reads and writes in a single call.

Examples of operations and results:

• A basic put or write operation does not return anything by default, though it can be set to return null through a write policy.
• A map or list modify operation returns the map or list size for the bin_name.
• A get or read operation returns the value for the bin_name.

See Bitwise Operations, List Operations, Map Operations, HLL Operations, and Expressions for more information about return values.

The operate method takes the results of all the operations executed within the call and groups them together by bin_name. If a specific bin_name has multiple results, such as an operate call containing multiple operations that return results for a single bin_name, a list is created containing the results of each operation. If a bin_name has a single value, the bin_name value is returned as expected.

When grouped by bin_name, the way results are accessed will vary based on what operations are performed.

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();