Map operations

Map operations read, update, and remove elements in map-type bins directly on the server.

These operations have expression counterparts, which evaluate to a value instead of writing it. See Map expressions for the set, and Operations and expressions for which to reach for.

Each operation is governed by a map policy (order, write flags, PERSIST_INDEX), can target nested elements using a context, and returns results controlled by a return type.

Map policy

The map policy defines the characteristics of a map write operation.

Map order

The map order is set in the map policy and determines the map subtype. The order type determines how the server accesses map elements:

• Unordered — no ordering guarantees. Key lookup is a linear scan. Lowest storage overhead.
• K-ordered — elements are maintained in key order. Key lookup uses binary search. Without a persisted index, the key offset index is built temporarily per operation at O(N) cost.
• KV-ordered — elements are maintained in key and value order. Without a persisted full index, rank and value lookups use the same heap/scan fallback as K-ordered (the value order index is not built on-demand). With a persisted full index, rank lookups are O(1) and value searches are O(log N).

Use set_type() to convert between order types. See Map performance for the operational complexity of each order type.

Persisting the map index

For large maps with a high read-to-write ratio, rebuilding the offset index on every access can consume significant CPU. Setting PERSIST_INDEX in the map policy stores the index on disk alongside the map itself, so subsequent operations load it directly instead of rebuilding it.

PERSIST_INDEX is set per write and applies only to the top-level map, not nested maps.

Setting PERSIST_INDEX on an unordered map sorts its keys into key order and persists the offset index, giving it the same binary-search key lookup behavior as a K-ordered map with a persisted index (column 3 in the performance table).

Write flags

Flag	Description
MODIFY_DEFAULT	Default: upserts; create or update map keys
CREATE_ONLY	Only create new map keys. Fail if the key already exists
UPDATE_ONLY	Only update existing map keys. Fail if a key does not exist
NO_FAIL	No-op instead of fail if a policy violation occurred, such as CREATE_ONLY
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, UPDATE_ONLY | NO_FAIL | DO_PARTIAL updates existing keys, skips keys that do not exist, and applies the remaining updates without failing.

Context

Context Type	Description
MAP_INDEX	Finds an element in a Map by index. A negative index is a lookup performed in reverse from the end of the map. If it is out of bounds, a parameter error is returned.
MAP_KEY	Finds an element in a Map by key.
MAP_RANK	Finds an element in a Map by rank. A negative rank is a lookup performed in reverse from the highest ranked.
MAP_VALUE	Finds an element in a Map by value.
MAP_KEY_CREATE	Finds an element in a Map by key. Creates the element if it does not exist.

The context is a list of element selectors describing a path to the nested map element where the operation should be applied. Without a context it is assumed that the operation occurs at the top level of the map.

Return types

Return Type	Description
KEY	The key of the element (in single result operations) or elements (in multi result operations)
VALUE	The value of the element (in single result operations) or elements (in multi result operations)
KEY_VALUE	The key/value pair of the element (in single result operations) or elements (in multi result operations)
ORDERED_MAP	Returns results as an ordered Map
UNORDERED_MAP	Returns results as an unordered Map
NONE	Nothing is returned. It speeds up remove operations by not constructing a reply
COUNT	Number of elements returned
INDEX	Key order position of the element, from 0 (smallest key) to N-1 (largest)
REVERSE_INDEX	Reverse key order position of the element, from 0 (largest key) to N-1 (smallest)
RANK	Value order of the element, with 0 being the smallest value
REVERSE_RANK	Reverse value order of the element, with 0 being the largest value
INVERTED	Invert meaning of map 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 with EXISTS returns true if the value is in the map.

Examples

• Remove the 10 map elements with the largest key values: remove_by_index_range(-10, 10, NONE)
• Remove all but the 10 map elements with the largest key values: remove_by_index_range(-10, 10, NONE | INVERTED)
• Keep only the top 10 key elements and return the count of removed elements: remove_by_index_range(-10, 10, COUNT | INVERTED)

Modify operations

clear

clear(bin_name[, context])

Description

Clears the map. Map type stays the same.

Arguments

Name	Type	Description
bin_name	string	Name of the bin to operate on.
context	Context instance	Optional context path from the bin to a nested List or Map, one selector per nesting level. Omit it to operate on the top level of the map.

Returns

null

Expression form

map_clear

Code sample

Java SDK

// m = {a: 1, b: 2, c: 3}

try (RecordStream rs = session.upsert(key)
    .bin("m").mapClear()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}
// m == {}

Python SDK

# m = {a: 1, b: 2, c: 3}

session.upsert(key).bin("m").map_clear().execute()
# m == {}

Rust

// Requires: use aerospike::operations::maps::{self};
// m = {a: 1, b: 2, c: 3}

client.operate(&WritePolicy::default(), &key,
    &[maps::clear("m")]).await?;
// m == {}

C#

// m = {a: 1, b: 2, c: 3}

client.Operate(null, key,
    MapOperation.Clear("m")
);
// m == {}

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
// m = {a: 1, b: 2, c: 3}

_, err := client.Operate(nil, key,
    as.MapClearOp("m"),
)
// m == {}

Node.js

// m = {a: 1, b: 2, c: 3}

const maps = Aerospike.maps

await client.operate(key, [
    maps.clear('m')
])
// m == {}

C

// m = {a: 1, b: 2, c: 3}

as_operations ops;
as_operations_inita(&ops, 1);
as_operations_map_clear(&ops, "m", NULL);

as_record* rec = NULL;
aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);
// m == {}

Java

// m = {a: 1, b: 2, c: 3}

client.operate(null, key,
    MapOperation.clear("m")
);
// m == {}

Python

# m = {a: 1, b: 2, c: 3}

client.operate(key, [
    map_operations.map_clear("m")
])
# m == {}

decrement

decrement(policy, bin_name, key, delta[, context])

Description

Decrements values by delta-value for all items identified by key.

Only works for integer or float value types in the {key: value} pair. If the bin does not exist, a new unordered map is created unless a different map order is specified through the map policy.

Type interaction between value and delta-value

Value-Type	Delta: integer	Delta: float
Map Entry: integer	Subtract normally	Truncate to nearest integer and subtract
Map Entry: float	Convert integer to float and subtract	Subtract normally

Arguments

Name	Type	Description
policy	Map policy	Ordering and write flags for the operation. See Write flags. The ordering attribute takes effect only when this operation creates the map; on a map that already exists it is ignored.
bin_name	string	Name of the bin to operate on.
key	any	Map key whose value is decremented.
delta	integer or float	Amount to subtract. A negative value adds.
context	Context instance	Optional context path from the bin to a nested List or Map, one selector per nesting level. Omit it to operate on the top level of the map.

Returns

New value after decrement

Code sample

Java SDK

// m = {a: 1, b: 10, c: 3}
// Decrement by incrementing with a negative value.

try (RecordStream rs = session.upsert(key)
    .bin("m").onMapKey("b").add(-3)
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns 7 (new value of key "b")
}
// m == {a: 1, b: 7, c: 3}

Python SDK

# m = {a: 1, b: 10, c: 3}
# Decrement by incrementing with a negative value.

stream = session.upsert(key).bin("m").on_map_key("b").add(-3).execute()
# returns 7 (new value of key "b")
# m == {a: 1, b: 7, c: 3}

Rust

// Requires: use aerospike::operations::maps::{self, MapPolicy};
// m = {a: 1, b: 10, c: 3}
// Decrement by incrementing with a negative value.

let record = client.operate(&WritePolicy::default(), &key,
    &[maps::increment_value(&MapPolicy::default(), "m", as_val!("b"), as_val!(-3))]).await?;
// returns 7 (new value of key "b")
// m == {a: 1, b: 7, c: 3}

C#

// m = {a: 1, b: 10, c: 3}
// Decrement by incrementing with a negative value.

Record record = client.Operate(null, key,
    MapOperation.Increment(MapPolicy.Default, "m", Value.Get("b"), Value.Get(-3))
);
// returns 7 (new value of key "b")
// m == {a: 1, b: 7, c: 3}

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
// m = {a: 1, b: 10, c: 3}
// Decrement by incrementing with a negative value.

record, err := client.Operate(nil, key,
    as.MapIncrementOp(as.DefaultMapPolicy(), "m", "b", -3),
)
// record.Bins["m"] == 7 (new value of key "b")
// m == {a: 1, b: 7, c: 3}

Node.js

// m = {a: 1, b: 10, c: 3}
// Decrement by incrementing with a negative value.

const maps = Aerospike.maps

const result = await client.operate(key, [
    maps.increment('m', 'b', -3)
])
// result.bins.m == 7 (new value of key "b")
// m == {a: 1, b: 7, c: 3}

C

// m = {a: 1, b: 10, c: 3}
// Decrement by incrementing with a negative value.

as_map_policy mp;
as_map_policy_init(&mp);

as_operations ops;
as_operations_inita(&ops, 1);
as_operations_map_increment(&ops, "m", NULL, &mp,
    (as_val*)as_string_new("b", false),
    (as_val*)as_integer_new(-3));

as_record* rec = NULL;
aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);
// returns 7 (new value of key "b")
// m == {a: 1, b: 7, c: 3}

Java

// m = {a: 1, b: 10, c: 3}
// Decrement by incrementing with a negative value.

Record record = client.operate(null, key,
    MapOperation.increment(MapPolicy.Default, "m", Value.get("b"), Value.get(-3))
);
// returns 7 (new value of key "b")
// m == {a: 1, b: 7, c: 3}

Python

# m = {a: 1, b: 10, c: 3}
# Decrement by incrementing with a negative value.

_, _, bins = client.operate(key, [
    map_operations.map_increment("m", "b", -3)
])
# bins["m"] == 7 (new value of key "b")
# m == {a: 1, b: 7, c: 3}

increment

increment(policy, bin_name, key, delta[, context])

Description

Increments values by delta-value for all items identified by key.

Only works for integer or float value types in the {key: value} pair. If the bin does not exist, a new unordered map is created unless a different map order is specified through the map policy.

Type interaction between value and delta-value

Value-Type	Delta: integer	Delta: float
Map Entry: integer	Add normally	Truncate to nearest integer and add
Map Entry: float	Convert integer to float and add	Add normally

Arguments

Name	Type	Description
policy	Map policy	Ordering and write flags for the operation. See Write flags. The ordering attribute takes effect only when this operation creates the map; on a map that already exists it is ignored.
bin_name	string	Name of the bin to operate on.
key	any	Map key whose value is incremented.
delta	integer or float	Amount to add. A negative value subtracts.
context	Context instance	Optional context path from the bin to a nested List or Map, one selector per nesting level. Omit it to operate on the top level of the map.

Returns

New value after increment

Expression form

map_increment

Code sample

Java SDK

// m = {a: 1, b: 2, c: 3}

try (RecordStream rs = session.upsert(key)
    .bin("m").onMapKey("b").add(10)
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns 12 (new value of key "b")
}
// m == {a: 1, b: 12, c: 3}

Python SDK

# m = {a: 1, b: 2, c: 3}

stream = session.upsert(key).bin("m").on_map_key("b").add(10).execute()
# returns 12 (new value of key "b")
# m == {a: 1, b: 12, c: 3}

Rust

// Requires: use aerospike::operations::maps::{self, MapPolicy};
// m = {a: 1, b: 2, c: 3}

let record = client.operate(&WritePolicy::default(), &key,
    &[maps::increment_value(&MapPolicy::default(), "m", as_val!("b"), as_val!(10))]).await?;
// returns 12 (new value of key "b")
// m == {a: 1, b: 12, c: 3}

C#

// m = {a: 1, b: 2, c: 3}

Record record = client.Operate(null, key,
    MapOperation.Increment(MapPolicy.Default, "m", Value.Get("b"), Value.Get(10))
);
// returns 12 (new value of key "b")
// m == {a: 1, b: 12, c: 3}

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
// m = {a: 1, b: 2, c: 3}

record, err := client.Operate(nil, key,
    as.MapIncrementOp(as.DefaultMapPolicy(), "m", "b", 10),
)
// record.Bins["m"] == 12 (new value of key "b")
// m == {a: 1, b: 12, c: 3}

Node.js

// m = {a: 1, b: 2, c: 3}

const maps = Aerospike.maps

const result = await client.operate(key, [
    maps.increment('m', 'b', 10)
])
// result.bins.m == 12 (new value of key "b")
// m == {a: 1, b: 12, c: 3}

C

// m = {a: 1, b: 2, c: 3}

as_map_policy mp;
as_map_policy_init(&mp);

as_operations ops;
as_operations_inita(&ops, 1);
as_operations_map_increment(&ops, "m", NULL, &mp,
    (as_val*)as_string_new("b", false),
    (as_val*)as_integer_new(10));

as_record* rec = NULL;
aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);
// returns 12 (new value of key "b")
// m == {a: 1, b: 12, c: 3}

Java

// m = {a: 1, b: 2, c: 3}

Record record = client.operate(null, key,
    MapOperation.increment(MapPolicy.Default, "m", Value.get("b"), Value.get(10))
);
// returns 12 (new value of key "b")
// m == {a: 1, b: 12, c: 3}

Python

# m = {a: 1, b: 2, c: 3}

_, _, bins = client.operate(key, [
    map_operations.map_increment("m", "b", 10)
])
# bins["m"] == 12 (new value of key "b")
# m == {a: 1, b: 12, c: 3}

put_items

put_items(policy, bin_name, items[, context])

Description

Creates a map bin with a specified order, if the bin does not exist. Takes a map of key/value items and adds them to the map bin.

Arguments

Name	Type	Description
policy	Map policy	Ordering and write flags for the operation. See Write flags. The ordering attribute takes effect only when this operation creates the map; on a map that already exists it is ignored.
bin_name	string	Name of the bin to operate on.
items	map	Key/value pairs to write, as a map. A key already present is overwritten; a key that is absent is added.
context	Context instance	Optional context path from the bin to a nested List or Map, one selector per nesting level. Omit it to operate on the top level of the map.

Returns

The element count of the map after the operation, in the ‘bins’ part of the record under the bin name.

Expression form

map_put_items

Order

If the bin does not exist, a new unordered map is created unless a different map order is specified through the map policy.

K_ORDERED maps are preferred over UNORDERED maps, with no real disadvantage in terms of space used.

A note on write flags

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

Using DO_PARTIAL will ensure that any element not violating the policy is added, even on a failed operation.

Code sample

Java SDK

// m = {a: 1}

try (RecordStream rs = session.upsert(key)
    .bin("m").mapUpsertItems(Map.of("b", 2, "c", 3))
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns 3 (new map size)
}
// m == {a: 1, b: 2, c: 3}

Python SDK

# m = {a: 1}

stream = session.upsert(key).bin("m").map_upsert_items({"b": 2, "c": 3}).execute()
# returns 3 (new map size)
# m == {a: 1, b: 2, c: 3}

Rust

// Requires: use aerospike::operations::maps::{self, MapPolicy}; use std::collections::HashMap;
// m = {a: 1}

let items = HashMap::from([(as_val!("b"), as_val!(2)), (as_val!("c"), as_val!(3))]);
let record = client.operate(&WritePolicy::default(), &key,
    &[maps::put_items(&MapPolicy::default(), "m", items)]).await?;
