Aerospike

Module: aerospike/lists

This module defines operations on the List data type. Create list operations used by the Client#operate command.

For more information, please refer to the ⇑Lists and ⇑List Operations documentation in the Aerospike Feature Guide.

List Index

List operations support negative indexing. If the index is negative, the resolved index starts backwards from end of list.

Index/Range examples:

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

If an index is out of bounds, a parameter error will be returned. If a range is partially out of bounds, the valid part of the range will be returned.

CDT Context - Operating on Nested Lists

To operate on nested lists, use the ListOperation#withContext function to set the context for a list operation.

Source:
See:

Classes

ListOperation

Members

<static> order :Object

List order.

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

Type:
  • Object
Properties:
Name Type Description
UNORDERED number

List is not ordered. This is the default.
ORDERED number

List is ordered.
Source:

<static> returnType :Object

List 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.
VALUE number

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

<static> sortFlags :Object

List sort flags.

Type:
  • Object
Properties:
Name Type Description
DEFAULT number

Preserve duplicate values when sorting lists. This is the default.
DROP_DUPLICATES number

Drop duplicate values when sorting list.
Source:

<static> writeFlags :Object

List write flags.

Type:
  • Object
Properties:
Name Type Description
DEFAULT number

Allow duplicate values and insertions at any index.
ADD_UNIQUE number

Only add unique values.
INSERT_BOUNDED number

Enforce list boundaries when inserting. Do not allow values to be inserted at index outside current list boundaries.
NO_FAIL number

Do not raise error, if a list item fails due to write flag constraints. Requires Aerospike server v4.3.0 or later.
PARTIAL number

Allow other valid list items to be committed, if a list item fails due to write flag constraints. Requires Aerospike server v4.3.0 or later.
Source:

Methods

<static> append(bin, value [, policy])

Appends an element to the end of a list.

This operation returns the element count of the list after the operation.

Parameters:
Name Type Argument Description
bin string

The name of the bin. The bin must contain a List value.
value any

The value to be appended.
policy ListPolicy <optional>

Optional list policy.
Source:
Returns:

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

Type
Object
Example
const Aerospike = require('aerospike')
const op = Aerospike.operator
const lists = Aerospike.lists
const key = new Aerospike.Key('test', 'demo', 'mykey1')

var ops = [
  lists.append('tags', 'orange'),
  op.read('tags')
]

Aerospike.client().connect((error, client) => {
  if (error) throw error
  client.put(key, { tags: ['blue', 'yellow', 'pink'] }, (error) => {
    if (error) throw error
    client.operate(key, ops, (error, result) => {
      if (error) throw error
      console.log(result.tags) // => [ 'blue', 'yellow', 'pink', 'orange' ]
      client.close()
    })
  })
})

<static> appendItems(bin, list [, policy])

Appends a list of elements to the end of a list.

This operation returns the element count of the list after the operation.

Parameters:
Name Type Argument Description
bin string

The name of the bin. The bin must contain a List value.
list Array.<any>

Array of elements to be appended.
policy ListPolicy <optional>

Optional list policy.
Source:
Returns:

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

Type
Object
Example
const Aerospike = require('aerospike')
const op = Aerospike.operator
const lists = Aerospike.lists
const key = new Aerospike.Key('test', 'demo', 'mykey1')

var ops = [
  lists.appendItems('tags', ['orange', 'green']),
  op.read('tags')
]

Aerospike.client().connect((error, client) => {
  if (error) throw error
  client.put(key, { tags: ['blue', 'yellow', 'pink'] }, (error) => {
    if (error) throw error
    client.operate(key, ops, (error, result) => {
      if (error) throw error
      console.log(result.tags) // => [ 'blue', 'yellow', 'pink', 'orange', 'green' ]
      client.close()
    })
  })
})

<static> clear(bin)

Removes all the elements from the list.

This operation returns no result.

Parameters:
Name Type Description
bin string

The name of the bin. The bin must contain a List value.
Source:
Returns:

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

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

var ops = [
  lists.clear('tags')
]

Aerospike.client().connect((error, client) => {
  if (error) throw error
  client.put(key, { tags: ['blue', 'yellow', 'pink'] }, (error) => {
    if (error) throw error
    client.operate(key, ops, (error) => {
      if (error) throw error
      client.get(key, (error, record) => {
        if (error) throw error
        console.log(record) // => { tags: [ ] }
        client.close()
      })
    })
  })
})

