---
title: "List operations"
description: "Append to, trim, and read ranges of a list bin on the server with the Aerospike Python client's list_operations helpers."
---

# List operations

> For the complete documentation index see: [llms.txt](https://aerospike.com/docs/llms.txt)
> 
> All documentation pages available in markdown.

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()`](https://aerospike.com/docs/develop/client/python/usage/atomic/multi), which runs the operations on one record atomically in a single round trip.

For the list data type itself, see [Collections](https://aerospike.com/docs/develop/data-types/collections).

## Setup

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

```python
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.

```python
# 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.

```python
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.

```python
# 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`.

```python
# 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.

```python
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

```python
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()
```