# List bin operations

Aerospike list bin expressions enable you to manipulate list-type bins directly in queries.

This guide covers operations like `append`, `insert`, `remove`, `set`, and `increment`, allowing you to read or modify lists efficiently.

-   List modify expressions differ from [CDT List operations](https://aerospike.com/docs/develop/data-types/collections/list/operations) in that they return the modified list-bin instead of a specified return type (for remove-by ops) or predefined return type (The CDT operation `append` returns an int for example).
    
-   List read expressions (other than `LIST_SIZE`) return a result based on their `integer_value` parameter.
    
    Calling single result CDT operations (e.g. `LIST_GET_BY_INDEX`) requires an `integer_value` when `integer_value` is `LIST_RETURN_VALUE` because a list element value can be any expression type.
    

## Modify

#### `list_append`

```python
list_append(context, policy, value, bin)
```

Description: Append `value` to list bin. `list_append` does not create a new bin if the specified bin does not exist, unlike the [`append`](https://aerospike.com/docs/develop/data-types/collections/list/operations#append) CDT List operation, which does create a new bin if the specified bin does not exist.

Arguments: | Name | Type |
| --- | --- |
| `context` | `library_specific` |
| `policy` | `library_specific` |
| `value` | `expr` |
| `bin` | `list_bin_expr` |

Returns: `list_bin`

Introduced: 5.2.0.4

---

#### `list_append_items`

```python
list_append_items(context, policy, values, bin)
```

Description: [Append](https://aerospike.com/develop/data-types/collections/list/operations#append_items) all elements in **values** to list bin.

Arguments: | Name | Type |
| --- | --- |
| `context` | `library_specific` |
| `policy` | `library_specific` |
| `values` | `list_expr` |
| `bin` | `list_bin_expr` |

Returns: `list_bin`

Introduced: 5.2.0.4

---

#### `list_clear`

```python
list_clear(context, bin)
```

Description: [Clear](https://aerospike.com/develop/data-types/collections/list/operations#clear) all elements in list bin.

Arguments: | Name | Type |
| --- | --- |
| `context` | `library_specific` |
| `bin` | `list_bin_expr` |

Returns: `list_bin`

Introduced: 5.2.0.4

---

#### `list_increment`

```python
list_increment(context, policy, index, delta, bin)
```

Description: [Increment](https://aerospike.com/develop/data-types/collections/list/operations#increment) element at **index** by **delta**.

Arguments: | Name | Type |
| --- | --- |
| `context` | `library_specific` |
| `policy` | `library_specific` |
| `index` | `integer_expr` |
| `delta` | `integer_expr` |
| `bin` | `list_bin_expr` |

Returns: `list_bin`

---

#### `list_insert`

```python
list_insert(context, policy, index, value, bin)
```

Description: [Insert](https://aerospike.com/develop/data-types/collections/list/operations#insert) **value** at **index**.

Arguments: | Name | Type |
| --- | --- |
| `context` | `library_specific` |
| `policy` | `library_specific` |
| `index` | `integer_expr` |
| `value` | `expr` |
| `bin` | `list_bin_expr` |

Returns: `list_bin`

Introduced: 5.2.0.4

---

#### `list_insert_items`

```python
list_insert_items(context, policy, index, values, bin)
```

Description: [Insert](https://aerospike.com/develop/data-types/collections/list/operations#insert) all elements in **values** at **index**.

Arguments: | Name | Type |
| --- | --- |
| `context` | `library_specific` |
| `policy` | `library_specific` |
| `index` | `integer_expr` |
| `values` | `list_expr` |
| `bin` | `list_bin_expr` |

Returns: `list_bin`

Introduced: 5.2.0.4

---

#### `list_remove_by_index`

```python
list_remove_by_index(context, index, bin)
```

Description: [Remove](https://aerospike.com/develop/data-types/collections/list/operations#remove_by_index) element at **index**.

Arguments: | Name | Type |
| --- | --- |
| `context` | `library_specific` |
| `index` | `integer_expr` |
| `bin` | `list_bin_expr` |

Returns: `list_bin`

Introduced: 5.2.0.4

---

#### `list_remove_by_index_range`

```python
list_remove_by_index_range(context, index, count, bin)
```

Description: [Remove](https://aerospike.com/develop/data-types/collections/list/operations#remove_by_index_range) **count** element at **index**.

Arguments: | Name | Type |
| --- | --- |
| `context` | `library_specific` |
| `index` | `integer_expr` |
| `count` | `integer_expr` |
| `bin` | `list_bin_expr` |

Returns: `list_bin`

Introduced: 5.2.0.4

---

#### `list_remove_by_index_range_to_end`

```python
list_remove_by_index_range_to_end(context, index, bin)
```

Description: [Remove](https://aerospike.com/develop/data-types/collections/list/operations#remove_by_index_range) all elements at and after **index**.

Arguments: | Name | Type |
| --- | --- |
| `context` | `library_specific` |
| `index` | `integer_expr` |
| `bin` | `list_bin_expr` |

Returns: `list_bin`

Introduced: 5.2.0.4

---

#### `list_remove_by_rank`

```python
list_remove_by_rank(context, rank, bin)
```

Description: [Remove](https://aerospike.com/develop/data-types/collections/list/operations#remove_by_rank_range) all element with rank **rank**.

Arguments: | Name | Type |
| --- | --- |
| `context` | `library_specific` |
| `rank` | `integer_expr` |
| `bin` | `list_bin_expr` |

Returns: `list_bin`

Introduced: 5.2.0.4

---

#### `list_remove_by_rank_range`

```python
list_remove_by_rank_range(context, rank, count, bin)
```

Description: [Remove](https://aerospike.com/develop/data-types/collections/list/operations#remove_by_rank_range) **count** element at **rank**.

Arguments: | Name | Type |
| --- | --- |
| `context` | `library_specific` |
| `rank` | `integer_expr` |
| `count` | `integer_expr` |
| `bin` | `list_bin_expr` |

Returns: `list_bin`

Introduced: 5.2.0.4

---

#### `list_remove_by_rank_range_to_end`

```python
list_remove_by_rank_range_to_end(context, rank, bin)
```

Description: [Remove](https://aerospike.com/develop/data-types/collections/list/operations#remove_by_rank_range) all elements at and after **rank**.

Arguments: | Name | Type |
| --- | --- |
| `context` | `library_specific` |
| `rank` | `integer_expr` |
| `bin` | `list_bin_expr` |

Returns: `list_bin`

Introduced: 5.2.0.4

---

#### `list_remove_by_rel_rank_range`

```python
list_remove_by_rel_rank_range(context, value, rank, count, bin)
```

Description: [Remove](https://aerospike.com/develop/data-types/collections/list/operations#remove_by_value_rel_rank_range) **count** element at **rank** relative to **value**.

Arguments: | Name | Type |
| --- | --- |
| `context` | `library_specific` |
| `value` | `expr` |
| `rank` | `integer_expr` |
| `count` | `integer_expr` |
| `bin` | `list_bin_expr` |

Returns: `list_bin`

Introduced: 5.2.0.4

---

#### `list_remove_by_rel_rank_range_to_end`

```python
list_remove_by_rel_rank_range_to_end(context, value, rank, bin)
```

Description: [Remove](https://aerospike.com/develop/data-types/collections/list/operations#remove_by_value_rel_rank_range) all elements at and after **rank** relative to **value**.

Arguments: | Name | Type |
| --- | --- |
| `context` | `library_specific` |
| `value` | `expr` |
| `rank` | `integer_expr` |
| `bin` | `list_bin_expr` |

Returns: `list_bin`

Introduced: 5.2.0.4

---

#### `list_remove_by_value`

```python
list_remove_by_value(context, value, bin)
```

Description: [Remove](https://aerospike.com/develop/data-types/collections/list/operations#remove_all_by_value) all **value** values from list.

Arguments: | Name | Type |
| --- | --- |
| `context` | `library_specific` |
| `value` | `expr` |
| `bin` | `list_bin_expr` |

Returns: `list_bin`

Introduced: 5.2.0.4

---

#### `list_remove_by_value_list`

```python
list_remove_by_value_list(context, value, bin)
```

Description: [Remove](https://aerospike.com/develop/data-types/collections/list/operations#remove_all_by_value_list) all elements with values in **value\_list** from list.

Arguments: | Name | Type |
| --- | --- |
| `context` | `library_specific` |
| `value` | `list_expr` |
| `bin` | `list_bin_expr` |

Returns: `list_bin`

Introduced: 5.2.0.4

---

#### `list_remove_by_value_range`

```python
list_remove_by_value_range(context, start, end, bin)
```

Description: [Remove](https://aerospike.com/develop/data-types/collections/list/operations#remove_by_value_interval) all elements x in interval **start** ≤ x < **end** from list.

Arguments: | Name | Type |
| --- | --- |
| `context` | `library_specific` |
| `start` | `expr` |
| `end` | `expr` |
| `bin` | `list_bin_expr` |

Returns: `list_bin`

Introduced: 5.2.0.4

---

#### `list_set`

```python
list_set(context, index, value, bin)
```

Description: [Set](https://aerospike.com/develop/data-types/collections/list/operations#set) element at **index** to **value**.

Arguments: | Name | Type |
| --- | --- |
| `context` | `library_specific` |
| `index` | `integer-expr` |
| `value` | `expr` |
| `bin` | `list_bin_expr` |

Returns: `list_bin`

Introduced: 5.2.0.4

---

#### `list_sort`

```python
list_sort(context, flag, bin)
```

Description: [Sort](https://aerospike.com/develop/data-types/collections/list/operations#sort) list.

Arguments: | Name | Type |
| --- | --- |
| `context` | `library_specific` |
| `flag` | `integer` |
| `bin` | `list_bin_expr` |

Returns: `list_bin`

Introduced: 5.2.0.4

---

## Read

#### `list_get_by_index`

```python
list_get_by_index(type, context, result_type, index, bin)
```

Description: [Get](https://aerospike.com/develop/data-types/collections/list/operations#get_by_index) element at **index**.

Arguments: | Name | Type |
| --- | --- |
| `type` | `integer_value` |
| `context` | `library_specific` |
| `result_type` | `integer_value` |
| `index` | `integer_expr` |
| `bin` | `list_bin_expr` |

Introduced: 5.2.0.4

---

#### `list_get_by_index_range`

```python
list_get_by_index_range(context, result_type, index, count, bin)
```

Description: [Get](https://aerospike.com/develop/data-types/collections/list/operations#get_by_index_range) **count** elements at **index**.

Arguments: | Name | Type |
| --- | --- |
| `context` | `library_specific` |
| `result_type` | `integer_value` |
| `index` | `integer_expr` |
| `count` | `integer_expr` |
| `bin` | `list_bin_expr` |

Introduced: 5.2.0.4

---

#### `list_get_by_index_range_to_end`

```python
list_get_by_index_range_to_end(context, result_type, index, bin)
```

Description: [Get](https://aerospike.com/develop/data-types/collections/list/operations#get_by_index_range) elements at and after **index**.

Arguments: | Name | Type |
| --- | --- |
| `context` | `library_specific` |
| `result_type` | `integer_value` |
| `index` | `integer_expr` |
| `bin` | `list_bin_expr` |

Introduced: 5.2.0.4

---

#### `list_get_by_rank`

```python
list_get_by_rank(type, context, result_type, rank, bin)
```

Description: [Get](https://aerospike.com/develop/data-types/collections/list/operations#get_by_rank) element at **rank**.

Arguments: | Name | Type |
| --- | --- |
| `type` | `integer_value` |
| `context` | `library_specific` |
| `result_type` | `integer_value` |
| `rank` | `integer_expr` |
| `bin` | `list_bin_expr` |

Introduced: 5.2.0.4

---

#### `list_get_by_rank_range`

```python
list_get_by_rank_range(context, result_type, rank, count, bin)
```

Description: [Get](https://aerospike.com/develop/data-types/collections/list/operations#get_by_rank_range) **count** elements at **rank**.

Arguments: | Name | Type |
| --- | --- |
| `context` | `library_specific` |
| `result_type` | `integer_value` |
| `rank` | `integer_expr` |
| `count` | `integer_expr` |
| `bin` | `list_bin_expr` |

---

#### `list_get_by_rank_range_to_end`

```python
list_get_by_rank_range_to_end(context, result_type, rank, bin)
```

Description: [Get](https://aerospike.com/develop/data-types/collections/list/operations#get_by_rank_range) elements at and after **rank**.

Arguments: | Name | Type |
| --- | --- |
| `context` | `library_specific` |
| `result_type` | `integer_value` |
| `rank` | `integer_expr` |
| `bin` | `list_bin_expr` |

Introduced: 5.2.0.4

---

#### `list_get_by_rel_rank_range`

```python
list_get_by_rel_rank_range(context, result_type, value, rank, count, bin)
```

Description: [Get](https://aerospike.com/develop/data-types/collections/list/operations#get_by_value_rel_rank_range) **count** element at **rank** relative to **value**.

Arguments: | Name | Type |
| --- | --- |
| `context` | `library_specific` |
| `result_type` | `integer_value` |
| `value` | `expr` |
| `rank` | `integer_expr` |
| `count` | `integer_expr` |
| `bin` | `list_bin_expr` |

Introduced: 5.2.0.4

---

#### `list_get_by_rel_rank_range_to_end`

```python
list_get_by_rel_rank_range_to_end(context, result_type, value, rank, bin)
```

Description: [Get](https://aerospike.com/develop/data-types/collections/list/operations#get_by_value_rel_rank_range) all elements at and after **rank** relative to **value**.

Arguments: | Name | Type |
| --- | --- |
| `context` | `library_specific` |
| `result_type` | `integer_value` |
| `value` | `expr` |
| `rank` | `integer_expr` |
| `bin` | `list_bin_expr` |

Introduced: 5.2.0.4

---

#### `list_get_by_value`

```python
list_get_by_value(context, result_type, value, bin)
```

Description: [Get](https://aerospike.com/develop/data-types/collections/list/operations#get_all_by_value) all **value** values from list.

Arguments: | Name | Type |
| --- | --- |
| `context` | `library_specific` |
| `result_type` | `integer_value` |
| `value` | `expr` |
| `bin` | `list_bin_expr` |

Introduced: 5.2.0.4

---

#### `list_get_by_value_list`

```python
list_get_by_value_list(context, result_type, values, bin)
```

Description: [Get](https://aerospike.com/develop/data-types/collections/list/operations#get_all_by_value_list) all elements with values in **values** from list.

Arguments: | Name | Type |
| --- | --- |
| `context` | `library_specific` |
| `result_type` | `integer_value` |
| `values` | `list_expr` |
| `bin` | `list_bin_expr` |

Introduced: 5.2.0.4

---

#### `list_get_by_value_range`

```python
list_get_by_value_range(context, result_type, start, end, bin)
```

Description: [Get](https://aerospike.com/develop/data-types/collections/list/operations#get_by_value_interval) all elements x in interval **start** ≤ x < **end** from list.

Arguments: | Name | Type |
| --- | --- |
| `context` | `library_specific` |
| `result_type` | `integer_value` |
| `start` | `expr` |
| `end` | `expr` |
| `bin` | `list_bin_expr` |

Introduced: 5.2.0.4

---

#### `list_size`

```python
list_size(context, bin)
```

Description: [Get](https://aerospike.com/develop/data-types/collections/list/operations#size) list element count.

Arguments: | Name | Type |
| --- | --- |
| `context` | `library_specific` |
| `bin` | `list_bin_expr` |

Returns: `integer_bin`

Introduced: 5.2.0.4

---