Module: aerospike/maps

This module defines operations on the Sorted Map data type that can be used with the Client#operate command. Operations on Sorted Maps require Aerospike Server ⇑version 3.8.4 or later.

For more information, please refer to the ⇑Maps documentation in the Aerospike Feature Guide.

Sorted Maps

The Map data type supports both unordered and ordered maps. Maps can be ordered by key, or by key and value. By default, maps are unordered. The map order is controlled through the map policy and can be set either when the map is created through the put or putItems operations or later on through the setPolicy operation.

All maps maintain an index and a rank. The index is the item offset from the start of the map, for both unordered and ordered maps. The rank is the sorted index of the value component. Map supports negative indexing for index and rank.

Index examples:

  • Index 0: First item in map.
  • Index 4: Fifth item in map.
  • Index -1: Last item in map.
  • Index -3: Third to last item in map.
  • Index 1 Count 2: Second and third items in map.
  • Index -3 Count 3: Last three items in map.
  • Index -5 Count 4: Range between fifth to last item to second to last item inclusive.

Rank examples:

  • Rank 0: Item with lowest value rank in map.
  • Rank 4: Fifth lowest ranked item in map.
  • Rank -1: Item with highest ranked value in map.
  • Rank -3: Item with third highest ranked value in map.
  • Rank 1 Count 2: Second and third lowest ranked items in map.
  • Rank -3 Count 3: Top three ranked items in map.

CDT Context - Operating on Nested Maps

To operate on nested maps, use the MapOperation#withContext function to set the context for a map operation.

Source:
See:

Example

Manipulating a map bin using map operations

const Aerospike = require('aerospike')
const maps = Aerospike.maps
const key = new Aerospike.Key('test', 'demo', 'mapKey')

Aerospike.connect().then(async client => {
  let ops = [
    maps.put('map', 'e', 5, {
      order: maps.order.KEY_ORDERED
    }),                                           // => { e: 5 }
    maps.putItems('map', { d: 4, b: 2, c: 3 }),   // => { b: 2, c: 3, d: 4, e: 5 }
    maps.putItems('map', { c: 99, a: 1 }, {
      writeFlags: maps.writeFlags.CREATE_ONLY
        | maps.writeFlags.NO_FAIL
        | maps.writeFlags.PARTIAL
    }),                                           // => { a: 1, b: 2, c: 3, d: 4, e: 5 }
    maps.removeByValue('map', 3),                 // => { a: 1, b: 2, d: 4, e: 5 }
    maps.removeByIndexRange('map', -2)
      .andReturn(maps.returnType.KEY)             // => { a: 1, b: 2 }
  ]
  let result = await client.operate(key, ops)
  console.log(result.bins.map)                    // => ['d', 'e']
  let record = await client.get(key)
  console.log(record.bins.map)                    // => { a: 1, b: 2 }
  await client.remove(key)
  client.close()
})

Classes

MapOperation

Members


<static> order :Object

Map order.

The order determines what kind of index the Aerospike server maintains for the map.

Type:
  • Object
Properties:
Name Type Description
UNORDERED number

Map is not ordered. This is the default.

KEY_ORDERED number

Order map by key.

KEY_VALUE_ORDERED number

Order map by key, then value.

Source:

<static> returnType :Object

Map return type.

The return type determines what data of the selected items the get and remove operations return in the result of the Client#operate command. It is optional to specify the return type for remove operations; default is NONE. For get operations the return type parameter is required.

Type:
  • Object
Properties:
Name Type Description
NONE number

Do not return a result; this is the default.

INDEX number

Return key index order. (0 = first key, 1 = second key, ...)

REVERSE_INDEX number

Return reverse key order. (0 = last key, -1 = second last key, ...)

RANK number

Return value order. (0 = smallest value, 1 = second smallest value, ...)

REVERSE_RANK number

Return reverse value order. (0 = largest value, -1 = second largest value, ...)

COUNT number

Return count of items selected.

KEY number

Return key for single key read and key list for range read.

VALUE number

Return value for single key read and value list for range read.

KEY_VALUE number

Return map items keys and values as an Array, i.e. [key1, value1, key2, value2, ...].

Source:

<static> writeFlags :Object

Map write flags.