// returns 3 (new map size)
// m == {a: 1, b: 2, c: 3}

C#

// m = {a: 1}

Dictionary<Value, Value> items = new Dictionary<Value, Value> {
    { Value.Get("b"), Value.Get(2) },
    { Value.Get("c"), Value.Get(3) }
};

Record record = client.Operate(null, key,
    MapOperation.PutItems(MapPolicy.Default, "m", items)
);
// returns 3 (new map size)
// m == {a: 1, b: 2, c: 3}

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
// m = {a: 1}

items := map[interface{}]interface{}{
    "b": 2,
    "c": 3,
}
record, err := client.Operate(nil, key,
    as.MapPutItemsOp(as.DefaultMapPolicy(), "m", items),
)
// record.Bins["m"] == 3 (new map size)
// m == {a: 1, b: 2, c: 3}

Node.js

// m = {a: 1}

const maps = Aerospike.maps

const result = await client.operate(key, [
    maps.putItems('m', { b: 2, c: 3 })
])
// result.bins.m == 3 (new map size)
// m == {a: 1, b: 2, c: 3}

C

// m = {a: 1}

as_map_policy mp;
as_map_policy_init(&mp);

as_hashmap items;
as_hashmap_init(&items, 2);
as_stringmap_set_int64((as_map*)&items, "b", 2);
as_stringmap_set_int64((as_map*)&items, "c", 3);

as_operations ops;
as_operations_inita(&ops, 1);
as_operations_map_put_items(&ops, "m", NULL, &mp, (as_map*)&items);

as_record* rec = NULL;
aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);
// returns 3 (new map size)
// m == {a: 1, b: 2, c: 3}

Java

// m = {a: 1}

Map<Value, Value> items = new HashMap<>();
items.put(Value.get("b"), Value.get(2));
items.put(Value.get("c"), Value.get(3));

Record record = client.operate(null, key,
    MapOperation.putItems(MapPolicy.Default, "m", items)
);
// returns 3 (new map size)
// m == {a: 1, b: 2, c: 3}

Python

# m = {a: 1}

_, _, bins = client.operate(key, [
    map_operations.map_put_items("m", {"b": 2, "c": 3})
])
# bins["m"] == 3 (new map size)
# m == {a: 1, b: 2, c: 3}

put

put(policy, bin_name, key, value[, context])

Description

Creates a map bin with a specified order, if the bin does not exist. Adds a key/value element to the map.

Arguments

Name	Type	Description
policy	Map policy	Ordering and write flags for the operation. See Write flags. The ordering attribute takes effect only when this operation creates the map; on a map that already exists it is ignored.
bin_name	string	Name of the bin to operate on.
key	any	Map key to write.
value	any	Value to store under key, replacing any value already there.
context	Context instance	Optional context path from the bin to a nested List or Map, one selector per nesting level. Omit it to operate on the top level of the map.

Returns

The element count of the map after the operation, in the ‘bins’ part of the record under the bin name.

Expression form

map_put

Order

If the bin does not exist, a new unordered map is created unless a different map order is specified through the map policy.

K_ORDERED maps are preferred over UNORDERED maps, with no real disadvantage in terms of space used.

A note on write flags

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

DO_PARTIAL is not applicable for this operation.

Performance

With a persisted index, ordered maps have 𝓞(log N) worst-case performance. Without a persisted index or for unordered maps, the worst-case performance is 𝓞(N). See Map performance.

Code sample

Java SDK

// m = {a: 1}

try (RecordStream rs = session.upsert(key)
    .bin("m").onMapKey("b").setTo(2)
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns 2 (new map size)
}
// m == {a: 1, b: 2}

Python SDK

# m = {a: 1}

stream = session.upsert(key).bin("m").on_map_key("b").set_to(2).execute()
# returns 2 (new map size)
# m == {a: 1, b: 2}

Rust

// Requires: use aerospike::operations::maps::{self, MapPolicy};
// m = {a: 1}

let record = client.operate(&WritePolicy::default(), &key,
    &[maps::put(&MapPolicy::default(), "m", as_val!("b"), as_val!(2))]).await?;
// returns 2 (new map size)
// m == {a: 1, b: 2}

C#

// m = {a: 1}

Record record = client.Operate(null, key,
    MapOperation.Put(MapPolicy.Default, "m", Value.Get("b"), Value.Get(2))
);
// returns 2 (new map size)
// m == {a: 1, b: 2}

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
// m = {a: 1}

record, err := client.Operate(nil, key,
    as.MapPutOp(as.DefaultMapPolicy(), "m", "b", 2),
)
// record.Bins["m"] == 2 (new map size)
// m == {a: 1, b: 2}

Node.js

// m = {a: 1}

const maps = Aerospike.maps

const result = await client.operate(key, [
    maps.put('m', 'b', 2)
])
// result.bins.m == 2 (new map size)
// m == {a: 1, b: 2}

C

// m = {a: 1}

as_map_policy mp;
as_map_policy_init(&mp);

as_operations ops;
as_operations_inita(&ops, 1);
as_operations_map_put(&ops, "m", NULL, &mp,
    (as_val*)as_string_new("b", false),
    (as_val*)as_integer_new(2));

as_record* rec = NULL;
aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);
// returns 2 (new map size)
// m == {a: 1, b: 2}

Java

// m = {a: 1}

Record record = client.operate(null, key,
    MapOperation.put(MapPolicy.Default, "m", Value.get("b"), Value.get(2))
);
// returns 2 (new map size)
// m == {a: 1, b: 2}

Python

# m = {a: 1}

_, _, bins = client.operate(key, [
    map_operations.map_put("m", "b", 2)
])
# bins["m"] == 2 (new map size)
# m == {a: 1, b: 2}

remove_all_by_key_list

remove_by_key_list(bin_name, keys, result_type[, context])

Description

Remove all {key: value} pairs where map.key ∈ keyList.

Arguments

Name	Type	Description
bin_name	string	Name of the bin to operate on.
keys	list	Keys to match, as a list.
result_type	integer literal	Which form the result takes — a count, an index, a rank, a value, or nothing. See Return types.
context	Context instance	Optional context path from the bin to a nested List or Map, one selector per nesting level. Omit it to operate on the top level of the map.

Returns

Multi result

Expression form

map_remove_by_key_list

Performance

Requesting an ORDERED_MAP return type on an unordered map adds extra ordering cost relative to the number of elements in the result set. See Map performance.

Code sample

Java SDK

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

try (RecordStream rs = session.upsert(key)
    .bin("m").onMapKeyList(List.of("a", "c", "e")).removeAnd().getKeysAndValues()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns {a: 1, c: 3, e: 5}
}
// m == {b: 2, d: 4}

Python SDK

# m = {a: 1, b: 2, c: 3, d: 4, e: 5}

stream = (session.upsert(key).bin("m").on_map_key_list(["a", "c", "e"])
          .remove(return_type=MapReturnType.KEY_VALUE).execute())
# returns {"a": 1, "c": 3, "e": 5}
# m == {b: 2, d: 4}

Rust

// Requires: use aerospike::operations::maps::{self, MapReturnType};
// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

let record = client.operate(&WritePolicy::default(), &key,
    &[maps::remove_by_key_list("m", as_values!("a", "c", "e"), MapReturnType::KeyValue)]).await?;
// returns [("a", 1), ("c", 3), ("e", 5)]
// m == {b: 2, d: 4}

C#

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

IList keys = new List<Value> {
    Value.Get("a"), Value.Get("c"), Value.Get("e")
};
Record record = client.Operate(null, key,
    MapOperation.RemoveByKeyList("m", keys, MapReturnType.KEY_VALUE)
);
// returns [(a, 1), (c, 3), (e, 5)]
// m == {b: 2, d: 4}

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

record, err := client.Operate(nil, key,
    as.MapRemoveByKeyListOp("m", []any{"a", "c", "e"},
        as.MapReturnType.KEY_VALUE),
)
// record.Bins["m"] == [{a: 1}, {c: 3}, {e: 5}]
// m == {b: 2, d: 4}

Node.js

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

const maps = Aerospike.maps

const result = await client.operate(key, [
    maps.removeByKeyList('m', ['a', 'c', 'e'], maps.returnType.KEY_VALUE)
])
// result.bins.m == ['a', 1, 'c', 3, 'e', 5]
// m == {b: 2, d: 4}

C

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

as_arraylist keys;
as_arraylist_init(&keys, 3, 0);
as_arraylist_append_str(&keys, "a");
as_arraylist_append_str(&keys, "c");
as_arraylist_append_str(&keys, "e");

as_operations ops;
as_operations_inita(&ops, 1);
as_operations_map_remove_by_key_list(&ops, "m", NULL,
    (as_list*)&keys, AS_MAP_RETURN_KEY_VALUE);

as_record* rec = NULL;
aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);
// rec bins "m" == ["a", 1, "c", 3, "e", 5]
// m == {b: 2, d: 4}

Java

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

List<Value> keys = Arrays.asList(Value.get("a"), Value.get("c"), Value.get("e"));
Record record = client.operate(null, key,
    MapOperation.removeByKeyList("m", keys, MapReturnType.KEY_VALUE)
);
// returns [a=1, c=3, e=5]
// m == {b: 2, d: 4}

Python

# m = {a: 1, b: 2, c: 3, d: 4, e: 5}

_, _, bins = client.operate(key, [
    map_operations.map_remove_by_key_list("m", ["a", "c", "e"],
        aerospike.MAP_RETURN_KEY_VALUE)
])
# bins["m"] == ["a", 1, "c", 3, "e", 5]
# m == {b: 2, d: 4}

remove_all_by_value_list

remove_by_value_list(bin_name, values, result_type[, context])

Description

Remove all {key: value} pairs where map.value ∈ valueList.

Arguments

Name	Type	Description
bin_name	string	Name of the bin to operate on.
values	list	Values to match, as a list. Every entry whose value equals any of them is selected.
result_type	integer literal	Which form the result takes — a count, an index, a rank, a value, or nothing. See Return types.
context	Context instance	Optional context path from the bin to a nested List or Map, one selector per nesting level. Omit it to operate on the top level of the map.

Returns

Multi result

Expression form

map_remove_by_value_list

Performance

Requesting an ORDERED_MAP return type on an unordered map adds extra ordering cost relative to the number of elements in the result set. See Map performance.

Code sample

Java SDK

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

try (RecordStream rs = session.upsert(key)
    .bin("m").onMapValueList(List.of(2, 4)).removeAnd().getKeys()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns [b, d]
}
// m == {a: 1, c: 3, e: 5}

Python SDK

# m = {a: 1, b: 2, c: 3, d: 4, e: 5}

stream = (session.upsert(key).bin("m").on_map_value_list([2, 4])
          .remove(return_type=MapReturnType.KEY).execute())
# returns ["b", "d"]
# m == {a: 1, c: 3, e: 5}

Rust

// Requires: use aerospike::operations::maps::{self, MapReturnType};
// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

let record = client.operate(&WritePolicy::default(), &key,
    &[maps::remove_by_value_list("m", as_values!(2, 4), MapReturnType::Key)]).await?;
// returns ["b", "d"]
// m == {a: 1, c: 3, e: 5}

C#

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

IList values = new List<Value> { Value.Get(2), Value.Get(4) };
Record record = client.Operate(null, key,
    MapOperation.RemoveByValueList("m", values, MapReturnType.KEY)
);
// returns [b, d]
// m == {a: 1, c: 3, e: 5}

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

record, err := client.Operate(nil, key,
    as.MapRemoveByValueListOp("m", []any{2, 4}, as.MapReturnType.KEY),
)
// record.Bins["m"] == ["b", "d"]
// m == {a: 1, c: 3, e: 5}

Node.js

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

const maps = Aerospike.maps

const result = await client.operate(key, [
    maps.removeByValueList('m', [2, 4], maps.returnType.KEY)
])
// result.bins.m == ['b', 'd']
// m == {a: 1, c: 3, e: 5}

C

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

as_arraylist values;
as_arraylist_init(&values, 2, 0);
as_arraylist_append_int64(&values, 2);
as_arraylist_append_int64(&values, 4);

as_operations ops;
as_operations_inita(&ops, 1);
as_operations_map_remove_by_value_list(&ops, "m", NULL,
    (as_list*)&values, AS_MAP_RETURN_KEY);

as_record* rec = NULL;
aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);
// rec bins "m" == ["b", "d"]
// m == {a: 1, c: 3, e: 5}

Java

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

List<Value> values = Arrays.asList(Value.get(2), Value.get(4));
Record record = client.operate(null, key,
    MapOperation.removeByValueList("m", values, MapReturnType.KEY)
);
// returns [b, d]
// m == {a: 1, c: 3, e: 5}

Python

# m = {a: 1, b: 2, c: 3, d: 4, e: 5}

_, _, bins = client.operate(key, [
    map_operations.map_remove_by_value_list("m", [2, 4],
        aerospike.MAP_RETURN_KEY)
])
# bins["m"] == ["b", "d"]
# m == {a: 1, c: 3, e: 5}

remove_all_by_value

remove_by_value(bin_name, value, result_type[, context])

Description

Remove all {key: value} pairs where map.value == value.

Arguments

Name	Type	Description
bin_name	string	Name of the bin to operate on.
value	any	Value to match. Every entry whose value equals it is selected.
result_type	integer literal	Which form the result takes — a count, an index, a rank, a value, or nothing. See Return types.
context	Context instance	Optional context path from the bin to a nested List or Map, one selector per nesting level. Omit it to operate on the top level of the map.

Returns

Multi result

Expression form

map_remove_by_value

Performance

Requesting an INDEX return type adds 𝓞(N + M) on an unordered map, or 𝓞(M) on a map with a persisted offset index. Requesting an ORDERED_MAP return type on an unordered map adds extra ordering cost relative to the number of elements in the result set. See Map performance.

Code sample

Java SDK

// m = {a: 1, b: 2, c: 1, d: 3}

try (RecordStream rs = session.upsert(key)
    .bin("m").onMapValue(1).removeAnd().getKeys()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns [a, c] (keys of removed entries)
}
// m == {b: 2, d: 3}

Python SDK

# m = {a: 1, b: 2, c: 1, d: 3}

stream = (session.upsert(key).bin("m").on_map_value(1)
          .remove(return_type=MapReturnType.KEY).execute())
# returns ["a", "c"] (keys of removed entries)
# m == {b: 2, d: 3}

Rust

// Requires: use aerospike::operations::maps::{self, MapReturnType};
// m = {a: 1, b: 2, c: 1, d: 3}

let record = client.operate(&WritePolicy::default(), &key,
    &[maps::remove_by_value("m", as_val!(1), MapReturnType::Key)]).await?;
// returns ["a", "c"] (keys of removed entries)
// m == {b: 2, d: 3}

C#

// m = {a: 1, b: 2, c: 1, d: 3}

Record record = client.Operate(null, key,
    MapOperation.RemoveByValue("m", Value.Get(1), MapReturnType.KEY)
);
// returns [a, c] (keys of removed entries)
// m == {b: 2, d: 3}

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
// m = {a: 1, b: 2, c: 1, d: 3}