<static> get(bin, index)

Returns the list element at the specified index.

Parameters:
Name Type Description
bin string

The name of the bin. The bin must contain a List value.
index number

Index of the element to be returned.
Source:
Returns:

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

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

var ops = [
  lists.get('tags', 0)
]

Aerospike.client().connect((error, client) => {
  if (error) throw error
  client.put(key, { tags: ['blue', 'yellow', 'pink'] }, (error) => {
    if (error) throw error
    client.operate(key, ops, (error) => {
      if (error) throw error
      client.get(key, (error, record) => {
        if (error) throw error
        console.log(record) // => { tags: 'blue' }
        client.close()
      })
    })
  })
})

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

Retrieves a single list element identified by its index from the list.

This operation returns the data specified by returnType.

Parameters:
Name Type Argument Description
bin string

The name of the bin. The bin must contain a List value.
index number

Zero-based index of the item to retrieve.
returnType number <optional>

The return type indicating what data of the removed item(s) to return (if any).
Since:
  • v3.4.0
Source:
See:
Returns:

List operation that can be used with the Client#operate command.

Type
module:aerospike/lists~ListOperation
Example

Retrieve the 2nd item in the list and return its value

const Aerospike = require('aerospike')
const lists = Aerospike.lists
const key = new Aerospike.Key('test', 'demo', 'listsTest')

Aerospike.connect().then(async client => {
  await client.put(key, { tags: ['blue', 'yellow', 'pink'] })
  const ops = [
    lists.getByIndex('tags', 1)
      .andReturn(lists.returnType.VALUE)
  ]
  const result = await client.operate(key, ops)
  console.info('Result:', result.bins.tags) // => Result: yellow
  client.close()
})

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

Retrieves the list elements identified by the index range from the list.

This operation returns the data specified by returnType.

Parameters:
Name Type Argument Description
bin string

The name of the bin. The bin must contain a List value.
index number

Index of the first element in the range.
count number <optional>

Number of elements in the range; if not specified, the range extends to the end of the list.
returnType number <optional>

The return type indicating what data of the removed item(s) to return (if any).
Since:
  • v3.4.0
Source:
See:
Returns:

List operation that can be used with the Client#operate command.

Type
module:aerospike/lists~ListOperation

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

Retrieves a single item identified by its rank value from the list.

This operation returns the data specified by returnType.

Parameters:
Name Type Argument Description
bin string

The name of the bin. The bin must contain a List value.
rank number

Rank of the item to retrieve.
returnType number <optional>

The return type indicating what data of the removed item(s) to return (if any).
Since:
  • v3.4.0
Source:
See:
Returns:

List operation that can be used with the Client#operate command.

Type
module:aerospike/lists~ListOperation

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

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

This operation returns the data specified by returnType.

Parameters:
Name Type Argument Description
bin string

The name of the bin. The bin must contain a List value.
index number

Starting rank.
count number <optional>

Number of items to retrieve. If undefined, the range includes all items starting from rank.
returnType number <optional>

The return type indicating what data of the removed item(s) to return (if any).
Since:
  • v3.4.0
Source:
See:
Returns:

List operation that can be used with the Client#operate command.

Type
module:aerospike/lists~ListOperation

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

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

This operation returns the data specified by returnType.

Parameters:
Name Type Argument Description
bin string

The name of the bin. The bin must contain a List value.
value any

The list value to retrieve.
returnType number <optional>

The return type indicating what data of the removed item(s) to return (if any).
Since:
  • v3.4.0
Source:
See:
Returns:

List operation that can be used with the Client#operate command.

Type
module:aerospike/lists~ListOperation

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

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

This operation returns the data specified by returnType.

Parameters:
Name Type Argument Description
bin string

The name of the bin. The bin must contain a List value.
values Array.<any>

An array of list values to retrieve.
returnType number <optional>

The return type indicating what data of the removed item(s) to return (if any).
Since:
  • v3.4.0
Source:
See:
Returns:

List operation that can be used with the Client#operate command.

Type
module:aerospike/lists~ListOperation

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

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

This operation returns the data specified by returnType.

Parameters:
Name Type Argument Description
bin string

The name of the bin. The bin must contain a List 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 removed item(s) to return (if any).
Since:
  • v3.4.0