The write flags determine whether a write operation succeeds, depending on whether the map key(s) to be written already exist. They also determine whether a new map will be created automatically if the record bin, which the map operation is targeting, is currently empty.

Map write flags require server version v4.3 or later. For earier server versions, set the writeMode instead.

Type:
  • Object
Properties:
Name Type Description
DEFAULT number

Allow create or update. Default.

CREATE_ONLY number

If the key already exists, the item will be denied. If the key does not exist, a new item will be created.

UPDATE_ONLY number

If the key already exists, the item will be overwritten. If the key does not exist, the item will be denied.

NO_FAIL number

Do not raise error, if map item is denied due to write flag constraints.

PARTIAL number

Allow other valid map items to be committed, if a map item is denied due to write flag constraints.

Since:
  • v3.5.0
Source:

<static> writeMode :Object

Map write mode.

The write mode determines whether a write operation succeeds, depending on whether the map key(s) to be written already exist. It also determines whether a new map will be created automatically if the record bin, which the map operation is targeting, is currently empty.

Map write mode should only be used for server versions prior to v4.3. For server versions v4.3 or later, the use of writeFlags is recommended.

Type:
  • Object
Properties:
Name Type Description
UPDATE number

If the key already exists, the item will be overwritten. If the key does not exist, a new item will be created. This is the default write mode.

UPDATE_ONLY number

If the key already exists, the item will be overwritten. If the key does not exist, the write will fail.

CREATE_ONLY number

If the key already exists, the write will fail. If the key does not exist, a new item will be created.

Deprecated:
  • since v3.5.0
Source:

Methods


<static> clear(bin)

Removes all items in the map.

This operation does not return any result.

Parameters:
Name Type Description
bin string

The name of the bin. If the bin exists, it must contain a Map value; if it does not yet exist, a new Map may be created depending on the map policy's write mode.

Source:
Returns:

Operation that can be passed to the Client#operate command.

Type
Object

<static> decrement(bin, key, decr [, policy])

Decrements the map entry identified by the given key by the value decr. Valid only for numeric values.

If a map entry with the given key does not exist, the map policy's write mode determines whether a new entry will be created same as for the put command. This operation may create a new map if the map bin is currently empty.

This operation returns the new value of the map entry.

Parameters:
Name Type Argument Description
bin string

The name of the bin. If the bin exists, it must contain a Map value; if it does not yet exist, a new Map may be created depending on the map policy's write mode.

key any

The map key.

decr number

The value to decrement the map entry by.

policy MapPolicy <optional>

The map policy.

Deprecated:
  • since v4.0.0 - use increment function with negative value instead.
Source:
Returns:

Operation that can be passed to the Client#operate command.

Type
Object

<static> getByIndex(bin, index [, returnType])

Retrieves a single item identified by it's index value from the map.

This operation returns the data specified by returnType.

Parameters:
Name Type Argument Description
bin string

The name of the bin, which must contain a Map value.

index number

Index of the entry to remove.

returnType number <optional>

The return type indicating what data of the selected item(s) to return.

Source:
See:
Returns:

Operation that can be passed to the Client#operate command.

Type
Object

<static> getByIndexRange(bin, index [, count] [, returnType])

Retrieves one or more items in the specified index range from the map.

This operation returns the data specified by returnType.

Parameters:
Name Type Argument Description
bin string

The name of the bin, which must contain a Map value.

index number

Starting index.

count number <optional>

Number of items to delete. If undefined, the range includes all items starting from index.

returnType number <optional>

The return type indicating what data of the selected item(s) to return.

Source:
See:
Returns:

Operation that can be passed to the Client#operate command.

Type
Object

<static> getByKey(bin, key [, returnType])

Retrieves a single item identified by key from the map.

This operation returns the data specified by returnType.

Parameters:
Name Type Argument Description
bin string

The name of the bin, which must contain a Map value.

key any

The map key.

returnType number <optional>

The return type indicating what data of the selected item(s) to return.

Source:
See:
Returns:

Operation that can be passed to the Client#operate command.

Type
Object

<static> getByKeyRange(bin, begin, end [, returnType])

Retrieves one or more items identified by a range of keys from the map.

This operation returns the data specified by returnType.

Parameters:
Name Type Argument Description
bin string

The name of the bin, which must contain a Map value.

begin any <nullable>

Start key in the range (inclusive). If set to null, the range includes all keys less than the end key.

end any <nullable>

End key in the range (exclusive). If set to null, the range includes all keys greater than or equal to the begin key.

returnType number <optional>

The return type indicating what data of the selected item(s) to return.

Source:
See:
Returns:

Operation that can be passed to the Client#operate command.

Type
Object

<static> getByKeyRelIndexRange(bin, key, index [, count] [, returnType])

Retrieves map items nearest to key and greater, by index, from the map.

This operation returns the selected data specified by returnType.

Examples for map { a: 17, e: 2, f: 15, j: 10 }:

  • (value, index, count) = [selected items]
  • ('f', 0, 1) = { f: 15 }
  • ('f', 1, 2) = { j: 10 }
  • ('f', -1, 1) = { e: 2 }
  • ('b', 2, 1) = { j: 10 }
  • ('b', -2, 2) = { a: 17 }

Without count:

  • (value, index) = [selected items]
  • ('f', 0) = { f: 15, j: 10 }
  • ('f', 1) = { j: 10 }
  • ('f', -1) = { e: 2, f: 15, j: 10 }
  • ('b', 2) = { j: 10 }
  • ('b', -2) = { a: 17, e: 2, f: 15, j: 10 }

Requires Aerospike Server v4.3.0 or later.

Parameters:
Name Type Argument Description
bin string

The name of the bin, which must contain a Map value.

key any

Find map items nearest to this key and greater.

index number

Index of items to be retrieved relative to the given key.

count number <optional>

Number of items to retrieve. If undefined, the range includes all items nearest to key and greater, until the end.

returnType number <optional>

The return type indicating what data of the selected item(s) to return.

Since:
  • v3.5.0
Source:
See:
Returns:

Operation that can be passed to the Client#operate command.

Type
Object
Example
const Aerospike = require('aerospike')
const maps = Aerospike.maps
const key = new Aerospike.Key('test', 'demo', 'mapKey')

Aerospike.connect()
  .then(async client => {
    await client.put(key, { map: { a: 17, e: 2, f: 15, j: 10 } })
    let result = await client.operate(key, [
      maps.getByKeyRelIndexRange('map', 'b', 2, 1)
        .andReturn(maps.returnType.KEY_VALUE)])
    console.info(result.bins.map) // => [ 'j', 10 ]
    client.close()
  })

<static> getByRank(bin, rank [, returnType])

Retrieves a single item identified by it's rank value from the map.

This operation returns the data specified by returnType.

Parameters:
Name Type Argument Description
bin string

The name of the bin, which must contain a Map value.

rank number

Rank of the entry to remove.

returnType number <optional>

The return type indicating what data of the selected item(s) to return.

Source:
See:
Returns:

Operation that can be passed to the Client#operate command.

Type
Object

<static> getByRankRange(bin, index, count [, returnType])

Retrieves one or more items in the specified rank range from the map.

This operation returns the data specified by returnType.

Parameters:
Name Type Argument Description
bin string

The name of the bin, which must contain a Map value.

index number

Starting rank.

count number

Number of items to delete; if not specified, the range includes all items starting from rank.

returnType number <optional>

The return type indicating what data of the selected item(s) to return.

Source:
See:
Returns:

Operation that can be passed to the Client#operate command.

Type
Object

<static> getByValue(bin, value [, returnType])

Retrieves one or more items identified by a single value from the map.

This operation returns the data specified by returnType.

Parameters:
Name Type Argument Description
bin string

The name of the bin, which must contain a Map value.

value any

The map value.

returnType number <optional>

The return type indicating what data of the selected item(s) to return.

Source:
See:
Returns:

Operation that can be passed to the Client#operate command.

Type
Object

<static> getByValueRange(bin, begin, end [, returnType])

Retrieves one or more items identified by a range of values from the map.

This operation returns the data specified by returnType.

Parameters:
Name Type Argument Description
bin string

The name of the bin, which must contain a Map value.

begin any <nullable>

Start values in the range (inclusive). If set to null, the range includes all values less than the end value.

end any <nullable>

End value in the range (exclusive). If set to null, the range includes all values greater than or equal to the begin value.

returnType number <optional>

The return type indicating what data of the selected item(s) to return.

Source:
See:
Returns:

Operation that can be passed to the Client#operate command.

Type
Object

<static> getByValueRelRankRange(bin, value, rank [, count] [, returnType])

Retrieves map items nearest to value and greater, by relative rank.

This operation returns the selected data specified by returnType.

Examples for map { e: 2, j: 10, f: 15, a: 17 }:

  • (value, rank, count) = [selected items]
  • (11, 1, 1) = { a: 17 }
  • (11, -1, 1) = { j: 10 }

Without count:

  • (value, rank) = [selected items]
  • (11, 1) = { a: 17 }
  • (11, -1) = { j: 10, f: 15, a: 17 }
Parameters:
Name Type Argument Description
bin string

The name of the bin, which must contain a Map value.

value any

Find map items nearest to this value and greater.

rank number

Rank of items to be retrieved relative to the given value.

count number <optional>

Number of items to retrieve. If undefined, the range includes all items nearest to value and greater, until the end.

returnType number <optional>

The return type indicating what data of the selected item(s) to return.

Since:
  • v3.5.0
Source:
See:
Returns:

Operation that can be passed to the Client#operate command.

Type
Object
Example
const Aerospike = require('aerospike')
const maps = Aerospike.maps
const key = new Aerospike.Key('test', 'demo', 'mapKey')

Aerospike.connect()
  .then(async client => {
    await client.put(key, { map: { e: 2, j: 10, f: 15, a: 17 } })
    let result = await client.operate(key, [
      maps.getByValueRelRankRange('map', 11, 1, 1)
        .andReturn(maps.returnType.KEY_VALUE)])
    console.info(result.bins.map) // => [ 'a', 17 ]
    client.close()
  })

<static> increment(bin, key, incr [, policy])

Increments the map entry identified by the given key by the value incr. Valid only for numeric values.

If a map entry with the given key does not exist, the map policy's write mode determines whether a new entry will be created same as for the put command. This operation may create a new map if the map bin is currently empty.

This operation returns the new value of the map entry.

Parameters:
Name Type Argument Description
bin string

The name of the bin. If the bin exists, it must contain a Map value; if it does not yet exist, a new Map may be created depending on the map policy's write mode.

key any

The map key.

incr number

The value to increment the map entry by. Use negative value to decrement map entry.

policy MapPolicy <optional>

The map policy.

Source:
Returns:

Operation that can be passed to the Client#operate command.

Type
Object

<static> put(bin, key, value [, policy])

Writes a key/value item to the map.

Depending on the map policy and whether an entry with the same key already exists in the map, a new key will be added to the map or the existing entry with the same key will be updated. If the bin does not yet contain a map value, a new map may be created.

This operation returns the new size of the map.

Parameters:
Name Type Argument Description
bin string

The name of the bin. If the bin exists, it must contain a Map value; if it does not yet exist, a new Map may be created depending on the map policy's write mode.

key any

Map key to write.

value any

Map value to write.

policy MapPolicy <optional>

The map policy.

Source:
Returns:

Operation that can be passed to the Client#operate command.

Type
Object

<static> putItems(bin, items [, policy])

Writes each entry of the given map to the map bin on the server.

Depending on the map policy and whether an entry with the same key already exists in the map, a new entry will be added to the map or the existing entry with the same key will be updated. If the bin does not yet contain a map value, a new map may be created.

This operation returns the new size of the map.

Parameters:
Name Type Argument Description
bin string

The name of the bin. If the bin exists, it must contain a Map value; if it does not yet exist, a new Map may be created depending on the map policy's write mode.

items object

One or more key value pairs to write to the map.

policy MapPolicy <optional>

The map policy.

Source:
Returns:

Operation that can be passed to the Client#operate command.

Type
Object

<static> removeByIndex(bin, index [, returnType])

Removes a single item identified by its index value from the map.

This operation returns the removed data specified by returnType.

Parameters:
Name Type Argument Description
bin string

The name of the bin, which must contain a Map value.

index number

Index of the entry to remove.

returnType number <optional>

The return type indicating what data of the affected item(s) to return (if any).

Source:
See:
Returns:

Operation that can be passed to the Client#operate command.

Type
Object

<static> removeByIndexRange(bin, index [, count] [, returnType])

Removes one or more items in the specified index range from the map.

This operation returns the removed data specified by returnType.

Parameters:
Name Type Argument Description
bin string

The name of the bin, which must contain a Map value.

