---
title: "List operations"
description: "Guide to the C# client's ListOperation builders for server-side list CDT operations with AerospikeClient.Operate()."
---

# List operations

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

Aerospike’s list [collection data type](https://aerospike.com/docs/develop/data-types/collections) (CDT) operations let the server add, read, and remove individual list elements in a single round trip, while the client reads only the operation results. A _list bin_ stores an ordered collection of values.

`AerospikeClient.Put` always replaces the full bin value. To change a list bin that already exists, use the `ListOperation` builders with [`AerospikeClient.Operate()`](https://aerospike.com/docs/develop/client/csharp/usage/atomic/multi). Each builder returns an `Operation`, and the server runs the operations in the order you pass them.

## Setup

```csharp
using Aerospike.Client;

using System.Collections;

using System.Collections.Generic;

// Define host configuration

Host config = new Host("127.0.0.1", 3000);

// Establishes a connection to the server

AerospikeClient client = new AerospikeClient(null, config);

// Creates a key with the namespace "sandbox", set "feeds", and user key "feed:1"

Key key = new Key("sandbox", "feeds", "feed:1");
```

> 📖 **API reference**: [`ListOperation`](https://aerospike.com/apidocs/csharp/api/Aerospike.Client.ListOperation.html) | [`ListReturnType`](https://aerospike.com/apidocs/csharp/api/Aerospike.Client.ListReturnType.html)

## Write a list bin

To write a list as the whole value of a bin, pass a `List<object>` to a `Bin`:

```csharp
List<object> events = new List<object> { 1, 2, 3, 4, 5, 6, 7, 8 };

client.Put(null, key, new Bin("events", events));
```

## Append to a list bin

`ListOperation.Append(binName, value)` appends one value to the end of a list bin. It creates the bin and an empty list if the bin doesn’t exist yet. `ListOperation.AppendItems(binName, list)` appends every element of a list as a separate element. Both return the new size of the list.

```csharp
// Append one value

client.Operate(null, key, ListOperation.Append("events", Value.Get(9)));

// Append three values as three separate elements, not one nested list

client.Operate(null, key,

    ListOperation.AppendItems("events", new List<object> { "login", "view", "logout" })

);
```

## Read the list size

`ListOperation.Size(binName)` returns the number of elements. Combine it with an append in one `Operate()` call to append and get the new length in a round trip.

When one call runs several operations on the same bin, the `Record` holds one bin whose value is a list of results, one result for each operation, in order. Read it with `record.GetList(binName)`:

```csharp
Record record = client.Operate(null, key,

    ListOperation.Append("events", Value.Get(10)),

    ListOperation.Size("events")

);

// The results are in the order of the operations: [new size from Append, size from Size]

IList results = record.GetList("events");

Console.WriteLine("size: {0}", results[1]);
```

## Read elements back

`ListOperation.Get(binName, index)` reads one element. `ListOperation.GetRange(binName, index, count)` reads `count` elements that start at `index`. `ListOperation.GetRange(binName, index)` reads from `index` to the end of the list. The server selects the elements, so the whole list doesn’t travel to your program.

An index can be negative. `-1` is the last element, `-2` the one before it, and so on. To read the last three elements, start at index `-3`:

```csharp
Record record = client.Operate(null, key, ListOperation.GetRange("events", -3, 3));

// A list read returns the elements as an IList

foreach (object element in record.GetList("events"))

{

    Console.WriteLine(element);

}
```

`ListOperation.GetByIndexRange(binName, index, count, returnType)` selects the same elements and also takes a `ListReturnType`. It returns the elements as values with `ListReturnType.VALUE`, and returns the number of elements selected with `ListReturnType.COUNT`. Use it when you need something other than the values.

## Remove elements

`ListOperation.Pop(binName, index)` removes the element at an index and returns it. `ListOperation.Remove(binName, index)` removes it and returns the number of elements removed. `ListOperation.RemoveRange(binName, index, count)` removes `count` elements that start at `index`, and returns the number of elements removed.

```csharp
// Remove and return the first element

Record record = client.Operate(null, key, ListOperation.Pop("events", 0));

Console.WriteLine("popped: {0}", record.GetValue("events"));

// Remove the next two elements

client.Operate(null, key, ListOperation.RemoveRange("events", 0, 2));
```

### Keep only the last elements of a list

`ListOperation.Trim(binName, index, count)` keeps the `count` elements that start at `index` and removes all the others. With a negative index, it counts from the end of the list, so `-5, 5` keeps the last five elements. `Trim` returns the number of elements it removed.

To cap a list at its five most recent entries, append the new element and trim in the same `Operate()` call. The server runs the operations in order, so no read comes first:

```csharp
client.Operate(null, key,

    ListOperation.Append("events", Value.Get(9)),

    ListOperation.Trim("events", -5, 5) // keep the last five elements

);
```

## Read a list from a record

`Get()` returns a list bin as an `IList` of `object` elements. Integers come back as `long`. Read the list with `record.GetList(binName)`:

```csharp
Record record = client.Get(null, key);

foreach (object element in record.GetList("events"))

{

    Console.WriteLine(element);

}
```

For nested-list navigation with a nested CDT context (`CTX`), see the [`ListOperation`](https://aerospike.com/apidocs/csharp/api/Aerospike.Client.ListOperation.html) API reference and [Context for operations on nested elements](https://aerospike.com/docs/develop/data-types/collections/context).

## Next steps

-   [Map operations](https://aerospike.com/docs/develop/client/csharp/usage/cdt/maps)
-   [Bin operations](https://aerospike.com/docs/develop/client/csharp/usage/atomic/multi)
-   [List data type](https://aerospike.com/docs/develop/data-types/collections/list)