record, err := client.Operate(nil, key,
    as.MapRemoveByValueOp("m", 1, as.MapReturnType.KEY),
)
// record.Bins["m"] == ["a", "c"] (keys of removed entries)
// m == {b: 2, d: 3}

Node.js

// m = {a: 1, b: 2, c: 1, d: 3}

const maps = Aerospike.maps

const result = await client.operate(key, [
    maps.removeByValue('m', 1, maps.returnType.KEY)
])
// result.bins.m == ['a', 'c'] (keys of removed entries)
// m == {b: 2, d: 3}

C

// m = {a: 1, b: 2, c: 1, d: 3}

as_operations ops;
as_operations_inita(&ops, 1);
as_operations_map_remove_by_value(&ops, "m", NULL,
    (as_val*)as_integer_new(1), AS_MAP_RETURN_KEY);

as_record* rec = NULL;
aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);
// rec bins "m" == ["a", "c"] (keys of removed entries)
// m == {b: 2, d: 3}

Java

// m = {a: 1, b: 2, c: 1, d: 3}

Record record = client.operate(null, key,
    MapOperation.removeByValue("m", Value.get(1), MapReturnType.KEY)
);
// returns [a, c] (keys of removed entries)
// m == {b: 2, d: 3}

Python

# m = {a: 1, b: 2, c: 1, d: 3}

_, _, bins = client.operate(key, [
    map_operations.map_remove_by_value("m", 1, aerospike.MAP_RETURN_KEY)
])
# bins["m"] == ["a", "c"] (keys of removed entries)
# m == {b: 2, d: 3}

remove_by_index_range

remove_by_index_range(bin_name, index[, count], result_type[, context])

Description

Remove all {key: value} pairs where k = indexof(map.key) and k >= index and k < index + count. Omitting count select element(s) where k >= origin + index.

Arguments

Name	Type	Description
bin_name	string	Name of the bin to operate on.
index	integer	Zero-based position, 0 being the first element. A negative index counts back from the end.
count	integer	Number of elements to select. Optional; defaults to the rest of the collection.
result_type	integer literal	Which form the result takes — a count, an index, a rank, a value, or nothing. See Return types.
context	Context instance	Optional context path from the bin to a nested List or Map, one selector per nesting level. Omit it to operate on the top level of the map.

Returns

Multi result

Expression form

map_remove_by_index_range, map_remove_by_index_range_to_end

Performance

Requesting a RANK return type adds 𝓞(N log N). Requesting an ORDERED_MAP return type on an unordered map adds extra ordering cost relative to the number of elements in the result set. See Map performance.

Code sample

Java SDK

// m = {a: 1, b: 2, c: 3, d: 4, e: 5} (K_ORDERED)

try (RecordStream rs = session.upsert(key)
    .bin("m").onMapIndexRange(1, 2).removeAnd().getKeysAndValues()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns {b: 2, c: 3}
}
// m == {a: 1, d: 4, e: 5}

Python SDK

# m = {a: 1, b: 2, c: 3, d: 4, e: 5} (K_ORDERED)

stream = (session.upsert(key).bin("m").on_map_index_range(1, 2)
          .remove(return_type=MapReturnType.KEY_VALUE).execute())
# returns {"b": 2, "c": 3}
# m == {a: 1, d: 4, e: 5}

Rust

// Requires: use aerospike::operations::maps::{self, MapReturnType};
// m = {a: 1, b: 2, c: 3, d: 4, e: 5} (K_ORDERED)

let record = client.operate(&WritePolicy::default(), &key,
    &[maps::remove_by_index_range("m", 1, 2, MapReturnType::KeyValue)]).await?;
// returns [("b", 2), ("c", 3)]
// m == {a: 1, d: 4, e: 5}

C#

// m = {a: 1, b: 2, c: 3, d: 4, e: 5} (K_ORDERED)

Record record = client.Operate(null, key,
    MapOperation.RemoveByIndexRange("m", 1, 2, MapReturnType.KEY_VALUE)
);
// returns [(b, 2), (c, 3)]
// m == {a: 1, d: 4, e: 5}

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
// m = {a: 1, b: 2, c: 3, d: 4, e: 5} (K_ORDERED)

record, err := client.Operate(nil, key,
    as.MapRemoveByIndexRangeCountOp("m", 1, 2, as.MapReturnType.KEY_VALUE),
)
// record.Bins["m"] == [{b: 2}, {c: 3}]
// m == {a: 1, d: 4, e: 5}

Node.js

// m = {a: 1, b: 2, c: 3, d: 4, e: 5} (K_ORDERED)

const maps = Aerospike.maps

const result = await client.operate(key, [
    maps.removeByIndexRange('m', 1, 2, maps.returnType.KEY_VALUE)
])
// result.bins.m == ['b', 2, 'c', 3]
// m == {a: 1, d: 4, e: 5}

C

// m = {a: 1, b: 2, c: 3, d: 4, e: 5} (K_ORDERED)

as_operations ops;
as_operations_inita(&ops, 1);
as_operations_map_remove_by_index_range(&ops, "m", NULL,
    1, 2, AS_MAP_RETURN_KEY_VALUE);

as_record* rec = NULL;
aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);
// rec bins "m" == ["b", 2, "c", 3]
// m == {a: 1, d: 4, e: 5}

Java

// m = {a: 1, b: 2, c: 3, d: 4, e: 5} (K_ORDERED)

Record record = client.operate(null, key,
    MapOperation.removeByIndexRange("m", 1, 2, MapReturnType.KEY_VALUE)
);
// returns [b=2, c=3]
// m == {a: 1, d: 4, e: 5}

Python

# m = {a: 1, b: 2, c: 3, d: 4, e: 5} (K_ORDERED)

_, _, bins = client.operate(key, [
    map_operations.map_remove_by_index_range("m", 1, 2,
        aerospike.MAP_RETURN_KEY_VALUE)
])
# bins["m"] == ["b", 2, "c", 3]
# m == {a: 1, d: 4, e: 5}

remove_by_index

remove_by_index(bin_name, index, result_type[, context])

Description

Remove {key: value} entry where map.key is the ith smallest key where i == index.

Arguments

Name	Type	Description
bin_name	string	Name of the bin to operate on.
index	integer	Zero-based position, 0 being the first element. A negative index counts back from the end.
result_type	integer literal	Which form the result takes — a count, an index, a rank, a value, or nothing. See Return types.
context	Context instance	Optional context path from the bin to a nested List or Map, one selector per nesting level. Omit it to operate on the top level of the map.

Returns

Single result

Expression form

map_remove_by_index

Performance

Requesting a RANK return type adds 𝓞(N), or 𝓞(log N) with a persisted full index. Requesting an ORDERED_MAP return type on an unordered map adds extra ordering cost relative to the number of elements in the result set. See Map performance.

Code sample

Java SDK

// m = {a: 1, b: 2, c: 3} (K_ORDERED)

try (RecordStream rs = session.upsert(key)
    .bin("m").onMapIndex(0).removeAnd().getKeysAndValues()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns {a: 1} (smallest key removed)
}
// m == {b: 2, c: 3}

Python SDK

# m = {a: 1, b: 2, c: 3} (K_ORDERED)

stream = (session.upsert(key).bin("m").on_map_index(0)
          .remove(return_type=MapReturnType.KEY_VALUE).execute())
# returns {"a": 1} (smallest key removed)
# m == {b: 2, c: 3}

Rust

// Requires: use aerospike::operations::maps::{self, MapReturnType};
// m = {a: 1, b: 2, c: 3} (K_ORDERED)

let record = client.operate(&WritePolicy::default(), &key,
    &[maps::remove_by_index("m", 0, MapReturnType::KeyValue)]).await?;
// returns [("a", 1)] (smallest key removed)
// m == {b: 2, c: 3}

C#

// m = {a: 1, b: 2, c: 3} (K_ORDERED)

Record record = client.Operate(null, key,
    MapOperation.RemoveByIndex("m", 0, MapReturnType.KEY_VALUE)
);
// returns [(a, 1)] (smallest key removed)
// m == {b: 2, c: 3}

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
// m = {a: 1, b: 2, c: 3} (K_ORDERED)

record, err := client.Operate(nil, key,
    as.MapRemoveByIndexOp("m", 0, as.MapReturnType.KEY_VALUE),
)
// record.Bins["m"] == [{a: 1}] (smallest key removed)
// m == {b: 2, c: 3}

Node.js

// m = {a: 1, b: 2, c: 3} (K_ORDERED)

const maps = Aerospike.maps

const result = await client.operate(key, [
    maps.removeByIndex('m', 0, maps.returnType.KEY_VALUE)
])
// result.bins.m == ['a', 1] (smallest key removed)
// m == {b: 2, c: 3}

C

// m = {a: 1, b: 2, c: 3} (K_ORDERED)

as_operations ops;
as_operations_inita(&ops, 1);
as_operations_map_remove_by_index(&ops, "m", NULL, 0,
    AS_MAP_RETURN_KEY_VALUE);

as_record* rec = NULL;
aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);
// rec bins "m" == ["a", 1] (smallest key removed)
// m == {b: 2, c: 3}

Java

// m = {a: 1, b: 2, c: 3} (K_ORDERED)

Record record = client.operate(null, key,
    MapOperation.removeByIndex("m", 0, MapReturnType.KEY_VALUE)
);
// returns [a=1] (smallest key removed)
// m == {b: 2, c: 3}

Python

# m = {a: 1, b: 2, c: 3} (K_ORDERED)

_, _, bins = client.operate(key, [
    map_operations.map_remove_by_index("m", 0, aerospike.MAP_RETURN_KEY_VALUE)
])
# bins["m"] == ["a", 1] (smallest key removed)
# m == {b: 2, c: 3}

remove_by_key_interval

remove_by_key_range(bin_name, key_begin, key_end, result_type[, context])

Description

Remove all {key: value} pairs where map.key >= keyStart and map.key < keyStop. Omitting keyStop select element(s) where map.key >= keyStart.

Arguments

Name	Type	Description
bin_name	string	Name of the bin to operate on.
key_begin	any	Lowest key to match, inclusive.
key_end	any	Upper bound on the key, exclusive. Omit it to match everything from key_begin upward.
result_type	integer literal	Which form the result takes — a count, an index, a rank, a value, or nothing. See Return types.
context	Context instance	Optional context path from the bin to a nested List or Map, one selector per nesting level. Omit it to operate on the top level of the map.

Returns

Multi result

Expression form

map_remove_by_key_range

Performance

Requesting a RANK return type adds 𝓞(N log N). Requesting an ORDERED_MAP return type on an unordered map adds extra ordering cost relative to the number of elements in the result set. See Map performance.

Code sample

Java SDK

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

try (RecordStream rs = session.upsert(key)
    .bin("m").onMapKeyRange("b", "d").removeAnd().getKeysAndValues()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns {b: 2, c: 3} (keys >= "b" and < "d")
}
// m == {a: 1, d: 4, e: 5}

Python SDK

# m = {a: 1, b: 2, c: 3, d: 4, e: 5}

stream = (session.upsert(key).bin("m").on_map_key_range("b", "d")
          .remove(return_type=MapReturnType.KEY_VALUE).execute())
# returns {"b": 2, "c": 3} (keys >= "b" and < "d")
# m == {a: 1, d: 4, e: 5}

Rust

// Requires: use aerospike::operations::maps::{self, MapReturnType};
// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

let record = client.operate(&WritePolicy::default(), &key,
    &[maps::remove_by_key_range("m", as_val!("b"), as_val!("d"), MapReturnType::KeyValue)]).await?;
// returns [("b", 2), ("c", 3)] (keys >= "b" and < "d")
// m == {a: 1, d: 4, e: 5}

C#

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

Record record = client.Operate(null, key,
    MapOperation.RemoveByKeyRange("m", Value.Get("b"), Value.Get("d"),
        MapReturnType.KEY_VALUE)
);
// returns [(b, 2), (c, 3)] (keys >= "b" and < "d")
// m == {a: 1, d: 4, e: 5}

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

record, err := client.Operate(nil, key,
    as.MapRemoveByKeyRangeOp("m", "b", "d", as.MapReturnType.KEY_VALUE),
)
// record.Bins["m"] == [{b: 2}, {c: 3}] (keys >= "b" and < "d")
// m == {a: 1, d: 4, e: 5}

Node.js

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

const maps = Aerospike.maps

const result = await client.operate(key, [
    maps.removeByKeyRange('m', 'b', 'd', maps.returnType.KEY_VALUE)
])
// result.bins.m == ['b', 2, 'c', 3] (keys >= "b" and < "d")
// m == {a: 1, d: 4, e: 5}

C

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

as_operations ops;
as_operations_inita(&ops, 1);
as_operations_map_remove_by_key_range(&ops, "m", NULL,
    (as_val*)as_string_new("b", false),
    (as_val*)as_string_new("d", false),
    AS_MAP_RETURN_KEY_VALUE);

as_record* rec = NULL;
aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);
// rec bins "m" == ["b", 2, "c", 3] (keys >= "b" and < "d")
// m == {a: 1, d: 4, e: 5}

Java

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

Record record = client.operate(null, key,
    MapOperation.removeByKeyRange("m", Value.get("b"), Value.get("d"),
        MapReturnType.KEY_VALUE)
);
// returns [b=2, c=3] (keys >= "b" and < "d")
// m == {a: 1, d: 4, e: 5}

Python

# m = {a: 1, b: 2, c: 3, d: 4, e: 5}

_, _, bins = client.operate(key, [
    map_operations.map_remove_by_key_range("m", "b", "d",
        aerospike.MAP_RETURN_KEY_VALUE)
])
# bins["m"] == ["b", 2, "c", 3] (keys >= "b" and < "d")
# m == {a: 1, d: 4, e: 5}

remove_by_key_rel_index_range

remove_by_key_rel_index_range(bin_name, key, index[, count], result_type[, context])

Description

Remove all {key: value} pairs where origin = index(key), k = indexof(map.key) and k >= origin + index and k < origin + index + count. Omitting count select element(s) where k >= origin + index.

Arguments

Name	Type	Description
bin_name	string	Name of the bin to operate on.
key	any	Key that index is measured from. It need not be present in the map — the index is taken from where it would sort.
index	integer	Zero-based position, 0 being the first element. A negative index counts back from the end.
count	integer	Number of elements to select. Optional; defaults to the rest of the collection.
result_type	integer literal	Which form the result takes — a count, an index, a rank, a value, or nothing. See Return types.
context	Context instance	Optional context path from the bin to a nested List or Map, one selector per nesting level. Omit it to operate on the top level of the map.

Returns

Multi result

Expression form

map_remove_by_rel_index_range, map_remove_by_rel_index_range_to_end

Code sample

Java SDK

// m = {a: 1, b: 2, c: 3, d: 4, e: 5} (K_ORDERED)
// From key "b" (index 1), offset 0, count 3

try (RecordStream rs = session.upsert(key)
    .bin("m").onMapKeyRelativeIndexRange("b", 0, 3).removeAnd().getKeysAndValues()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns {b: 2, c: 3, d: 4}
}
// m == {a: 1, e: 5}

Python SDK

# m = {a: 1, b: 2, c: 3, d: 4, e: 5} (K_ORDERED)
# From key "b" (index 1), offset 0, count 3

stream = (session.upsert(key).bin("m").on_map_key_relative_index_range("b", 0, 3)
          .remove(return_type=MapReturnType.KEY_VALUE).execute())
# returns {"b": 2, "c": 3, "d": 4}
# m == {a: 1, e: 5}

Rust

// Requires: use aerospike::operations::maps::{self, MapReturnType};
// m = {a: 1, b: 2, c: 3, d: 4, e: 5} (K_ORDERED)
// From key "b" (index 1), offset 0, count 3

let record = client.operate(&WritePolicy::default(), &key,
    &[maps::remove_by_key_relative_index_range_count("m", as_val!("b"), 0, 3, MapReturnType::KeyValue)]).await?;
// returns [("b", 2), ("c", 3), ("d", 4)]
// m == {a: 1, e: 5}

C#

// m = {a: 1, b: 2, c: 3, d: 4, e: 5} (K_ORDERED)
// From key "b" (index 1), offset 0, count 3

Record record = client.Operate(null, key,
    MapOperation.RemoveByKeyRelativeIndexRange("m", Value.Get("b"), 0, 3,
        MapReturnType.KEY_VALUE)
);
// returns [(b, 2), (c, 3), (d, 4)]
// m == {a: 1, e: 5}

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
// m = {a: 1, b: 2, c: 3, d: 4, e: 5} (K_ORDERED)
// From key "b" (index 1), offset 0, count 3

record, err := client.Operate(nil, key,
    as.MapRemoveByKeyRelativeIndexRangeCountOp("m", "b", 0, 3,
        as.MapReturnType.KEY_VALUE),
)
// record.Bins["m"] == [{b: 2}, {c: 3}, {d: 4}]
// m == {a: 1, e: 5}

Node.js

// m = {a: 1, b: 2, c: 3, d: 4, e: 5} (K_ORDERED)
// From key "b" (index 1), offset 0, count 3

const maps = Aerospike.maps

const result = await client.operate(key, [
    maps.removeByKeyRelIndexRange('m', 'b', 0, 3, maps.returnType.KEY_VALUE)
])
// result.bins.m == ['b', 2, 'c', 3, 'd', 4]
// m == {a: 1, e: 5}

C

// m = {a: 1, b: 2, c: 3, d: 4, e: 5} (K_ORDERED)
// From key "b" (index 1), offset 0, count 3

as_operations ops;
as_operations_inita(&ops, 1);
as_operations_map_remove_by_key_rel_index_range(&ops, "m", NULL,
    (as_val*)as_string_new("b", false), 0, 3,
    AS_MAP_RETURN_KEY_VALUE);

as_record* rec = NULL;
aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);
// rec bins "m" == ["b", 2, "c", 3, "d", 4]
// m == {a: 1, e: 5}

Java

// m = {a: 1, b: 2, c: 3, d: 4, e: 5} (K_ORDERED)
// From key "b" (index 1), offset 0, count 3

Record record = client.operate(null, key,
    MapOperation.removeByKeyRelativeIndexRange("m", Value.get("b"), 0, 3,
        MapReturnType.KEY_VALUE)
);
// returns [b=2, c=3, d=4]
// m == {a: 1, e: 5}

Python

# m = {a: 1, b: 2, c: 3, d: 4, e: 5} (K_ORDERED)
# From key "b" (index 1), offset 0, count 3

_, _, bins = client.operate(key, [
    map_operations.map_remove_by_key_index_range_relative("m", "b", 0,
        aerospike.MAP_RETURN_KEY_VALUE, count=3)
])
# bins["m"] == ["b", 2, "c", 3, "d", 4]
# m == {a: 1, e: 5}

remove_by_key

remove_by_key(bin_name, key, result_type[, context])

Description

Remove entry {key: value} where map.key == key.

Arguments

Name	Type	Description
bin_name	string	Name of the bin to operate on.
key	any	Map key to match.
result_type	integer literal	Which form the result takes — a count, an index, a rank, a value, or nothing. See Return types.
context	Context instance	Optional context path from the bin to a nested List or Map, one selector per nesting level. Omit it to operate on the top level of the map.

Returns

Single result

Expression form

map_remove_by_key

Performance

Requesting an INDEX return type adds 𝓞(N), or 𝓞(log N) with a persisted index. Requesting an ORDERED_MAP return type on an unordered map adds extra ordering cost relative to the number of elements in the result set. See Map performance.

Code sample

Java SDK

// m = {a: 1, b: 2, c: 3}

try (RecordStream rs = session.upsert(key)
    .bin("m").onMapKey("b").removeAnd().getValues()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns 2 (removed value)
}
// m == {a: 1, c: 3}

Python SDK

# m = {a: 1, b: 2, c: 3}

stream = (session.upsert(key).bin("m").on_map_key("b")
          .remove(return_type=MapReturnType.VALUE).execute())
# returns 2 (removed value)
# m == {a: 1, c: 3}

Rust

// Requires: use aerospike::operations::maps::{self, MapReturnType};
// m = {a: 1, b: 2, c: 3}

let record = client.operate(&WritePolicy::default(), &key,
    &[maps::remove_by_key("m", as_val!("b"), MapReturnType::Value)]).await?;
// returns 2 (removed value)
// m == {a: 1, c: 3}

C#

// m = {a: 1, b: 2, c: 3}

Record record = client.Operate(null, key,
    MapOperation.RemoveByKey("m", Value.Get("b"), MapReturnType.VALUE)
);
// returns 2 (removed value)
// m == {a: 1, c: 3}

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
// m = {a: 1, b: 2, c: 3}

record, err := client.Operate(nil, key,
    as.MapRemoveByKeyOp("m", "b", as.MapReturnType.VALUE),
)
// record.Bins["m"] == 2 (removed value)
// m == {a: 1, c: 3}

Node.js

// m = {a: 1, b: 2, c: 3}

const maps = Aerospike.maps

const result = await client.operate(key, [
    maps.removeByKey('m', 'b', maps.returnType.VALUE)
])
// result.bins.m == 2 (removed value)
// m == {a: 1, c: 3}

C

// m = {a: 1, b: 2, c: 3}

as_operations ops;
as_operations_inita(&ops, 1);
as_operations_map_remove_by_key(&ops, "m", NULL,
    (as_val*)as_string_new("b", false), AS_MAP_RETURN_VALUE);

as_record* rec = NULL;
aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);
// rec bins "m" == 2 (removed value)
// m == {a: 1, c: 3}

Java

// m = {a: 1, b: 2, c: 3}

Record record = client.operate(null, key,
    MapOperation.removeByKey("m", Value.get("b"), MapReturnType.VALUE)
);
// returns 2 (removed value)
// m == {a: 1, c: 3}

Python

# m = {a: 1, b: 2, c: 3}

_, _, bins = client.operate(key, [
    map_operations.map_remove_by_key("m", "b", aerospike.MAP_RETURN_VALUE)
])
# bins["m"] == 2 (removed value)
# m == {a: 1, c: 3}

remove_by_rank_range

remove_by_rank_range(bin_name, rank[, count], result_type[, context])

Description

Remove all {key: value} pairs where r = rankof(map.value) and r >= rank and r < rank + count. Omitting count select element(s) where r >= rank.

Arguments

Name	Type	Description
bin_name	string	Name of the bin to operate on.
rank	integer	Zero-based rank in value order, 0 being the smallest. A negative rank counts back from the largest.
count	integer	Number of elements to select. Optional; defaults to the rest of the collection.
result_type	integer literal	Which form the result takes — a count, an index, a rank, a value, or nothing. See Return types.
context	Context instance	Optional context path from the bin to a nested List or Map, one selector per nesting level. Omit it to operate on the top level of the map.

Returns

Multi result

Expression form

map_remove_by_rank_range, map_remove_by_rank_range_to_end

Performance

Requesting an INDEX return type adds 𝓞(N log N) on an unordered map, or 𝓞(M) on a map with a persisted offset index. Requesting an ORDERED_MAP return type on an unordered map adds extra ordering cost relative to the number of elements in the result set. See Map performance.

Code sample

Java SDK

// m = {a: 3, b: 1, c: 5, d: 2, e: 4}

try (RecordStream rs = session.upsert(key)
    .bin("m").onMapRankRange(0, 2).removeAnd().getKeysAndValues()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns {b: 1, d: 2} (2 smallest values removed)
}
// m == {a: 3, c: 5, e: 4}

Python SDK

# m = {a: 3, b: 1, c: 5, d: 2, e: 4}

stream = (session.upsert(key).bin("m").on_map_rank_range(0, 2)
          .remove(return_type=MapReturnType.KEY_VALUE).execute())
# returns {"b": 1, "d": 2} (2 smallest values removed)
# m == {a: 3, c: 5, e: 4}

Rust

// Requires: use aerospike::operations::maps::{self, MapReturnType};
// m = {a: 3, b: 1, c: 5, d: 2, e: 4}

let record = client.operate(&WritePolicy::default(), &key,
    &[maps::remove_by_rank_range("m", 0, 2, MapReturnType::KeyValue)]).await?;
// returns [("b", 1), ("d", 2)] (2 smallest values removed)
// m == {a: 3, c: 5, e: 4}

C#

// m = {a: 3, b: 1, c: 5, d: 2, e: 4}

Record record = client.Operate(null, key,
    MapOperation.RemoveByRankRange("m", 0, 2, MapReturnType.KEY_VALUE)
);
// returns [(b, 1), (d, 2)] (2 smallest values removed)
// m == {a: 3, c: 5, e: 4}

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
// m = {a: 3, b: 1, c: 5, d: 2, e: 4}

record, err := client.Operate(nil, key,
    as.MapRemoveByRankRangeCountOp("m", 0, 2, as.MapReturnType.KEY_VALUE),
)
// record.Bins["m"] == [{b: 1}, {d: 2}] (2 smallest values removed)
// m == {a: 3, c: 5, e: 4}

Node.js

// m = {a: 3, b: 1, c: 5, d: 2, e: 4}

const maps = Aerospike.maps

const result = await client.operate(key, [
    maps.removeByRankRange('m', 0, 2, maps.returnType.KEY_VALUE)
])
// result.bins.m == ['b', 1, 'd', 2] (2 smallest values removed)
// m == {a: 3, c: 5, e: 4}

C

// m = {a: 3, b: 1, c: 5, d: 2, e: 4}

as_operations ops;
as_operations_inita(&ops, 1);
as_operations_map_remove_by_rank_range(&ops, "m", NULL,
    0, 2, AS_MAP_RETURN_KEY_VALUE);

as_record* rec = NULL;
aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);
// rec bins "m" == ["b", 1, "d", 2] (2 smallest values removed)
// m == {a: 3, c: 5, e: 4}

Java

// m = {a: 3, b: 1, c: 5, d: 2, e: 4}

Record record = client.operate(null, key,
    MapOperation.removeByRankRange("m", 0, 2, MapReturnType.KEY_VALUE)
);
// returns [b=1, d=2] (2 smallest values removed)
// m == {a: 3, c: 5, e: 4}

Python

# m = {a: 3, b: 1, c: 5, d: 2, e: 4}

_, _, bins = client.operate(key, [
    map_operations.map_remove_by_rank_range("m", 0, 2,
        aerospike.MAP_RETURN_KEY_VALUE)
])
# bins["m"] == ["b", 1, "d", 2] (2 smallest values removed)
# m == {a: 3, c: 5, e: 4}

remove_by_rank

remove_by_rank(bin_name, rank, result_type[, context])

Description

Remove {key: value} entry where map.value is the ith smallest value where i == rank.

Arguments

Name	Type	Description
bin_name	string	Name of the bin to operate on.
rank	integer	Zero-based rank in value order, 0 being the smallest. A negative rank counts back from the largest.
result_type	integer literal	Which form the result takes — a count, an index, a rank, a value, or nothing. See Return types.
context	Context instance	Optional context path from the bin to a nested List or Map, one selector per nesting level. Omit it to operate on the top level of the map.

Returns

Single result

Expression form

map_remove_by_rank

Performance

Requesting an INDEX return type adds 𝓞(N) on an unordered map, or 𝓞(1) on a map with a persisted offset index. Requesting an ORDERED_MAP return type on an unordered map adds extra ordering cost relative to the number of elements in the result set. See Map performance.

Code sample

Java SDK

// m = {a: 3, b: 1, c: 2}

try (RecordStream rs = session.upsert(key)
    .bin("m").onMapRank(0).removeAnd().getKeysAndValues()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns {b: 1} (smallest value removed)
}
// m == {a: 3, c: 2}

Python SDK

# m = {a: 3, b: 1, c: 2}

stream = (session.upsert(key).bin("m").on_map_rank(0)
          .remove(return_type=MapReturnType.KEY_VALUE).execute())
# returns {"b": 1} (smallest value removed)
# m == {a: 3, c: 2}

Rust

// Requires: use aerospike::operations::maps::{self, MapReturnType};
// m = {a: 3, b: 1, c: 2}

let record = client.operate(&WritePolicy::default(), &key,
    &[maps::remove_by_rank("m", 0, MapReturnType::KeyValue)]).await?;
// returns [("b", 1)] (smallest value removed)
// m == {a: 3, c: 2}

C#

// m = {a: 3, b: 1, c: 2}

Record record = client.Operate(null, key,
    MapOperation.RemoveByRank("m", 0, MapReturnType.KEY_VALUE)
);
// returns [(b, 1)] (smallest value removed)
// m == {a: 3, c: 2}

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
// m = {a: 3, b: 1, c: 2}

record, err := client.Operate(nil, key,
    as.MapRemoveByRankOp("m", 0, as.MapReturnType.KEY_VALUE),
)
// record.Bins["m"] == [{b: 1}] (smallest value removed)
// m == {a: 3, c: 2}

Node.js

// m = {a: 3, b: 1, c: 2}

const maps = Aerospike.maps

const result = await client.operate(key, [
    maps.removeByRank('m', 0, maps.returnType.KEY_VALUE)
])
// result.bins.m == ['b', 1] (smallest value removed)
// m == {a: 3, c: 2}

C

// m = {a: 3, b: 1, c: 2}

as_operations ops;
as_operations_inita(&ops, 1);
as_operations_map_remove_by_rank(&ops, "m", NULL, 0,
    AS_MAP_RETURN_KEY_VALUE);

as_record* rec = NULL;
aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);
// rec bins "m" == ["b", 1] (smallest value removed)
// m == {a: 3, c: 2}

Java

// m = {a: 3, b: 1, c: 2}

Record record = client.operate(null, key,
    MapOperation.removeByRank("m", 0, MapReturnType.KEY_VALUE)
);
// returns [b=1] (smallest value removed)
// m == {a: 3, c: 2}

Python

# m = {a: 3, b: 1, c: 2}

_, _, bins = client.operate(key, [
    map_operations.map_remove_by_rank("m", 0, aerospike.MAP_RETURN_KEY_VALUE)
])
# bins["m"] == ["b", 1] (smallest value removed)
# m == {a: 3, c: 2}

remove_by_value_interval

remove_by_value_range(bin_name, value_begin, value_end, result_type[, context])

Description

Remove all {key: value} pairs where map.value >= valueStart and map.value < valueStop. Omitting valueStop select element(s) where map.value >= valueStart.

Arguments

Name	Type	Description
bin_name	string	Name of the bin to operate on.
value_begin	any	Lowest value to match, inclusive.
value_end	any	Upper bound on the value, exclusive. Omit it to match everything from value_begin upward.
result_type	integer literal	Which form the result takes — a count, an index, a rank, a value, or nothing. See Return types.
context	Context instance	Optional context path from the bin to a nested List or Map, one selector per nesting level. Omit it to operate on the top level of the map.

Returns

Multi result

Expression form

map_remove_by_value_range

Performance

Requesting an INDEX return type adds 𝓞(N + M) on an unordered map, or 𝓞(M) on a map with a persisted offset index. Requesting an ORDERED_MAP return type on an unordered map adds extra ordering cost relative to the number of elements in the result set. See Map performance.

Code sample

Java SDK

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

try (RecordStream rs = session.upsert(key)
    .bin("m").onMapValueRange(2, 4).removeAnd().getKeysAndValues()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns {b: 2, c: 3} (values >= 2 and < 4)
}
// m == {a: 1, d: 4, e: 5}

Python SDK

# m = {a: 1, b: 2, c: 3, d: 4, e: 5}

stream = (session.upsert(key).bin("m").on_map_value_range(2, 4)
          .remove(return_type=MapReturnType.KEY_VALUE).execute())
# returns {"b": 2, "c": 3} (values >= 2 and < 4)
# m == {a: 1, d: 4, e: 5}

Rust

// Requires: use aerospike::operations::maps::{self, MapReturnType};
// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

let record = client.operate(&WritePolicy::default(), &key,
    &[maps::remove_by_value_range("m", as_val!(2), as_val!(4), MapReturnType::KeyValue)]).await?;
// returns [("b", 2), ("c", 3)] (values >= 2 and < 4)
// m == {a: 1, d: 4, e: 5}

C#

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

Record record = client.Operate(null, key,
    MapOperation.RemoveByValueRange("m", Value.Get(2), Value.Get(4),
        MapReturnType.KEY_VALUE)
);
// returns [(b, 2), (c, 3)] (values >= 2 and < 4)
// m == {a: 1, d: 4, e: 5}

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

record, err := client.Operate(nil, key,
    as.MapRemoveByValueRangeOp("m", 2, 4, as.MapReturnType.KEY_VALUE),
)
// record.Bins["m"] == [{b: 2}, {c: 3}] (values >= 2 and < 4)
// m == {a: 1, d: 4, e: 5}

Node.js

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

const maps = Aerospike.maps

const result = await client.operate(key, [
    maps.removeByValueRange('m', 2, 4, maps.returnType.KEY_VALUE)
])
// result.bins.m == ['b', 2, 'c', 3] (values >= 2 and < 4)
// m == {a: 1, d: 4, e: 5}

C

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

as_operations ops;
as_operations_inita(&ops, 1);
as_operations_map_remove_by_value_range(&ops, "m", NULL,
    (as_val*)as_integer_new(2),
    (as_val*)as_integer_new(4),
    AS_MAP_RETURN_KEY_VALUE);

as_record* rec = NULL;
aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);
// rec bins "m" == ["b", 2, "c", 3] (values >= 2 and < 4)
// m == {a: 1, d: 4, e: 5}

Java

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

Record record = client.operate(null, key,
    MapOperation.removeByValueRange("m", Value.get(2), Value.get(4),
        MapReturnType.KEY_VALUE)
);
// returns [b=2, c=3] (values >= 2 and < 4)
// m == {a: 1, d: 4, e: 5}

Python

# m = {a: 1, b: 2, c: 3, d: 4, e: 5}

_, _, bins = client.operate(key, [
    map_operations.map_remove_by_value_range("m", 2, 4,
        aerospike.MAP_RETURN_KEY_VALUE)
])
# bins["m"] == ["b", 2, "c", 3] (values >= 2 and < 4)
# m == {a: 1, d: 4, e: 5}

remove_by_value_rel_rank_range

remove_by_value_rel_rank_range(bin_name, value, rank[, count], result_type[, context])

Description

Remove all {key: value} pairs where origin = rank(value), r = rankof(map.value) and r >= origin + rank and r < origin + rank + count. Omitting count select element(s) where r >= origin + rank.

Arguments

Name	Type	Description
bin_name	string	Name of the bin to operate on.
value	any	Value that rank is measured from. It need not be present in the collection — the rank is taken from where it would sort.
rank	integer	Zero-based rank in value order, 0 being the smallest. A negative rank counts back from the largest.
count	integer	Number of elements to select. Optional; defaults to the rest of the collection.
result_type	integer literal	Which form the result takes — a count, an index, a rank, a value, or nothing. See Return types.
context	Context instance	Optional context path from the bin to a nested List or Map, one selector per nesting level. Omit it to operate on the top level of the map.

Returns

Multi result

Expression form

map_remove_by_rel_rank_range, map_remove_by_rel_rank_range_to_end

Code sample

Java SDK

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}
// From value 3 (rank 2), offset 0, count 2

try (RecordStream rs = session.upsert(key)
    .bin("m").onMapValueRelativeRankRange(3, 0, 2).removeAnd().getKeysAndValues()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns {c: 3, d: 4}
}
// m == {a: 1, b: 2, e: 5}

Python SDK

# m = {a: 1, b: 2, c: 3, d: 4, e: 5}
# From value 3 (rank 2), offset 0, count 2

stream = (session.upsert(key).bin("m").on_map_value_relative_rank_range(3, 0, 2)
          .remove(return_type=MapReturnType.KEY_VALUE).execute())
# returns {"c": 3, "d": 4}
# m == {a: 1, b: 2, e: 5}

Rust

// Requires: use aerospike::operations::maps::{self, MapReturnType};
// m = {a: 1, b: 2, c: 3, d: 4, e: 5}
// From value 3 (rank 2), offset 0, count 2

let record = client.operate(&WritePolicy::default(), &key,
    &[maps::remove_by_value_relative_rank_range_count("m", as_val!(3), 0, 2, MapReturnType::KeyValue)]).await?;
// returns [("c", 3), ("d", 4)]
// m == {a: 1, b: 2, e: 5}

C#

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}
// From value 3 (rank 2), offset 0, count 2

Record record = client.Operate(null, key,
    MapOperation.RemoveByValueRelativeRankRange("m", Value.Get(3), 0, 2,
        MapReturnType.KEY_VALUE)
);
// returns [(c, 3), (d, 4)]
// m == {a: 1, b: 2, e: 5}

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
// m = {a: 1, b: 2, c: 3, d: 4, e: 5}
// From value 3 (rank 2), offset 0, count 2

record, err := client.Operate(nil, key,
    as.MapRemoveByValueRelativeRankRangeCountOp("m", 3, 0, 2,
        as.MapReturnType.KEY_VALUE),
)
// record.Bins["m"] == [{c: 3}, {d: 4}]
// m == {a: 1, b: 2, e: 5}

Node.js

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}
// From value 3 (rank 2), offset 0, count 2

const maps = Aerospike.maps

const result = await client.operate(key, [
    maps.removeByValueRelRankRange('m', 3, 0, 2, maps.returnType.KEY_VALUE)
])
// result.bins.m == ['c', 3, 'd', 4]
// m == {a: 1, b: 2, e: 5}

C

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}
// From value 3 (rank 2), offset 0, count 2

as_operations ops;
as_operations_inita(&ops, 1);
as_operations_map_remove_by_value_rel_rank_range(&ops, "m", NULL,
    (as_val*)as_integer_new(3), 0, 2,
    AS_MAP_RETURN_KEY_VALUE);

as_record* rec = NULL;
aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);
// rec bins "m" == ["c", 3, "d", 4]
// m == {a: 1, b: 2, e: 5}

Java

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}
// From value 3 (rank 2), offset 0, count 2

Record record = client.operate(null, key,
    MapOperation.removeByValueRelativeRankRange("m", Value.get(3), 0, 2,
        MapReturnType.KEY_VALUE)
);
// returns [c=3, d=4]
// m == {a: 1, b: 2, e: 5}

Python

# m = {a: 1, b: 2, c: 3, d: 4, e: 5}
# From value 3 (rank 2), offset 0, count 2

_, _, bins = client.operate(key, [
    map_operations.map_remove_by_value_rank_range_relative("m", 3, 0,
        aerospike.MAP_RETURN_KEY_VALUE, count=2)
])
# bins["m"] == ["c", 3, "d", 4]
# m == {a: 1, b: 2, e: 5}

Read operations

get_all_by_key_list

get_by_key_list(bin_name, keys, result_type[, context])

Description

Get all {key: value} pairs where map.key ∈ keyList.

Arguments

Name	Type	Description
bin_name	string	Name of the bin to operate on.
keys	list	Keys to match, as a list.
result_type	integer literal	Which form the result takes — a count, an index, a rank, a value, or nothing. See Return types.
context	Context instance	Optional context path from the bin to a nested List or Map, one selector per nesting level. Omit it to operate on the top level of the map.

Returns

Multi result

Expression form

map_get_by_key_list

Performance

Requesting an ORDERED_MAP return type on an unordered map adds extra ordering cost relative to the number of elements in the result set. See Map performance.

Code sample

Java SDK

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

try (RecordStream rs = session.query(key)
    .bin("m").onMapKeyList(List.of("a", "c", "e")).getKeysAndValues()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns {a: 1, c: 3, e: 5}
}

Python SDK

# m = {a: 1, b: 2, c: 3, d: 4, e: 5}

stream = (session.query(key).bin("m").on_map_key_list(["a", "c", "e"])
          .get_keys_and_values().execute())
# returns {"a": 1, "c": 3, "e": 5}

Rust

// Requires: use aerospike::operations::maps::{self, MapReturnType};
// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

let record = client.operate(&WritePolicy::default(), &key,
    &[maps::get_by_key_list("m", as_values!("a", "c", "e"), MapReturnType::KeyValue)]).await?;
// returns [("a", 1), ("c", 3), ("e", 5)]

C#

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

IList keys = new List<Value> {
    Value.Get("a"), Value.Get("c"), Value.Get("e")
};
Record record = client.Operate(null, key,
    MapOperation.GetByKeyList("m", keys, MapReturnType.KEY_VALUE)
);
// returns [(a, 1), (c, 3), (e, 5)]

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

record, err := client.Operate(nil, key,
    as.MapGetByKeyListOp("m", []interface{}{"a", "c", "e"},
        as.MapReturnType.KEY_VALUE),
)
// record.Bins["m"] == [{a: 1}, {c: 3}, {e: 5}]

Node.js

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

const maps = Aerospike.maps

const result = await client.operate(key, [
    maps.getByKeyList('m', ['a', 'c', 'e'], maps.returnType.KEY_VALUE)
])
// result.bins.m == ['a', 1, 'c', 3, 'e', 5]

C

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

as_arraylist keys;
as_arraylist_init(&keys, 3, 0);
as_arraylist_append_str(&keys, "a");
as_arraylist_append_str(&keys, "c");
as_arraylist_append_str(&keys, "e");

as_operations ops;
as_operations_inita(&ops, 1);
as_operations_map_get_by_key_list(&ops, "m", NULL,
    (as_list*)&keys, AS_MAP_RETURN_KEY_VALUE);

as_record* rec = NULL;
aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);
// rec bins "m" == ["a", 1, "c", 3, "e", 5]

Java

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

List<Value> keys = Arrays.asList(Value.get("a"), Value.get("c"), Value.get("e"));
Record record = client.operate(null, key,
    MapOperation.getByKeyList("m", keys, MapReturnType.KEY_VALUE)
);
// returns [a=1, c=3, e=5]

Python

# m = {a: 1, b: 2, c: 3, d: 4, e: 5}

_, _, bins = client.operate(key, [
    map_operations.map_get_by_key_list("m", ["a", "c", "e"],
        aerospike.MAP_RETURN_KEY_VALUE)
])
# bins["m"] == ["a", 1, "c", 3, "e", 5]

get_all_by_value_list

get_by_value_list(bin_name, values, result_type[, context])

Description

Get all {key: value} pairs where map.value ∈ valueList.

Arguments

Name	Type	Description
bin_name	string	Name of the bin to operate on.
values	list	Values to match, as a list. Every entry whose value equals any of them is selected.
result_type	integer literal	Which form the result takes — a count, an index, a rank, a value, or nothing. See Return types.
context	Context instance	Optional context path from the bin to a nested List or Map, one selector per nesting level. Omit it to operate on the top level of the map.

Returns

Multi result

Expression form

map_get_by_value_list

Performance

Requesting an ORDERED_MAP return type on an unordered map adds extra ordering cost relative to the number of elements in the result set. See Map performance.

Code sample

Java SDK

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

try (RecordStream rs = session.query(key)
    .bin("m").onMapValueList(List.of(2, 4)).getKeys()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns [b, d]
}

Python SDK

# m = {a: 1, b: 2, c: 3, d: 4, e: 5}

stream = session.query(key).bin("m").on_map_value_list([2, 4]).get_keys().execute()
# returns ["b", "d"]

Rust

// Requires: use aerospike::operations::maps::{self, MapReturnType};
// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

let record = client.operate(&WritePolicy::default(), &key,
    &[maps::get_by_value_list("m", as_values!(2, 4), MapReturnType::Key)]).await?;
// returns ["b", "d"]

C#

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

IList values = new List<Value> { Value.Get(2), Value.Get(4) };
Record record = client.Operate(null, key,
    MapOperation.GetByValueList("m", values, MapReturnType.KEY)
);
// returns [b, d]

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

record, err := client.Operate(nil, key,
    as.MapGetByValueListOp("m", []any{2, 4}, as.MapReturnType.KEY),
)
// record.Bins["m"] == ["b", "d"]

Node.js

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

const maps = Aerospike.maps

const result = await client.operate(key, [
    maps.getByValueList('m', [2, 4], maps.returnType.KEY)
])
// result.bins.m == ['b', 'd']

C

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

as_arraylist values;
as_arraylist_init(&values, 2, 0);
as_arraylist_append_int64(&values, 2);
as_arraylist_append_int64(&values, 4);

as_operations ops;
as_operations_inita(&ops, 1);
as_operations_map_get_by_value_list(&ops, "m", NULL,
    (as_list*)&values, AS_MAP_RETURN_KEY);

as_record* rec = NULL;
aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);
// rec bins "m" == ["b", "d"]

Java

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

List<Value> values = Arrays.asList(Value.get(2), Value.get(4));
Record record = client.operate(null, key,
    MapOperation.getByValueList("m", values, MapReturnType.KEY)
);
// returns [b, d]

Python

# m = {a: 1, b: 2, c: 3, d: 4, e: 5}

_, _, bins = client.operate(key, [
    map_operations.map_get_by_value_list("m", [2, 4],
        aerospike.MAP_RETURN_KEY)
])
# bins["m"] == ["b", "d"]

get_all_by_value

get_by_value(bin_name, value, result_type[, context])

Description

Get all {key: value} pairs where map.value == value.

Arguments