Source:
See:
Returns:

List operation that can be used with the Client#operate command.

Type
module:aerospike/lists~ListOperation

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

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

This operation returns the data specified by returnType.

Examples for ordered list [0, 4, 5, 9, 11, 15]:

  • (value, rank, count) = [selected items]
  • (5, 0, 2) = [5, 9]
  • (5, 1, 1) = [9]
  • (5, -1, 2) = [4, 5]
  • (3, 0, 1) = [4]
  • (3, 3, 7) = [11, 15]
  • (3, -3, 2) = []

Without count:

  • (value, rank) = [selected items]
  • (5, 0) = [5, 9, 11, 15]
  • (5, 1) = [9, 11, 15]
  • (5, -1) = [4, 5, 9, 11, 15]
  • (3, 0) = [4, 5, 9, 11, 15]
  • (3, 3) = [11, 15]
  • (3, -3) = [0, 4, 5, 9, 11, 15]

Requires Aerospike Server v4.3.0 or later.

Parameters:
Name Type Argument Description
bin string

The name of the bin. The bin must contain a List value.
value any

Find list items nearest to this value and greater.
rank number

Rank of the 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:

List operation that can be used with the Client#operate command.

Type
module:aerospike/lists~ListOperation
Example
const Aerospike = require('aerospike')
const lists = Aerospike.lists
const key = new Aerospike.Key('test', 'demo', 'listKey')

Aerospike.connect().then(async client => {
  await client.put(key, { list: [0, 4, 5, 9, 11, 15] })
  await client.operate(key, [ lists.setOrder('list', lists.order.ORDERED) ])
  let result = await client.operate(key, [
    lists.getByValueRelRankRange('list', 5, -1, 2)
      .andReturn(lists.returnType.VALUE)])
  console.info(result.bins.list) // => [ 4, 5 ]
  client.close()
})

<static> getRange(bin, index [, count])

Returns the list element at the specified range.

Parameters:
Name Type Argument Description
bin string

The name of the bin. The bin must contain a List value.
index number

Index of the first element in the range.
count number <optional>

Number of elements in the range; if not specified, the range extends to the end of the list.
Source:
Returns:

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

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

var ops = [
  lists.getRange('tags', 1)
]

Aerospike.client().connect((error, client) => {
  if (error) throw error
  client.put(key, { tags: ['blue', 'yellow', 'pink'] }, (error) => {
    if (error) throw error
    client.operate(key, ops, (error) => {
      if (error) throw error
      client.get(key, (error, record) => {
        if (error) throw error
        console.log(record) // => { tags: [ 'yellow', 'pink' ] }
        client.close()
      })
    })
  })
})

<static> increment(bin, index [, value] [, policy])

Increments the value at the given list index and returns the new value after increment.

Parameters:
Name Type Argument Default Description
bin string

The name of the bin. The bin must contain a List value.
index number

Index of the list element to increment.
value number <optional>
 1

Value to increment the element by.
policy ListPolicy <optional>

Optional list policy.
Since:
  • v2.4
Source:
Returns:

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

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

var ops = [
  lists.increment('counters', 1, 3)
]

Aerospike.client().connect((error, client) => {
  if (error) throw error
  client.put(key, { counters: [1, 2, 3] }, (error) => {
    if (error) throw error
    client.operate(key, ops, (error, result) => {
      if (error) throw error
      console.log(result['counters']) => 5
      client.get(key, (error, record) => {
        if (error) throw error
        console.log(record) // => { counters: [1, 5, 3] }
        client.close()
      })
    })
  })
})

<static> insert(bin, index, value [, policy])

Inserts an element at the specified index.

This operation returns the element count of the list after the operation.

Parameters:
Name Type Argument Description
bin string

The name of the bin. The bin must contain a List value.
index number

List index at which the new element should be inserted.
value any

The value to be appended.
policy ListPolicy <optional>

Optional list policy.
Source:
Returns:

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

Type
Object
Example
const Aerospike = require('aerospike')
const op = Aerospike.operator
const lists = Aerospike.lists
const key = new Aerospike.Key('test', 'demo', 'mykey1')

var ops = [
  lists.insert('tags', 2, 'orange'),
  op.read('tags')
]

