Map operations

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(), which runs the operations on one record atomically in a single round trip.

For the map data type itself, see Collections.

Setup

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

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.

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

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

# 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

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