Aerospike

Module: aerospike/policy

The policy module defines policies and policy values that define the behavior of database operations. Most Client methods, including scans and queries, accept a policy object, that affects how the database operation is executed, by specifying timeouts, transactional behavior, etc. Global defaults for specific types of database operations can also be set through the client config, when a new Client instance is created.

Different policies apply to different types of database operations:

Base policy BasePolicy class which defines common policy values that apply to all database operations (except InfoPolicy, MapPolicy and ListPolicy).

This module also defines global values for the following policy settings:

  • commitLevel - Specifies the number of replicas required to be successfully committed before returning success in a write operation to provide the desired consistency guarantee.
  • exists - Specifies the behavior for writing the record depending whether or not it exists.
  • gen - Specifies the behavior of record modifications with regard to the generation value.
  • key - Specifies the behavior for whether keys or digests should be sent to the cluster.
  • readModeAP - How duplicates should be consulted in a read operation.
  • readModeSC - Determines SC read consistency options.
  • replica - Specifies which partition replica to read from.
Source:

Example

const Aerospike = require('aerospike')

const config = {
  hosts: '192.168.33.10:3000'
}

const key = new Aerospike.Key('test', 'demo', 'k1')

Aerospike.connect(config)
  .then(client => {
    let record = {i: 1234}

    // Override policy for put command
    let policy = new Aerospike.policy.WritePolicy({
      exists: Aerospike.policy.exists.CREATE,
      key: Aerospike.policy.key.SEND,
      socketTimeout: 0,
      totalTimeout: 0
    })

    return client.put(key, record, {}, policy)
      .then(() => client.close())
      .catch(error => {
        client.close()
        if (error.code === Aerospike.status.ERR_RECORD_EXISTS) {
          console.info('record already exists')
        } else {
          return Promise.reject(error)
        }
      })
  })
  .catch(error => console.error('Error:', error))

Members

<static> ApplyPolicy

ApplyPolicy class

A policy affecting the behavior of apply operations.

Source:

<static> BasePolicy

BasePolicy class

A base class extended to client policies.

Source:

<static> BatchApplyPolicy

BatchApplyPolicy class

A policy affecting the behavior of batchApply operations.

Source:

<static> BatchPolicy

BatchPolicy class

A policy affecting the behavior of batch operations.

Source:

<static> BatchReadPolicy

BatchReadPolicy class

A policy affecting the behavior of batchRead operations.

Source:

<static> BatchRemovePolicy

BatchRemovePolicy class

A policy affecting the behavior of batchRemove operations.

Source:

<static> BatchWritePolicy

BatchWritePolicy class

A policy affecting the behavior of batchWrite operations.

Source:

<static> CommandQueuePolicy

CommandQueuePolicy class

A policy affecting the use of the global command queue.

Source:

<static> HLLPolicy

HLLPolicy class

A policy affecting the behavior of HLL operations.

Source:

<static> InfoPolicy

InfoPolicy class

A policy affecting the behavior of info operations.

Source:

<static> ListPolicy

ListPolicy class

A policy affecting the behavior of list operations.

Source:

<static> MapPolicy

MapPolicy class

A policy affecting the behavior of map operations.

Source:

<static> OperatePolicy

OperatePolicy class

A policy affecting the behavior of operate operations.

Source:

<static> QueryPolicy

QueryPolicy class

A policy affecting the behavior of query operations.

Source:

<static> ReadPolicy

ReadPolicy class

A policy affecting the behavior of read operations.

Source:

<static> RemovePolicy

RemovePolicy class

A policy affecting the behavior of remove operations.

Source:

<static> ScanPolicy

ScanPolicy class

A policy affecting the behavior of scan operations.

Source:

<static> WritePolicy

WritePolicy class

A policy affecting the behavior of write operations.

Source:

<static> commitLevel :Object

Specifies the number of replicas required to be successfully committed before returning success in a write operation to provide the desired consistency guarantee.

Type:
  • Object
Properties:
Name Type Description
ALL

Return success only after successfully committing all replicas.
MASTER

Return success after successfully committing the master replica.
Source:

<static> exists :Object

Specifies the behavior for writing the record depending whether or not it exists.

Type:
  • Object
Properties:
Name Type Description
IGNORE

Write the record, regardless of existence. (I.e. create or update.)
CREATE

Create a record, ONLY if it doesn't exist.
UPDATE