Name	Type	Description
bin_name	string	Name of the bin to operate on.
value	any	Value to match. Every entry whose value equals it is selected.
result_type	integer literal	Which form the result takes — a count, an index, a rank, a value, or nothing. See Return types.
context	Context instance	Optional context path from the bin to a nested List or Map, one selector per nesting level. Omit it to operate on the top level of the map.

Returns

Multi result

Expression form

map_get_by_value

Performance

Requesting an INDEX return type adds 𝓞(N + M) on an unordered map, or 𝓞(M) on a map with a persisted offset index. Requesting an ORDERED_MAP return type on an unordered map adds extra ordering cost relative to the number of elements in the result set. See Map performance.

Code sample

Java SDK

// m = {a: 1, b: 2, c: 1, d: 3}

try (RecordStream rs = session.query(key)
    .bin("m").onMapValue(1).getKeys()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns [a, c] (all keys with value == 1)
}

Python SDK

# m = {a: 1, b: 2, c: 1, d: 3}

stream = session.query(key).bin("m").on_map_value(1).get_keys().execute()
# returns ["a", "c"] (all keys with value == 1)

Rust

// Requires: use aerospike::operations::maps::{self, MapReturnType};
// m = {a: 1, b: 2, c: 1, d: 3}

let record = client.operate(&WritePolicy::default(), &key,
    &[maps::get_by_value("m", as_val!(1), MapReturnType::Key)]).await?;
// returns ["a", "c"] (all keys with value == 1)

C#

// m = {a: 1, b: 2, c: 1, d: 3}

Record record = client.Operate(null, key,
    MapOperation.GetByValue("m", Value.Get(1), MapReturnType.KEY)
);
// returns [a, c] (all keys with value == 1)

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
// m = {a: 1, b: 2, c: 1, d: 3}

record, err := client.Operate(nil, key,
    as.MapGetByValueOp("m", 1, as.MapReturnType.KEY),
)
// record.Bins["m"] == ["a", "c"] (all keys with value == 1)

Node.js

// m = {a: 1, b: 2, c: 1, d: 3}

const maps = Aerospike.maps

const result = await client.operate(key, [
    maps.getByValue('m', 1, maps.returnType.KEY)
])
// result.bins.m == ['a', 'c'] (all keys with value == 1)

C

// m = {a: 1, b: 2, c: 1, d: 3}

as_operations ops;
as_operations_inita(&ops, 1);
as_operations_map_get_by_value(&ops, "m", NULL,
    (as_val*)as_integer_new(1), AS_MAP_RETURN_KEY);

as_record* rec = NULL;
aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);
// rec bins "m" == ["a", "c"] (all keys with value == 1)

Java

// m = {a: 1, b: 2, c: 1, d: 3}

Record record = client.operate(null, key,
    MapOperation.getByValue("m", Value.get(1), MapReturnType.KEY)
);
// returns [a, c] (all keys with value == 1)

Python

# m = {a: 1, b: 2, c: 1, d: 3}

_, _, bins = client.operate(key, [
    map_operations.map_get_by_value("m", 1, aerospike.MAP_RETURN_KEY)
])
# bins["m"] == ["a", "c"] (all keys with value == 1)

get_by_index_range

get_by_index_range(bin_name, index[, count], result_type[, context])

Description

Get all {key: value} pairs where k = indexof(map.key) and k >= index and k < index + count. Omitting count select element(s) where k >= origin + index.

Arguments

Name	Type	Description
bin_name	string	Name of the bin to operate on.
index	integer	Zero-based position, 0 being the first element. A negative index counts back from the end.
count	integer	Number of elements to select. Optional; defaults to the rest of the collection.
result_type	integer literal	Which form the result takes — a count, an index, a rank, a value, or nothing. See Return types.
context	Context instance	Optional context path from the bin to a nested List or Map, one selector per nesting level. Omit it to operate on the top level of the map.

Returns

Multi result

Expression form

map_get_by_index_range, map_get_by_index_range_to_end

Performance

Requesting a RANK return type adds 𝓞(N log N). Requesting an ORDERED_MAP return type on an unordered map adds extra ordering cost relative to the number of elements in the result set. See Map performance.

Code sample

Java SDK

// m = {a: 1, b: 2, c: 3, d: 4, e: 5} (K_ORDERED)

try (RecordStream rs = session.query(key)
    .bin("m").onMapIndexRange(1, 2).getKeysAndValues()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns {b: 2, c: 3} (2 entries starting at index 1)
}

Python SDK

# m = {a: 1, b: 2, c: 3, d: 4, e: 5} (K_ORDERED)

stream = (session.query(key).bin("m").on_map_index_range(1, 2)
          .get_keys_and_values().execute())
# returns {"b": 2, "c": 3} (2 entries starting at index 1)

Rust

// Requires: use aerospike::operations::maps::{self, MapReturnType};
// m = {a: 1, b: 2, c: 3, d: 4, e: 5} (K_ORDERED)

let record = client.operate(&WritePolicy::default(), &key,
    &[maps::get_by_index_range("m", 1, 2, MapReturnType::KeyValue)]).await?;
// returns [("b", 2), ("c", 3)] (2 entries starting at index 1)

C#

// m = {a: 1, b: 2, c: 3, d: 4, e: 5} (K_ORDERED)

Record record = client.Operate(null, key,
    MapOperation.GetByIndexRange("m", 1, 2, MapReturnType.KEY_VALUE)
);
// returns [(b, 2), (c, 3)] (2 entries starting at index 1)

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
// m = {a: 1, b: 2, c: 3, d: 4, e: 5} (K_ORDERED)

record, err := client.Operate(nil, key,
    as.MapGetByIndexRangeCountOp("m", 1, 2, as.MapReturnType.KEY_VALUE),
)
// record.Bins["m"] == [{b: 2}, {c: 3}] (2 entries starting at index 1)

Node.js

// m = {a: 1, b: 2, c: 3, d: 4, e: 5} (K_ORDERED)

const maps = Aerospike.maps

const result = await client.operate(key, [
    maps.getByIndexRange('m', 1, 2, maps.returnType.KEY_VALUE)
])
// result.bins.m == ['b', 2, 'c', 3] (2 entries starting at index 1)

C

// m = {a: 1, b: 2, c: 3, d: 4, e: 5} (K_ORDERED)

as_operations ops;
as_operations_inita(&ops, 1);
as_operations_map_get_by_index_range(&ops, "m", NULL,
    1, 2, AS_MAP_RETURN_KEY_VALUE);

as_record* rec = NULL;
aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);
// rec bins "m" == ["b", 2, "c", 3] (2 entries starting at index 1)

Java

// m = {a: 1, b: 2, c: 3, d: 4, e: 5} (K_ORDERED)

Record record = client.operate(null, key,
    MapOperation.getByIndexRange("m", 1, 2, MapReturnType.KEY_VALUE)
);
// returns [b=2, c=3] (2 entries starting at index 1)

Python

# m = {a: 1, b: 2, c: 3, d: 4, e: 5} (K_ORDERED)

_, _, bins = client.operate(key, [
    map_operations.map_get_by_index_range("m", 1, 2,
        aerospike.MAP_RETURN_KEY_VALUE)
])
# bins["m"] == ["b", 2, "c", 3] (2 entries starting at index 1)

get_by_index

get_by_index(bin_name, index, result_type[, context])

Description

Get {key: value} entry where map.key is the ith smallest key where i == index.

Arguments

Name	Type	Description
bin_name	string	Name of the bin to operate on.
index	integer	Zero-based position, 0 being the first element. A negative index counts back from the end.
result_type	integer literal	Which form the result takes — a count, an index, a rank, a value, or nothing. See Return types.
context	Context instance	Optional context path from the bin to a nested List or Map, one selector per nesting level. Omit it to operate on the top level of the map.

Returns

Single result

Expression form

map_get_by_index

Performance

Requesting a RANK return type adds 𝓞(N), or 𝓞(log N) with a persisted full index. See Map performance.

Code sample

Java SDK

// m = {a: 1, b: 2, c: 3} (K_ORDERED)

try (RecordStream rs = session.query(key)
    .bin("m").onMapIndex(0).getKeysAndValues()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns {a: 1} (smallest key by index)
}

try (RecordStream rs = session.query(key)
    .bin("m").onMapIndex(-1).getKeysAndValues()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns {c: 3} (largest key by index)
}

Python SDK

# m = {a: 1, b: 2, c: 3} (K_ORDERED)

stream = session.query(key).bin("m").on_map_index(0).get_keys_and_values().execute()
# returns {"a": 1} (smallest key by index)
stream = session.query(key).bin("m").on_map_index(-1).get_keys_and_values().execute()
# returns {"c": 3} (largest key by index)

Rust

// Requires: use aerospike::operations::maps::{self, MapReturnType};
// m = {a: 1, b: 2, c: 3} (K_ORDERED)

let record = client.operate(&WritePolicy::default(), &key,
    &[maps::get_by_index("m", 0, MapReturnType::KeyValue)]).await?;
// returns [("a", 1)] (smallest key by index)

let record = client.operate(&WritePolicy::default(), &key,
    &[maps::get_by_index("m", -1, MapReturnType::KeyValue)]).await?;
// returns [("c", 3)] (largest key by index)

C#

// m = {a: 1, b: 2, c: 3} (K_ORDERED)

Record record = client.Operate(null, key,
    MapOperation.GetByIndex("m", 0, MapReturnType.KEY_VALUE)
);
// returns [(a, 1)] (smallest key by index)

record = client.Operate(null, key,
    MapOperation.GetByIndex("m", -1, MapReturnType.KEY_VALUE)
);
// returns [(c, 3)] (largest key by index)

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
// m = {a: 1, b: 2, c: 3} (K_ORDERED)

record, err := client.Operate(nil, key,
    as.MapGetByIndexOp("m", 0, as.MapReturnType.KEY_VALUE),
)
// record.Bins["m"] == [{a: 1}] (smallest key by index)

record, err = client.Operate(nil, key,
    as.MapGetByIndexOp("m", -1, as.MapReturnType.KEY_VALUE),
)
// record.Bins["m"] == [{c: 3}] (largest key by index)

Node.js

// m = {a: 1, b: 2, c: 3} (K_ORDERED)

const maps = Aerospike.maps

let result = await client.operate(key, [
    maps.getByIndex('m', 0, maps.returnType.KEY_VALUE)
])
// result.bins.m == ['a', 1] (smallest key by index)

result = await client.operate(key, [
    maps.getByIndex('m', -1, maps.returnType.KEY_VALUE)
])
// result.bins.m == ['c', 3] (largest key by index)

C

// m = {a: 1, b: 2, c: 3} (K_ORDERED)

as_operations ops;
as_operations_inita(&ops, 1);
as_operations_map_get_by_index(&ops, "m", NULL, 0, AS_MAP_RETURN_KEY_VALUE);

as_record* rec = NULL;
aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);
// rec bins "m" == ["a", 1] (smallest key by index)

as_operations ops2;
as_operations_inita(&ops2, 1);
as_operations_map_get_by_index(&ops2, "m", NULL, -1, AS_MAP_RETURN_KEY_VALUE);

as_record* rec2 = NULL;
aerospike_key_operate(&as, &err, NULL, &key, &ops2, &rec2);
// rec2 bins "m" == ["c", 3] (largest key by index)

Java

// m = {a: 1, b: 2, c: 3} (K_ORDERED)

Record record = client.operate(null, key,
    MapOperation.getByIndex("m", 0, MapReturnType.KEY_VALUE)
);
// returns [a=1] (smallest key by index)

record = client.operate(null, key,
    MapOperation.getByIndex("m", -1, MapReturnType.KEY_VALUE)
);
// returns [c=3] (largest key by index)

Python

# m = {a: 1, b: 2, c: 3} (K_ORDERED)

_, _, bins = client.operate(key, [
    map_operations.map_get_by_index("m", 0, aerospike.MAP_RETURN_KEY_VALUE)
])
# bins["m"] == ["a", 1] (smallest key by index)

_, _, bins = client.operate(key, [
    map_operations.map_get_by_index("m", -1, aerospike.MAP_RETURN_KEY_VALUE)
])
# bins["m"] == ["c", 3] (largest key by index)

get_by_key_interval

get_by_key_range(bin_name, key_begin, key_end, result_type[, context])

Description

Get all {key: value} pairs where map.key >= keyStart and map.key < keyStop. Omitting keyStop select element(s) where map.key >= keyStart.

Arguments

Name	Type	Description
bin_name	string	Name of the bin to operate on.
key_begin	any	Lowest key to match, inclusive.
key_end	any	Upper bound on the key, exclusive. Omit it to match everything from key_begin upward.
result_type	integer literal	Which form the result takes — a count, an index, a rank, a value, or nothing. See Return types.
context	Context instance	Optional context path from the bin to a nested List or Map, one selector per nesting level. Omit it to operate on the top level of the map.

Returns

Multi result

Expression form

map_get_by_key_range

Performance

Requesting a RANK return type adds 𝓞(N log N). Requesting an ORDERED_MAP return type on an unordered map adds extra ordering cost relative to the number of elements in the result set. See Map performance.

Code sample

Java SDK

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

try (RecordStream rs = session.query(key)
    .bin("m").onMapKeyRange("b", "d").getKeysAndValues()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns {b: 2, c: 3} (keys >= "b" and < "d")
}

Python SDK

# m = {a: 1, b: 2, c: 3, d: 4, e: 5}

stream = (session.query(key).bin("m").on_map_key_range("b", "d")
          .get_keys_and_values().execute())
# returns {"b": 2, "c": 3} (keys >= "b" and < "d")

Rust

// Requires: use aerospike::operations::maps::{self, MapReturnType};
// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

let record = client.operate(&WritePolicy::default(), &key,
    &[maps::get_by_key_range("m", as_val!("b"), as_val!("d"), MapReturnType::KeyValue)]).await?;
// returns [("b", 2), ("c", 3)] (keys >= "b" and < "d")

C#

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

Record record = client.Operate(null, key,
    MapOperation.GetByKeyRange("m", Value.Get("b"), Value.Get("d"),
        MapReturnType.KEY_VALUE)
);
// returns [(b, 2), (c, 3)] (keys >= "b" and < "d")

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

record, err := client.Operate(nil, key,
    as.MapGetByKeyRangeOp("m", "b", "d", as.MapReturnType.KEY_VALUE),
)
// record.Bins["m"] == [{b: 2}, {c: 3}] (keys >= "b" and < "d")

Node.js

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

const maps = Aerospike.maps

const result = await client.operate(key, [
    maps.getByKeyRange('m', 'b', 'd', maps.returnType.KEY_VALUE)
])
// result.bins.m == ['b', 2, 'c', 3] (keys >= "b" and < "d")

C

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

as_operations ops;
as_operations_inita(&ops, 1);
as_operations_map_get_by_key_range(&ops, "m", NULL,
    (as_val*)as_string_new("b", false),
    (as_val*)as_string_new("d", false),
    AS_MAP_RETURN_KEY_VALUE);

as_record* rec = NULL;
aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);
// rec bins "m" == ["b", 2, "c", 3] (keys >= "b" and < "d")

Java

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

