Skip to content

Latest commit

 

History

History
209 lines (167 loc) · 6.22 KB

aerospike_operate.md

File metadata and controls

209 lines (167 loc) · 6.22 KB

Aerospike::operate

Aerospike::operate - multiple operations on a single record

Description

public int Aerospike::operate ( array $key, array $operations [, array &$returned [, array $options]] )

Aerospike::operate() allows for multiple per-bin operations on a record with a given key, with write operations happening before read ones. Non-existent bins being read will have a NULL value.

Currently only a call to operate() can include only one write operation per-bin. For example, you cannot both append and prepend to the same bin, in the same call.

Like other bin operations, operate() only works on existing records (i.e. ones that were previously created with a put()).

Parameters

key the key identifying the record. An array with keys ['ns','set','key'] or ['ns','set','digest'].

operations an array of one or more per-bin operations conforming to the following structure:

Write Operation:
  op => Aerospike::OPERATOR_WRITE
  bin => bin name (cannot be longer than 14 characters)
  val => the value to store in the bin

Increment Operation:
  op => Aerospike::OPERATOR_INCR
  bin => bin name
  val => the integer by which to increment the value in the bin

Prepend Operation:
  op => Aerospike::OPERATOR_PREPEND
  bin => bin name
  val => the string to prepend the string value in the bin

Append Operation:
  op => Aerospike::OPERATOR_APPEND
  bin => bin name
  val => the string to append the string value in the bin

Read Operation:
  op => Aerospike::OPERATOR_READ
  bin => name of the bin we want to read after any write operations

Touch Operation: reset the time-to-live of the record and increment its generation
                 (only combines with read operations)
  op => Aerospike::OPERATOR_TOUCH
  ttl => a positive integer value to set as time-to-live for the record

List Append Operation:
  op => Aerospike::OP_LIST_APPEND,
  bin =>  "events",
  val =>  1234

List Merge Operation:
  op => Aerospike::OP_LIST_MERGE,
  bin =>  "events",
  val =>  [ 123, 456 ]

List Insert Operation:
  op => Aerospike::OP_LIST_INSERT,
  bin =>  "events",
  index =>  2,
  val =>  1234

List Insert Items Operation:
  op => Aerospike::OP_LIST_INSERT_ITEMS,
  bin =>  "events",
  index =>  2,
  val =>  [ 123, 456 ]

List Pop Operation:
  op => Aerospike::OP_LIST_POP, # returns a value
  bin =>  "events",
  index =>  2

List Pop Range Operation:
  op => Aerospike::OP_LIST_POP_RANGE, # returns a value
  bin =>  "events",
  index =>  2,
  val =>  3 # remove 3 elements starting at index 2

List Remove Operation:
  op => Aerospike::OP_LIST_REMOVE,
  bin =>  "events",
  index =>  2

List Remove Range Operation:
  op => Aerospike::OP_LIST_REMOVE_RANGE,
  bin =>  "events",
  index =>  2,
  val =>  3 # remove 3 elements starting at index 2

List Clear Operation:
  op => Aerospike::OP_LIST_CLEAR,
  bin =>  "events"

List Set Operation:
  op => Aerospike::OP_LIST_SET,
  bin =>  "events",
  index =>  2,
  val =>  "latest event at index 2" # set this value at index 2

List Get Operation:
  op => Aerospike::OP_LIST_GET, # returns a value
  bin =>  "events",
  index =>  2 # similar to Aerospike::OPERATOR_READ but only returns the value
                at index 2 of the list, not the whole bin

List Get Range Operation:
  op => Aerospike::OP_LIST_GET_RANGE, # returns a value
  bin =>  "events",
  index =>  2,
  val =>  3 # get 3 elements starting at index 2

List Trim Operation:
  op => Aerospike::OP_LIST_TRIM,
  bin =>  "events",
  index =>  2,
  val =>  3 # remove all elements not in the range between index 2 and index 2 + 3

List Size Operation:
  op => Aerospike::OP_LIST_SIZE, # returns a value
  bin =>  "events" # gets the size of a list contained in the bin

examples: Combining several write operations into one multi-op call:

[
  ["op" => Aerospike::OPERATOR_APPEND, "bin" => "name", "val" => " Ph.D."],
  ["op" => Aerospike::OPERATOR_INCR, "bin" => "age", "val" => 1],
  ["op" => Aerospike::OPERATOR_READ, "bin" => "age"]
]

To implement an LRU you can read a bin and touch a record in the same operation:

[
  ["op" => Aerospike::OPERATOR_READ, "bin" => "age"],
  ["op" => Aerospike::OPERATOR_TOUCH, "ttl" => 20]
]

returned an array of bins retrieved by read operations. If multiple operations exist for a specific bin name, the last operation will be the one placed as the value.

options including

Return Values

Returns an integer status code. Compare to the Aerospike class status constants. When non-zero the Aerospike::error() and Aerospike::errorno() methods can be used.

Examples

<?php

$config = ["hosts" => [["addr"=>"localhost", "port"=>3000]], "shm"=>[]];
$client = new Aerospike($config, true);
if (!$client->isConnected()) {
   echo "Aerospike failed to connect[{$client->errorno()}]: {$client->error()}\n";
   exit(1);
}

$key = $client->initKey("test", "users", 1234);
$operations = [
  ["op" => Aerospike::OPERATOR_APPEND, "bin" => "name", "val" => " Ph.D."],
  ["op" => Aerospike::OPERATOR_INCR, "bin" => "age", "val" => 1],
  ["op" => Aerospike::OPERATOR_READ, "bin" => "age"],
];
$options = [Aerospike::OPT_TTL => 600];
$status = $client->operate($key, $operations, $returned, $options);
if ($status == Aerospike::OK) {
    var_dump($returned);
} else {
    echo "[{$client->errorno()}] ".$client->error();
}

?>

We expect to see:

array(1) {
  ["age"]=>
  int(34)
}