---
title: "List operations"
description: "Guide to Aerospike list operations for modifying, reading, and managing ordered and unordered list data types."
---

# List operations

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

## List policy

The list policy defines the order and write behavior for a list.

### List order

The list order is set in the list policy and determines the [list subtype](https://aerospike.com/docs/develop/data-types/collections/list#element-ordering):

-   **Unordered** (default) - maintains insertion order. New elements are appended to the end.
-   **Ordered** - maintains sorted (rank) order. Elements are sorted on each write.

Use [`set_order()`](https://aerospike.com/docs/develop/data-types/collections/list/operations#set_order) to convert between order types.

See [List performance](https://aerospike.com/docs/develop/data-types/collections/list/performance) for the operational complexity of each order type.

### Persisting the list index

For large ordered lists with a high read-to-write ratio, rebuilding the offset index on every access can consume significant CPU. Setting `persistIndex` to `true` in [`set_order()`](https://aerospike.com/docs/develop/data-types/collections/list/operations#set_order) or `create()` stores the offset index on disk inside the list particle, so subsequent operations load it directly instead of rebuilding it.

Once set, both the order and persist-index flags are preserved across all subsequent list operations (append, insert, remove, etc.) until changed by another `set_order()` call.

The persist-index flag applies only to top-level lists. For nested lists the flag is silently ignored.

See column (3) in the [List performance table](https://aerospike.com/docs/develop/data-types/collections/list/performance) for the performance impact.

### Write flags

| Flag | Description |
| --- | --- |
| `MODIFY_DEFAULT` | Default: not bound by list size; accepts duplicate elements; throws error on failure |
| `ADD_UNIQUE` | Only add elements if they do not already exist in the list |
| `INSERT_BOUNDED` | Do not insert past index N, where N is the element count |
| `NO_FAIL` | No-op instead of fail if a policy violation occurred, such as `ADD_UNIQUE` or `INSERT_BOUNDED` |
| `DO_PARTIAL` | When used with `NO_FAIL`, add elements that did not violate a policy |

Write flags can be combined using bitwise OR. For example, `ADD_UNIQUE | NO_FAIL | DO_PARTIAL` adds only unique elements, skips duplicates without failing, and commits the non-duplicate elements.

## Context

| Context Type | Description |
| --- | --- |
| `LIST_INDEX` | Finds an element in a List by index. A negative index is a lookup performed in reverse from the end of the list. If it is out of bounds, a parameter error is returned. |
| `LIST_RANK` | Finds an element in a List by rank. A negative rank is a lookup performed in reverse from the highest ranked. |
| `LIST_VALUE` | Finds an element in a List by value. |
| `LIST_INDEX_CREATE` | Finds an element in a List by index. Creates the element if it does not exist. |

The [context](https://aerospike.com/docs/develop/data-types/collections/context/) is a list of element selectors describing a path to the nested list element where the operation should be applied. Without a context it is assumed that the operation occurs at the top level of the list.

## Return types

| Return Type | Description |
| --- | --- |
| `VALUE` | The value of the element (in single result operations) or elements (in multi result operations) |
| `NONE` | Nothing is returned. It speeds up remove operations by not constructing a reply |
| `COUNT` | Number of elements returned |
| `INDEX` | Index position of the element, from 0 (first) to N-1 (last) |
| `REVERSE_INDEX` | Reverse index position of the element, from 0 (last) to N-1 (first) |
| `RANK` | Value order of the element, with 0 being the smallest |
| `REVERSE_RANK` | Reverse rank order of the element, with 0 being the largest value |
| `INVERTED` | Invert meaning of list command and return values. Combine with another return type using bitwise OR, such as \`COUNT |
| `EXISTS` | Returns a boolean `true` if any elements match the criteria. For example, [`get_all_by_value`](https://aerospike.com/docs/develop/data-types/collections/list/operations#get_all_by_value) with `EXISTS` returns `true` if the value is in the list. |

### Examples

-   Remove the last 3 elements: `remove_by_index_range(-3, 3, NONE)`
-   Remove all _but_ the last 3 elements: `remove_by_index_range(-3, 3, NONE | INVERTED)`
-   Keep only the last 3 elements and return the count of removed elements: `remove_by_index_range(-3, 3, COUNT | INVERTED)`

Availability

`EXISTS` available since [6.1.0](https://aerospike.com/docs/database/release/6-1).

## Modify operations

#### `append_items`

```python
append_items(listPolicy, binName, items[, ctx])
```

Description: Creates a list bin with a specified order, if the bin does not exist. Adds the items to the list. In an `UNORDERED` list the items are appended to the end of the list. In an `ORDERED` list the items are inserted by [value order](https://aerospike.com/docs/develop/data-types/collections/ordering).

Returns: The element count due to the operation, in the ‘bins’ part of the record under the _bin_ name.

Order: A list newly created with `append_items` can be declared `UNORDERED` (default) or `ORDERED` using the list order attribute of the list policy. Once a list is created its order can only be modified with [`set_order`](#set_order).

A note on write flags

Write flags can be combined to alter the behavior of the operation. For example, `ADD_UNIQUE | NO_FAIL` will fail gracefully without throwing an exception if any new item already exists.

`INSERT_BOUNDED` is not applicable for this operation.

Performance: The worst-case performance of append\_items on an unordered list is 𝓞(M), and 𝓞((M+N) log (M+N)) on an ordered list, where M is the number of items to append and N is the number of items already in the list.

Code sample: -   [Java](#tab-panel-1888)
-   [Python](#tab-panel-1889)
-   [Go](#tab-panel-1890)
-   [C](#tab-panel-1891)
-   [C#](#tab-panel-1892)
-   [Node.js](#tab-panel-1893)

```java
// scores = [10, 20, 30]

List<Value> newItems = Arrays.asList(Value.get(40), Value.get(50));

Record record = client.operate(null, key,

    ListOperation.appendItems("scores", newItems)

);

// returns 5 (new list size)

// scores == [10, 20, 30, 40, 50]
```

```python
# scores = [10, 20, 30]

_, _, bins = client.operate(key, [

    list_operations.list_append_items("scores", [40, 50])

])

# bins["scores"] == 5 (new list size)

# scores == [10, 20, 30, 40, 50]
```

```go
// scores = [10, 20, 30]

record, err := client.Operate(nil, key,

    as.ListAppendOp("scores", 40, 50),

)

// record.Bins["scores"] == 5

// scores == [10, 20, 30, 40, 50]
```

```c
// scores = [10, 20, 30]

as_arraylist items;

as_arraylist_inita(&items, 2);

as_arraylist_append_int64(&items, 40);

as_arraylist_append_int64(&items, 50);

as_operations ops;

as_operations_inita(&ops, 1);

as_operations_list_append_items(&ops, "scores", NULL, NULL,

    (as_list*)&items);

as_record* rec = NULL;

aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);

// rec bins "scores" == 5
```

```csharp
// scores = [10, 20, 30]

IList newItems = new List<Value> { Value.Get(40), Value.Get(50) };

Record record = client.Operate(null, key,

    ListOperation.AppendItems("scores", newItems)

);

// returns 5 (new list size)

// scores == [10, 20, 30, 40, 50]
```

```javascript
// scores = [10, 20, 30]

const lists = Aerospike.lists

const result = await client.operate(key, [

    lists.appendItems('scores', [40, 50])

])

// result.bins.scores == 5

// scores == [10, 20, 30, 40, 50]
```

---

#### `append`

```python
append(listPolicy, binName, value[, ctx])
```

Description: Creates a list bin with a specified order, if the bin does not exist. Adds a value to the list. In an `UNORDERED` list the value is appended to the end of the list. In an `ORDERED` list the value is inserted by [value order](https://aerospike.com/docs/develop/data-types/collections/ordering).

Returns: The element count due to the operation, in the ‘bins’ part of the record under the _bin_ name.

Order: A list newly created with `append` can be declared `UNORDERED` (default) or `ORDERED` using the list order attribute of the list policy. Once a list is created its order can only be modified with [`set_order`](#set_order).

A note on write flags

Write flags can be combined to alter the behavior of the operation. For example, `ADD_UNIQUE | NO_FAIL` will fail gracefully without throwing an exception if the element already exists.

`INSERT_BOUNDED` and `DO_PARTIAL` are not applicable for this operation.

Performance: The worst-case performance of append() on an unordered list is 𝓞(N).

Code sample: -   [Java](#tab-panel-1894)
-   [Python](#tab-panel-1895)
-   [Go](#tab-panel-1896)
-   [C](#tab-panel-1897)
-   [C#](#tab-panel-1898)
-   [Node.js](#tab-panel-1899)

```java
// scores = [10, 20, 30]

Record record = client.operate(null, key,

    ListOperation.append("scores", Value.get(40))

);

// returns 4 (new list size)

// scores == [10, 20, 30, 40]
```

```python
# scores = [10, 20, 30]

_, _, bins = client.operate(key, [

    list_operations.list_append("scores", 40)

])

# bins["scores"] == 4 (new list size)

# scores == [10, 20, 30, 40]
```

```go
// scores = [10, 20, 30]

record, err := client.Operate(nil, key,

    as.ListAppendOp("scores", 40),

)

// record.Bins["scores"] == 4

// scores == [10, 20, 30, 40]
```

```c
// scores = [10, 20, 30]

as_operations ops;

as_operations_inita(&ops, 1);

as_operations_list_append(&ops, "scores", NULL, NULL,

    (as_val*)as_integer_new(40));

as_record* rec = NULL;

aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);

// rec bins "scores" == 4 (new list size)
```

```csharp
// scores = [10, 20, 30]

Record record = client.Operate(null, key,

    ListOperation.Append("scores", Value.Get(40))

);

// returns 4 (new list size)

// scores == [10, 20, 30, 40]
```

```javascript
// scores = [10, 20, 30]

const lists = Aerospike.lists

const result = await client.operate(key, [

    lists.append('scores', 40)

])

// result.bins.scores == 4

// scores == [10, 20, 30, 40]
```

---

#### `clear`

```python
clear(binName[, ctx])
```

Description: Clears a list, optionally at a given subcontext.

Returns: null

Performance: The worst-case performance of clearing a list is 𝓞(1).

Code sample: -   [Java](#tab-panel-1900)
-   [Python](#tab-panel-1901)
-   [Go](#tab-panel-1902)
-   [C](#tab-panel-1903)
-   [C#](#tab-panel-1904)
-   [Node.js](#tab-panel-1905)

```java
// scores = [10, 20, 30, 40, 50]

client.operate(null, key,

    ListOperation.clear("scores")

);

// scores == []
```

```python
# scores = [10, 20, 30, 40, 50]

client.operate(key, [

    list_operations.list_clear("scores")

])

# scores == []
```

```go
// scores = [10, 20, 30, 40, 50]

_, err := client.Operate(nil, key,

    as.ListClearOp("scores"),

)

// scores == []
```

```c
// scores = [10, 20, 30, 40, 50]

as_operations ops;

as_operations_inita(&ops, 1);

as_operations_list_clear(&ops, "scores", NULL);

aerospike_key_operate(&as, &err, NULL, &key, &ops, NULL);

// scores == []
```

```csharp
// scores = [10, 20, 30, 40, 50]

client.Operate(null, key,

    ListOperation.Clear("scores")

);

// scores == []
```

```javascript
// scores = [10, 20, 30, 40, 50]

const lists = Aerospike.lists

await client.operate(key, [

    lists.clear('scores')

])

// scores == []
```

---

#### `increment`

```python
increment(listPolicy, binName, index, delta[, ctx])
```

Description: Creates an unordered list bin if the bin does not exist. In an `UNORDERED` list, increment() initializes or increments a numeric value at the specified list index. In an `ORDERED` list, increments a numeric value at a specific rank, given by the index argument.

By default the index can be any number, and `NIL` values will be added as padding to the left of the new element, as needed. Using the `INSERT_BOUNDED` policy, a developer can limit this behavior, and only allow for an element to be incremented at an index value between 0 and the size of the list.

Increment delta values can be either float or integer. An integer delta value will be converted into a float if the server-side type is a float. A float delta-value will be converted and truncated into an integer if the server-side value is an integer.

Returns: The new value after the increment, in the ‘bins’ part of the record under the _bin_ name.

Order: A list newly created with `increment` is always unordered. Once a list is created its order can only be modified with [`set_order`](#set_order).

A note on write flags

Write flags can be combined to alter the behavior of the operation. For example, `ADD_UNIQUE | NO_FAIL` will fail gracefully without throwing an exception if the element already exists.

`DO_PARTIAL` is not applicable for this operation, as we only increment one element at a time.

Performance: The worst-case performance of increment() on an unordered list is 𝓞(N).

Code sample: -   [Java](#tab-panel-1906)
-   [Python](#tab-panel-1907)
-   [Go](#tab-panel-1908)
-   [C](#tab-panel-1909)
-   [C#](#tab-panel-1910)
-   [Node.js](#tab-panel-1911)

```java
// scores = [10, 20, 30]

Record record = client.operate(null, key,

    ListOperation.increment("scores", 1, Value.get(5))

);

// returns 25 (new value at index 1)

// scores == [10, 25, 30]
```

```python
# scores = [10, 20, 30]

_, _, bins = client.operate(key, [

    list_operations.list_increment("scores", 1, 5)

])

# bins["scores"] == 25

# scores == [10, 25, 30]
```

```go
// scores = [10, 20, 30]

record, err := client.Operate(nil, key,

    as.ListIncrementOp("scores", 1, 5),

)

// record.Bins["scores"] == 25

// scores == [10, 25, 30]
```

```c
// scores = [10, 20, 30]

as_operations ops;

as_operations_inita(&ops, 1);

as_operations_list_increment(&ops, "scores", NULL, NULL, 1,

    (as_val*)as_integer_new(5));

as_record* rec = NULL;

aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);

// rec bins "scores" == 25
```

```csharp
// scores = [10, 20, 30]

Record record = client.Operate(null, key,

    ListOperation.Increment("scores", 1, Value.Get(5))

);

// returns 25

// scores == [10, 25, 30]
```

```javascript
// scores = [10, 20, 30]

const lists = Aerospike.lists

const result = await client.operate(key, [

    lists.increment('scores', 1, 5)

])

// result.bins.scores == 25

// scores == [10, 25, 30]
```

---

#### `insert`

```python
insert(listPolicy, binName, index, value[, ctx])
```

Description: Creates an unordered list bin, if the bin does not exist. Inserts a _value_ into the list at the specified _index_, and shifts elements with a higher index to the right of the new element.

By default the index can be any number, and `NIL` values will be added as padding to the left of the new element, as needed. Using the `INSERT_BOUNDED` policy, a developer can limit this behavior, and only allow for an element to be inserted at an index value between 0 and the size of the list.

you cannot insert into an ordered list, only [`append`](#append) or [`append_items`](#append_items) to one.

Returns: The element count due to the operation, in the ‘bins’ part of the record under the _bin_ name.

Order: A list newly created with `insert` is always unordered. Once a list is created its order can only be modified with [`set_order`](#set_order).

A note on write flags

Write flags can be combined to alter the behavior of the operation. For example, `ADD_UNIQUE | NO_FAIL` will fail gracefully without throwing an exception if any new item already exists.

`DO_PARTIAL` is not applicable for this operation, as we only insert one element at a time.

Performance: The worst-case performance of inserting an item at the head of a list (at its 0th index) is 𝓞(1). At any other index it is 𝓞(N).

Code sample: -   [Java](#tab-panel-1912)
-   [Python](#tab-panel-1913)
-   [Go](#tab-panel-1914)
-   [C](#tab-panel-1915)
-   [C#](#tab-panel-1916)
-   [Node.js](#tab-panel-1917)

```java
// scores = [10, 30, 40]

Record record = client.operate(null, key,

    ListOperation.insert("scores", 1, Value.get(20))

);

// returns 4 (new list size)

// scores == [10, 20, 30, 40]
```

```python
# scores = [10, 30, 40]

_, _, bins = client.operate(key, [

    list_operations.list_insert("scores", 1, 20)

])

# bins["scores"] == 4

# scores == [10, 20, 30, 40]
```

```go
// scores = [10, 30, 40]

record, err := client.Operate(nil, key,

    as.ListInsertOp("scores", 1, 20),

)

// record.Bins["scores"] == 4

// scores == [10, 20, 30, 40]
```

```c
// scores = [10, 30, 40]

as_operations ops;

as_operations_inita(&ops, 1);

as_operations_list_insert(&ops, "scores", NULL, NULL, 1,

    (as_val*)as_integer_new(20));

as_record* rec = NULL;

aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);

// rec bins "scores" == 4
```

```csharp
// scores = [10, 30, 40]

Record record = client.Operate(null, key,

    ListOperation.Insert("scores", 1, Value.Get(20))

);

// returns 4 (new list size)

// scores == [10, 20, 30, 40]
```

```javascript
// scores = [10, 30, 40]

const lists = Aerospike.lists

const result = await client.operate(key, [

    lists.insert('scores', 1, 20)

])

// result.bins.scores == 4

// scores == [10, 20, 30, 40]
```

---

#### `remove_all_by_value_list`

```python
remove_by_value_list(binName, values, returnType[, ctx])
```

Description: Removes all the elements in the list matching one of the specified values. The `INVERTED` flag may be used to remove the elements _not_ matching the specified values.

Returns: Zero, one or a list of values, based on the return type. The `NONE` return type will execute faster because no reply is constructed for the operation. The elements returned by other return types may not be in index order.

Order: Whether the list is unordered or ordered, `remove_all_by_value_list` will return the same elements, based on the [ordering rules](https://aerospike.com/docs/develop/data-types/collections/ordering). The performance of ‘by value’ operations is better on an ordered list than an unordered one.

Performance: The worst-case performance of removing elements by a value list is 𝓞((M+N) log M) for an ordered list with a persisted index, 𝓞((M+N) log M + N) for an ordered list without a persisted index, or for an unordered list, where M is the number of items in the parameter list and N is the number of items already in the list.

Examples: Trivial example

Remove scalar values from the list matching one of several specified values. See the code sample below.

---

Matching tuples with wildcard

See the example given for [`remove_all_by_value`](#remove_all_by_value).

In a list of mostly ordered pairs, we could remove all the tuples matching the patterns `[v1, *]` and `[v2, *]`.

The wildcard matches any sequence of elements to the end of the tuple. In this example, this means matching any tuple whose first position is “v1” or “v2”, and whose size is two or more elements.

The wildcard has different language-specific constructs, such as `aerospike.CDTWildcard()` in the Python client and `Value.WILDCARD` in the Java client.

Code sample: -   [Java](#tab-panel-1936)
-   [Python](#tab-panel-1937)
-   [Go](#tab-panel-1938)
-   [C](#tab-panel-1939)
-   [C#](#tab-panel-1940)
-   [Node.js](#tab-panel-1941)

```java
// Trivial example

// l = [1, 2, 3, 4, 3, 2, 1]

List<Value> removeValues = Arrays.asList(Value.get(2), Value.get(3));

Record record = client.operate(null, key,

    ListOperation.removeByValueList("l", removeValues, ListReturnType.COUNT)

);

// returns 4

// l == [1, 4, 1]

// Matching tuples with wildcard

// l = [["v1", 1], ["v2", 2], ["v3", 3], ["v2", 4], ["v1", 5]]

List<Value> patterns = Arrays.asList(

    Value.get(Arrays.asList("v1", Value.WILDCARD)),

    Value.get(Arrays.asList("v2", Value.WILDCARD))

);

record = client.operate(null, key,

    ListOperation.removeByValueList("l", patterns, ListReturnType.NONE),

    Operation.get("l")

);

// l == [["v3", 3]]
```

```python
# Trivial example

# l = [1, 2, 3, 4, 3, 2, 1]

_, _, bins = client.operate(key, [

    list_operations.list_remove_by_value_list("l", [2, 3], aerospike.LIST_RETURN_COUNT)

])

# bins["l"] == 4

# l == [1, 4, 1]

# Matching tuples with wildcard

# l = [["v1", 1], ["v2", 2], ["v3", 3], ["v2", 4], ["v1", 5]]

_, _, bins = client.operate(key, [

    list_operations.list_remove_by_value_list(

        "l", [["v1", aerospike.CDTWildcard()], ["v2", aerospike.CDTWildcard()]],

        aerospike.LIST_RETURN_NONE

    ),

    operations.read("l"),

])

# bins["l"] == [["v3", 3]]
```

```go
// Trivial example

// l = [1, 2, 3, 4, 3, 2, 1]

record, err := client.Operate(nil, key,

    as.ListRemoveByValueListOp("l", []any{2, 3}, as.ListReturnTypeCount),

)

// record.Bins["l"] == 4

// l == [1, 4, 1]

// Matching tuples with wildcard

// l = [["v1", 1], ["v2", 2], ["v3", 3], ["v2", 4], ["v1", 5]]

record, err = client.Operate(nil, key,

    as.ListRemoveByValueListOp("l",

        []any{

            []any{"v1", as.NewWildCardValue()},

            []any{"v2", as.NewWildCardValue()},

        },

        as.ListReturnTypeNone),

    as.GetOpForBin("l"),

)

// record.Bins["l"] == [["v3", 3]]
```

```c
// Trivial example

// l = [1, 2, 3, 4, 3, 2, 1]

as_arraylist values;

as_arraylist_inita(&values, 2);

as_arraylist_append_int64(&values, 2);

as_arraylist_append_int64(&values, 3);

as_operations ops;

as_operations_inita(&ops, 1);

as_operations_list_remove_by_value_list(&ops, "l", NULL,

    (as_list*)&values, AS_LIST_RETURN_COUNT);

as_record* rec = NULL;

aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);

// rec bins "l" == 4

// Matching tuples with wildcard

// l = [["v1", 1], ["v2", 2], ["v3", 3], ["v2", 4], ["v1", 5]]

as_arraylist pat1;

as_arraylist_inita(&pat1, 2);

as_arraylist_append_str(&pat1, "v1");

as_arraylist_append(&pat1, (as_val*)&as_cdt_wildcard);

as_arraylist pat2;

as_arraylist_inita(&pat2, 2);

as_arraylist_append_str(&pat2, "v2");

as_arraylist_append(&pat2, (as_val*)&as_cdt_wildcard);

as_arraylist patterns;

as_arraylist_inita(&patterns, 2);

as_arraylist_append(&patterns, (as_val*)&pat1);

as_arraylist_append(&patterns, (as_val*)&pat2);

as_operations ops2;

as_operations_inita(&ops2, 2);

as_operations_list_remove_by_value_list(&ops2, "l", NULL,

    (as_list*)&patterns, AS_LIST_RETURN_NONE);

as_operations_add_read(&ops2, "l");

as_record* rec2 = NULL;

aerospike_key_operate(&as, &err, NULL, &key, &ops2, &rec2);

// rec2 bins "l" == [["v3", 3]]
```

```csharp
// Trivial example

// l = [1, 2, 3, 4, 3, 2, 1]

IList removeValues = new List<Value> {

    Value.Get(2), Value.Get(3)

};

Record record = client.Operate(null, key,

    ListOperation.RemoveByValueList("l", removeValues, ListReturnType.COUNT)

);

// returns 4

// l == [1, 4, 1]

// Matching tuples with wildcard

// l = [["v1", 1], ["v2", 2], ["v3", 3], ["v2", 4], ["v1", 5]]

IList patterns = new List<Value> {

    Value.Get(new List<Value> { Value.Get("v1"), Value.AsNull }),

    Value.Get(new List<Value> { Value.Get("v2"), Value.AsNull })

};

record = client.Operate(null, key,

    ListOperation.RemoveByValueList("l", patterns, ListReturnType.NONE),

    Operation.Get("l")

);

// l == [["v3", 3]]
```

```javascript
// Trivial example

// l = [1, 2, 3, 4, 3, 2, 1]

const lists = Aerospike.lists

let result = await client.operate(key, [

    lists.removeByValueList('l', [2, 3]).andReturn(lists.returnType.COUNT)

])

// result.bins.l == 4

// l == [1, 4, 1]

// Matching tuples with wildcard

// l = [["v1", 1], ["v2", 2], ["v3", 3], ["v2", 4], ["v1", 5]]

result = await client.operate(key, [

    lists.removeByValueList('l',

        [['v1', new Aerospike.Wildcard()], ['v2', new Aerospike.Wildcard()]])

        .andReturn(lists.returnType.NONE),

    Aerospike.operations.read('l')

])

// result.bins.l == [["v3", 3]]
```

---

#### `remove_all_by_value`

```python
remove_by_value(binName, value, returnType[, ctx])
```

Description: Removes all the elements in the list matching _value_. The `INVERTED` flag may be used to remove the elements _not_ matching the specified value.

Returns: Zero, one or a list of values, based on the return type. The `NONE` return type will execute faster because no reply is constructed for the operation. The elements returned by other return types may not be in index order.

Order: Whether the list is unordered or ordered, `remove_all_by_value` will return the same elements, based on the [ordering rules](https://aerospike.com/docs/develop/data-types/collections/ordering). The performance of ‘by value’ operations is better on an ordered list than an unordered one.

Performance: The worst-case performance of removing elements by value is 𝓞(log N + M) for an ordered list with a persisted index, 𝓞(log N + N) for an ordered list without a persisted index, and 𝓞(N + M) for an unordered list, where M is the number of items in the parameter list and N is the number of items already in the list.

Examples: Trivial example

Remove scalar values from the list. See the code sample below.

---

Matching tuples with wildcard

It is common to model complex data in Aerospike as a list of tuples, each element a list, where the index order carries meaning. For an example, see [Aerospike Modeling: IoT Sensors](https://dev.to/aerospike/aerospike-modeling-iot-sensors-453a).

In a list of mostly ordered pairs, we could remove a specific kind of element, such as all the tuples where the 0th position is “v2”, by using a wildcard (typically stylized as a \* in documentation).

The wildcard matches any sequence of elements to the end of the tuple. In this example, this means matching any tuple whose first position is “v2”, and whose size is two or more elements.

The wildcard has different language-specific constructs, such as `aerospike.CDTWildcard()` in the Python client and `Value.WILDCARD` in the Java client.

Code sample: -   [Java](#tab-panel-1930)
-   [Python](#tab-panel-1931)
-   [Go](#tab-panel-1932)
-   [C](#tab-panel-1933)
-   [C#](#tab-panel-1934)
-   [Node.js](#tab-panel-1935)

```java
// Trivial example

// l = [1, 2, 1, 2]

Record record = client.operate(null, key,

    ListOperation.removeByValue("l", Value.get(2), ListReturnType.COUNT)

);

// returns 2

// Matching tuples with wildcard

// l = [["v1", 1], ["v2", 2], ["v1", 3], ["v2", 4, {"a": 1}]]

record = client.operate(null, key,

    ListOperation.removeByValue("l", Value.get(Arrays.asList("v2", Value.WILDCARD)),

        ListReturnType.VALUE)

);

// returns [["v2", 2], ["v2", 4, {"a": 1}]]
```

```python
# Trivial example

# l = [1, 2, 1, 2]

_, _, bins = client.operate(key, [

    list_operations.list_remove_by_value("l", 2, aerospike.LIST_RETURN_COUNT)

])

# bins["l"] == 2

# Matching tuples with wildcard

# l = [["v1", 1], ["v2", 2], ["v1", 3], ["v2", 4, {"a": 1}]]

_, _, bins = client.operate(key, [

    list_operations.list_remove_by_value(

        "l", ["v2", aerospike.CDTWildcard()], aerospike.LIST_RETURN_VALUE

    )

])

# bins["l"] == [["v2", 2], ["v2", 4, {"a": 1}]]
```

```go
// Trivial example

// l = [1, 2, 1, 2]

record, err := client.Operate(nil, key,

    as.ListRemoveByValueOp("l", 2, as.ListReturnTypeCount),

)

// record.Bins["l"] == 2

// Matching tuples with wildcard

// l = [["v1", 1], ["v2", 2], ["v1", 3], ["v2", 4, {"a": 1}]]

record, err = client.Operate(nil, key,

    as.ListRemoveByValueOp("l", []any{"v2", as.NewWildCardValue()},

        as.ListReturnTypeValue),

)

// record.Bins["l"] == [["v2", 2], ["v2", 4, {"a": 1}]]
```

```c
// Trivial example

// l = [1, 2, 1, 2]

as_integer val;

as_integer_init(&val, 2);

as_operations ops;

as_operations_inita(&ops, 1);

as_operations_list_remove_by_value(&ops, "l", NULL,

    (as_val*)&val, AS_LIST_RETURN_COUNT);

as_record* rec = NULL;

aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);

