Skip to main content

Map Operations

Context

Context TypeDescription
LIST_INDEXFinds an element in a List by index. A negative index is a lookup performed in reverse from the end of the list. If it is out of bounds, a parameter error is returned.
LIST_RANKFinds an element in a List by rank. A negative rank is a lookup performed in reverse from the highest ranked.
LIST_VALUEFinds an element in a List by value.
LIST_INDEX_CREATEFinds an element in a List by index. Creates the element if it does not exist.
MAP_INDEXFinds 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_KEYFinds an element in a Map by key.
MAP_RANKFinds an element in a Map by rank. A negative rank is a lookup performed in reverse from the highest ranked.
MAP_VALUEFinds an element in a Map by value.
MAP_KEY_CREATEFinds an element in a Map by key. Creates the element if it does not exist.

The context parameter is a list of context types defining a path to the nested list or map element the operation should be applied to. Without a context it is assumed that the operation occurs at the top level of the List or Map.

Write Flags

FlagDescription
MODIFY_DEFAULTDefault: upserts; create or update map keys
CREATE_ONLYOnly create new map keys. Fail if the key already exists
UPDATE_ONLYOnly update existing map keys. Fail if a key does not exist
NO_FAILNo-op instead of fail if a policy violation occurred, such as CREATE_ONLY
DO_PARTIALWhen used with NO_FAIL, add elements that did not violate a policy

Return Types

Return TypeDescription
KEYThe key of the element (in single result operations) or elements (in multi result operations)
VALUEThe value of the element (in single result operations) or elements (in multi result operations)
KEY_VALUEThe key/value pair of the element (in single result operations) or elements (in multi result operations)
NONENothing is returned. It speeds up remove operations by not constructing a reply
COUNTNumber of elements returned
INDEXKey order position of the element, from 0 (smallest key) to N-1 (largest)
REVERSE_INDEXReverse key order position of the element, from 0 (largest key) to N-1 (smallest)
RANKValue order of the element, with 0 being the smallest value
REVERSE_RANKReverse value order of the element, with 0 being the largest value
INVERTEDInvert the search criteria. It can be combined with another return type in the range operations
EXISTSIf the return type is EXISTS, the function returns a boolean value. For example, using the Map function get_all_by_value with the return type EXISTS returns true if the specified value is contained in the Map. The Map function get_all_by_value_list with the EXISTS, returns true if the Map contains any of the specified values.

Availability

Available since 3.8.4.
INVERTED flag available since 3.16.0.
NO_FAIL and DO_PARTIAL write flags available since 4.3.0.
Relative rank operations since 4.3.0.
Context available since 4.6.0.

Set Type Operations

set_type

set_type(type)

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

Returns: null

The writeFlags and context are described at the top of this page.

Performance: The worst-case performance of modifying an unordered map to a K_ORDERED or KV_ORDERED one is 𝓞(N log N). See Map Performance for the full worst-case performance analysis of the Map API.

Read Operations

size

size()

Returns: Element count

The writeFlags and context are described at the top of this page.

Performance: See Map Performance for the full worst-case performance analysis of the Map API.

get_by_key

get_by_key(resultType, key)

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

Returns: Single result, see resultType table

The returnTypes and context are described at the top of this page.

Performance: See Map Performance for the full worst-case performance analysis of the Map API.

get_by_index

get_by_index(resultType, index)

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

Returns: Single result, see resultType table

The returnTypes and context are described at the top of this page.

Performance: See Map Performance for the full worst-case performance analysis of the Map API.

get_by_rank

get_by_rank(resultType, rank)

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

Returns: Single result, see resultType table

The returnTypes and context are described at the top of this page.

Performance: See Map Performance for the full worst-case performance analysis of the Map API.

get_by_key_interval

get_by_key_interval(resultType, keyStart[, keyStop])

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

Returns: Multi result, see resultType table

The returnTypes and context are described at the top of this page.

Performance: See Map Performance for the full worst-case performance analysis of the Map API.

get_by_index_range

get_by_index_range(resultType, index[, count])

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.

