Map operations
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 parameter is a list of context types defining a path to the nested map element the operation should be applied to. Without a context it is assumed that the operation occurs at the top level of the 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. |
Modify operations
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 |
New value after decrement
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 |
New value after increment
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.
The element count of the map after the operation, in the ‘bins’ part of the record under the bin name.
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.
_, _, 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}}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.
The element count of the map after the operation, in the ‘bins’ part of the record under the bin name.
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.
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).
# {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}}remove_all_by_key_list(returnType, keyList)Remove all {key: value} pairs where map.key ∈ keyList.
Multi result
remove_all_by_value_list(returnType, valueList)Remove all {key: value} pairs where map.value ∈ valueList.
Multi result
remove_all_by_value(returnType, value)Remove all {key: value} pairs where map.value == value.
Multi result
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.
Multi result
remove_by_index(returnType, index)Remove {key: value} entry where map.key is the ith smallest key where i == index.
Single result
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.
Multi result
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.
Multi result
remove_by_key(returnType, key)Remove entry {key: value} where map.key == key.
Single result
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.
Multi result
remove_by_rank(returnType, rank)Remove {key: value} entry where map.value is the ith smallest value where i == rank.
Single result
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.
Multi result
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.
Multi result
Read operations
get_all_by_key_list(returnType, keyList)Get all {key: value} pairs where map.key ∈ keyList.
Multi result
get_all_by_value_list(returnType, valueList)Get all {key: value} pairs where map.value ∈ valueList.
Multi result
get_all_by_value(returnType, value)Get all {key: value} pairs where map.value == value.
Multi result
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.
Multi result
get_by_index(returnType, index)Get {key: value} entry where map.key is the ith smallest key where i == index.
Single result
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.
Multi result
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.
Multi result
get_by_key(returnType, key)Get entry {key: value} where map.key == key.
Single result
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.
Multi result
get_by_rank(returnType, rank)Get {key: value} entry where map.value is the ith smallest value where i == rank.
Single result
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.
Multi result
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.
Multi result