// rec bins "l" == 2

// Matching tuples with wildcard

// l = [["v1", 1], ["v2", 2], ["v1", 3], ["v2", 4, {"a": 1}]]

as_arraylist match;

as_arraylist_inita(&match, 2);

as_arraylist_append_str(&match, "v2");

as_arraylist_append(&match, (as_val*)&as_cdt_wildcard);

as_operations ops2;

as_operations_inita(&ops2, 1);

as_operations_list_remove_by_value(&ops2, "l", NULL,

    (as_val*)&match, AS_LIST_RETURN_VALUE);

as_record* rec2 = NULL;

aerospike_key_operate(&as, &err, NULL, &key, &ops2, &rec2);

// rec2 bins "l" == [["v2", 2], ["v2", 4, {"a": 1}]]
```

```csharp
// Trivial example

// l = [1, 2, 1, 2]

Record record = client.Operate(null, key,

    ListOperation.RemoveByValue("l", Value.Get(2), ListReturnType.COUNT)

);

// returns 2

// Matching tuples with wildcard

// l = [["v1", 1], ["v2", 2], ["v1", 3], ["v2", 4, {"a": 1}]]

record = client.Operate(null, key,

    ListOperation.RemoveByValue("l",

        Value.Get(new List<Value> { Value.Get("v2"), Value.AsNull }),

        ListReturnType.VALUE)

);

// returns [["v2", 2], ["v2", 4, {"a": 1}]]
```

```javascript
// Trivial example

// l = [1, 2, 1, 2]

const lists = Aerospike.lists

let result = await client.operate(key, [

    lists.removeByValue('l', 2).andReturn(lists.returnType.COUNT)

])

// result.bins.l == 2

// Matching tuples with wildcard

// l = [["v1", 1], ["v2", 2], ["v1", 3], ["v2", 4, {"a": 1}]]

result = await client.operate(key, [

    lists.removeByValue('l', ['v2', new Aerospike.Wildcard()])

        .andReturn(lists.returnType.VALUE)

])

// result.bins.l == [["v2", 2], ["v2", 4, {"a": 1}]]
```

---

#### `remove_by_index_range`

```python
remove_by_index_range(binName, index[, count], returnType[, ctx])
```

Description: Removes a range of _count_ elements starting at a specified list index. The `INVERTED` flag may be used to remove the elements _not_ in a specified range.

The index and count can be any number, but the result may be an empty list if the specified range contains no elements.

Returns: Zero, one or a list of values, based on the return type. The `NONE` return type will execute faster because no reply is constructed for the operation. The elements returned by other return types may not be in index order.

A note on return types

`INDEX` is redundant for this operation.

Performance: The worst-case performance of removing elements by index range is 𝓞(M) for an ordered list with a persisted index, and 𝓞(N + M) for an ordered list without a persisted index or an unordered list, where M is the element count of the range, and N is the element count of the list. Requesting a `RANK` return type on an unordered list adds 𝓞(L\*N). See [List performance](https://aerospike.com/docs/develop/data-types/collections/list/performance).

Examples: Example

For `[1, 3, 3, 7, 0]` with return type `NONE` a range starting at index 2 and containing 3 elements removes `[3, 7, 0]`, while the `INVERTED | NONE` of the same range removes `[1, 3]`.

Code sample: -   [Java](#tab-panel-1924)
-   [Python](#tab-panel-1925)
-   [Go](#tab-panel-1926)
-   [C](#tab-panel-1927)
-   [C#](#tab-panel-1928)
-   [Node.js](#tab-panel-1929)

```java
// l = [1, 3, 3, 7, 0]

client.operate(null, key,

    ListOperation.removeByIndexRange("l", 2, 3, ListReturnType.NONE)

);

// l == [1, 3]

// INVERTED: remove everything outside the range

// l = [1, 3, 3, 7, 0]

client.operate(null, key,

    ListOperation.removeByIndexRange("l", 2, 3,

        ListReturnType.NONE | ListReturnType.INVERTED)

);

// l == [3, 7, 0]
```

```python
# l = [1, 3, 3, 7, 0]

client.operate(key, [

    list_operations.list_remove_by_index_range("l", 2, aerospike.LIST_RETURN_NONE, 3)

])

# l == [1, 3]

# INVERTED: remove everything outside the range

# l = [1, 3, 3, 7, 0]

client.operate(key, [

    list_operations.list_remove_by_index_range(

        "l", 2, aerospike.LIST_RETURN_NONE | aerospike.LIST_RETURN_INVERTED, 3)

])

# l == [3, 7, 0]
```

```go
// l = [1, 3, 3, 7, 0]

_, err := client.Operate(nil, key,

    as.ListRemoveByIndexRangeCountOp("l", 2, 3, as.ListReturnTypeNone),

)

// l == [1, 3]

// INVERTED: remove everything outside the range

// l = [1, 3, 3, 7, 0]

_, err = client.Operate(nil, key,

    as.ListRemoveByIndexRangeCountOp("l", 2, 3,

        as.ListReturnTypeNone|as.ListReturnTypeInverted),

)

// l == [3, 7, 0]
```

```c
// l = [1, 3, 3, 7, 0]

as_operations ops;

as_operations_inita(&ops, 1);

as_operations_list_remove_by_index_range(&ops, "l", NULL, 2, 3,

    AS_LIST_RETURN_NONE);

aerospike_key_operate(&as, &err, NULL, &key, &ops, NULL);

// l == [1, 3]

// INVERTED: remove everything outside the range

// l = [1, 3, 3, 7, 0]

as_operations ops2;

as_operations_inita(&ops2, 1);

as_operations_list_remove_by_index_range(&ops2, "l", NULL, 2, 3,

    AS_LIST_RETURN_NONE | AS_LIST_RETURN_INVERTED);

aerospike_key_operate(&as, &err, NULL, &key, &ops2, NULL);

// l == [3, 7, 0]
```

```csharp
// l = [1, 3, 3, 7, 0]

client.Operate(null, key,

    ListOperation.RemoveByIndexRange("l", 2, 3, ListReturnType.NONE)

);

// l == [1, 3]

// INVERTED: remove everything outside the range

// l = [1, 3, 3, 7, 0]

client.Operate(null, key,

    ListOperation.RemoveByIndexRange("l", 2, 3,

        ListReturnType.NONE | ListReturnType.INVERTED)

);

// l == [3, 7, 0]
```

```javascript
// l = [1, 3, 3, 7, 0]

const lists = Aerospike.lists

await client.operate(key, [

    lists.removeByIndexRange('l', 2, 3).andReturn(lists.returnType.NONE)

])

// l == [1, 3]

// INVERTED: remove everything outside the range

// l = [1, 3, 3, 7, 0]

await client.operate(key, [

    lists.removeByIndexRange('l', 2, 3)

        .invertSelection()

        .andReturn(lists.returnType.NONE)

])

// l == [3, 7, 0]
```

---

#### `remove_by_index`

```python
remove_by_index(binName, index, returnType[, ctx])
```

Description: Removes the element at the specified list index. The index must be a number between 0 and N-1, where N is the length of the list. The index can also be a negative number, with -1 being the last element by index position.

Returns: Zero or one value, based on the return type. The `NONE` return type will execute faster because no reply is constructed for the operation.

A note on return types

`INDEX` and `COUNT` are redundant for this operation. `INVERTED` has no meaning for this operation.

Throws: An Operation Not Applicable error (code 26) when trying to remove an inaccessible index.

Performance: The worst-case performance of removing the element by index is 𝓞(1) for an ordered list with a persisted index, and 𝓞(N) for an ordered list without a persisted index or an unordered list.

Code sample: -   [Java](#tab-panel-1918)
-   [Python](#tab-panel-1919)
-   [Go](#tab-panel-1920)
-   [C](#tab-panel-1921)
-   [C#](#tab-panel-1922)
-   [Node.js](#tab-panel-1923)

```java
// scores = [10, 20, 30, 40, 50]

Record record = client.operate(null, key,

    ListOperation.removeByIndex("scores", 2, ListReturnType.VALUE)

);

// returns 30

// scores == [10, 20, 40, 50]
```

```python
# scores = [10, 20, 30, 40, 50]

_, _, bins = client.operate(key, [

    list_operations.list_remove_by_index("scores", 2, aerospike.LIST_RETURN_VALUE)

])

# bins["scores"] == 30

# scores == [10, 20, 40, 50]
```

```go
// scores = [10, 20, 30, 40, 50]

record, err := client.Operate(nil, key,

    as.ListRemoveByIndexOp("scores", 2, as.ListReturnTypeValue),

)

// record.Bins["scores"] == 30

// scores == [10, 20, 40, 50]
```

```c
// scores = [10, 20, 30, 40, 50]

as_operations ops;

as_operations_inita(&ops, 1);

as_operations_list_remove_by_index(&ops, "scores", NULL, 2,

    AS_LIST_RETURN_VALUE);

as_record* rec = NULL;

aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);

// rec bins "scores" == 30
```

```csharp
// scores = [10, 20, 30, 40, 50]

Record record = client.Operate(null, key,

    ListOperation.RemoveByIndex("scores", 2, ListReturnType.VALUE)

);

// returns 30

// scores == [10, 20, 40, 50]
```

```javascript
// scores = [10, 20, 30, 40, 50]

const lists = Aerospike.lists

const result = await client.operate(key, [

    lists.removeByIndex('scores', 2).andReturn(lists.returnType.VALUE)

])

// result.bins.scores == 30

// scores == [10, 20, 40, 50]
```

---

#### `remove_by_rank_range`

```python
remove_by_rank_range(binName, rank[, count], returnType[, ctx])
```

Description: Removes a range of _count_ elements starting at a specified rank. The `INVERTED` flag may be used to remove the elements _not_ in a specified range.

The rank and count can be any number, but the result may be an empty list if the specified range contains no elements.

Returns: Zero, one or a list of values, based on the return type. The `NONE` return type will execute faster because no reply is constructed for the operation. The elements returned by other return types may not be in rank order.

A note on return types

`INDEX` is redundant for this operation.

Performance: The worst-case performance of removing elements by rank range is 𝓞(M) for an ordered list with a persisted index. An ordered list without a persisted index has a 𝓞(N + M), where M is the element count of the range, and N is the element count of the list. An unordered list has a 𝓞(R log N + N).

Examples: Example

For `[1, 3, 2, 7, 0]` with return type `NONE` a range starting at rank 2 and containing 2 elements removes `[2, 3]`, while the `INVERTED | NONE` of the same range removes `[0, 1, 7]`.

Code sample: -   [Java](#tab-panel-1942)
-   [Python](#tab-panel-1943)
-   [Go](#tab-panel-1944)
-   [C](#tab-panel-1945)
-   [C#](#tab-panel-1946)
-   [Node.js](#tab-panel-1947)

```java
// l = [1, 3, 2, 7, 0]

client.operate(null, key,

    ListOperation.removeByRankRange("l", 2, 2, ListReturnType.NONE)

);

// l == [1, 7, 0]

// INVERTED: remove everything outside the range

// l = [1, 3, 2, 7, 0]

client.operate(null, key,

    ListOperation.removeByRankRange("l", 2, 2,

        ListReturnType.NONE | ListReturnType.INVERTED)

);

// l == [3, 2]
```

```python
# l = [1, 3, 2, 7, 0]

client.operate(key, [

    list_operations.list_remove_by_rank_range("l", 2, aerospike.LIST_RETURN_NONE, 2)

])

# l == [1, 7, 0]

# INVERTED: remove everything outside the range

# l = [1, 3, 2, 7, 0]

client.operate(key, [

    list_operations.list_remove_by_rank_range(

        "l", 2, aerospike.LIST_RETURN_NONE | aerospike.LIST_RETURN_INVERTED, 2)

])

# l == [3, 2]
```

```go
// l = [1, 3, 2, 7, 0]

_, err := client.Operate(nil, key,

    as.ListRemoveByRankRangeCountOp("l", 2, 2, as.ListReturnTypeNone),

)

// l == [1, 7, 0]

// INVERTED: remove everything outside the range

// l = [1, 3, 2, 7, 0]

_, err = client.Operate(nil, key,

    as.ListRemoveByRankRangeCountOp("l", 2, 2,

        as.ListReturnTypeNone|as.ListReturnTypeInverted),

)

// l == [3, 2]
```

```c
// l = [1, 3, 2, 7, 0]

as_operations ops;

as_operations_inita(&ops, 1);

as_operations_list_remove_by_rank_range(&ops, "l", NULL, 2, 2,

    AS_LIST_RETURN_NONE);

aerospike_key_operate(&as, &err, NULL, &key, &ops, NULL);

// l == [1, 7, 0]

// INVERTED: remove everything outside the range

// l = [1, 3, 2, 7, 0]

as_operations ops2;

as_operations_inita(&ops2, 1);

as_operations_list_remove_by_rank_range(&ops2, "l", NULL, 2, 2,

    AS_LIST_RETURN_NONE | AS_LIST_RETURN_INVERTED);

aerospike_key_operate(&as, &err, NULL, &key, &ops2, NULL);

// l == [3, 2]
```

```csharp
// l = [1, 3, 2, 7, 0]

client.Operate(null, key,

    ListOperation.RemoveByRankRange("l", 2, 2, ListReturnType.NONE)

);

// l == [1, 7, 0]

// INVERTED: remove everything outside the range

// l = [1, 3, 2, 7, 0]

client.Operate(null, key,

    ListOperation.RemoveByRankRange("l", 2, 2,

        ListReturnType.NONE | ListReturnType.INVERTED)

);

// l == [3, 2]
```

```javascript
// l = [1, 3, 2, 7, 0]

const lists = Aerospike.lists

await client.operate(key, [

    lists.removeByRankRange('l', 2, 2).andReturn(lists.returnType.NONE)

])

// l == [1, 7, 0]

// INVERTED: remove everything outside the range

// l = [1, 3, 2, 7, 0]

await client.operate(key, [

    lists.removeByRankRange('l', 2, 2)

        .invertSelection()

        .andReturn(lists.returnType.NONE)

])

// l == [3, 2]
```

---

#### `remove_by_value_interval`

```python
remove_by_value_range(binName, valueBegin, valueEnd, returnType[, ctx])
```

Description: Removes the list elements that sort into the interval between _valueStart_ (inclusive) and _valueStop_ (exclusive). The `INVERTED` flag may be used to remove the elements outside this interval.

Returns: Zero, one or a list of values, based on the return type. The elements returned may not be in index order.

Order: Whether the list is unordered or ordered, `remove_by_value_interval` will return the same elements, based on the [ordering rules](https://aerospike.com/docs/develop/data-types/collections/ordering). The performance of ‘by value’ operations is better on an ordered list than an unordered one.

Performance: The worst-case performance of removing elements in a value interval is 𝓞(log N + M) for an ordered list with a persisted index, 𝓞(log N + N) for an ordered list without a persisted index, and 𝓞(N + M) for an unordered list, where M is the number of items in the parameter list and N is the number of items already in the list.

Examples: Trivial example

Remove the list elements in the interval between two scalar values. See the code sample below.

---

Interval comparison of tuples

It is common to model complex data in Aerospike as a list of tuples, each element a list, where the index order carries meaning. For an example, see [Aerospike Modeling: IoT Sensors](https://dev.to/aerospike/aerospike-modeling-iot-sensors-453a).

This modeling relies on the ordering rules that apply to list elements. Ordered pairs sort into

`[1, NIL]` < `[1, 1]` < `[1, 1, 2]` < `[1, 2]` < `[1, '1']` < `[1, 1.0]` < `[1, INF]`

Take the list of ordered pairs, `[[100, 1], [101, 2], [102, 3], [103, 4], [104, 5]]` and the following intervals:

**valueStart:** `[101, NIL]`, **valueStop:** `[103, NIL]`

Iterating over the elements we check if `[101, NIL] <= value < [103, NIL]`. This is true for the elements `[101, 2]` and `[102, 3]`. The element `[103, 4]` is not in this interval, because its order is higher than `[103, NIL]`. The comparison starts with the 0th index values, in this case both are 103. Next the 1st index position values are compared, and `NIL` is lower than 3 (actually its order is lower than _any_ value).

**valueStart:** `[101, NIL]`, **valueStop:** `[103, INF]`

The elements `[101, 2]` and `[102, 3]` are obviously in the interval. The element `[103, 4]` is also in this interval, because its order is lower than `[103, INF]`. The comparison starts with the 0th index values, in this case both are 103. Next the 1st index position values are compared, and `INF` is higher than 3 (actually its order is higher than _any_ value).

**valueStart:** `[101, INF]`, **valueStop:** `[103, INF]`

The elements `[102, 2]` and `[103, 4]` are in the interval. The element `[101, 2]` **is not** in this interval, because its order is lower than`[101, INF]`.

Code sample: -   [Java](#tab-panel-1948)
-   [Python](#tab-panel-1949)
-   [Go](#tab-panel-1950)
-   [C](#tab-panel-1951)
-   [C#](#tab-panel-1952)
-   [Node.js](#tab-panel-1953)

```java
// l = [1, 2, 3, 4, 5, 4, 3, 2, 1]

// remove all elements in the interval [2, 4), then read the bin

Record record = client.operate(null, key,

    ListOperation.removeByValueRange("l", Value.get(2), Value.get(4),

        ListReturnType.NONE),

    Operation.get("l")

);

// l == [1, 4, 5, 4, 1]
```

```python
# l = [1, 2, 3, 4, 5, 4, 3, 2, 1]

# remove all elements in the interval [2, 4), then read the bin

_, _, bins = client.operate(key, [

    list_operations.list_remove_by_value_range(

        "l", aerospike.LIST_RETURN_NONE, 2, 4),

    operations.read("l"),

])

# bins["l"] == [1, 4, 5, 4, 1]
```

```go
// l = [1, 2, 3, 4, 5, 4, 3, 2, 1]

// remove all elements in the interval [2, 4), then read the bin

record, err := client.Operate(nil, key,

    as.ListRemoveByValueRangeOp("l", as.ListReturnTypeNone, 2, 4),

    as.GetOpForBin("l"),

)

// record.Bins["l"] == [1, 4, 5, 4, 1]
```

```c
// l = [1, 2, 3, 4, 5, 4, 3, 2, 1]

// remove all elements in the interval [2, 4), then read the bin

as_integer begin;

as_integer_init(&begin, 2);

as_integer end;

as_integer_init(&end, 4);

as_operations ops;

as_operations_inita(&ops, 2);

as_operations_list_remove_by_value_range(&ops, "l", NULL,

    (as_val*)&begin, (as_val*)&end, AS_LIST_RETURN_NONE);

as_operations_add_read(&ops, "l");

as_record* rec = NULL;

aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);

// rec bins "l" == [1, 4, 5, 4, 1]
```

```csharp
// l = [1, 2, 3, 4, 5, 4, 3, 2, 1]

// remove all elements in the interval [2, 4), then read the bin

Record record = client.Operate(null, key,

    ListOperation.RemoveByValueRange("l", Value.Get(2), Value.Get(4),

        ListReturnType.NONE),

    Operation.Get("l")

);

// l == [1, 4, 5, 4, 1]
```

```javascript
// l = [1, 2, 3, 4, 5, 4, 3, 2, 1]

// remove all elements in the interval [2, 4), then read the bin

const lists = Aerospike.lists

const result = await client.operate(key, [

    lists.removeByValueRange('l', 2, 4).andReturn(lists.returnType.NONE),

    Aerospike.operations.read('l')

])

// result.bins.l == [1, 4, 5, 4, 1]
```

---

#### `remove_by_value_rel_rank_range`

```python
remove_by_value_rel_rank_range(binName, value, rank[, count], returnType[, ctx])
```

Description: Removes a range of _count_ elements starting at a specified _rank_, **relative to the given _value_**. The `INVERTED` flag may be used to remove the elements _not_ in a specified range.

The value can be anything, not necessarily a value that exists in the list. The rank and count can be any number, but the result may be an empty list if the specified range contains no elements.

Returns: Zero, one or a list of values, based on the return type. The elements returned may not be in rank order.

Order: The relative rank of the value compared to the current list follows the [ordering rules](https://aerospike.com/docs/develop/data-types/collections/ordering).

Performance: The worst-case performance of removing elements by relative rank range is 𝓞(M + log N) for an ordered list with a persisted index. An ordered list without a persisted index has a 𝓞(N + M + log N), where M is the element count of the range, and N is the element count of the list. An unordered list has a 𝓞(R log N + N), with R for rank.

Examples: Example

For `[0, 3, 9, 12, 15]` a value of 5 would rank between 3 and 9, relative to the current list. A rank of -1 from there would select 3 as the starting point of the range, and then the count would select the elements. So a count of 3 would remove the elements 3, 9 and 12.

Code sample: -   [Java](#tab-panel-1954)
-   [Python](#tab-panel-1955)
-   [Go](#tab-panel-1956)
-   [C](#tab-panel-1957)
-   [C#](#tab-panel-1958)
-   [Node.js](#tab-panel-1959)

```java
// scores = [0, 3, 9, 12, 15]

// Relative rank of value 5: between 3 and 9 (rank position 2)

// rank offset -1, count 3 → remove ranks 1..3

Record record = client.operate(null, key,

    ListOperation.removeByValueRelativeRankRange("scores",

        Value.get(5), -1, 3, ListReturnType.VALUE)

);

// returns [3, 9, 12]

// scores == [0, 15]
```

```python
# scores = [0, 3, 9, 12, 15]

_, _, bins = client.operate(key, [

    list_operations.list_remove_by_value_rank_range_relative(

        "scores", 5, -1, aerospike.LIST_RETURN_VALUE, 3)

])

# bins["scores"] == [3, 9, 12]

# scores == [0, 15]
```

```go
// scores = [0, 3, 9, 12, 15]

record, err := client.Operate(nil, key,

    as.ListRemoveByValueRelativeRankRangeCountOp("scores",

        as.ListReturnTypeValue, 5, -1, 3),

)

// record.Bins["scores"] == [3, 9, 12]

// scores == [0, 15]
```

```c
// scores = [0, 3, 9, 12, 15]

as_integer val;

as_integer_init(&val, 5);

as_operations ops;

as_operations_inita(&ops, 1);

as_operations_list_remove_by_value_rel_rank_range(&ops, "scores", NULL,

    (as_val*)&val, -1, 3, AS_LIST_RETURN_VALUE);

as_record* rec = NULL;

aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);

// rec bins "scores" == [3, 9, 12]
```

```csharp
// scores = [0, 3, 9, 12, 15]

Record record = client.Operate(null, key,

    ListOperation.RemoveByValueRelativeRankRange("scores",

        Value.Get(5), -1, 3, ListReturnType.VALUE)

);

// returns [3, 9, 12]

// scores == [0, 15]
```

```javascript
// scores = [0, 3, 9, 12, 15]

const lists = Aerospike.lists

const result = await client.operate(key, [

    lists.removeByValueRelRankRange('scores', 5, -1, 3)

        .andReturn(lists.returnType.VALUE)

])

// result.bins.scores == [3, 9, 12]

// scores == [0, 15]
```

---

#### `set`

```python
set(listPolicy, binName, index, value[, ctx])
```

Description: Creates an unordered list bin, if the bin does not exist. Sets or overwrites a value at the specified list index. (This set function has no relation to the Aerospike concept of sets as a collection of records.)

By default the index can be any number, and NIL values will be added as padding to the left of the new element, as needed. Using the `INSERT_BOUNDED` policy, a developer can limit this behavior, and only allow for an element to be set at an index value between 0 and the size of the list.

You cannot set a value in an ordered list, only [append](#append) or [append\_items](#append_items) to one.

Returns: The element count due to the operation, in the ‘bins’ part of the record under the _bin_ name.

Order: A list newly created with `set()` is always unordered.

A note on write flags

Write flags can be combined to alter the behavior of the operation. For example, `ADD_UNIQUE | NO_FAIL` will fail gracefully without throwing an exception if the element already exists.

`DO_PARTIAL` is not applicable for this operation, as we only set one element at a time.

Performance: The worst-case performance of setting an item at the head of a list (at its 0th index) is 𝓞(1). At any other index it is 𝓞(N).

Code sample: -   [Java](#tab-panel-1960)
-   [Python](#tab-panel-1961)
-   [Go](#tab-panel-1962)
-   [C](#tab-panel-1963)
-   [C#](#tab-panel-1964)
-   [Node.js](#tab-panel-1965)

```java
// scores = [10, 20, 30]

Record record = client.operate(null, key,

    ListOperation.set("scores", 1, Value.get(25))

);

// scores == [10, 25, 30]
```

```python
# scores = [10, 20, 30]

_, _, bins = client.operate(key, [

    list_operations.list_set("scores", 1, 25)

])

# scores == [10, 25, 30]
```

```go
// scores = [10, 20, 30]

_, err := client.Operate(nil, key,

    as.ListSetOp("scores", 1, 25),

)

// scores == [10, 25, 30]
```

```c
// scores = [10, 20, 30]

as_operations ops;

as_operations_inita(&ops, 1);

as_operations_list_set(&ops, "scores", NULL, NULL, 1,

    (as_val*)as_integer_new(25));

aerospike_key_operate(&as, &err, NULL, &key, &ops, NULL);

// scores == [10, 25, 30]
```

```csharp
// scores = [10, 20, 30]

client.Operate(null, key,

    ListOperation.Set("scores", 1, Value.Get(25))

);

// scores == [10, 25, 30]
```

```javascript
// scores = [10, 20, 30]

const lists = Aerospike.lists

await client.operate(key, [

    lists.set('scores', 1, 25)

])

// scores == [10, 25, 30]
```

---

#### `sort`

```python
sort(binName, sortFlags[, ctx])
```

Description: Sorts a list, but doesn’t change the list order. An unordered list will remain unordered after being sorted. An ordered list doesn’t need to be sorted, because by definition it sorts itself any time elements are added to it.

Returns: null

Sort Flags: | Flag | Description |
| --- | --- |
| `DEFAULT` | Default keep duplicates |
| `DROP_DUPLICATES` | Drop duplicates while sorting |

Performance: The sort operation will do no work when called on an already ordered list. The worst-case performance of sorting an unordered list is 𝓞(N log N).

Code sample: -   [Java](#tab-panel-1966)
-   [Python](#tab-panel-1967)
-   [Go](#tab-panel-1968)
-   [C](#tab-panel-1969)
-   [C#](#tab-panel-1970)
-   [Node.js](#tab-panel-1971)

```java
// scores = [30, 10, 50, 20, 40]

client.operate(null, key,

    ListOperation.sort("scores", ListSortFlags.DEFAULT)

);

// scores == [10, 20, 30, 40, 50]
```

```python
# scores = [30, 10, 50, 20, 40]

client.operate(key, [

    list_operations.list_sort("scores")

])

# scores == [10, 20, 30, 40, 50]
```

```go
// scores = [30, 10, 50, 20, 40]

_, err := client.Operate(nil, key,

    as.ListSortOp("scores", as.ListSortFlagsDefault),

)

// scores == [10, 20, 30, 40, 50]
```

```c
// scores = [30, 10, 50, 20, 40]

as_operations ops;

as_operations_inita(&ops, 1);

as_operations_list_sort(&ops, "scores", NULL, AS_LIST_SORT_DEFAULT);

aerospike_key_operate(&as, &err, NULL, &key, &ops, NULL);

// scores == [10, 20, 30, 40, 50]
```

```csharp
// scores = [30, 10, 50, 20, 40]

client.Operate(null, key,

    ListOperation.Sort("scores", ListSortFlags.DEFAULT)

);

// scores == [10, 20, 30, 40, 50]
```

```javascript
// scores = [30, 10, 50, 20, 40]

const lists = Aerospike.lists

await client.operate(key, [

    lists.sort('scores', lists.sortFlags.DEFAULT)

])

// scores == [10, 20, 30, 40, 50]
```

---

## Read operations

#### `get_all_by_value_list`

```python
get_by_value_list(binName, values, returnType[, ctx])
```

Description: Gets all the elements in the list matching one of the specified values. The `INVERTED` flag may be used to get the elements _not_ matching any of the values.

Whether the list is unordered or ordered, `get_all_by_value_list` will return the same elements, based on the [ordering rules](https://aerospike.com/docs/develop/data-types/collections/ordering). The performance of ‘by value’ operations is better on an ordered list than an unordered one.

Returns: Zero, one or a list of values, based on the return type. The elements returned may not be in index order.

Performance: The worst-case performance of getting elements by a value list is 𝓞((M+N) log M) for an ordered list with a persisted index, 𝓞((M+N) log M + N) for an ordered list without a persisted index, or for an unordered list, where M is the number of items in the parameter list and N is the number of items already in the list.

Examples: Trivial example

Count the number of elements in the list matching one of several specified scalar values. See the code sample below.

---

Matching tuples with wildcard

See the example given for [`get_all_by_value`](#get_all_by_value).

In a list of mostly ordered pairs, we could search for all the tuples that _do not_ start with “v1” or “v2”, by using a wildcard and an `INVERTED | VALUE` return type.

The wildcard matches any sequence of elements to the end of the tuple. In this example, this means matching any tuple whose first position is “v1” or “v2”, and whose size is two or more elements.

The wildcard has different language-specific constructs, such as `aerospike.CDTWildcard()` in the Python client and `Value.WILDCARD` in the Java client.

Code sample: -   [Java](#tab-panel-1990)
-   [Python](#tab-panel-1991)
-   [Go](#tab-panel-1992)
-   [C](#tab-panel-1993)
-   [C#](#tab-panel-1994)
-   [Node.js](#tab-panel-1995)

```java
// Trivial example

// l = [1, 2, 3, 2, 1]

List<Value> filterValues = Arrays.asList(Value.get(2), Value.get(3));

Record record = client.operate(null, key,

    ListOperation.getByValueList("l", filterValues, ListReturnType.COUNT)

);

// returns 3

// Matching tuples with wildcard (INVERTED)

// l = [["v1", 1], ["v2", 2], ["v3", 3], ["v2", 4]]

List<Value> patterns = Arrays.asList(

    Value.get(Arrays.asList("v2", Value.WILDCARD)),

    Value.get(Arrays.asList("v1", Value.WILDCARD))

);

record = client.operate(null, key,

    ListOperation.getByValueList("l", patterns,

        ListReturnType.VALUE | ListReturnType.INVERTED)

);

// returns [["v3", 3]]
```

```python
# Trivial example

# l = [1, 2, 3, 2, 1]

_, _, bins = client.operate(key, [

    list_operations.list_get_by_value_list("l", [2, 3], aerospike.LIST_RETURN_COUNT)

])

# bins["l"] == 3

# Matching tuples with wildcard (INVERTED)

# l = [["v1", 1], ["v2", 2], ["v3", 3], ["v2", 4]]

wildcard = aerospike.CDTWildcard()

_, _, bins = client.operate(key, [

    list_operations.list_get_by_value_list(

        "l", [["v2", wildcard], ["v1", wildcard]],

        aerospike.LIST_RETURN_VALUE, inverted=True,

    )

])

# bins["l"] == [["v3", 3]]
```

```go
// Trivial example

// l = [1, 2, 3, 2, 1]

record, err := client.Operate(nil, key,

    as.ListGetByValueListOp("l", []any{2, 3}, as.ListReturnTypeCount),

)

// record.Bins["l"] == 3

// Matching tuples with wildcard (INVERTED)

// l = [["v1", 1], ["v2", 2], ["v3", 3], ["v2", 4]]

record, err = client.Operate(nil, key,

    as.ListGetByValueListOp("l",

        []any{

            []any{"v2", as.NewWildCardValue()},

            []any{"v1", as.NewWildCardValue()},

        },

        as.ListReturnTypeValue|as.ListReturnTypeInverted),

)

// record.Bins["l"] == [["v3", 3]]
```

```c
// Trivial example

// l = [1, 2, 3, 2, 1]

as_arraylist values;

as_arraylist_inita(&values, 2);

as_arraylist_append_int64(&values, 2);

as_arraylist_append_int64(&values, 3);

as_operations ops;

as_operations_inita(&ops, 1);

as_operations_list_get_by_value_list(&ops, "l", NULL,

    (as_list*)&values, AS_LIST_RETURN_COUNT);

as_record* rec = NULL;

aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);

// rec bins "l" == 3

// Matching tuples with wildcard (INVERTED)

// l = [["v1", 1], ["v2", 2], ["v3", 3], ["v2", 4]]

as_arraylist pat1;

as_arraylist_inita(&pat1, 2);

as_arraylist_append_str(&pat1, "v2");

as_arraylist_append(&pat1, (as_val*)&as_cdt_wildcard);

as_arraylist pat2;

as_arraylist_inita(&pat2, 2);

as_arraylist_append_str(&pat2, "v1");

as_arraylist_append(&pat2, (as_val*)&as_cdt_wildcard);

as_arraylist patterns;

as_arraylist_inita(&patterns, 2);

as_arraylist_append(&patterns, (as_val*)&pat1);

as_arraylist_append(&patterns, (as_val*)&pat2);

as_operations ops2;

as_operations_inita(&ops2, 1);

as_operations_list_get_by_value_list(&ops2, "l", NULL,

    (as_list*)&patterns, AS_LIST_RETURN_VALUE | AS_LIST_RETURN_INVERTED);

as_record* rec2 = NULL;

aerospike_key_operate(&as, &err, NULL, &key, &ops2, &rec2);

// rec2 bins "l" == [["v3", 3]]
```

```csharp
// Trivial example

// l = [1, 2, 3, 2, 1]

IList filterValues = new List<Value> {

    Value.Get(2), Value.Get(3)

};

Record record = client.Operate(null, key,

    ListOperation.GetByValueList("l", filterValues, ListReturnType.COUNT)

);

// returns 3

// Matching tuples with wildcard (INVERTED)

// l = [["v1", 1], ["v2", 2], ["v3", 3], ["v2", 4]]

IList patterns = new List<Value> {

    Value.Get(new List<Value> { Value.Get("v2"), Value.AsNull }),

    Value.Get(new List<Value> { Value.Get("v1"), Value.AsNull })

};

record = client.Operate(null, key,

    ListOperation.GetByValueList("l", patterns,

        ListReturnType.VALUE | ListReturnType.INVERTED)

);

// returns [["v3", 3]]
```

```javascript
// Trivial example

// l = [1, 2, 3, 2, 1]

const lists = Aerospike.lists

let result = await client.operate(key, [

    lists.getByValueList('l', [2, 3]).andReturn(lists.returnType.COUNT)

])

// result.bins.l == 3

// Matching tuples with wildcard (INVERTED)

// l = [["v1", 1], ["v2", 2], ["v3", 3], ["v2", 4]]

result = await client.operate(key, [

    lists.getByValueList('l',

        [['v2', new Aerospike.Wildcard()], ['v1', new Aerospike.Wildcard()]])

        .invertSelection()

        .andReturn(lists.returnType.VALUE)

])

// result.bins.l == [["v3", 3]]
```

---

#### `get_all_by_value`

```python
get_by_value(binName, value, returnType[, ctx])
```

Description: Gets all the elements in the list matching _value_. The `INVERTED` flag may be used to get the elements _not_ matching the specified value.

Whether the list is unordered or ordered, `get_all_by_value` will return the same elements, based on the [ordering rules](https://aerospike.com/docs/develop/data-types/collections/ordering). The performance of ‘by value’ operations is better on an ordered list than an unordered one.

Returns: Zero, one or a list of values, based on the return type. The elements returned may not be in index order.

Performance: The worst-case performance of getting elements by value is 𝓞(log N + M) for an ordered list with a persisted index, 𝓞(log N + N) for an ordered list without a persisted index, and 𝓞(N + M) for an unordered list, where M is the number of items in the parameter list and N is the number of items already in the list.

Examples: Trivial example

Count the number of elements in the list with a specified scalar value. See the code sample below.

---

Matching tuples with wildcard

It is common to model complex data in Aerospike as a list of tuples, each element a list, where the index order carries meaning. For an example, see [Aerospike Modeling: IoT Sensors](https://dev.to/aerospike/aerospike-modeling-iot-sensors-453a).

In a list of mostly ordered pairs, we could search for a specific kind of element, such as all the tuples where the 0th position is “v2”, by using a wildcard (typically stylized as a \* in documentation).

The wildcard matches any sequence of elements to the end of the tuple. In this example, this means matching any tuple whose first position is “v2”, and whose size is two or more elements.

The wildcard has different language-specific constructs, such as `aerospike.CDTWildcard()` in the Python client and `Value.WILDCARD` in the Java client.

Code sample: -   [Java](#tab-panel-1978)
-   [Python](#tab-panel-1979)
-   [Go](#tab-panel-1980)
-   [C](#tab-panel-1981)
-   [C#](#tab-panel-1982)
-   [Node.js](#tab-panel-1983)

```java
// Trivial example

// l = [1, 2, 1, 2]

Record record = client.operate(null, key,

    ListOperation.getByValue("l", Value.get(2), ListReturnType.COUNT)

);

// returns 2

// Matching tuples with wildcard

// l = [["v1", 1], ["v2", 2], ["v1", 3], ["v2", 4, {"a": 1}]]

record = client.operate(null, key,

    ListOperation.getByValue("l", Value.get(Arrays.asList("v2", Value.WILDCARD)),

        ListReturnType.VALUE)

);

// returns [["v2", 2], ["v2", 4, {"a": 1}]]
```

```python
# Trivial example

# l = [1, 2, 1, 2]

_, _, bins = client.operate(key, [

    list_operations.list_get_by_value("l", 2, aerospike.LIST_RETURN_COUNT)

])

# bins["l"] == 2

# Matching tuples with wildcard

# l = [["v1", 1], ["v2", 2], ["v1", 3], ["v2", 4, {"a": 1}]]

_, _, bins = client.operate(key, [

    list_operations.list_get_by_value(

        "l", ["v2", aerospike.CDTWildcard()], aerospike.LIST_RETURN_VALUE

    )

])

# bins["l"] == [["v2", 2], ["v2", 4, {"a": 1}]]
```

```go
// Trivial example

// l = [1, 2, 1, 2]

record, err := client.Operate(nil, key,

    as.ListGetByValueOp("l", 2, as.ListReturnTypeCount),

)

// record.Bins["l"] == 2

// Matching tuples with wildcard

// l = [["v1", 1], ["v2", 2], ["v1", 3], ["v2", 4, {"a": 1}]]

record, err = client.Operate(nil, key,

    as.ListGetByValueOp("l", []any{"v2", as.NewWildCardValue()},

        as.ListReturnTypeValue),

)

// record.Bins["l"] == [["v2", 2], ["v2", 4, {"a": 1}]]
```

```c
// Trivial example

// l = [1, 2, 1, 2]

as_integer val;

as_integer_init(&val, 2);

as_operations ops;

as_operations_inita(&ops, 1);

as_operations_list_get_by_value(&ops, "l", NULL,

    (as_val*)&val, AS_LIST_RETURN_COUNT);

as_record* rec = NULL;

aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);

// rec bins "l" == 2

// Matching tuples with wildcard

// l = [["v1", 1], ["v2", 2], ["v1", 3], ["v2", 4, {"a": 1}]]

as_arraylist match;

as_arraylist_inita(&match, 2);

as_arraylist_append_str(&match, "v2");

as_arraylist_append(&match, (as_val*)&as_cdt_wildcard);

as_operations ops2;

as_operations_inita(&ops2, 1);

as_operations_list_get_by_value(&ops2, "l", NULL,

    (as_val*)&match, AS_LIST_RETURN_VALUE);

as_record* rec2 = NULL;

aerospike_key_operate(&as, &err, NULL, &key, &ops2, &rec2);

// rec2 bins "l" == [["v2", 2], ["v2", 4, {"a": 1}]]
```

```csharp
// Trivial example

// l = [1, 2, 1, 2]

Record record = client.Operate(null, key,

    ListOperation.GetByValue("l", Value.Get(2), ListReturnType.COUNT)

);

// returns 2

// Matching tuples with wildcard

// l = [["v1", 1], ["v2", 2], ["v1", 3], ["v2", 4, {"a": 1}]]

record = client.Operate(null, key,

    ListOperation.GetByValue("l",

        Value.Get(new List<Value> { Value.Get("v2"), Value.AsNull }),

        ListReturnType.VALUE)

);

// returns [["v2", 2], ["v2", 4, {"a": 1}]]
```

```javascript
// Trivial example

// l = [1, 2, 1, 2]

const lists = Aerospike.lists

let result = await client.operate(key, [

    lists.getByValue('l', 2).andReturn(lists.returnType.COUNT)

])

// result.bins.l == 2

// Matching tuples with wildcard

// l = [["v1", 1], ["v2", 2], ["v1", 3], ["v2", 4, {"a": 1}]]

result = await client.operate(key, [

    lists.getByValue('l', ['v2', new Aerospike.Wildcard()])

        .andReturn(lists.returnType.VALUE)

])

// result.bins.l == [["v2", 2], ["v2", 4, {"a": 1}]]
```

---

#### `get_by_index_range`

```python
get_by_index_range(binName, index[, count], returnType[, ctx])
```

Description: Gets a range of _count_ elements starting at a specified list index. The `INVERTED` flag may be used to get the elements _not_ in a specified range.

The index and count can be any number, but the result may be an empty list if the specified range contains no elements.

Returns: One or a list values, based on the return type. The elements returned may not be in index order.

A note on return types

`INDEX` is redundant in this operation.

Performance: The worst-case performance of getting elements by index range is 𝓞(M) for an ordered list with a persisted index, and 𝓞(N + M) for an ordered list without a persisted index or an unordered list, where M is the element count of the range, and N is the element count of the list. Requesting a `RANK` return type on an unordered list adds 𝓞(L\*N). See [List performance](https://aerospike.com/docs/develop/data-types/collections/list/performance).

Examples: Example

For `[1, 3, 3, 7, 0]` the `VALUE` range starting at index 2 and containing 3 elements gives back `[3, 7, 0]`, while the `INVERTED | VALUE` of the same range gives back `[1, 3]`.

Code sample: -   [Java](#tab-panel-1972)
-   [Python](#tab-panel-1973)
-   [Go](#tab-panel-1974)
-   [C](#tab-panel-1975)
-   [C#](#tab-panel-1976)
-   [Node.js](#tab-panel-1977)

```java
// l = [1, 3, 3, 7, 0]

Record record = client.operate(null, key,

    ListOperation.getByIndexRange("l", 2, 3, ListReturnType.VALUE)

);

// returns [3, 7, 0]

record = client.operate(null, key,

    ListOperation.getByIndexRange("l", 2, 3,

        ListReturnType.VALUE | ListReturnType.INVERTED)

);

// returns [1, 3]
```

```python
# l = [1, 3, 3, 7, 0]

_, _, bins = client.operate(key, [

    list_operations.list_get_by_index_range("l", 2, aerospike.LIST_RETURN_VALUE, 3)

])

# bins["l"] == [3, 7, 0]

_, _, bins = client.operate(key, [

    list_operations.list_get_by_index_range(

        "l", 2, aerospike.LIST_RETURN_VALUE | aerospike.LIST_RETURN_INVERTED, 3)

])

# bins["l"] == [1, 3]
```

```go
// l = [1, 3, 3, 7, 0]

record, err := client.Operate(nil, key,

    as.ListGetByIndexRangeCountOp("l", 2, 3, as.ListReturnTypeValue),

)

// record.Bins["l"] == [3, 7, 0]

record, err = client.Operate(nil, key,

    as.ListGetByIndexRangeCountOp("l", 2, 3,

        as.ListReturnTypeValue|as.ListReturnTypeInverted),

)

// record.Bins["l"] == [1, 3]
```

```c
// l = [1, 3, 3, 7, 0]

as_operations ops;

as_operations_inita(&ops, 1);

as_operations_list_get_by_index_range(&ops, "l", NULL, 2, 3,

    AS_LIST_RETURN_VALUE);

as_record* rec = NULL;

aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);

// rec bins "l" == [3, 7, 0]

as_operations ops2;

as_operations_inita(&ops2, 1);

as_operations_list_get_by_index_range(&ops2, "l", NULL, 2, 3,

    AS_LIST_RETURN_VALUE | AS_LIST_RETURN_INVERTED);

as_record* rec2 = NULL;

aerospike_key_operate(&as, &err, NULL, &key, &ops2, &rec2);

// rec2 bins "l" == [1, 3]
```

```csharp
// l = [1, 3, 3, 7, 0]

Record record = client.Operate(null, key,

    ListOperation.GetByIndexRange("l", 2, 3, ListReturnType.VALUE)

);

// returns [3, 7, 0]

record = client.Operate(null, key,

    ListOperation.GetByIndexRange("l", 2, 3,

        ListReturnType.VALUE | ListReturnType.INVERTED)

);

// returns [1, 3]
```

```javascript
// l = [1, 3, 3, 7, 0]

const lists = Aerospike.lists

let result = await client.operate(key, [

    lists.getByIndexRange('l', 2, 3).andReturn(lists.returnType.VALUE)

])

// result.bins.l == [3, 7, 0]

result = await client.operate(key, [

    lists.getByIndexRange('l', 2, 3)

        .invertSelection()

        .andReturn(lists.returnType.VALUE)

])

// result.bins.l == [1, 3]
```

---

#### `get_by_index`

```python
get_by_index(binName, index, returnType[, ctx])
```

Description: Gets the element at the specified list index. The index must be a number between 0 and N-1, where N is the length of the list. The index can also be a negative number, with -1 being the last element by index position.

On an ordered list this operation with a `VALUE` return type will be the same as a list [`get_by_rank`](#get_by_rank) operation.

Returns: A single result, based on the return type.

A note on return types

`INDEX` and `COUNT` are redundant in this operation. `INVERTED` has no meaning in this operation.

Throws: An Operation Not Applicable error (code 26) when trying to get an inaccessible index.

Performance: The worst-case performance of getting the element by index is 𝓞(1) for an ordered list with a persisted index, and 𝓞(N) for an ordered list without a persisted index or an unordered list.

Examples: Example

`[1, 3, 3, 7, 0]` modified with [`set_order`](#set_order) to `ORDERED` will turn into `[0, 1, 3, 3, 7]`.

The value of the element at index -1 is 7, the rank at -1 is 7.

The value of the element at index 2 is 3, the element with rank 2 is 3.

Code sample: -   [Java](#tab-panel-1984)
-   [Python](#tab-panel-1985)
-   [Go](#tab-panel-1986)
-   [C](#tab-panel-1987)
-   [C#](#tab-panel-1988)
-   [Node.js](#tab-panel-1989)

```java
// l = [0, 1, 3, 3, 7] (ORDERED)

Record record = client.operate(null, key,

    ListOperation.getByIndex("l", 2, ListReturnType.VALUE)

);

// returns 3

record = client.operate(null, key,

    ListOperation.getByIndex("l", 2, ListReturnType.RANK)

);

// returns 2