Returns: Multi result, see resultType table

The returnTypes and context are described at the top of this page.

Performance: See Map Performance for the full worst-case performance analysis of the Map API.

get_by_value_interval

get_by_value_interval(resultType, valueStart[, valueStop])

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

Returns: Multi result, see resultType table

The returnTypes and context are described at the top of this page.

Performance: See Map Performance for the full worst-case performance analysis of the Map API.

get_all_by_value

get_all_by_value(resultType, value)

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

Returns: Multi result, see resultType table

The returnTypes and context are described at the top of this page.

Performance: See Map Performance for the full worst-case performance analysis of the Map API.

get_by_rank_range

get_by_rank_range(resultType, rank[, count])

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.

Returns: Multi result, see resultType table

The returnTypes and context are described at the top of this page.

Performance: See Map Performance for the full worst-case performance analysis of the Map API.

get_by_key_rel_index_range

get_by_key_rel_index_range(resultType, key, index[, count])

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.

Returns: Multi result, see resultType table

The returnTypes and context are described at the top of this page.

Performance: See Map Performance for the full worst-case performance analysis of the Map API.

get_by_value_rel_rank_range

get_by_value_rel_rank_range(resultType, value, rank[, count])

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.

Returns: Multi result, see resultType table

The returnTypes and context are described at the top of this page.

Performance: See Map Performance for the full worst-case performance analysis of the Map API.

get_all_by_key_list

get_all_by_key_list(resultType, keyList)

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

Returns: Multi result, see resultType table

The returnTypes and context are described at the top of this page.

Performance: See Map Performance for the full worst-case performance analysis of the Map API.

get_all_by_value_list

get_all_by_value_list(resultType, valueList)

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

Returns: Multi result, see resultType table

The returnTypes and context are described at the top of this page.

Performance: See Map Performance for the full worst-case performance analysis of the Map API.

Modify Operations

put

put(bin, key, value[, writeFlags, createType, context])

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

Returns: The element count of the map after the operation, in the 'bins' part of the record under the bin name.

The writeFlags and context are described at the top of this page.

Order: A map newly created with put can be optionally declared as K_ORDERED, KV_ORDERED or UNORDERED (default) using the createType. In most clients this is the map order attribute of the map policy.

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

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: For an in-memory namespace, ordered maps will have a 𝓞(log N) worst-case performance. For unordered maps or namespaces not in memory the worst-case performance is 𝓞(N). See Map Performance for the full worst-case performance analysis of the Map API.

Code Samples

The following is a Python code sample.

# {a: 1}
client.operate(key, [map_operations.map_put("m", "b", {})])
# {a: 1, b: {}}

ctx = [cdt_ctx.cdt_ctx_map_key("b")]
client.operate(key, [map_operations.map_put("m", "c", 3, ctx=ctx)])
# {a: 1, b: {c: 3}}

More Code Samples: Python | Java | C | C#

put_items

put_items(bin, items[, writeFlags, createType, context])

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.

Returns: The element count of the map after the operation, in the 'bins' part of the record under the bin name.

The writeFlags and context are described at the top of this page.

Order: A map newly created with put_items can be optionally declared as K_ORDERED, KV_ORDERED or UNORDERED (default) using the createType. In most clients this is the map order attribute of the map policy.

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

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.

Performance: See Map Performance for the full worst-case performance analysis of the Map API.

Code Samples

The following is a Python code sample.

_, _, bins = client.operate(key, [map_operations.map_put_items("m", {"a":1, "b":{}})])
# {a: 1, b: {}}
print("The map has {} elements".format(bins["m"]))
# The map has 2 elements

ctx = [cdt_ctx.cdt_ctx_map_key("b")]
client.operate(key, [map_operations.map_put_items("m", {"c": 3, "d": 4}, ctx=ctx)])
# {a: 1, b: {c: 3, d: 4}}

More Code Samples: Python

increment

increment(createType, key, delta-value)

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

Only works for integer or float value types in the {key: value} pair. Create map bin with type=createType if bin did not exist.

