---
title: "Map operations"
description: "Increment counters, select entries by rank, and remove entries from a map bin on the server with the Aerospike Python client's map_operations helpers."
---

# Map operations

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

A map bin holds key-value pairs. Instead of reading a map, changing it in your application, and writing it back, use the `map_operations` helpers to change or read it on the server. Each helper builds an operation that you pass to [`client.operate()`](https://aerospike.com/docs/develop/client/python/usage/atomic/multi), which runs the operations on one record atomically in a single round trip.

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

## Setup

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

```python
import aerospike

from aerospike_helpers.operations import map_operations

# Define host configuration

config = {

    'hosts': [ ('127.0.0.1', 3000) ]

}

# Establishes a connection to the server

client = aerospike.client(config).connect()
```

## Results

`operate()` returns the tuple `(key, meta, bins)`. The `bins` dictionary has one entry for each bin that an operation read or returned a value from. When one `operate()` call contains several operations on the same bin, the entry holds only the result of the last of them. To get the result of every operation, use `client.operate_ordered()`. It returns results in operation order. Or run the earlier operation in a separate `operate()` call.

## Increment a counter

`map_increment(bin_name, key, amount)` adds `amount` to the value stored under `key`, and returns the new value. If the key is missing, the server starts it at `0` and applies the increment. You don’t need to create the key first.

The following example counts page views for each day in the `daily` map. In a single call, it records one view for an existing day and one view for a new day.

```python
# Creates a key with the namespace "sandbox", set "stats", and user key "page-1"

key = ('sandbox', 'stats', 'page-1')

# Write a record with a counter for one day

client.put(key, {'daily': {'2026-10-01': 5}})

# Increment the existing day, and create and increment a new one

ops = [

    map_operations.map_increment('daily', '2026-10-01', 1),

    map_operations.map_increment('daily', '2026-10-02', 1)

]

client.operate(key, ops)

# Read the map

(key_, meta, bins) = client.get(key)

print(bins['daily'])  # {'2026-10-01': 6, '2026-10-02': 1}
```

## Get the top entries by value

Every entry in a map has a rank that orders it by value. Rank `0` is the entry with the lowest value, and a negative rank counts from the highest, so `-1` is the entry with the highest value. `map_get_by_rank_range(bin_name, rank_start, get_amt, return_type)` returns `get_amt` entries that start at `rank_start`, so the server selects the entries and you don’t sort the map in your application.

The `return_type` sets what each selected entry contributes to the result:

| Return type | Result |
| --- | --- |
| `aerospike.MAP_RETURN_KEY` | A list of the keys. |
| `aerospike.MAP_RETURN_VALUE` | A list of the values. |
| `aerospike.MAP_RETURN_KEY_VALUE` | A single flat list that alternates keys and values: key, value, key, value. |
| `aerospike.MAP_RETURN_COUNT` | The number of entries selected. |

The result is in ascending rank order, so the entry with the highest value comes last.

The following example gets the three highest scores from a leaderboard, and prints them highest first.

```python
# Creates a key with the namespace "sandbox", set "stats", and user key "board-1"

key = ('sandbox', 'stats', 'board-1')

# Write a leaderboard

client.put(key, {'scores': {'ann': 120, 'bob': 340, 'cat': 90, 'dan': 500, 'eve': 275}})

# Get the three highest-ranked entries

ops = [

    map_operations.map_get_by_rank_range('scores', -3, 3, aerospike.MAP_RETURN_KEY_VALUE)

]

(key_, meta, bins) = client.operate(key, ops)

# The result is a flat list: ['eve', 275, 'bob', 340, 'dan', 500]

flat = bins['scores']

# Pair up the keys and values, and print the highest score first

pairs = list(zip(flat[::2], flat[1::2]))

for name, score in reversed(pairs):

    print('{0}: {1}'.format(name, score))
```

## Remove an entry and return its value

`map_remove_by_key(bin_name, key, return_type)` removes one entry from the map. The return type sets what the call returns about the removed entry. With `aerospike.MAP_RETURN_VALUE` it returns the value that was removed, so you get the value and remove it in one step, without rewriting the map.

```python
# Creates a key with the namespace "sandbox", set "stats", and user key "profile-1"

key = ('sandbox', 'stats', 'profile-1')

# Write a record with a map of preferences

client.put(key, {'prefs': {'lang': 'en', 'theme': 'dark', 'beta': True}})

# Remove the "beta" entry and return its value

ops = [

    map_operations.map_remove_by_key('prefs', 'beta', aerospike.MAP_RETURN_VALUE)

]

(key_, meta, bins) = client.operate(key, ops)

print(bins['prefs'])  # True

# Read the remaining map in a separate call

(key_, meta, bins) = client.get(key)

print(bins['prefs'])  # {'lang': 'en', 'theme': 'dark'}

# Close the connection to the server

client.close()
```

Read the remaining map with a separate call, as in the example. If you add a read of `prefs` to the same `operate()` call, that read replaces the removed value in `bins`. Only the last result for a bin is returned.

## Code block

Expand this section for a single code block to increment counters in a map

```python
import aerospike

from aerospike_helpers.operations import map_operations

# Define host configuration

config = {

    'hosts': [ ('127.0.0.1', 3000) ]

}

# Establishes a connection to the server

client = aerospike.client(config).connect()

# Creates a key with the namespace "sandbox", set "stats", and user key "page-1"

key = ('sandbox', 'stats', 'page-1')

# Write a record with a counter for one day

client.put(key, {'daily': {'2026-10-01': 5}})

# Increment the existing day, and create and increment a new one

ops = [

    map_operations.map_increment('daily', '2026-10-01', 1),

    map_operations.map_increment('daily', '2026-10-02', 1)

]

client.operate(key, ops)

# Read the map

(key_, meta, bins) = client.get(key)

print(bins['daily'])  # {'2026-10-01': 6, '2026-10-02': 1}

# Close the connection to the server

client.close()
```