Record record = client.operate(null, key,
    MapOperation.getByKeyRange("m", Value.get("b"), Value.get("d"),
        MapReturnType.KEY_VALUE)
);
// returns [b=2, c=3] (keys >= "b" and < "d")

Python

# m = {a: 1, b: 2, c: 3, d: 4, e: 5}

_, _, bins = client.operate(key, [
    map_operations.map_get_by_key_range("m", "b", "d",
        aerospike.MAP_RETURN_KEY_VALUE)
])
# bins["m"] == ["b", 2, "c", 3] (keys >= "b" and < "d")

get_by_key_rel_index_range

get_by_key_rel_index_range(bin_name, key, index[, count], result_type[, context])

Description

Get all {key: value} pairs where origin = index(key), k = indexof(map.key) and k >= origin + index and k < origin + index + count. Omitting count select element(s) where k >= origin + index.

Arguments

Name	Type	Description
bin_name	string	Name of the bin to operate on.
key	any	Key that index is measured from. It need not be present in the map — the index is taken from where it would sort.
index	integer	Zero-based position, 0 being the first element. A negative index counts back from the end.
count	integer	Number of elements to select. Optional; defaults to the rest of the collection.
result_type	integer literal	Which form the result takes — a count, an index, a rank, a value, or nothing. See Return types.
context	Context instance	Optional context path from the bin to a nested List or Map, one selector per nesting level. Omit it to operate on the top level of the map.

Returns

Multi result

Expression form

map_get_by_rel_index_range, map_get_by_rel_index_range_to_end

Code sample

Java SDK

// m = {a: 1, b: 2, c: 3, d: 4, e: 5} (K_ORDERED)
// Starting from key "b" (index 1), offset 0, count 3

try (RecordStream rs = session.query(key)
    .bin("m").onMapKeyRelativeIndexRange("b", 0, 3).getKeysAndValues()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns {b: 2, c: 3, d: 4}
}

Python SDK

# m = {a: 1, b: 2, c: 3, d: 4, e: 5} (K_ORDERED)
# Starting from key "b" (index 1), offset 0, count 3

stream = (session.query(key).bin("m").on_map_key_relative_index_range("b", 0, 3)
          .get_keys_and_values().execute())
# returns {"b": 2, "c": 3, "d": 4}

Rust

// Requires: use aerospike::operations::maps::{self, MapReturnType};
// m = {a: 1, b: 2, c: 3, d: 4, e: 5} (K_ORDERED)
// Starting from key "b" (index 1), offset 0, count 3

let record = client.operate(&WritePolicy::default(), &key,
    &[maps::get_by_key_relative_index_range_count("m", as_val!("b"), 0, 3, MapReturnType::KeyValue)]).await?;
// returns [("b", 2), ("c", 3), ("d", 4)]

C#

// m = {a: 1, b: 2, c: 3, d: 4, e: 5} (K_ORDERED)
// Starting from key "b" (index 1), offset 0, count 3

Record record = client.Operate(null, key,
    MapOperation.GetByKeyRelativeIndexRange("m", Value.Get("b"), 0, 3,
        MapReturnType.KEY_VALUE)
);
// returns [(b, 2), (c, 3), (d, 4)]

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
// m = {a: 1, b: 2, c: 3, d: 4, e: 5} (K_ORDERED)
// Starting from key "b" (index 1), offset 0, count 3

record, err := client.Operate(nil, key,
    as.MapGetByKeyRelativeIndexRangeCountOp("m", "b", 0, 3,
        as.MapReturnType.KEY_VALUE),
)
// record.Bins["m"] == [{b: 2}, {c: 3}, {d: 4}]

Node.js

// m = {a: 1, b: 2, c: 3, d: 4, e: 5} (K_ORDERED)
// Starting from key "b" (index 1), offset 0, count 3

const maps = Aerospike.maps

const result = await client.operate(key, [
    maps.getByKeyRelIndexRange('m', 'b', 0, 3, maps.returnType.KEY_VALUE)
])
// result.bins.m == ['b', 2, 'c', 3, 'd', 4]

C

// m = {a: 1, b: 2, c: 3, d: 4, e: 5} (K_ORDERED)
// Starting from key "b" (index 1), offset 0, count 3

as_operations ops;
as_operations_inita(&ops, 1);
as_operations_map_get_by_key_rel_index_range(&ops, "m", NULL,
    (as_val*)as_string_new("b", false), 0, 3,
    AS_MAP_RETURN_KEY_VALUE);

as_record* rec = NULL;
aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);
// rec bins "m" == ["b", 2, "c", 3, "d", 4]

Java

// m = {a: 1, b: 2, c: 3, d: 4, e: 5} (K_ORDERED)
// Starting from key "b" (index 1), offset 0, count 3

Record record = client.operate(null, key,
    MapOperation.getByKeyRelativeIndexRange("m", Value.get("b"), 0, 3,
        MapReturnType.KEY_VALUE)
);
// returns [b=2, c=3, d=4]

Python

# m = {a: 1, b: 2, c: 3, d: 4, e: 5} (K_ORDERED)
# Starting from key "b" (index 1), offset 0, count 3

_, _, bins = client.operate(key, [
    map_operations.map_get_by_key_index_range_relative("m", "b", 0,
        aerospike.MAP_RETURN_KEY_VALUE, count=3)
])
# bins["m"] == ["b", 2, "c", 3, "d", 4]

get_by_key

get_by_key(bin_name, key, result_type[, context])

Description

Get entry {key: value} where map.key == key.

Arguments

Name	Type	Description
bin_name	string	Name of the bin to operate on.
key	any	Map key to match.
result_type	integer literal	Which form the result takes — a count, an index, a rank, a value, or nothing. See Return types.
context	Context instance	Optional context path from the bin to a nested List or Map, one selector per nesting level. Omit it to operate on the top level of the map.

Returns

Single result

Expression form

map_get_by_key

Performance

Requesting an INDEX return type adds 𝓞(N), or 𝓞(log N) with a persisted index. Requesting an ORDERED_MAP return type on an unordered map adds extra ordering cost relative to the number of elements in the result set. See Map performance.

Code sample

Java SDK

// m = {a: 1, b: 2, c: 3}

try (RecordStream rs = session.query(key)
    .bin("m").onMapKey("b").getValues()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns 2
}

Python SDK

# m = {a: 1, b: 2, c: 3}

stream = session.query(key).bin("m").on_map_key("b").get_values().execute()
# returns 2

Rust

// Requires: use aerospike::operations::maps::{self, MapReturnType};
// m = {a: 1, b: 2, c: 3}

let record = client.operate(&WritePolicy::default(), &key,
    &[maps::get_by_key("m", as_val!("b"), MapReturnType::Value)]).await?;
// returns 2

C#

// m = {a: 1, b: 2, c: 3}

Record record = client.Operate(null, key,
    MapOperation.GetByKey("m", Value.Get("b"), MapReturnType.VALUE)
);
// returns 2

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
// m = {a: 1, b: 2, c: 3}

record, err := client.Operate(nil, key,
    as.MapGetByKeyOp("m", "b", as.MapReturnType.VALUE),
)
// record.Bins["m"] == 2

Node.js

// m = {a: 1, b: 2, c: 3}

const maps = Aerospike.maps

const result = await client.operate(key, [
    maps.getByKey('m', 'b', maps.returnType.VALUE)
])
// result.bins.m == 2

C

// m = {a: 1, b: 2, c: 3}

as_operations ops;
as_operations_inita(&ops, 1);
as_operations_map_get_by_key(&ops, "m", NULL,
    (as_val*)as_string_new("b", false), AS_MAP_RETURN_VALUE);

as_record* rec = NULL;
aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);
// rec bins "m" == 2

Java

// m = {a: 1, b: 2, c: 3}

Record record = client.operate(null, key,
    MapOperation.getByKey("m", Value.get("b"), MapReturnType.VALUE)
);
// returns 2

Python

# m = {a: 1, b: 2, c: 3}

_, _, bins = client.operate(key, [
    map_operations.map_get_by_key("m", "b", aerospike.MAP_RETURN_VALUE)
])
# bins["m"] == 2

get_by_rank_range

get_by_rank_range(bin_name, rank[, count], result_type[, context])

Description

Get all {key: value} pairs where r = rankof(map.value) and r >= rank and r < rank + count. Omitting count select element(s) where r >= rank.

Arguments

Name	Type	Description
bin_name	string	Name of the bin to operate on.
rank	integer	Zero-based rank in value order, 0 being the smallest. A negative rank counts back from the largest.
count	integer	Number of elements to select. Optional; defaults to the rest of the collection.
result_type	integer literal	Which form the result takes — a count, an index, a rank, a value, or nothing. See Return types.
context	Context instance	Optional context path from the bin to a nested List or Map, one selector per nesting level. Omit it to operate on the top level of the map.

Returns

Multi result

Expression form

map_get_by_rank_range, map_get_by_rank_range_to_end

Performance

Requesting an INDEX return type adds 𝓞(N log N) on an unordered map, or 𝓞(M) on a map with a persisted offset index. Requesting an ORDERED_MAP return type on an unordered map adds extra ordering cost relative to the number of elements in the result set. See Map performance.

Code sample

Java SDK

// m = {a: 3, b: 1, c: 5, d: 2, e: 4}

try (RecordStream rs = session.query(key)
    .bin("m").onMapRankRange(0, 2).getKeysAndValues()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns {b: 1, d: 2} (2 entries with lowest values)
}

Python SDK

# m = {a: 3, b: 1, c: 5, d: 2, e: 4}

stream = (session.query(key).bin("m").on_map_rank_range(0, 2)
          .get_keys_and_values().execute())
# returns {"b": 1, "d": 2} (2 entries with lowest values)

Rust

// Requires: use aerospike::operations::maps::{self, MapReturnType};
// m = {a: 3, b: 1, c: 5, d: 2, e: 4}

let record = client.operate(&WritePolicy::default(), &key,
    &[maps::get_by_rank_range("m", 0, 2, MapReturnType::KeyValue)]).await?;
// returns [("b", 1), ("d", 2)] (2 entries with lowest values)

C#

// m = {a: 3, b: 1, c: 5, d: 2, e: 4}

Record record = client.Operate(null, key,
    MapOperation.GetByRankRange("m", 0, 2, MapReturnType.KEY_VALUE)
);
// returns [(b, 1), (d, 2)] (2 entries with lowest values)

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
// m = {a: 3, b: 1, c: 5, d: 2, e: 4}

record, err := client.Operate(nil, key,
    as.MapGetByRankRangeCountOp("m", 0, 2, as.MapReturnType.KEY_VALUE),
)
// record.Bins["m"] == [{b: 1}, {d: 2}] (2 entries with lowest values)

Node.js

// m = {a: 3, b: 1, c: 5, d: 2, e: 4}

const maps = Aerospike.maps

const result = await client.operate(key, [
    maps.getByRankRange('m', 0, 2, maps.returnType.KEY_VALUE)
])
// result.bins.m == ['b', 1, 'd', 2] (2 entries with lowest values)

C

// m = {a: 3, b: 1, c: 5, d: 2, e: 4}

as_operations ops;
as_operations_inita(&ops, 1);
as_operations_map_get_by_rank_range(&ops, "m", NULL,
    0, 2, AS_MAP_RETURN_KEY_VALUE);

as_record* rec = NULL;
aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);
// rec bins "m" == ["b", 1, "d", 2] (2 entries with lowest values)

Java

// m = {a: 3, b: 1, c: 5, d: 2, e: 4}

Record record = client.operate(null, key,
    MapOperation.getByRankRange("m", 0, 2, MapReturnType.KEY_VALUE)
);
// returns [b=1, d=2] (2 entries with lowest values)

Python

# m = {a: 3, b: 1, c: 5, d: 2, e: 4}

_, _, bins = client.operate(key, [
    map_operations.map_get_by_rank_range("m", 0, 2,
        aerospike.MAP_RETURN_KEY_VALUE)
])
# bins["m"] == ["b", 1, "d", 2] (2 entries with lowest values)

get_by_rank

get_by_rank(bin_name, rank, result_type[, context])

Description

Get {key: value} entry where map.value is the ith smallest value where i == rank.

Arguments

Name	Type	Description
bin_name	string	Name of the bin to operate on.
rank	integer	Zero-based rank in value order, 0 being the smallest. A negative rank counts back from the largest.
result_type	integer literal	Which form the result takes — a count, an index, a rank, a value, or nothing. See Return types.
context	Context instance	Optional context path from the bin to a nested List or Map, one selector per nesting level. Omit it to operate on the top level of the map.

Returns

Single result

Expression form

map_get_by_rank

Performance

Requesting an INDEX return type adds 𝓞(N) on an unordered map, or 𝓞(1) on a map with a persisted offset index. Requesting an ORDERED_MAP return type on an unordered map adds extra ordering cost relative to the number of elements in the result set. See Map performance.

Code sample

Java SDK

// m = {a: 3, b: 1, c: 2}

try (RecordStream rs = session.query(key)
    .bin("m").onMapRank(0).getKeysAndValues()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns {b: 1} (smallest value)
}

try (RecordStream rs = session.query(key)
    .bin("m").onMapRank(-1).getKeysAndValues()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns {a: 3} (largest value)
}

Python SDK

# m = {a: 3, b: 1, c: 2}

stream = session.query(key).bin("m").on_map_rank(0).get_keys_and_values().execute()
# returns {"b": 1} (smallest value)
stream = session.query(key).bin("m").on_map_rank(-1).get_keys_and_values().execute()
# returns {"a": 3} (largest value)

Rust

// Requires: use aerospike::operations::maps::{self, MapReturnType};
// m = {a: 3, b: 1, c: 2}

let record = client.operate(&WritePolicy::default(), &key,
    &[maps::get_by_rank("m", 0, MapReturnType::KeyValue)]).await?;
// returns [("b", 1)] (smallest value)

let record = client.operate(&WritePolicy::default(), &key,
    &[maps::get_by_rank("m", -1, MapReturnType::KeyValue)]).await?;
// returns [("a", 3)] (largest value)

C#

// m = {a: 3, b: 1, c: 2}

Record record = client.Operate(null, key,
    MapOperation.GetByRank("m", 0, MapReturnType.KEY_VALUE)
);
// returns [(b, 1)] (smallest value)

record = client.Operate(null, key,
    MapOperation.GetByRank("m", -1, MapReturnType.KEY_VALUE)
);
// returns [(a, 3)] (largest value)

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
// m = {a: 3, b: 1, c: 2}

record, err := client.Operate(nil, key,
    as.MapGetByRankOp("m", 0, as.MapReturnType.KEY_VALUE),
)
// record.Bins["m"] == [{b: 1}] (smallest value)

record, err = client.Operate(nil, key,
    as.MapGetByRankOp("m", -1, as.MapReturnType.KEY_VALUE),
)
// record.Bins["m"] == [{a: 3}] (largest value)

Node.js

// m = {a: 3, b: 1, c: 2}

const maps = Aerospike.maps

let result = await client.operate(key, [
    maps.getByRank('m', 0, maps.returnType.KEY_VALUE)
])
// result.bins.m == ['b', 1] (smallest value)

result = await client.operate(key, [
    maps.getByRank('m', -1, maps.returnType.KEY_VALUE)
])
// result.bins.m == ['a', 3] (largest value)

