Skip to main content
Version: main

List & Map CDT Operations

Atomic server-side collection data type (CDT) operations via client.operate().

from aerospike_py import list_operations as list_ops
from aerospike_py import map_operations as map_ops
import aerospike_py as aerospike

List CDT Operations​

Each list_ops.* function returns an operation dict that you pass to client.operate() or client.operate_ordered():

ops = [
    list_ops.list_append("scores", 100),
    list_ops.list_size("scores"),
]
_, _, bins = client.operate(key, ops)

Basic Write Operations​

list_append(bin, val, policy=None) — Append a value to the end of a list.

ops = [list_ops.list_append("colors", "red")]
client.operate(key, ops)

Basic Read Operations​

list_get(bin, index)​

Get the item at a specific index.

ops = [list_ops.list_get("scores", 0)]
_, _, bins = client.operate(key, ops)
print(bins["scores"])  # first element

list_get_range(bin, index, count)​

Get count items starting at index.

ops = [list_ops.list_get_range("scores", 0, 3)]
_, _, bins = client.operate(key, ops)
print(bins["scores"])  # first 3 elements

list_size(bin)​

Return the number of items in a list.

ops = [list_ops.list_size("scores")]
_, _, bins = client.operate(key, ops)
print(bins["scores"])  # e.g., 5

Remove Operations​

list_remove(bin, index)​

Remove the item at the given index.

ops = [list_ops.list_remove("colors", 0)]
client.operate(key, ops)

list_remove_range(bin, index, count)​

Remove count items starting at index.

ops = [list_ops.list_remove_range("colors", 1, 2)]
client.operate(key, ops)

list_pop(bin, index)​

Remove and return the item at the given index.

ops = [list_ops.list_pop("colors", 0)]
_, _, bins = client.operate(key, ops)
print(bins["colors"])  # the removed item

list_pop_range(bin, index, count)​

Remove and return count items starting at index.

ops = [list_ops.list_pop_range("colors", 0, 2)]
_, _, bins = client.operate(key, ops)
print(bins["colors"])  # list of removed items

list_trim(bin, index, count)​

Remove items outside the specified range [index, index+count).

ops = [list_ops.list_trim("scores", 1, 3)]
client.operate(key, ops)

list_clear(bin)​

Remove all items from a list.

ops = [list_ops.list_clear("scores")]
client.operate(key, ops)

Sort & Order​

list_sort(bin, sort_flags=0)​

Sort the list in place.

ops = [list_ops.list_sort("scores")]
client.operate(key, ops)

# Drop duplicates while sorting
ops = [list_ops.list_sort("scores", aerospike.LIST_SORT_DROP_DUPLICATES)]
client.operate(key, ops)

list_set_order(bin, list_order=0)​

Set the list ordering type.

ops = [list_ops.list_set_order("scores", aerospike.LIST_ORDERED)]
client.operate(key, ops)

Advanced Read Operations (by Value/Index/Rank)​

These operations require a return_type parameter that controls what is returned.

list_get_by_value(bin, val, return_type)​

Get items matching the given value.

ops = [list_ops.list_get_by_value("tags", "urgent", aerospike.LIST_RETURN_INDEX)]
_, _, bins = client.operate(key, ops)

list_get_by_value_list(bin, values, return_type)​

Get items matching any of the given values.

ops = [list_ops.list_get_by_value_list(
    "tags", ["urgent", "important"], aerospike.LIST_RETURN_COUNT
)]
_, _, bins = client.operate(key, ops)

list_get_by_value_range(bin, begin, end, return_type)​

Get items with values in the range [begin, end).

ops = [list_ops.list_get_by_value_range(
    "scores", 80, 100, aerospike.LIST_RETURN_VALUE
)]
_, _, bins = client.operate(key, ops)

list_get_by_index(bin, index, return_type)​

Get item by index with specified return type.

ops = [list_ops.list_get_by_index("scores", 0, aerospike.LIST_RETURN_VALUE)]
_, _, bins = client.operate(key, ops)

list_get_by_index_range(bin, index, return_type, count=None)​

Get items by index range.

ops = [list_ops.list_get_by_index_range(
    "scores", 2, aerospike.LIST_RETURN_VALUE, count=3
)]
_, _, bins = client.operate(key, ops)

list_get_by_rank(bin, rank, return_type)​

Get item by rank (0 = smallest).

ops = [list_ops.list_get_by_rank("scores", 0, aerospike.LIST_RETURN_VALUE)]
_, _, bins = client.operate(key, ops)

list_get_by_rank_range(bin, rank, return_type, count=None)​

Get items by rank range.

ops = [list_ops.list_get_by_rank_range(
    "scores", -3, aerospike.LIST_RETURN_VALUE, count=3
)]
_, _, bins = client.operate(key, ops)

Advanced Remove Operations (by Value/Index/Rank)​

list_remove_by_value(bin, val, return_type)​

Remove items matching the given value.

ops = [list_ops.list_remove_by_value("tags", "temp", aerospike.LIST_RETURN_COUNT)]
_, _, bins = client.operate(key, ops)

list_remove_by_value_list(bin, values, return_type)​

Remove items matching any of the given values.

ops = [list_ops.list_remove_by_value_list(
    "tags", ["temp", "debug"], aerospike.LIST_RETURN_NONE
)]
client.operate(key, ops)

list_remove_by_value_range(bin, begin, end, return_type)​

Remove items with values in the range [begin, end).

ops = [list_ops.list_remove_by_value_range(
    "scores", 0, 50, aerospike.LIST_RETURN_COUNT
)]
_, _, bins = client.operate(key, ops)

list_remove_by_index(bin, index, return_type)​

Remove item by index.

ops = [list_ops.list_remove_by_index("scores", 0, aerospike.LIST_RETURN_VALUE)]
_, _, bins = client.operate(key, ops)

list_remove_by_index_range(bin, index, return_type, count=None)​

Remove items by index range.

ops = [list_ops.list_remove_by_index_range(
    "scores", 0, aerospike.LIST_RETURN_NONE, count=2
)]
client.operate(key, ops)

list_remove_by_rank(bin, rank, return_type)​

Remove item by rank.

ops = [list_ops.list_remove_by_rank("scores", 0, aerospike.LIST_RETURN_VALUE)]
_, _, bins = client.operate(key, ops)

list_remove_by_rank_range(bin, rank, return_type, count=None)​

Remove items by rank range.

ops = [list_ops.list_remove_by_rank_range(
    "scores", 0, aerospike.LIST_RETURN_NONE, count=2
)]
client.operate(key, ops)

List Constants​

ConstantDescription
LIST_RETURN_NONEReturn nothing
LIST_RETURN_INDEXReturn index(es)
LIST_RETURN_REVERSE_INDEXReturn reverse index(es)
LIST_RETURN_RANKReturn rank(s)
LIST_RETURN_REVERSE_RANKReturn reverse rank(s)
LIST_RETURN_COUNTReturn count of matched items
LIST_RETURN_VALUEReturn value(s)
LIST_RETURN_EXISTSReturn boolean existence
LIST_UNORDEREDUnordered list (default)
LIST_ORDEREDOrdered list (maintains sort order)
LIST_SORT_DEFAULTDefault sort
LIST_SORT_DROP_DUPLICATESDrop duplicates during sort

List Complete Example​

import aerospike_py as aerospike
from aerospike_py import list_operations as list_ops

with aerospike.client({
    "hosts": [("127.0.0.1", 3000)],
    "cluster_name": "docker",
}).connect() as client:

    key = ("test", "demo", "player1")

    # Initialize a scores list
    client.put(key, {"scores": [85, 92, 78, 95, 88]})

    # Atomic: sort, get top 3, and get size
    ops = [
        list_ops.list_sort("scores"),
        list_ops.list_get_by_rank_range(
            "scores", -3, aerospike.LIST_RETURN_VALUE, count=3
        ),
    ]
    _, _, bins = client.operate(key, ops)
    print(f"Top 3 scores: {bins['scores']}")

    # Remove scores below 80
    ops = [
        list_ops.list_remove_by_value_range(
            "scores", 0, 80, aerospike.LIST_RETURN_COUNT
        ),
    ]
    _, _, bins = client.operate(key, ops)
    print(f"Removed {bins['scores']} low scores")

    # Append a new score and get updated size
    ops = [
        list_ops.list_append("scores", 97),
        list_ops.list_size("scores"),
    ]
    _, _, bins = client.operate(key, ops)
    print(f"Total scores: {bins['scores']}")