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 indices 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.
EXISTS number

Return true if count > 0.
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.operations
const lists = Aerospike.lists
const key = new Aerospike.Key('test', 'demo', 'mykey1')
// 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}),
    operate : new Aerospike.OperatePolicy({socketTimeout : 0, totalTimeout : 0})
  }
}
var ops = [
  lists.append('tags', 'orange'),
  op.read('tags')
]

Aerospike.client(config).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.bins.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.operations
const lists = Aerospike.lists
const key = new Aerospike.Key('test', 'demo', 'mykey1')
// 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}),
    operate : new Aerospike.OperatePolicy({socketTimeout : 0, totalTimeout : 0})
  }
}
var ops = [
  lists.appendItems('tags', ['orange', 'green']),
  op.read('tags')
]

Aerospike.client(config).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.bins.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')
// 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: {
    read : new Aerospike.ReadPolicy({socketTimeout : 0, totalTimeout : 0}),
    write : new Aerospike.WritePolicy({socketTimeout : 0, totalTimeout : 0}),
    operate : new Aerospike.OperatePolicy({socketTimeout : 0, totalTimeout : 0})
  }
}
var ops = [
  lists.clear('tags')
]

Aerospike.client(config).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.bins.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')
// 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}),
    operate : new Aerospike.OperatePolicy({socketTimeout : 0, totalTimeout : 0})
  }
}
var ops = [
  lists.get('tags', 0)
]

Aerospike.client(config).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.bins) // => { tags: 'blue' }
      client.close()

    })
  })
})

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

Retrieves a single list element from the list using a specified index.

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')
// 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}),
    operate : new Aerospike.OperatePolicy({socketTimeout : 0, totalTimeout : 0})
  }
}
Aerospike.connect(config).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.log('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')
// 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}),
    operate : new Aerospike.OperatePolicy({socketTimeout : 0, totalTimeout : 0})
  }
}
Aerospike.connect(config).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.log(result.bins.list) // => [ 4, 5 ]
  client.close()
})

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

Returns the list element in 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')
// 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}),
    operate : new Aerospike.OperatePolicy({socketTimeout : 0, totalTimeout : 0})
  }
}
var ops = [
  lists.getRange('tags', 1)
]

Aerospike.client(config).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.bins.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)
]

// 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: {
    read : new Aerospike.ReadPolicy({socketTimeout : 0, totalTimeout : 0}),
    write : new Aerospike.WritePolicy({socketTimeout : 0, totalTimeout : 0}),
    operate : new Aerospike.OperatePolicy({socketTimeout : 0, totalTimeout : 0})
  }
}

Aerospike.client(config).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['bins']['counters']) // => 5
      client.get(key, (error, record) => {
        if (error) throw error
        console.log(record['bins']['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.operations
const lists = Aerospike.lists
const key = new Aerospike.Key('test', 'demo', 'mykey1')
// 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}),
    operate : new Aerospike.OperatePolicy({socketTimeout : 0, totalTimeout : 0})
  }
}

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

Aerospike.client(config).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.bins.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.operations
const lists = Aerospike.lists
const key = new Aerospike.Key('test', 'demo', 'mykey1')
// 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}),
    operate : new Aerospike.OperatePolicy({socketTimeout : 0, totalTimeout : 0})
  }
}
var ops = [
  lists.insertItems('tags', 2, ['orange', 'green']),
  op.read('tags')
]

Aerospike.client(config).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.bins.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.operations
const lists = Aerospike.lists
const key = new Aerospike.Key('test', 'demo', 'mykey1')
// 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: {
    read : new Aerospike.ReadPolicy({socketTimeout : 0, totalTimeout : 0}),
    write : new Aerospike.WritePolicy({socketTimeout : 0, totalTimeout : 0}),
    operate : new Aerospike.OperatePolicy({socketTimeout : 0, totalTimeout : 0})
  }
}
var ops = [
  lists.pop('tags', 1)
]

Aerospike.client(config).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.bins.tags) // => yellow
      client.get(key, (error, record) => {
        if (error) throw error
        console.log(record.bins.tags) // => { [ 'blue', 'pink' ] }
        client.close()
      })
    })
  })
})

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

Removes and returns the list elements in 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')
// 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: {
    read : new Aerospike.ReadPolicy({socketTimeout : 0, totalTimeout : 0}),
    write : new Aerospike.WritePolicy({socketTimeout : 0, totalTimeout : 0}),
    operate : new Aerospike.OperatePolicy({socketTimeout : 0, totalTimeout : 0})
  }
}
var ops = [
  lists.popRange('tags', 0, 2)
]

Aerospike.client(config).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.bins.tags) // => [ 'blue', 'yellow' ]
      client.get(key, (error, record) => {
        if (error) throw error
        console.log(record.bins.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')
// 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: {
    read : new Aerospike.ReadPolicy({socketTimeout : 0, totalTimeout : 0}),
    write : new Aerospike.WritePolicy({socketTimeout : 0, totalTimeout : 0}),
    operate : new Aerospike.OperatePolicy({socketTimeout : 0, totalTimeout : 0})
  }
}
var ops = [
  lists.remove('tags', 1)
]

Aerospike.client(config).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.bins.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')
// 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}),
    operate : new Aerospike.OperatePolicy({socketTimeout : 0, totalTimeout : 0})
  }
}
Aerospike.connect(config).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.log('Result:', result.bins.tags) // => Result: yellow
  const record = await client.get(key)
  console.log('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')
// 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: {
    read : new Aerospike.ReadPolicy({socketTimeout : 0, totalTimeout : 0}),
    write : new Aerospike.WritePolicy({socketTimeout : 0, totalTimeout : 0}),
    operate : new Aerospike.OperatePolicy({socketTimeout : 0, totalTimeout : 0})
  }
}
Aerospike.connect(config).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.log(result.bins.list) // => [ 11, 15 ]
  let record = await client.get(key)
  console.log(record.bins.list) // => [ 0, 4, 5, 9 ]
  client.close()
})

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

Removes the list elements in 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')
// 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: {
    read : new Aerospike.ReadPolicy({socketTimeout : 0, totalTimeout : 0}),
    write : new Aerospike.WritePolicy({socketTimeout : 0, totalTimeout : 0}),
    operate : new Aerospike.OperatePolicy({socketTimeout : 0, totalTimeout : 0})
  }
}
var ops = [
  lists.removeRange('tags', 0, 2)
]

Aerospike.client(config).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.bins.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

<static> setOrder(bin, order)

Sets the list order to ORDERED or UNORDERED

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')
// 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}),
    operate : new Aerospike.OperatePolicy({socketTimeout : 0, totalTimeout : 0})
  }
}
var ops = [
  lists.size('tags')
]

Aerospike.client(config).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.bins.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 that are 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')
// 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: {
    read : new Aerospike.ReadPolicy({socketTimeout : 0, totalTimeout : 0}),
    write : new Aerospike.WritePolicy({socketTimeout : 0, totalTimeout : 0}),
    operate : new Aerospike.OperatePolicy({socketTimeout : 0, totalTimeout : 0})
  }
}
var ops = [
  lists.trim('tags', 1, 1)
]

Aerospike.client(config).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.bins.tags) // => { ['yellow'] }
        client.close()
      })
    })
  })
})