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 or can be installed via npm from the package repository. The source code is available on GitHub. For more information about the Aerospike high-performance NoSQL database, please refer to


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.


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 exp module define secondary index (SI) filters and 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.


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 the following data types:

Aerospike data type Mapping to Node.js data type
Integer Number or BigInt
Double Number
String String
Boolean Boolean
Bytes Buffer
List Array
Map Object
HyperLogLog Buffer

Note: Support for the Boolean data type requires server 5.6+ and Aerospike Node.js client version 4.0+.

Nested Data Structure

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., to an arbitrary depth. To perform operations on nested lists and maps, you can provide a CDT Context object to the list and map operations.


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

const Aerospike = require('aerospike')

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

  .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.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) {


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