record = client.operate(null, key,

    ListOperation.getByIndex("l", -1, ListReturnType.VALUE)

);

// returns 7
```

```python
# l = [0, 1, 3, 3, 7] (ORDERED)

_, _, bins = client.operate(key, [

    list_operations.list_get_by_index("l", 2, aerospike.LIST_RETURN_VALUE)

])

# bins["l"] == 3

_, _, bins = client.operate(key, [

    list_operations.list_get_by_index("l", 2, aerospike.LIST_RETURN_RANK)

])

# bins["l"] == 2

_, _, bins = client.operate(key, [

    list_operations.list_get_by_index("l", -1, aerospike.LIST_RETURN_VALUE)

])

# bins["l"] == 7
```

```go
// l = [0, 1, 3, 3, 7] (ORDERED)

record, err := client.Operate(nil, key,

    as.ListGetByIndexOp("l", 2, as.ListReturnTypeValue),

)

// record.Bins["l"] == 3

record, err = client.Operate(nil, key,

    as.ListGetByIndexOp("l", 2, as.ListReturnTypeRank),

)

// record.Bins["l"] == 2

record, err = client.Operate(nil, key,

    as.ListGetByIndexOp("l", -1, as.ListReturnTypeValue),

)

// record.Bins["l"] == 7
```

```c
// l = [0, 1, 3, 3, 7] (ORDERED)

as_operations ops;

as_operations_inita(&ops, 1);

as_operations_list_get_by_index(&ops, "l", NULL, 2, AS_LIST_RETURN_VALUE);

as_record* rec = NULL;

aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);

// rec bins "l" == 3

as_operations ops2;

as_operations_inita(&ops2, 1);

as_operations_list_get_by_index(&ops2, "l", NULL, -1, AS_LIST_RETURN_VALUE);

as_record* rec2 = NULL;

aerospike_key_operate(&as, &err, NULL, &key, &ops2, &rec2);

// rec2 bins "l" == 7
```

```csharp
// l = [0, 1, 3, 3, 7] (ORDERED)

Record record = client.Operate(null, key,

    ListOperation.GetByIndex("l", 2, ListReturnType.VALUE)

);

// returns 3

record = client.Operate(null, key,

    ListOperation.GetByIndex("l", 2, ListReturnType.RANK)

);

// returns 2

record = client.Operate(null, key,

    ListOperation.GetByIndex("l", -1, ListReturnType.VALUE)

);

// returns 7
```

```javascript
// l = [0, 1, 3, 3, 7] (ORDERED)

const lists = Aerospike.lists

let result = await client.operate(key, [

    lists.getByIndex('l', 2).andReturn(lists.returnType.VALUE)

])

// result.bins.l == 3

result = await client.operate(key, [

    lists.getByIndex('l', 2).andReturn(lists.returnType.RANK)

])

// result.bins.l == 2

result = await client.operate(key, [

    lists.getByIndex('l', -1).andReturn(lists.returnType.VALUE)

])

// result.bins.l == 7
```

---

#### `get_by_rank_range`

```python
get_by_rank_range(binName, rank[, count], returnType[, ctx])
```

Description: Gets a range of _count_ elements starting at a specified rank. The `INVERTED` flag may be used to get the elements _not_ in a specified range.

The rank and count can be any number, but the result may be an empty list if the specified range contains no elements.

Returns: One or a list of values, based on the return type. The elements returned may not be in rank order.

A note on return types

`INDEX` is redundant in this operation.

Performance: The worst-case performance of getting elements by rank range is 𝓞(M) for an ordered list with a persisted index. An ordered list without a persisted index has a 𝓞(N + M), where M is the element count of the range, and N is the element count of the list. An unordered list has a 𝓞(R log N + N).

Examples: Example

For `[1, 3, 2, 7, 0]` the `VALUE` range starting at rank 2 and containing 2 elements gives back `[2, 3]`, while the `INVERTED | VALUE` of the same range gives back `[0, 1, 7]`.

Code sample: -   [Java](#tab-panel-1996)
-   [Python](#tab-panel-1997)
-   [Go](#tab-panel-1998)
-   [C](#tab-panel-1999)
-   [C#](#tab-panel-2000)
-   [Node.js](#tab-panel-2001)

```java
// l = [1, 3, 2, 7, 0]

Record record = client.operate(null, key,

    ListOperation.getByRankRange("l", 2, 2, ListReturnType.VALUE)

);

// returns [2, 3]

record = client.operate(null, key,

    ListOperation.getByRankRange("l", 2, 2,

        ListReturnType.VALUE | ListReturnType.INVERTED)

);

// returns [0, 1, 7]
```

```python
# l = [1, 3, 2, 7, 0]

_, _, bins = client.operate(key, [

    list_operations.list_get_by_rank_range("l", 2, aerospike.LIST_RETURN_VALUE, 2)

])

# bins["l"] == [2, 3]

_, _, bins = client.operate(key, [

    list_operations.list_get_by_rank_range(

        "l", 2, aerospike.LIST_RETURN_VALUE | aerospike.LIST_RETURN_INVERTED, 2)

])

# bins["l"] == [0, 1, 7]
```

```go
// l = [1, 3, 2, 7, 0]

record, err := client.Operate(nil, key,

    as.ListGetByRankRangeCountOp("l", 2, 2, as.ListReturnTypeValue),

)

// record.Bins["l"] == [2, 3]

record, err = client.Operate(nil, key,

    as.ListGetByRankRangeCountOp("l", 2, 2,

        as.ListReturnTypeValue|as.ListReturnTypeInverted),

)

// record.Bins["l"] == [0, 1, 7]
```

```c
// l = [1, 3, 2, 7, 0]

as_operations ops;

as_operations_inita(&ops, 1);

as_operations_list_get_by_rank_range(&ops, "l", NULL, 2, 2,

    AS_LIST_RETURN_VALUE);

as_record* rec = NULL;

aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);

// rec bins "l" == [2, 3]

as_operations ops2;

as_operations_inita(&ops2, 1);

as_operations_list_get_by_rank_range(&ops2, "l", NULL, 2, 2,

    AS_LIST_RETURN_VALUE | AS_LIST_RETURN_INVERTED);

as_record* rec2 = NULL;

aerospike_key_operate(&as, &err, NULL, &key, &ops2, &rec2);

// rec2 bins "l" == [0, 1, 7]
```

```csharp
// l = [1, 3, 2, 7, 0]

Record record = client.Operate(null, key,

    ListOperation.GetByRankRange("l", 2, 2, ListReturnType.VALUE)

);

// returns [2, 3]

record = client.Operate(null, key,

    ListOperation.GetByRankRange("l", 2, 2,

        ListReturnType.VALUE | ListReturnType.INVERTED)

);

// returns [0, 1, 7]
```

```javascript
// l = [1, 3, 2, 7, 0]

const lists = Aerospike.lists

let result = await client.operate(key, [

    lists.getByRankRange('l', 2, 2).andReturn(lists.returnType.VALUE)

])

// result.bins.l == [2, 3]

result = await client.operate(key, [

    lists.getByRankRange('l', 2, 2)

        .invertSelection()

        .andReturn(lists.returnType.VALUE)

])

// result.bins.l == [0, 1, 7]
```

---

#### `get_by_rank`

```python
get_by_rank(binName, rank, returnType[, ctx])
```

Description: Gets the element with the specified rank order. The rank must be a number between 0 (lowest rank) and N-1 (highest rank), where N is the length of the list. The rank can also be a negative number, with -1 being the element with the highest rank.

On an ordered list this operation with a `VALUE` return type will be the same as a list [`get_by_index`](#get_by_index) operation, (see [this example](#get_by_index)).

Whether the list is unordered or ordered, `get_by_rank` will return the same elements, based on the [ordering rules](https://aerospike.com/docs/develop/data-types/collections/ordering). The performance of ‘by rank’ operations is better on an ordered list than an unordered one.

Returns: A single result, based on the return type.

A note on return types

`RANK` and `COUNT` are redundant in this operation. `INVERTED` has no meaning in this operation.

Throws: An Operation Not Applicable error (code 26) when trying to get an inaccessible rank.

Performance: The worst-case performance of getting an element by rank is 𝓞(1) for an ordered list with a persisted index, 𝓞(N) for an ordered list without a persisted index, and 𝓞(R log N + N) for an unordered list.

Examples: Example

For `[30, 10, 50, 20, 40]` the element at rank 0 is 10 (lowest value), and the element at rank -1 is 50 (highest value).

Code sample: -   [Java](#tab-panel-2002)
-   [Python](#tab-panel-2003)
-   [Go](#tab-panel-2004)
-   [C](#tab-panel-2005)
-   [C#](#tab-panel-2006)
-   [Node.js](#tab-panel-2007)

```java
// l = [30, 10, 50, 20, 40]

Record record = client.operate(null, key,

    ListOperation.getByRank("l", 0, ListReturnType.VALUE)

);

// returns 10 (lowest rank)

record = client.operate(null, key,

    ListOperation.getByRank("l", -1, ListReturnType.VALUE)

);

// returns 50 (highest rank)

record = client.operate(null, key,

    ListOperation.getByRank("l", -1, ListReturnType.INDEX)

);

// returns 2
```

```python
# l = [30, 10, 50, 20, 40]

_, _, bins = client.operate(key, [

    list_operations.list_get_by_rank("l", 0, aerospike.LIST_RETURN_VALUE)

])

# bins["l"] == 10

_, _, bins = client.operate(key, [

    list_operations.list_get_by_rank("l", -1, aerospike.LIST_RETURN_VALUE)

])

# bins["l"] == 50

_, _, bins = client.operate(key, [

    list_operations.list_get_by_rank("l", -1, aerospike.LIST_RETURN_INDEX)

])

# bins["l"] == 2
```

```go
// l = [30, 10, 50, 20, 40]

record, err := client.Operate(nil, key,

    as.ListGetByRankOp("l", 0, as.ListReturnTypeValue),

)

// record.Bins["l"] == 10

record, err = client.Operate(nil, key,

    as.ListGetByRankOp("l", -1, as.ListReturnTypeValue),

)

// record.Bins["l"] == 50

record, err = client.Operate(nil, key,

    as.ListGetByRankOp("l", -1, as.ListReturnTypeIndex),

)

// record.Bins["l"] == 2
```

```c
// l = [30, 10, 50, 20, 40]

as_operations ops;

as_operations_inita(&ops, 1);

as_operations_list_get_by_rank(&ops, "l", NULL, 0, AS_LIST_RETURN_VALUE);

as_record* rec = NULL;

aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);

// rec bins "l" == 10

as_operations ops2;

as_operations_inita(&ops2, 1);

as_operations_list_get_by_rank(&ops2, "l", NULL, -1, AS_LIST_RETURN_VALUE);

as_record* rec2 = NULL;

aerospike_key_operate(&as, &err, NULL, &key, &ops2, &rec2);

// rec2 bins "l" == 50
```

```csharp
// l = [30, 10, 50, 20, 40]

Record record = client.Operate(null, key,

    ListOperation.GetByRank("l", 0, ListReturnType.VALUE)

);

// returns 10

record = client.Operate(null, key,

    ListOperation.GetByRank("l", -1, ListReturnType.VALUE)

);

// returns 50

record = client.Operate(null, key,

    ListOperation.GetByRank("l", -1, ListReturnType.INDEX)

);

// returns 2
```

```javascript
// l = [30, 10, 50, 20, 40]

const lists = Aerospike.lists

let result = await client.operate(key, [

    lists.getByRank('l', 0).andReturn(lists.returnType.VALUE)

])

// result.bins.l == 10

result = await client.operate(key, [

    lists.getByRank('l', -1).andReturn(lists.returnType.VALUE)

])

// result.bins.l == 50

result = await client.operate(key, [

    lists.getByRank('l', -1).andReturn(lists.returnType.INDEX)

])