index number

Starting index.

count number <optional>

Number of items to delete. If undefined, the range includes all items starting from index.

returnType number <optional>

The return type indicating what data of the affected item(s) to return (if any).

Source:
See:
Returns:

Operation that can be passed to the Client#operate command.

Type
Object

<static> removeByKey(bin, key [, returnType])

Removes a single item identified by key from the map.

This operation returns the removed data specified by returnType.

Parameters:
Name Type Argument Description
bin string

The name of the bin, which must contain a Map value.

key any

The map key.

returnType number <optional>

The return type indicating what data of the affected item(s) to return (if any).

Source:
See:
Returns:

Operation that can be passed to the Client#operate command.

Type
Object

<static> removeByKeyList(bin, keys [, returnType])

Removes one or more items identified by key from the map.

This operation returns the removed data specified by returnType.

Parameters:
Name Type Argument Description
bin string

The name of the bin, which must contain a Map value.

keys Array.<any>

An array of map keys.

returnType number <optional>

The return type indicating what data of the affected item(s) to return (if any).

Source:
See:
Returns:

Operation that can be passed to the Client#operate command.

Type
Object

<static> removeByKeyRange(bin, begin, end [, returnType])

Removes one or more items identified by a range of keys from the map.

This operation returns the removed data specified by returnType.

Parameters:
Name Type Argument Description
bin string

The name of the bin, which must contain a Map value.

begin any <nullable>

Start key in the range (inclusive). If set to null, the range includes all keys less than the end key.

end any <nullable>

End key in the range (exclusive). If set to null, the range includes all keys greater than or equal to the begin key.

returnType number <optional>

The return type indicating what data of the affected item(s) to return (if any).

Source:
See:
Returns:

Operation that can be passed to the Client#operate command.

Type
Object

<static> removeByKeyRelIndexRange(bin, key, index [, count] [, returnType])

Removes map items nearest to key and greater, by index, from the map.

This operation returns the removed data specified by returnType.

Examples for map { a: 17, e: 2, f: 15, j: 10 }:

  • (value, index, count) = [removed items]
  • ('f', 0, 1) = { f: 15 }
  • ('f', 1, 2) = { j: 10 }
  • ('f', -1, 1) = { e: 2 }
  • ('b', 2, 1) = { j: 10 }
  • ('b', -2, 2) = { a: 17 }

Without count:

  • (value, index) = [removed items]
  • ('f', 0) = { f: 15, j: 10 }
  • ('f', 1) = { j: 10 }
  • ('f', -1) = { e: 2, f: 15, j: 10 }
  • ('b', 2) = { j: 10 }
  • ('b', -2) = { a: 17, e: 2, f: 15, j: 10 }

Requires Aerospike Server v4.3.0 or later.

Parameters:
Name Type Argument Description
bin string

The name of the bin, which must contain a Map value.

key any

Find map items nearest to this key and greater.

index number

Index of items to be removed relative to the given key.

count number <optional>

Number of items to remove. If undefined, the range includes all items nearest to key and greater, until the end.

returnType number <optional>

The return type indicating what data of the affected item(s) to return (if any).

Since:
  • v3.5.0
Source:
See:
Returns:

Operation that can be passed to the Client#operate command.

Type
Object
Example
const Aerospike = require('aerospike')
const maps = Aerospike.maps
const key = new Aerospike.Key('test', 'demo', 'mapKey')

Aerospike.connect()
  .then(async client => {
    await client.put(key, { map: { a: 17, e: 2, f: 15, j: 10 } })
    let result = await client.operate(key, [
      maps.removeByKeyRelIndexRange('map', 'f', -1, 1)
        .andReturn(maps.returnType.KEY_VALUE)])
    console.info(result.bins.map) // => [ 'e', 2 ]
    let record = await client.get(key)
    console.info(record.bins.map) // => { a: 17, f: 15, j: 10 }
    client.close()
  })

<static> removeByRank(bin, rank [, returnType])

Removes a single item identified by its rank value from the map.

This operation returns the removed data specified by returnType.

Parameters:
Name Type Argument Description
bin string

The name of the bin, which must contain a Map value.

rank number

Rank of the item to remove.

returnType number <optional>

The return type indicating what data of the affected item(s) to return (if any).

Source:
See:
Returns:

