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 portconst config = { hosts: "YOUR_HOST_ADDRESS:YOUR_PORT" };
// Creates a key with the namespace "sandbox", set "ufodata", and user key 5001const key = new Aerospike.Key("sandbox", "ufodata", 5001);
// Establishes a connection to the serverconst 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 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. 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_ORDEREDconst mapPolicy = new Aerospike.MapPolicy({ order: map.order.KEY_ORDERED });
// Create the opsconst ops = [map.setPolicy("report", mapPolicy)];
// Apply the map policyawait 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 opsconst ops = [ op.write("posted", 20220602), map.put("report", "city", "Ypsilanti"), op.read("report"),];
// Update the recordconst record = await client.operate(key, ops);
// Do somethingconsole.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
writeoperation returns no value, and its bin isn’t included inbins. - A list or map modify operation returns a value that depends on the operation. For example,
list.append()returns the list’s new size andlist.trim()returns the number of elements removed. - A
readoperation 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 portconst config = { hosts: "YOUR_HOST_ADDRESS:YOUR_PORT" };
// Creates a key with the namespace "sandbox", set "ufodata", and user key 5001const key = new Aerospike.Key("sandbox", "ufodata", 5001);
// Establishes a connection to the serverconst client = await Aerospike.connect(config);
// Create the opsconst ops = [ op.write("posted", 20220602), map.put("report", "city", "Ypsilanti"), op.read("report"),];
// Update the recordconst record = await client.operate(key, ops);
await client.close();