Aerospike.client().connect((error, client) => {
  if (error) throw error
  client.put(key, { tags: ['blue', 'yellow', 'pink'] }, (error) => {
    if (error) throw error
    client.operate(key, ops, (error, result) => {
      if (error) throw error
      console.log(result.tags) // => [ 'blue', 'yellow', 'orange', 'pink' ]
      client.close()
    })
  })
})

<static> insertItems(bin, index, list)

Inserts a list of elements at the specified index.

This operation returns the element count of the list after the operation.

Parameters:
Name Type Description
bin string

The name of the bin. The bin must contain a List value.
index number

List index at which the new elements should be inserted.
list Array.<any>

Array of elements to be inserted.
Source:
Returns:

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

Type
Object
Example
const Aerospike = require('aerospike')
const op = Aerospike.operator
const lists = Aerospike.lists
const key = new Aerospike.Key('test', 'demo', 'mykey1')

var ops = [
  lists.insertItems('tags', 2, ['orange', 'green']),
  op.read('tags')
]

Aerospike.client().connect((error, client) => {
  if (error) throw error
  client.put(key, { tags: ['blue', 'yellow', 'pink'] }, (error) => {
    if (error) throw error
    client.operate(key, ops, (error, result) => {
      if (error) throw error
      console.log(result.tags) // => [ 'blue', 'yellow', 'orange', 'green', 'pink' ]
      client.close()
    })
  })
})

<static> pop(bin, index)

Removes and returns the list element at the specified index.

Parameters:
Name Type Description
bin string

The name of the bin. The bin must contain a List value.
index number

List index of the element to be removed.
Source:
Returns:

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

Type
Object
Example
const Aerospike = require('aerospike')
const op = Aerospike.operator
const key = new Aerospike.Key('test', 'demo', 'mykey1')

var ops = [
  lists.pop('tags', 1)
]

Aerospike.client().connect((error, client) => {
  if (error) throw error
  client.put(key, { tags: ['blue', 'yellow', 'pink'] }, (error) => {
    if (error) throw error
    client.operate(key, ops, (error, result) => {
      if (error) throw error
      console.log(result.tags) // => [ 'yellow' ]
      client.get(key, (error, record) => {
        if (error) throw error
        console.log(record) // => { tags: [ 'blue', 'pink' ] }
        client.close()
      })
    })
  })
})

<static> popRange(bin, index [, count])

Removes and returns the list elements at the specified range.

Parameters:
Name Type Argument Description
bin string

The name of the bin. The bin must contain a List value.
index number

Index of the first element in the range.
count number <optional>

Number of elements in the range; if not specified, the range extends to the end of the list.
Source:
Returns:

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

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

var ops = [
  lists.popRange('tags', 0, 2)
]

Aerospike.client().connect((error, client) => {
  if (error) throw error
  client.put(key, { tags: ['blue', 'yellow', 'pink'] }, (error) => {
    if (error) throw error
    client.operate(key, ops, (error, result) => {
      if (error) throw error
      console.log(result.tags) // => [ 'blue', 'yellow' ]
      client.get(key, (error, record) => {
        if (error) throw error
        console.log(record) // => { tags: [ 'pink' ] }
        client.close()
      })
    })
  })
})

<static> remove(bin, index)

Removes the list element at the specified index.

This operation returns the number of elements removed from the list.

Parameters:
Name Type Description
bin string

The name of the bin. The bin must contain a List value.
index number

Index of the element to be removed
Source:
Returns:

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

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

var ops = [
  lists.remove('tags', 1)
]

Aerospike.client().connect((error, client) => {
  if (error) throw error
  client.put(key, { tags: ['blue', 'yellow', 'pink'] }, (error) => {
    if (error) throw error
    client.operate(key, ops, (error) => {
      if (error) throw error
      client.get(key, (error, record) => {
        if (error) throw error
        console.log(record) // => { tags: [ 'blue', 'pink' ] }
        client.close()
      })
    })
  })
})

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

Removes a single list element identified by its index from the list.

This operation returns the data specified by returnType.

Parameters:
Name Type Argument Description
bin string

The name of the bin. The bin must contain a List value.
index number

Zero-based index of the item to remove.
returnType number <optional>

The return type indicating what data of the removed item(s) to return (if any).
Since:
  • v3.4.0
Source:
See:
Returns:

List operation that can be used with the Client#operate command.

Type
module:aerospike/lists~ListOperation
Example