Update a record, ONLY if it exists.
REPLACE

Completely replace a record, ONLY if it exists.
CREATE_OR_REPLACE

Completely replace a record if it exists, otherwise create it.
Source:

<static> gen :Object

The generation policy specifies how to handle record writes based on record generation.

To use the EQ or GT generation policy (see below), the generation value to use for the comparison needs to be specified in the metadata parameter (meta) of the Client#put operation.

Type:
  • Object
Properties:
Name Type Description
IGNORE

Do not use record generation to restrict writes.
EQ

Update/delete record if expected generation is equal to server generation. Otherwise, fail.
GT

Update/delete record if expected generation greater than the server generation. Otherwise, fail. This is useful for restore after backup.
Source:
Example

Update record, only if generation matches

const Aerospike = require('aerospike')
const key = new Aerospike.Key('test', 'test', 'myKey')
// INSERT HOSTNAME AND PORT NUMBER OF AEROSPIKE SERVER NODE HERE!
var config = {
  hosts: '192.168.33.10:3000',
  // Timeouts disabled, latency dependent on server location. Configure as needed.
  policies: {
    write : new Aerospike.WritePolicy({socketTimeout : 0, totalTimeout : 0})
  }
}
Aerospike.connect(config).then(async (client) => {
  await client.put(key, { foo: 'bar' })

  const record = await client.get(key)
  const gen = record.gen // Current generation of the record. (1 for new record.)
  // Perform some operation using record. Some other process might update the
  // record in the meantime, which would change the generation value.
  if (Math.random() < 0.1) await client.put(key, { foo: 'fox' })

  try {
    // Update record only if generation is still the same.
    const meta = { gen }
    const policy = { gen: Aerospike.policy.gen.EQ }
    await client.put(key, { status: 'updated' }, meta, policy)
    console.log('Record updated successfully.')
  } catch (error) {
    if (error.code == Aerospike.status.ERR_RECORD_GENERATION) {
      console.error('Failed to update record, because generation did not match.')
    }
  }

  client.close()
})

<static> key :Object

Specifies the behavior for whether keys or digests should be sent to the cluster.

Type:
  • Object
Properties:
Name Type Description
DIGEST

Send the digest value of the key. This is the recommended mode of operation. This calculates the digest and sends the digest to the server. The digest is only calculated on the client, and not the server.
SEND

Send the key, in addition to the digest value. If you want keys to be returned when scanning or querying, the keys must be stored on the server. This policy causes a write operation to store the key. Once the key is stored, the server will keep it - there is no need to use this policy on subsequent updates of the record. If this policy is used on read or delete operations, or on subsequent updates of a record with a stored key, the key sent will be compared with the key stored on the server. A mismatch will cause ERR_RECORD_KEY_MISMATCH to be returned.
Source:

<static> readModeAP :Object

Read policy for AP (availability) namespaces.

How duplicates should be consulted in a read operation. Only makes a difference during migrations and only applicable in AP mode.

Type:
  • Object
Properties:
Name Type Description
ONE

Involve a single node in the read operation.
ALL

Involve all duplicates in the read operation.
Source:

<static> readModeSC :Object

Read policy for SC (strong consistency) namespaces.

Determines SC read consistency options.

Type:
  • Object
Properties:
Name Type Description
SESSION

Ensures this client will only see an increasing sequence of record versions. Server only reads from master. This is the default.
LINEARIZE

Ensures ALL clients will only see an increasing sequence of record versions. Server only reads from master.
ALLOW_REPLICA

Server may read from master or any full (non-migrating) replica. Increasing sequence of record versions is not guaranteed.
ALLOW_UNAVAILABLE

Server may read from master or any full (non-migrating) replica or from unavailable partitions. Increasing sequence of record versions is not guaranteed.
Source:

<static> replica

Specifies which partition replica to read from.

Properties:
Name Type Description
MASTER

Read from the partition master replica node.
ANY

Distribute reads across nodes containing key's master and replicated partition in round-robin fashion. Currently restricted to master and one prole.
SEQUENCE

Always try node containing master partition first. If the command times out and the policy settings allow for an automatic retry, try the node containing the prole partition. Currently restricted to master and one prole.
PREFER_RACK

Try node on the same rack as the client first. If there are no nodes on the same rack, use SEQUENCE instead. rackAware config, rackId config, and server rack configuration must also be set to enable this functionality.
Source: