Map operations
Context
Write Flags
Return Types
Availability
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(returnType, key)
Get entry {key: value} where map.key == key.
Returns: Single result, see returnType 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(returnType, index)
Get {key: value} entry where map.key is the ith smallest key where i == index.
Returns: Single result, see returnType 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(returnType, rank)
Get {key: value} entry where map.value is the ith smallest value where i == rank.
Returns: Single result, see returnType 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(returnType, 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 returnType 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(returnType, 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 returnType 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(returnType, 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 returnType 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(returnType, value)
Get all {key: value} pairs where map.value == value.
Returns: Multi result, see returnType 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(returnType, 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 returnType 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(returnType, 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 returnType 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(returnType, 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 returnType 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(returnType, keyList)
Get all {key: value} pairs where map.key ∈ keyList.
Returns: Multi result, see returnType 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(returnType, valueList)
Get all {key: value} pairs where map.value ∈ valueList.
Returns: Multi result, see returnType 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.
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}}
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.
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-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 |
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-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 |
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(returnType, key)
Remove entry {key: value} where map.key == key.
Returns: Single result, see returnType 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(returnType, index)
Remove {key: value} entry where map.key is the ith smallest key where i == index.
Returns: Single result, see returnType 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(returnType, rank)
Remove {key: value} entry where map.value is the ith smallest value where i == rank.
Returns: Single result, see returnType 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(returnType, 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 returnType 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(returnType, 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 returnType 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(returnType, 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 returnType 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(returnType, value)
Remove all {key: value} pairs where map.value == value.
Returns: Multi result, see returnType 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(returnType, 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 returnType 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(returnType, 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 returnType 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(returnType, 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.
Relative operations added since version 4.3
Returns: Multi result, see returnType 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(returnType, keyList)
Remove all {key: value} pairs where map.key ∈ keyList.
Returns: Multi result, see returnType 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(returnType, valueList)
Remove all {key: value} pairs where map.value ∈ valueList.
INDEX result supported since version 3.16.0
Returns: Multi result, see returnType 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.