Operation that can be passed to the Client#operate command.

Type
Object

<static> removeByRankRange(bin, index [, count] [, returnType])

Removes one or more items in the specified rank range from the map.

This operation returns the removed data specified by returnType.

Parameters:
Name Type Argument Description
bin string

The name of the bin, which must contain a Map value.

index number

Starting rank.

count number <optional>

Number of items to delete. If undefined, the range includes all items starting from rank.

returnType number <optional>

The return type indicating what data of the affected item(s) to return (if any).

Source:
See:
Returns:

Operation that can be passed to the Client#operate command.

Type
Object

<static> removeByValue(bin, value [, returnType])

Removes one or more items identified by a single value from the map.

This operation returns the removed data specified by returnType.

Parameters:
Name Type Argument Description
bin string

The name of the bin, which must contain a Map value.

value any

The map value.

returnType number <optional>

The return type indicating what data of the affected item(s) to return (if any).

Source:
See:
Returns:

Operation that can be passed to the Client#operate command.

Type
Object

<static> removeByValueList(bin, values [, returnType])

Removes one or more items identified by a list of values from the map.

This operation returns the removed data specified by returnType.

Parameters:
Name Type Argument Description
bin string

The name of the bin, which must contain a Map value.

values Array.<any>

An array of map values.

returnType number <optional>

The return type indicating what data of the affected item(s) to return (if any).

Source:
See:
Returns:

Operation that can be passed to the Client#operate command.

Type
Object

<static> removeByValueRange(bin, begin, end [, returnType])

Removes one or more items identified by a range of values from the map.

This operation returns the removed data specified by returnType.

Parameters:
Name Type Argument Description
bin string

The name of the bin, which must contain a Map value.

begin any <nullable>

Start values in the range (inclusive). If set to null, the range includes all values less than the end value.

end any <nullable>

End value in the range (exclusive). If set to null, the range includes all values greater than or equal to the begin value.

returnType number <optional>

The return type indicating what data of the affected item(s) to return (if any).

Source:
See:
Returns:

Operation that can be passed to the Client#operate command.

Type
Object

<static> removeByValueRelRankRange(bin, value, rank [, count] [, returnType])

Removes map items nearest to value and greater, by relative rank.

This operation returns the removed data specified by returnType.

Examples for map { e: 2, j: 10, f: 15, a: 17 }:

  • (value, rank, count) = [removed items]
  • (11, 1, 1) = { a: 17 }
  • (11, -1, 1) = { j: 10 }

Without count:

  • (value, rank) = [removed items]
  • (11, 1) = { a: 17 }
  • (11, -1) = { j: 10, f: 15, a: 17 }
Parameters:
Name Type Argument Description
bin string

The name of the bin, which must contain a Map value.

value any

Find map items nearest to this value and greater.

rank number

Rank of items to be removed relative to the given value.

count number <optional>

Number of items to remove. If undefined, the range includes all items nearest to value and greater, until the end.

returnType number <optional>

The return type indicating what data of the affected item(s) to return (if any).

Since:
  • v3.5.0
Source:
See:
Returns:

Operation that can be passed to the Client#operate command.

Type
Object
Example
const Aerospike = require('aerospike')
const maps = Aerospike.maps
const key = new Aerospike.Key('test', 'demo', 'mapKey')

Aerospike.connect()
  .then(async client => {
    await client.put(key, { map: { e: 2, j: 10, f: 15, a: 17 } })
    let result = await client.operate(key, [
      maps.removeByValueRelRankRange('map', 11, -1)
        .andReturn(maps.returnType.KEY_VALUE)])
    console.info(result.bins.map) // => [ 'j', 10, 'f', 15, 'a', 17 ]
    let record = await client.get(key)
    console.info(record.bins.map) // => { e: 2 }
    client.close()
  })

<static> setPolicy(bin, policy)

Sets map policy attributes.

This operation does not return any result.

Parameters:
Name Type Description
bin string

The name of the bin. The bin must contain a Map value.

policy MapPolicy

The map policy.

Source:
Returns:

Operation that can be passed to the Client#operate command.

Type
Object

<static> size(bin)

Returns the size of the map.

Parameters:
Name Type Description
bin string

The name of the bin, which must contain a Map value.

Source:
Returns:

Operation that can be passed to the Client#operate command.

Type
Object