Type interaction between value and delta-value

Value-TypeDelta: integerDelta: float
Map Entry: integerAdd normallyTruncate to nearest integer and add
Map Entry: floatConvert integer to float and addAdd normally

Returns: New value after increment

The writeFlags and context are described at the top of this page.

Performance: See Map Performance for the full worst-case performance analysis of the Map API.

decrement

decrement(createType, key, delta-value)

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

Only works for integer or float value types in the {key: value} pair. Create map bin with type=createType if bin did not exist.

Type interaction between value and delta-value

Value-TypeDelta: integerDelta: float
Map Entry: integerSubtract normallyTruncate to nearest integer and subtract
Map Entry: floatConvert integer to float and subtractSubtract normally

Returns: New value after decrement

The writeFlags and context are described at the top of this page.

Performance: See Map Performance for the full worst-case performance analysis of the Map API.

clear

clear()

Clears the map. Map type stays the same.

Returns: null

The writeFlags and context are described at the top of this page.

Performance: See Map Performance for the full worst-case performance analysis of the Map API.

remove_by_key

remove_by_key(resultType, key)

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

Returns: Single result, see resultType table

The returnTypes and context are described at the top of this page.

Performance: See Map Performance for the full worst-case performance analysis of the Map API.

remove_by_index

remove_by_index(resultType, index)

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

Returns: Single result, see resultType table

The returnTypes and context are described at the top of this page.

Performance: See Map Performance for the full worst-case performance analysis of the Map API.

remove_by_rank

remove_by_rank(resultType, rank)

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

Returns: Single result, see resultType table

The returnTypes and context are described at the top of this page.

Performance: See Map Performance for the full worst-case performance analysis of the Map API.

remove_by_key_interval

remove_by_key_interval(resultType, keyStart[, keyStop])

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

Returns: Multi result, see resultType table

The returnTypes and context are described at the top of this page.

Performance: See Map Performance for the full worst-case performance analysis of the Map API.

remove_by_index_range

remove_by_index_range(resultType, index[, count])

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.

Returns: Multi result, see resultType table

The returnTypes and context are described at the top of this page.

Performance: See Map Performance for the full worst-case performance analysis of the Map API.

remove_by_value_interval

remove_by_value_interval(resultType, valueStart[, valueStop])

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

Returns: Multi result, see resultType table

The returnTypes and context are described at the top of this page.

Performance: See Map Performance for the full worst-case performance analysis of the Map API.

remove_all_by_value

remove_all_by_value(resultType, value)

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

Returns: Multi result, see resultType table

The returnTypes and context are described at the top of this page.

Performance: See Map Performance for the full worst-case performance analysis of the Map API.

remove_by_rank_range

remove_by_rank_range(resultType, rank[, count])

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.

Returns: Multi result, see resultType table

The returnTypes and context are described at the top of this page.

Performance: See Map Performance for the full worst-case performance analysis of the Map API.

remove_by_key_rel_index_range

remove_by_key_rel_index_range(resultType, key, index[, count])

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.

Returns: Multi result, see resultType table

The returnTypes and context are described at the top of this page.

Performance: See Map Performance for the full worst-case performance analysis of the Map API.

remove_by_value_rel_rank_range

remove_by_value_rel_rank_range(resultType, value, rank[, count])

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.

note

Relative operations added since version 4.3

Returns: Multi result, see resultType table

The returnTypes and context are described at the top of this page.

Performance: See Map Performance for the full worst-case performance analysis of the Map API.

remove_all_by_key_list

remove_all_by_key_list(resultType, keyList)

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

Returns: Multi result, see resultType table

The returnTypes and context are described at the top of this page.

Performance: See Map Performance for the full worst-case performance analysis of the Map API.

remove_all_by_value_list

remove_all_by_value_list(resultType, valueList)

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

note

INDEX result supported since version 3.16.0

Returns: Multi result, see resultType table

The returnTypes and context are described at the top of this page.

Performance: See Map Performance for the full worst-case performance analysis of the Map API.