// result.bins.l == 2
```

---

#### `get_by_value_interval`

```python
get_by_value_range(binName, valueBegin, valueEnd, returnType[, ctx])
```

Description: Gets the list elements that sort into the interval between _valueStart_ (inclusive) and _valueStop_ (exclusive). The `INVERTED` flag may be used to get the elements outside this interval.

Whether the list is unordered or ordered, `get_by_value_interval` will return the same elements, based on the [ordering rules](https://aerospike.com/docs/develop/data-types/collections/ordering). The performance of ‘by value’ operations is better on an ordered list than an unordered one.

Returns: Zero, one or a list of values, based on the return type. The elements returned may not be in index order.

Performance: The worst-case performance of getting elements in a value interval is 𝓞(log N + M) for an ordered list with a persisted index, 𝓞(log N + N) for an ordered list without a persisted index, and 𝓞(N + M) for an unordered list, where M is the number of items in the parameter list and N is the number of items already in the list.

Examples: Trivial example

Get the list elements in the interval between two scalar values. See the code sample below.

---

Interval comparison of tuples

It is common to model complex data in Aerospike as a list of tuples, each element a list, where the index order carries meaning. For an example, see [Aerospike Modeling: IoT Sensors](https://dev.to/aerospike/aerospike-modeling-iot-sensors-453a).

This modeling relies on the ordering rules that apply to list elements. Ordered pairs sort into

`[1, NIL]` < `[1, 1]` < `[1, 1, 2]` < `[1, 2]` < `[1, '1']` < `[1, 1.0]` < `[1, INF]`

Take the list of ordered pairs, `[[100, 1], [101, 2], [102, 3], [103, 4], [104, 5]]` and the following intervals:

**valueStart:** `[101, NIL]`, **valueStop:** `[103, NIL]`

Iterating over the elements we check if `[101, NIL] <= value < [103, NIL]`. This is true for the elements `[101, 2]` and `[102, 3]`. The element `[103, 4]` is not in this interval, because its order is higher than `[103, NIL]`. The comparison starts with the 0th index values, in this case both are 103. Next the 1st index position values are compared, and `NIL` is lower than 3 (actually its order is lower than _any_ value).

**valueStart:** `[101, NIL]`, **valueStop:** `[103, INF]`

The elements `[101, 2]` and `[102, 3]` are obviously in the interval. The element `[103, 4]` is also in this interval, because its order is lower than `[103, INF]`. The comparison starts with the 0th index values, in this case both are 103. Next the 1st index position values are compared, and `INF` is higher than 3 (actually its order is higher than _any_ value).

**valueStart:** `[101, INF]`, **valueStop:** `[103, INF]`

The elements `[102, 2]` and `[103, 4]` are in the interval. The element `[101, 2]` **is not** in this interval, because its order is lower than `[101, INF]`.

Code sample: -   [Java](#tab-panel-2008)
-   [Python](#tab-panel-2009)
-   [Go](#tab-panel-2010)
-   [C](#tab-panel-2011)
-   [C#](#tab-panel-2012)
-   [Node.js](#tab-panel-2013)

```java
// l = [1, 2, 3, 4, 5, 4, 3, 2, 1]

// get all elements in the interval [2, 4)

Record record = client.operate(null, key,

    ListOperation.getByValueRange("l", Value.get(2), Value.get(4),

        ListReturnType.VALUE)

);

// returns [2, 3, 3, 2]
```

```python
# l = [1, 2, 3, 4, 5, 4, 3, 2, 1]

# get all elements in the interval [2, 4)

_, _, bins = client.operate(key, [

    list_operations.list_get_by_value_range(

        "l", aerospike.LIST_RETURN_VALUE, 2, 4)

])

# bins["l"] == [2, 3, 3, 2]
```

```go
// l = [1, 2, 3, 4, 5, 4, 3, 2, 1]

// get all elements in the interval [2, 4)

record, err := client.Operate(nil, key,

    as.ListGetByValueRangeOp("l", 2, 4, as.ListReturnTypeValue),

)

// record.Bins["l"] == [2, 3, 3, 2]
```

```c
// l = [1, 2, 3, 4, 5, 4, 3, 2, 1]

// get all elements in the interval [2, 4)

as_integer begin;

as_integer_init(&begin, 2);

as_integer end;

as_integer_init(&end, 4);

as_operations ops;

as_operations_inita(&ops, 1);

as_operations_list_get_by_value_range(&ops, "l", NULL,

    (as_val*)&begin, (as_val*)&end, AS_LIST_RETURN_VALUE);

as_record* rec = NULL;

aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);

// rec bins "l" == [2, 3, 3, 2]
```

```csharp
// l = [1, 2, 3, 4, 5, 4, 3, 2, 1]

// get all elements in the interval [2, 4)

Record record = client.Operate(null, key,

    ListOperation.GetByValueRange("l", Value.Get(2), Value.Get(4),

        ListReturnType.VALUE)

);

// returns [2, 3, 3, 2]
```

```javascript
// l = [1, 2, 3, 4, 5, 4, 3, 2, 1]

// get all elements in the interval [2, 4)

const lists = Aerospike.lists

const result = await client.operate(key, [

    lists.getByValueRange('l', 2, 4).andReturn(lists.returnType.VALUE)

])

// result.bins.l == [2, 3, 3, 2]
```

---

#### `get_by_value_rel_rank_range`

```python
get_by_value_rel_rank_range(binName, value, rank[, count], returnType[, ctx])
```

Description: Gets a range of _count_ elements starting at a _rank_ offset from the **relative rank of the given _value_**. The `INVERTED` flag may be used to get the elements _not_ in this range.

The value can be anything, not necessarily a value that exists in the list. The rank and count can be any number, but the result may be an empty list if the specified range contains no elements.

The relative rank of the value compared to the current list follows the [ordering rules](https://aerospike.com/docs/develop/data-types/collections/ordering).

Returns: Zero, one or a list of values, based on the return type. The elements returned may not be in index order.

Performance: The worst-case performance of getting elements by relative rank range is 𝓞(M + log N) for an ordered list with a persisted index. An ordered list without a persisted index has a 𝓞(N + M + log N), where M is the element count of the range, and N is the element count of the list. An unordered list has a 𝓞(R log N + N), with R for rank.

Formula: ```python
origin = relative-rank(_value_) # compared to the current list elements

r = rank(element)

Get all elements in the range where

(r >= (origin + _rank_)) and (r < (origin + _rank_ + _count_))
```

Examples: Example

For `[0, 3, 9, 12, 15]` a value of 5 would rank between 3 and 9, relative to the current list. A rank of -1 from there would select 3 as the starting point of the range, and then the count would select the elements. So a count of 3 would return the range 3, 9 and 12.

Code sample: -   [Java](#tab-panel-2014)
-   [Python](#tab-panel-2015)
-   [Go](#tab-panel-2016)
-   [C](#tab-panel-2017)
-   [C#](#tab-panel-2018)
-   [Node.js](#tab-panel-2019)

```java
// scores = [0, 3, 9, 12, 15]

// Relative rank of value 5: between 3 and 9 (rank position 2)

// rank offset -1, count 3 → start at rank 1, get 3 elements

Record record = client.operate(null, key,

    ListOperation.getByValueRelativeRankRange("scores",

        Value.get(5), -1, 3, ListReturnType.VALUE)

);

// returns [3, 9, 12]
```

```python
# scores = [0, 3, 9, 12, 15]

# Relative rank of value 5: between 3 and 9 (rank position 2)

# rank offset -1, count 3 -> start at rank 1, get 3 elements

_, _, bins = client.operate(key, [

    list_operations.list_get_by_value_rank_range_relative(

        "scores", 5, -1, aerospike.LIST_RETURN_VALUE, 3)

])

# bins["scores"] == [3, 9, 12]
```

```go
// scores = [0, 3, 9, 12, 15]

// Relative rank of value 5: between 3 and 9 (rank position 2)

// rank offset -1, count 3 -> start at rank 1, get 3 elements

record, err := client.Operate(nil, key,

    as.ListGetByValueRelativeRankRangeCountOp("scores",

        5, -1, 3, as.ListReturnTypeValue),

)

// record.Bins["scores"] == [3, 9, 12]
```

```c
// scores = [0, 3, 9, 12, 15]

as_integer val;

as_integer_init(&val, 5);

as_operations ops;

as_operations_inita(&ops, 1);

as_operations_list_get_by_value_rel_rank_range(&ops, "scores", NULL,

    (as_val*)&val, -1, 3, AS_LIST_RETURN_VALUE);

as_record* rec = NULL;

aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);

// rec bins "scores" == [3, 9, 12]
```

```csharp
// scores = [0, 3, 9, 12, 15]

Record record = client.Operate(null, key,

    ListOperation.GetByValueRelativeRankRange("scores",

        Value.Get(5), -1, 3, ListReturnType.VALUE)

);

// returns [3, 9, 12]
```

```javascript
// scores = [0, 3, 9, 12, 15]

const lists = Aerospike.lists

const result = await client.operate(key, [

    lists.getByValueRelRankRange('scores', 5, -1, 3)

        .andReturn(lists.returnType.VALUE)

])

// result.bins.scores == [3, 9, 12]
```

---

#### `size`

```python
size(binName[, ctx])
```

Description: Gets the size of a list, optionally at a given subcontext.

Returns: Returns the count of elements in the list at the level specified.

Performance: The worst-case performance of getting the size of the list is 𝓞(1).

Code sample: -   [Java](#tab-panel-2020)
-   [Python](#tab-panel-2021)
-   [Go](#tab-panel-2022)
-   [C](#tab-panel-2023)
-   [C#](#tab-panel-2024)
-   [Node.js](#tab-panel-2025)

```java
// scores = [10, 20, 30, 40, 50]

Record record = client.operate(null, key,

    ListOperation.size("scores")

);

// returns 5
```

```python
# scores = [10, 20, 30, 40, 50]

_, _, bins = client.operate(key, [

    list_operations.list_size("scores")

])

print(bins["scores"])

# 5
```

```go
// scores = [10, 20, 30, 40, 50]

record, err := client.Operate(nil, key,

    as.ListSizeOp("scores"),

)

// record.Bins["scores"] == 5
```

```c
// scores = [10, 20, 30, 40, 50]

as_operations ops;

as_operations_inita(&ops, 1);

as_operations_list_size(&ops, "scores", NULL);

as_record* rec = NULL;

aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);

// rec bins "scores" == 5
```

```csharp
// scores = [10, 20, 30, 40, 50]

Record record = client.Operate(null, key,

    ListOperation.Size("scores")

);

// returns 5
```

```javascript
// scores = [10, 20, 30, 40, 50]

const lists = Aerospike.lists

const result = await client.operate(key, [

    lists.size('scores')

])

// result.bins.scores == 5
```

---

## Set operations

#### `set_order`

```python
set_order(binName, order[, ctx])
```

Description: Modifies the order of an existing list. Order can be `UNORDERED` (default) or `ORDERED`. An optional `persistIndex` flag stores the offset index in the list particle for O(1) index access on subsequent operations.

Once set, both the order and persist-index flags are preserved across all subsequent list operations until changed by another `set_order()` call. The persist-index flag applies only to top-level lists.

See [CDT Element Ordering and Comparison](https://aerospike.com/docs/develop/data-types/collections/ordering).

Returns: null

Performance: The `set_order` operation does nothing when called on an already ordered list or on an ordered-to-unordered transition. The worst-case performance of modifying an unordered list to an ordered one is 𝓞(N log N).

Examples: Example

`[1, 3, [3, 7], 0, [3, 2]]` modified with `set_order` to `ORDERED` will turn into `[0, 1, 3, [3, 2], [3, 7]]`, because a list has higher ranking order than integers, and the list elements are compared by index when sorted.

Code sample: -   [Java](#tab-panel-2026)
-   [Python](#tab-panel-2027)
-   [Go](#tab-panel-2028)
-   [C](#tab-panel-2029)
-   [C#](#tab-panel-2030)
-   [Node.js](#tab-panel-2031)

```java
// l = [1, 3, [3, 7], 0, [3, 2]]

client.operate(null, key,

    ListOperation.setOrder("l", ListOrder.ORDERED)

);

// l == [0, 1, 3, [3, 2], [3, 7]]
```

```python
# l = [1, 3, [3, 7], 0, [3, 2]]

client.operate(key, [

    list_operations.list_set_order("l", aerospike.LIST_ORDERED)

])

# l == [0, 1, 3, [3, 2], [3, 7]]
```

```go
// l = [1, 3, [3, 7], 0, [3, 2]]

_, err := client.Operate(nil, key,

    as.ListSetOrderOp("l", as.ListOrderOrdered),

)

// l == [0, 1, 3, [3, 2], [3, 7]]
```

```c
// l = [1, 3, [3, 7], 0, [3, 2]]

as_operations ops;

as_operations_inita(&ops, 1);

as_operations_list_set_order(&ops, "l", NULL, AS_LIST_ORDERED);

aerospike_key_operate(&as, &err, NULL, &key, &ops, NULL);

// l == [0, 1, 3, [3, 2], [3, 7]]
```

```csharp
// l = [1, 3, [3, 7], 0, [3, 2]]

client.Operate(null, key,

    ListOperation.SetOrder("l", ListOrder.ORDERED)

);

// l == [0, 1, 3, [3, 2], [3, 7]]
```

```javascript
// l = [1, 3, [3, 7], 0, [3, 2]]

const lists = Aerospike.lists

await client.operate(key, [

    lists.setOrder('l', lists.order.ORDERED)

])

// l == [0, 1, 3, [3, 2], [3, 7]]
```

---