Map Operations
Context
| Context Type | Description |
|---|---|
LIST_INDEX | Finds 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_RANK | Finds an element in a List by rank. A negative rank is a lookup performed in reverse from the highest ranked. |
LIST_VALUE | Finds an element in a List by value. |
LIST_INDEX_CREATE | Finds an element in a List by index. Creates the element if it does not exist. |
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 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
| 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 |
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 the search criteria. It can be combined with another return type in the range operations |
EXISTS | If 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
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.