Remove the 2nd item in the list and return its value

const Aerospike = require('aerospike')
const lists = Aerospike.lists
const key = new Aerospike.Key('test', 'demo', 'listsTest')

Aerospike.connect().then(async client => {
  await client.put(key, { tags: ['blue', 'yellow', 'pink'] })
  const ops = [
    lists.removeByIndex('tags', 1)
      .andReturn(lists.returnType.VALUE)
  ]
  const result = await client.operate(key, ops)
  console.info('Result:', result.bins.tags) // => Result: yellow
  const record = await client.get(key)
  console.info('Record:', record.bins.tags) // => Record: [ 'blue', 'pink' ]
  client.close()
})

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

Removes the list elements identified by the index range from the list.

This operation returns the data specified by returnType.

Parameters:
Name Type Argument Description
bin string

The name of the bin. The bin must contain a List value.
index number

Index of the first element in the range.
count number <optional>

Number of elements in the range; if not specified, the range extends to the end of the list.
returnType number <optional>

The return type indicating what data of the removed item(s) to return (if any).
Since:
  • v3.4.0
Source:
See:
Returns:

List operation that can be used with the Client#operate command.

Type
module:aerospike/lists~ListOperation

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

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

This operation returns the data specified by returnType.

Parameters:
Name Type Argument Description
bin string

The name of the bin. The bin must contain a List value.
rank number

Rank of the item to remove.
returnType number <optional>

The return type indicating what data of the removed item(s) to return (if any).
Since:
  • v3.4.0
Source:
See:
Returns:

List operation that can be used with the Client#operate command.

Type
module:aerospike/lists~ListOperation

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

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

This operation returns the data specified by returnType.

Parameters:
Name Type Argument Description
bin string

The name of the bin. The bin must contain a List value.
index number

Starting rank.
count number <optional>

Number of items to remove; if undefined, the range includes all items starting from rank.
returnType number <optional>

The return type indicating what data of the removed item(s) to return (if any).
Since:
  • v3.4.0
Source:
See:
Returns:

List operation that can be used with the Client#operate command.

Type
module:aerospike/lists~ListOperation

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

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

This operation returns the data specified by returnType.

Parameters:
Name Type Argument Description
bin string

The name of the bin. The bin must contain a List value.
value any

The list value to remove.
returnType number <optional>

The return type indicating what data of the removed item(s) to return (if any).
Since:
  • v3.4.0
Source:
See:
Returns:

List operation that can be used with the Client#operate command.

Type
module:aerospike/lists~ListOperation

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

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

This operation returns the data specified by returnType.

Parameters:
Name Type Argument Description
bin string

The name of the bin. The bin must contain a List value.
values Array.<any>

An array of list values to remove.
returnType number <optional>

The return type indicating what data of the removed item(s) to return (if any).
Since:
  • v3.4.0
Source:
See:
Returns:

List operation that can be used with the Client#operate command.

Type
module:aerospike/lists~ListOperation

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

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

This operation returns the data specified by returnType.

Parameters:
Name Type Argument Description
bin string

The name of the bin. The bin must contain a List 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 removed item(s) to return (if any).
Since:
  • v3.4.0
Source:
See:
Returns:

List operation that can be used with the Client#operate command.

Type
module:aerospike/lists~ListOperation

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

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

This operation returns the data specified by returnType.

Examples for ordered list [0, 4, 5, 9, 11, 15]:

  • (value, rank, count) = [removed items]
  • (5, 0, 2) = [5, 9]
  • (5, 1, 1) = [9]
  • (5, -1, 2) = [4, 5]
  • (3, 0, 1) = [4]
  • (3, 3, 7) = [11, 15]
  • (3, -3, 2) = []

Without count:

  • (value, rank) = [removed items]
  • (5, 0) = [5, 9, 11, 15]
  • (5, 1) = [9, 11, 15]
  • (5, -1) = [4, 5, 9, 11, 15]
  • (3, 0) = [4, 5, 9, 11, 15]
  • (3, 3) = [11, 15]
  • (3, -3) = [0, 4, 5, 9, 11, 15]

Requires Aerospike Server v4.3.0 or later.

Parameters:
Name Type Argument Description
bin string

The name of the bin. The bin must contain a List value.
value any

Find list items nearest to this value and greater.
rank number

Rank of the 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 removed item(s) to return (if any).
Since:
  • v3.5.0
