List operations

A list bin holds an ordered sequence of values. Instead of reading a list, changing it in your application, and writing it back, use the list_operations helpers to change or read it on the server. Each helper builds an operation that you pass to client.operate(), which runs the operations on one record atomically in a single round trip.

For the list data type itself, see Collections.

Setup

The following examples use the setup and record below to illustrate list operations in an Aerospike database.

import aerospike
from aerospike_helpers.operations import list_operations

# Define host configuration
config = {
    'hosts': [ ('127.0.0.1', 3000) ]
}
# Establishes a connection to the server
client = aerospike.client(config).connect()

# Creates a key with the namespace "sandbox", set "activity", and user key "user-1"
key = ('sandbox', 'activity', 'user-1')

# Write a record with an empty list in the "events" bin
client.put(key, {'events': []})

Results

operate() returns the tuple (key, meta, bins). The bins dictionary has one entry for each bin that an operation read or returned a value from. When one operate() call contains several operations on the same bin, the entry holds only the result of the last of them. To get the result of every operation, use client.operate_ordered(). It returns results in operation order. Or run the earlier operation in a separate operate() call.

Append elements

list_append_items() appends each value in a Python list to the list bin as its own element. It returns the new list size.

# Append three elements
ops = [
    list_operations.list_append_items('events', ['login', 'view', 'logout'])
]
(key_, meta, bins) = client.operate(key, ops)

# The result is the new size of the list
print(bins['events'])  # 3

list_append() appends a single value. If that value is itself a list, the whole list is added as one nested element. Use list_append_items() to add the values as separate elements.

Get the size of a list

list_size() returns the number of elements in the list.

ops = [list_operations.list_size('events')]
(key_, meta, bins) = client.operate(key, ops)

print(bins['events'])  # 3

Keep the last N elements

To cap a list at its most recent elements, append the new element and trim the list in the same operate() call. list_trim(bin_name, index, count) keeps the count elements that start at index and removes all others. A negative index counts from the end of the list, so -5 is the fifth element from the end. The operation returns the number of elements it removed.

The following example appends 9 to a list that holds eight elements, and keeps only the last five.

# Write a list of eight elements
client.put(key, {'events': [1, 2, 3, 4, 5, 6, 7, 8]})

# Append 9, then keep only the last five elements
ops = [
    list_operations.list_append('events', 9),
    list_operations.list_trim('events', -5, 5)
]
client.operate(key, ops)

# Read the list
(key_, meta, bins) = client.get(key)
print(bins['events'])  # [5, 6, 7, 8, 9]

Read the last N elements

To return only part of a list, use a range operation so that the server returns only those elements. list_get_range(bin_name, index, count) returns count elements that start at index.

# Write a list of six elements
client.put(key, {'events': ['a', 'b', 'c', 'd', 'e', 'f']})

# Get the last three elements
ops = [list_operations.list_get_range('events', -3, 3)]
(key_, meta, bins) = client.operate(key, ops)

print(bins['events'])  # ['d', 'e', 'f']

# Close the connection to the server
client.close()

list_get_by_index_range(bin_name, index, return_type, count) reads the same range and lets you choose what to return. For example, aerospike.LIST_RETURN_VALUE returns the values, and aerospike.LIST_RETURN_COUNT returns how many elements are in the range.

ops = [
    list_operations.list_get_by_index_range('events', -3, aerospike.LIST_RETURN_VALUE, 3)
]

Code block

Expand this section for a single code block to append to a list, keep its last five elements, and read its last three

import aerospike
from aerospike_helpers.operations import list_operations

# Define host configuration
config = {
    'hosts': [ ('127.0.0.1', 3000) ]
}
# Establishes a connection to the server
client = aerospike.client(config).connect()

# Creates a key with the namespace "sandbox", set "activity", and user key "user-1"
key = ('sandbox', 'activity', 'user-1')

# Write a record with a list of eight elements
client.put(key, {'events': [1, 2, 3, 4, 5, 6, 7, 8]})

# Append 9, then keep only the last five elements
ops = [
    list_operations.list_append('events', 9),
    list_operations.list_trim('events', -5, 5)
]
client.operate(key, ops)

# Get the last three elements
ops = [list_operations.list_get_range('events', -3, 3)]
(key_, meta, bins) = client.operate(key, ops)

print(bins['events'])  # [7, 8, 9]

# Close the connection to the server
client.close()