Aerospike Node.js Client API

This documentation describes the Aerospike Node.js Client API in detail. The client API package is available for download from www.aerospike.com or can be installed via npm from the npmjs.com package repository. The source code is available on GitHub. For more information about the Aerospike high-performance NoSQL database, please refer to http://www.aerospike.com/.

Contents

The aerospike npm package provides the aerospike module, which includes a number of submodules, classes as well as module level functions which together form the Client SDK enabling Node.js applications to connect to Aerospike database clusters.

Modules

The main modules included in the aerospike package are:

  • The aerospike module contains the core classes that make up the Client API, such as the Client, Record, Query classes, etc. It provides module level functions to connect to an Aerospike cluster.
  • The policy module defines policies and policy values that define the behavior of database operations.
  • The filter module and predexp module define secondary index filters and predicate expressions that can be used to limit the scope of query operations.
  • The operations, lists and maps modules define the operations on scalar, list and map values that can be executed with the Client#operate command.
  • The info protocol provides access to configuration and statistics for the Aerospike server. The info module includes utility functions for parsing the info data returned by the Aerospike cluster.

Classes

The main classes included in the aerospike module are:

  • Client - The main interface of the Aerospike client. Through the Client class commands such as put, get or query can be sent to an Aerospike database cluster.
  • Key - Keys are used to uniquely identify a record in the Aerospike database.
  • Record - Records consists of one or more record "bins" (name-value pairs) and meta-data, incl. time-to-live and generation; a record is uniquely identified by it's key within a given namespace.
  • Query - The Query class can be used to perform value-based searches on secondary indexes.
  • Scan - Through the Scan class scans of an entire namespaces can be performed.
  • RecordStream - Queries and scans return records through a RecordStream instance which acts as an EventEmitter.
  • Job - The Job class is used to query the status of long running background jobs, such as background scans or index creation.
  • Double - Wrapper class for double precision floating point values.
  • GeoJSON - A representation of GeoJSON values.
  • AerospikeError - Error class representing a Aerospike server and/or client error.

All modules and classes can also be accessed directly through the drop-down menu at the top of each page.

Supported Data Types

Aerospike supports integer, double, string, bytes, list and map data types. Within the Node.js client these values are represented as JS numbers (integer and double), JS strings, Buffers (bytes), Arrays (list) and Objects (map). Lists and Maps can contain any of the other supported data types and can be nested (e.g. lists-within-lists, maps-within-maps, lists-within-maps, etc.).

Aerospike currently does not support a boolean data type. To store boolean values in the database, the application needs to convert them to a supported data type as the client does not do any automatica data type conversions. Attempting to store a boolean value in a record bin will lead to a parameter error being returned by the client.

Example

The following is very simple example of how to write and read a record from Aerospike.

const Aerospike = require('aerospike')

const config = {
  hosts: '192.168.33.10:3000'
}
const key = new Aerospike.Key('test', 'demo', 'demo')

Aerospike.connect(config)
  .then(client => {
    const bins = {
      i: 123,
      s: 'hello',
      b: Buffer.from('world'),
      d: new Aerospike.Double(3.1415),
      g: Aerospike.GeoJSON.Point(103.913, 1.308),
      l: [1, 'a', {x: 'y'}],
      m: {foo: 4, bar: 7}
    }
    const meta = { ttl: 10000 }
    const policy = new Aerospike.WritePolicy({
      exists: Aerospike.policy.exists.CREATE_OR_REPLACE
    })

    return client.put(key, bins, meta, policy)
      .then(() => {
        const ops = [
          Aerospike.operations.incr('i', 1),
          Aerospike.operations.read('i'),
          Aerospike.lists.append('l', 'z'),
          Aerospike.maps.removeByKey('m', 'bar')
        ]

        return client.operate(key, ops)
      })
      .then(result => {
        console.log(result.bins) // => { i: 124, l: 4, m: null }

        return client.get(key)
      })
      .then(record => {
        console.log(record.bins) // => { i: 124,
                                 //      s: 'hello',
                                 //      b: <Buffer 77 6f 72 6c 64>,
                                 //      d: 3.1415,
                                 //      g: '{"type":"Point","coordinates":[103.913,1.308]}',
                                 //      l: [ 1, 'a', { x: 'y' }, 'z' ],
                                 //      m: { foo: 4 } }
      })
      .then(() => client.close())
  })
  .catch(error => {
    console.error('Error: %s [%i]', error.message, error.code)
    if (error.client) {
      error.client.close()
    }
  })

Tutorials

The following tutorials provide more in-depth examples for specific aspects of working with the Aerospike Node.js Client SDK:

Further Documentation

For a detailed technical documentation of the Aerospike distributed NoSQL database, including an architecture overview and in-depth feature guides, please visit http://www.aerospike.com/docs.