aerospike/policy

Description:
Source:

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, AdminPolicy, 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.

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) AdminPolicy

AdminPolicy class

Description:

  • A policy affecting the behavior of admin operations.

Source:

A policy affecting the behavior of admin operations.

(static) ApplyPolicy

ApplyPolicy class

Description:

  • A policy affecting the behavior of apply operations.

Source:

A policy affecting the behavior of apply operations.

(static) BasePolicy

BasePolicy class

Description:

  • A base class extended to client policies.

Source:

A base class extended to client policies.

(static) BatchApplyPolicy

BatchApplyPolicy class

Description:

  • A policy affecting the behavior of batchApply operations.

Source:

A policy affecting the behavior of batchApply operations.

(static) BatchPolicy

BatchPolicy class

Description:

  • A policy affecting the behavior of batch operations.

Source:

A policy affecting the behavior of batch operations.

(static) BatchReadPolicy

BatchReadPolicy class

Description:

  • A policy affecting the behavior of batchRead operations.

Source:

A policy affecting the behavior of batchRead operations.

(static) BatchRemovePolicy

BatchRemovePolicy class

Description:

  • A policy affecting the behavior of batchRemove operations.

Source:

A policy affecting the behavior of batchRemove operations.

(static) BatchWritePolicy

BatchWritePolicy class

Description:

  • A policy affecting the behavior of batchWrite operations.

Source:

A policy affecting the behavior of batchWrite operations.

(static) CommandQueuePolicy

CommandQueuePolicy class

Description:

  • A policy affecting the use of the global command queue.

Source:

A policy affecting the use of the global command queue.

(static) HLLPolicy

HLLPolicy class

Description:

  • A policy affecting the behavior of HLL operations.

Source:

A policy affecting the behavior of HLL operations.

(static) InfoPolicy

InfoPolicy class

Description:

  • A policy affecting the behavior of info operations.

Source:

A policy affecting the behavior of info operations.

(static) ListPolicy

ListPolicy class

Description:

  • A policy affecting the behavior of list operations.

Source:

A policy affecting the behavior of list operations.

(static) MapPolicy

MapPolicy class

Description:

  • A policy affecting the behavior of map operations.

Source:

A policy affecting the behavior of map operations.

(static) OperatePolicy

OperatePolicy class

Description:

  • A policy affecting the behavior of operate operations.

Source:

A policy affecting the behavior of operate operations.

(static) QueryPolicy

QueryPolicy class

Description:

  • A policy affecting the behavior of query operations.

Source:

A policy affecting the behavior of query operations.

(static) ReadPolicy

ReadPolicy class

Description:

  • A policy affecting the behavior of read operations.

Source:

A policy affecting the behavior of read operations.

(static) RemovePolicy

RemovePolicy class

Description:

  • A policy affecting the behavior of remove operations.

Source:

A policy affecting the behavior of remove operations.

(static) ScanPolicy

ScanPolicy class

Description:

  • A policy affecting the behavior of scan operations.

Source:

A policy affecting the behavior of scan operations.

(static) WritePolicy

WritePolicy class

Description:

  • A policy affecting the behavior of write operations.

Source:

A policy affecting the behavior of write operations.

(static) commitLevel :Object

Description:

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

Source:
Properties:
Name Type Description
ALL

Return success only after successfully committing all replicas.
MASTER

Return success after successfully committing the master replica.

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

(static) exists :Object

Description:

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

Source:
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.

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

Type:
  • Object

(static) gen :Object

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

Description:

  • 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.

Source:
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.

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
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

Description:

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

Source:
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.

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

Type:
  • Object

(static) readModeAP :Object

Read policy for AP (availability) namespaces.

Description:

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

Source:
Properties:
Name Type Description
ONE

Involve a single node in the read operation.
ALL

Involve all duplicates in the read operation.

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

Type:
  • Object

(static) readModeSC :Object

Read policy for SC (strong consistency) namespaces.

Description:

  • Determines SC read consistency options.

Source:
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.

Determines SC read consistency options.

Type:
  • Object

(static) replica

Description:

  • Specifies which partition replica to read from.

Source:
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.

Specifies which partition replica to read from.