Source:
See:
Returns:

List operation that can be used with the Client#operate command.

Type
module:aerospike/lists~ListOperation
Example
const Aerospike = require('aerospike')
const lists = Aerospike.lists
const key = new Aerospike.Key('test', 'demo', 'listKey')

Aerospike.connect().then(async client => {
  await client.put(key, { list: [0, 4, 5, 9, 11, 15] })
  let result = await client.operate(key, [
    lists.removeByValueRelRankRange('list', 3, 3)
      .andReturn(lists.returnType.VALUE)])
  console.info(result.bins.list) // => [ 11, 15 ]
  let record = await client.get(key)
  console.info(record.bins.list) // => [ 0, 4, 5, 9 ]
  client.close()
})

<static> removeRange(bin, index [, count])

Removes the list elements at the specified range.

This operation returns the number of elements removed from the list.

Parameters:
Name Type Argument Description
bin string

The name of the bin. The bin must contain a List value.
index number

Index of the first element in the range.
count number <optional>

Number of elements in the range; if not specified, the range extends to the end of the list.
Source:
Returns:

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

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

var ops = [
  lists.removeRange('tags', 0, 2)
]

Aerospike.client().connect((error, client) => {
  if (error) throw error
  client.put(key, { tags: ['blue', 'yellow', 'pink'] }, (error) => {
    if (error) throw error
    client.operate(key, ops, (error) => {
      if (error) throw error
      client.get(key, (error, record) => {
        if (error) throw error
        console.log(record) // => { tags: [ 'pink' ] }
        client.close()
      })
    })
  })
})

<static> set(bin, index, value [, policy])

Sets the list element at the specified index to a new value.

This operation returns no result.

Parameters:
Name Type Argument Description
bin string

The name of the bin. The bin must contain a List value.
index number

Index of the element to be replaced.
value any

The new value to assigned to the list element.
policy ListPolicy <optional>

Optional list policy.
Source:
Returns:

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

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

var ops = [
  lists.set('tags', 1, 'green')
]

Aerospike.client().connect((error, client) => {
  if (error) throw error
  client.put(key, { tags: ['blue', 'yellow', 'pink'] }, (error) => {
    if (error) throw error
    client.operate(key, ops, (error) => {
      if (error) throw error
      client.get(key, (error, record) => {
        if (error) throw error
        console.log(record) // => { tags: [ 'blue', 'green', 'pink' ] }
        client.close()
      })
    })
  })
})

<static> setOrder(bin, order)

Sets the list order.

This operation does not return any result.

Parameters:
Name Type Description
bin string

The name of the bin. The bin must contain a List value.
order number

The new list order.
Since:
  • v3.4.0
Source:
Returns:

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

Type
Object

<static> size(bin)

Returns the element count of the list

Parameters:
Name Type Description
bin string

The name of the bin. The bin must contain a List value.
Source:
Returns:

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

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

var ops = [
  lists.size('tags')
]

Aerospike.client().connect((error, client) => {
  if (error) throw error
  client.put(key, { tags: ['blue', 'yellow', 'pink'] }, (error) => {
    if (error) throw error
    client.operate(key, ops, (error) => {
      if (error) throw error
      console.log(record) // => { tags: 3 }
      client.close()
    })
  })
})

<static> sort(bin, flags)

Sort the list according to flags.

This operation does not return any result.

Parameters:
Name Type Description
bin string

The name of the bin. The bin must contain a List value.
flags number

The sort flags to use.
Since:
  • v3.4.0
Source:
Returns:

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

Type
Object

<static> trim(bin, index, count)

Removes all list elements not within the specified range.

This operation returns the number of list elements removed.

Parameters:
Name Type Description
bin string

The name of the bin. The bin must contain a List value.
index number

Index of the first element in the range.
count number

Number of elements in the range.
Source:
Returns:

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

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

var ops = [
  lists.trim('tags', 1, 1)
]

Aerospike.client().connect((error, client) => {
  if (error) throw error
  client.put(key, { tags: ['blue', 'yellow', 'pink'] }, (error) => {
    if (error) throw error
    client.operate(key, ops, (error) => {
      if (error) throw error
      client.get(key, (error, record) => {
        if (error) throw error
        console.log(record) // => { tags: [ 'yellow' ] }
        client.close()
      })
    })
  })
})