C

// m = {a: 3, b: 1, c: 2}

as_operations ops;
as_operations_inita(&ops, 1);
as_operations_map_get_by_rank(&ops, "m", NULL, 0, AS_MAP_RETURN_KEY_VALUE);

as_record* rec = NULL;
aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);
// rec bins "m" == ["b", 1] (smallest value)

as_operations ops2;
as_operations_inita(&ops2, 1);
as_operations_map_get_by_rank(&ops2, "m", NULL, -1, AS_MAP_RETURN_KEY_VALUE);

as_record* rec2 = NULL;
aerospike_key_operate(&as, &err, NULL, &key, &ops2, &rec2);
// rec2 bins "m" == ["a", 3] (largest value)

Java

// m = {a: 3, b: 1, c: 2}

Record record = client.operate(null, key,
    MapOperation.getByRank("m", 0, MapReturnType.KEY_VALUE)
);
// returns [b=1] (smallest value)

record = client.operate(null, key,
    MapOperation.getByRank("m", -1, MapReturnType.KEY_VALUE)
);
// returns [a=3] (largest value)

Python

# m = {a: 3, b: 1, c: 2}

_, _, bins = client.operate(key, [
    map_operations.map_get_by_rank("m", 0, aerospike.MAP_RETURN_KEY_VALUE)
])
# bins["m"] == ["b", 1] (smallest value)

_, _, bins = client.operate(key, [
    map_operations.map_get_by_rank("m", -1, aerospike.MAP_RETURN_KEY_VALUE)
])
# bins["m"] == ["a", 3] (largest value)

get_by_value_interval

get_by_value_range(bin_name, value_begin, value_end, result_type[, context])

Description

Get all {key: value} pairs where map.value >= valueStart and map.value < valueStop. Omitting valueStop select element(s) where map.value >= valueStart.

Arguments

Name	Type	Description
bin_name	string	Name of the bin to operate on.
value_begin	any	Lowest value to match, inclusive.
value_end	any	Upper bound on the value, exclusive. Omit it to match everything from value_begin upward.
result_type	integer literal	Which form the result takes — a count, an index, a rank, a value, or nothing. See Return types.
context	Context instance	Optional context path from the bin to a nested List or Map, one selector per nesting level. Omit it to operate on the top level of the map.

Returns

Multi result

Expression form

map_get_by_value_range

Performance

Requesting an INDEX return type adds 𝓞(N + M) on an unordered map, or 𝓞(M) on a map with a persisted offset index. Requesting an ORDERED_MAP return type on an unordered map adds extra ordering cost relative to the number of elements in the result set. See Map performance.

Code sample

Java SDK

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

try (RecordStream rs = session.query(key)
    .bin("m").onMapValueRange(2, 4).getKeysAndValues()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns {b: 2, c: 3} (values >= 2 and < 4)
}

Python SDK

# m = {a: 1, b: 2, c: 3, d: 4, e: 5}

stream = (session.query(key).bin("m").on_map_value_range(2, 4)
          .get_keys_and_values().execute())
# returns {"b": 2, "c": 3} (values >= 2 and < 4)

Rust

// Requires: use aerospike::operations::maps::{self, MapReturnType};
// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

let record = client.operate(&WritePolicy::default(), &key,
    &[maps::get_by_value_range("m", as_val!(2), as_val!(4), MapReturnType::KeyValue)]).await?;
// returns [("b", 2), ("c", 3)] (values >= 2 and < 4)

C#

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

Record record = client.Operate(null, key,
    MapOperation.GetByValueRange("m", Value.Get(2), Value.Get(4),
        MapReturnType.KEY_VALUE)
);
// returns [(b, 2), (c, 3)] (values >= 2 and < 4)

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

record, err := client.Operate(nil, key,
    as.MapGetByValueRangeOp("m", 2, 4, as.MapReturnType.KEY_VALUE),
)
// record.Bins["m"] == [{b: 2}, {c: 3}] (values >= 2 and < 4)

Node.js

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

const maps = Aerospike.maps

const result = await client.operate(key, [
    maps.getByValueRange('m', 2, 4, maps.returnType.KEY_VALUE)
])
// result.bins.m == ['b', 2, 'c', 3] (values >= 2 and < 4)

C

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

as_operations ops;
as_operations_inita(&ops, 1);
as_operations_map_get_by_value_range(&ops, "m", NULL,
    (as_val*)as_integer_new(2),
    (as_val*)as_integer_new(4),
    AS_MAP_RETURN_KEY_VALUE);

as_record* rec = NULL;
aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);
// rec bins "m" == ["b", 2, "c", 3] (values >= 2 and < 4)

Java

// m = {a: 1, b: 2, c: 3, d: 4, e: 5}

Record record = client.operate(null, key,
    MapOperation.getByValueRange("m", Value.get(2), Value.get(4),
        MapReturnType.KEY_VALUE)
);
// returns [b=2, c=3] (values >= 2 and < 4)

Python

# m = {a: 1, b: 2, c: 3, d: 4, e: 5}

_, _, bins = client.operate(key, [
    map_operations.map_get_by_value_range("m", 2, 4,
        aerospike.MAP_RETURN_KEY_VALUE)
])
# bins["m"] == ["b", 2, "c", 3] (values >= 2 and < 4)

get_by_value_rel_rank_range

get_by_value_rel_rank_range(bin_name, value, rank[, count], result_type[, context])

Description

Get all {key: value} pairs where origin = rank(value), r = rankof(map.value) and r >= origin + rank and r < origin + rank + count. Omitting count select element(s) where r >= origin + rank.

Arguments

Name	Type	Description
bin_name	string	Name of the bin to operate on.
value	any	Value that rank is measured from. It need not be present in the collection — the rank is taken from where it would sort.
rank	integer	Zero-based rank in value order, 0 being the smallest. A negative rank counts back from the largest.
count	integer	Number of elements to select. Optional; defaults to the rest of the collection.
result_type	integer literal	Which form the result takes — a count, an index, a rank, a value, or nothing. See Return types.
context	Context instance	Optional context path from the bin to a nested List or Map, one selector per nesting level. Omit it to operate on the top level of the map.

Returns

Multi result

Expression form

map_get_by_rel_rank_range, map_get_by_rel_rank_range_to_end

Code sample

Java SDK

// m = {a: 11, b: 22, c: 33, d: 44, e: 55}
// Relative to value 30 (rank would be between b:22 and c:33), offset 0, count 2

try (RecordStream rs = session.query(key)
    .bin("m").onMapValueRelativeRankRange(30, 0, 2).getKeysAndValues()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns {c: 33, d: 44}
}

Python SDK

# m = {a: 11, b: 22, c: 33, d: 44, e: 55}
# Relative to value 30 (rank would be between b:22 and c:33), offset 0, count 2

stream = (session.query(key).bin("m").on_map_value_relative_rank_range(30, 0, 2)
          .get_keys_and_values().execute())
# returns {"c": 33, "d": 44}

Rust

// Requires: use aerospike::operations::maps::{self, MapReturnType};
// m = {a: 11, b: 22, c: 33, d: 44, e: 55}
// Relative to value 30 (rank would be between b:22 and c:33), offset 0, count 2

let record = client.operate(&WritePolicy::default(), &key,
    &[maps::get_by_value_relative_rank_range_count("m", as_val!(30), 0, 2, MapReturnType::KeyValue)]).await?;
// returns [("c", 33), ("d", 44)]

C#

// m = {a: 11, b: 22, c: 33, d: 44, e: 55}
// Relative to value 30 (rank would be between b:22 and c:33), offset 0, count 2

Record record = client.Operate(null, key,
    MapOperation.GetByValueRelativeRankRange("m", Value.Get(30), 0, 2,
        MapReturnType.KEY_VALUE)
);
// returns [(c, 33), (d, 44)]

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
// m = {a: 11, b: 22, c: 33, d: 44, e: 55}
// Relative to value 30 (rank would be between b:22 and c:33), offset 0, count 2

record, err := client.Operate(nil, key,
    as.MapGetByValueRelativeRankRangeCountOp("m", 30, 0, 2,
        as.MapReturnType.KEY_VALUE),
)
// record.Bins["m"] == [{c: 33}, {d: 44}]

Node.js

// m = {a: 11, b: 22, c: 33, d: 44, e: 55}
// Relative to value 30 (rank would be between b:22 and c:33), offset 0, count 2

const maps = Aerospike.maps

const result = await client.operate(key, [
    maps.getByValueRelRankRange('m', 30, 0, 2, maps.returnType.KEY_VALUE)
])
// result.bins.m == ['c', 33, 'd', 44]

C

// m = {a: 11, b: 22, c: 33, d: 44, e: 55}
// Relative to value 30 (rank would be between b:22 and c:33), offset 0, count 2

as_operations ops;
as_operations_inita(&ops, 1);
as_operations_map_get_by_value_rel_rank_range(&ops, "m", NULL,
    (as_val*)as_integer_new(30), 0, 2,
    AS_MAP_RETURN_KEY_VALUE);

as_record* rec = NULL;
aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);
// rec bins "m" == ["c", 33, "d", 44]

Java

// m = {a: 11, b: 22, c: 33, d: 44, e: 55}
// Relative to value 30 (rank would be between b:22 and c:33), offset 0, count 2

Record record = client.operate(null, key,
    MapOperation.getByValueRelativeRankRange("m", Value.get(30), 0, 2,
        MapReturnType.KEY_VALUE)
);
// returns [c=33, d=44]

Python

# m = {a: 11, b: 22, c: 33, d: 44, e: 55}
# Relative to value 30 (rank would be between b:22 and c:33), offset 0, count 2

_, _, bins = client.operate(key, [
    map_operations.map_get_by_value_rank_range_relative("m", 30, 0,
        aerospike.MAP_RETURN_KEY_VALUE, count=2)
])
# bins["m"] == ["c", 33, "d", 44]

size

size(bin_name[, context])

Arguments

Name	Type	Description
bin_name	string	Name of the bin to operate on.
context	Context instance	Optional context path from the bin to a nested List or Map, one selector per nesting level. Omit it to operate on the top level of the map.

Returns

Element count

Expression form

map_size

Code sample

Java SDK

// m = {a: 1, b: 2, c: 3}

try (RecordStream rs = session.query(key)
    .bin("m").mapSize()
    .execute()) {
    Record rec = rs.next().recordOrThrow();
    // returns 3
}

Python SDK

# m = {a: 1, b: 2, c: 3}

stream = session.query(key).bin("m").map_size().execute()
# returns 3

Rust

// Requires: use aerospike::operations::maps::{self};
// m = {a: 1, b: 2, c: 3}

let record = client.operate(&WritePolicy::default(), &key,
    &[maps::size("m")]).await?;
// returns 3

C#

// m = {a: 1, b: 2, c: 3}

Record record = client.Operate(null, key,
    MapOperation.Size("m")
);
// returns 3

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
// m = {a: 1, b: 2, c: 3}

record, err := client.Operate(nil, key,
    as.MapSizeOp("m"),
)
// record.Bins["m"] == 3

Node.js

// m = {a: 1, b: 2, c: 3}

const maps = Aerospike.maps

const result = await client.operate(key, [
    maps.size('m')
])
// result.bins.m == 3

C

// m = {a: 1, b: 2, c: 3}

as_operations ops;
as_operations_inita(&ops, 1);
as_operations_map_size(&ops, "m", NULL);

as_record* rec = NULL;
aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);
// rec bins "m" == 3

Java

// m = {a: 1, b: 2, c: 3}

Record record = client.operate(null, key,
    MapOperation.size("m")
);
// returns 3

Python

# m = {a: 1, b: 2, c: 3}

_, _, bins = client.operate(key, [
    map_operations.map_size("m")
])
# bins["m"] == 3

Set operations

set_type

set_map_policy(policy, bin_name[, context])

Description

Modifies the order of an existing map. Order can be UNORDERED, K_ORDERED, or KV_ORDERED

Arguments

Name	Type	Description
policy	Map policy	Ordering and write flags for the operation. See Write flags. The ordering attribute takes effect only when this operation creates the map; on a map that already exists it is ignored.
bin_name	string	Name of the bin to operate on.
context	Context instance	Optional context path from the bin to a nested List or Map, one selector per nesting level. Omit it to operate on the top level of the map.

Returns

null

Performance

The worst-case performance of modifying an unordered map to a K_ORDERED or KV_ORDERED one is 𝓞(N log N).

Code sample

Java SDK

// m = {a: 1, b: 2, c: 3} (UNORDERED)

try (RecordStream rs = session.upsert(key)
    .bin("m").mapSetPolicy(MapOrder.KEY_ORDERED)
    .execute()) {
    Record rec = rs.next().recordOrThrow();
}
// m is now K_ORDERED

Python SDK

# m = {a: 1, b: 2, c: 3} (UNORDERED)

session.upsert(key).bin("m").map_set_policy(MapOrder.KEY_ORDERED).execute()
# m is now K_ORDERED

Rust

// Requires: use aerospike::operations::maps::{self, MapOrder};
// m = {a: 1, b: 2, c: 3} (UNORDERED)

client.operate(&WritePolicy::default(), &key,
    &[maps::set_order("m", MapOrder::KeyOrdered)]).await?;
// m is now K_ORDERED

C#

// m = {a: 1, b: 2, c: 3} (UNORDERED)

client.Operate(null, key,
    MapOperation.SetMapPolicy(
        new MapPolicy(MapOrder.KEY_ORDERED, MapWriteFlags.DEFAULT), "m")
);
// m is now K_ORDERED

Go

// Requires: import as "github.com/aerospike/aerospike-client-go/v8"
// m = {a: 1, b: 2, c: 3} (UNORDERED)

policy := as.NewMapPolicy(as.MapOrder.KEY_ORDERED, as.MapWriteMode.UPDATE)
_, err := client.Operate(nil, key,
    as.MapSetPolicyOp(policy, "m"),
)
// m is now K_ORDERED

Node.js

// m = {a: 1, b: 2, c: 3} (UNORDERED)

const maps = Aerospike.maps

await client.operate(key, [
    maps.setPolicy('m', new Aerospike.MapPolicy({
        order: maps.order.KEY_ORDERED
    }))
])
// m is now K_ORDERED

C

// m = {a: 1, b: 2, c: 3} (UNORDERED)

as_map_policy mp;
as_map_policy_set_flags(&mp, AS_MAP_KEY_ORDERED, AS_MAP_WRITE_DEFAULT);

as_operations ops;
as_operations_inita(&ops, 1);
as_operations_map_set_policy(&ops, "m", NULL, &mp);

as_record* rec = NULL;
aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);
// m is now K_ORDERED

Java

// m = {a: 1, b: 2, c: 3} (UNORDERED)

client.operate(null, key,
    MapOperation.setMapPolicy(
        new MapPolicy(MapOrder.KEY_ORDERED, MapWriteFlags.DEFAULT), "m")
);
// m is now K_ORDERED

Python

# m = {a: 1, b: 2, c: 3} (UNORDERED)

client.operate(key, [
    map_operations.map_set_policy("m", {
        "map_order": aerospike.MAP_KEY_ORDERED
    })
])
# m is now K_ORDERED