# Map functions

> 20 Map functions in NYXDB: names, aliases, signatures and behaviour.

{/* AUTO-GENERATED from the function catalog. DO NOT EDIT — overwritten on every build. */}

20 functions. Names resolve case-insensitively; an alias binds the same function as its canonical name. Each entry gives the signatures, the behaviour and an example.

| Function | Summary |
| --- | --- |
| [`map_add`](#map_add) | Merges key domains and totals their associated numeric contributions. |
| [`map_all`](#map_all) | Requires every stored key-value pair to satisfy a supplied predicate. |
| [`map_apply`](#map_apply) | Transforms both keys and values, then sorts the resulting unique keys. |
| [`map_cast`](#map_cast) | Constructs a unique-key mapping from alternating entries or parallel arrays. |
| [`map_concat`](#map_concat) | Combines disjoint mappings and rejects any repeated key across inputs. |
| [`map_contains`](#map_contains) | Checks whether a mapping stores a particular key regardless of its associated value. |
| [`map_contains_key_like`](#map_contains_key_like) | Detects string keys matching a SQL LIKE pattern among eligible entries. |
| [`map_contains_value_like`](#map_contains_value_like) | Searches stored text values for wildcard matches. |
| [`map_exists`](#map_exists) | Finds at least one key-value entry accepted by a Boolean lambda. |
| [`map_extract_key_like`](#map_extract_key_like) | Retains matching key entries as a canonically ordered submap. |
| [`map_extract_key_value_pairs`](#map_extract_key_value_pairs) | Parses delimited text into unique string-keyed string values. |
| [`map_extract_key_value_pairs_with_escaping`](#map_extract_key_value_pairs_with_escaping) | Decodes backslash-escaped pair text into an ordered dictionary. |
| [`map_extract_value_like`](#map_extract_value_like) | Selects entries by SQL wildcard matching on their textual payloads. |
| [`map_filter`](#map_filter) | Keeps key-value pairs selected by an entry-wise Boolean condition. |
| [`map_from_arrays`](#map_from_arrays) | Associates aligned key and value vectors into a sorted unique mapping. |
| [`map_keys`](#map_keys) | Extracts stored lookup keys in their canonical sorted order. |
| [`map_populate_series`](#map_populate_series) | Fills missing integer keys between range endpoints with default numeric values. |
| [`map_subtract`](#map_subtract) | Computes per-key differences by deducting later mappings from the first. |
| [`map_update`](#map_update) | Overlays right-hand entries onto a mapping, replacing matching left values. |
| [`map_values`](#map_values) | Projects stored payloads in the same positional order as their sorted keys. |

## map_add

Merges key domains and totals their associated numeric contributions.

```text
map_add(map(K,V:number),map(K,V),...) -> map(K,sum_type(V))
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/variadic+generic` |
| Returns | `map(K,sum_type(V))` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | NULL map gives NULL; NULL value treated as numeric zero |

Combines all keys and adds the numeric values associated with each key using checked SQL sum widening. Missing keys and NULL values contribute zero, whereas a NULL outer map returns NULL. Output keys retain canonical order; incompatible descriptors raise TYPE_MISMATCH and unrepresentable totals raise NUMERIC_OVERFLOW.

**Example**

```sql
map_add(map_cast('a', 2), map_cast('a', 3, 'b', 4))
-- → {'a': 5, 'b': 4}
```

## map_all

Requires every stored key-value pair to satisfy a supplied predicate.

```text
map_all(lambda(K,V)->bool,map(K,V)) -> bool
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary+generic+lambda` |
| Returns | `bool` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | NULL map gives NULL; NULL predicate is false |

Evaluates the lambda for each key-value pair and returns true only when every evaluation is true. Empty maps return true, NULL predicate results count as false, and a NULL outer map returns NULL. Keys are non-NULL and ordered, values retain their declared nullability, and an incompatible Boolean lambda signature raises TYPE_MISMATCH.

**Example**

```sql
map_all((k, v) -> v > 0, map_cast('a', 2, 'b', 3))
-- → true
```

## map_apply

Transforms both keys and values, then sorts the resulting unique keys.

```text
map_apply(lambda(K,V)->tuple(K′,V′),map(K,V)) -> map(K′,V′)
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary+generic+lambda` |
| Returns | `map(K′,V′)` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | NULL map gives NULL; value NULLs passed to lambda; resulting NULL keys rejected |

Applies a lambda returning a key-value tuple to every entry and orders the result by the transformed key descriptor. Input value NULLs are passed to the lambda, a NULL outer map returns NULL, and transformed NULL or duplicate keys raise INVALID_ARGUMENT. The new key type must support ordered keys and the lambda must return a compatible tuple or TYPE_MISMATCH is raised.

**Example**

```sql
map_apply((k, v) -> (k, v * 2), map_cast('a', 2))
-- → {'a': 4}
```

## map_cast

Constructs a unique-key mapping from alternating entries or parallel arrays.

```text
map_cast(K,V,...) -> map(K,V)
map_cast(array(K),array(V)) -> map(K,V)
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/variadic+generic` |
| Returns | `map(K,V)` |
| Aliases | `map` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | NULL keys rejected; NULL values retained only for nullable V; NULL array inputs give NULL |

Builds a map with canonical key order from alternating key-value arguments or equally sized key and value arrays. Keys must be non-NULL and support ordering; duplicates, NULL keys, odd variadic arity and unequal array lengths raise INVALID_ARGUMENT. NULL values require a nullable value descriptor, NULL outer arrays return NULL, and incompatible descriptors raise TYPE_MISMATCH.

**Example**

```sql
map_cast('b', 2, 'a', 1)
-- → {'a': 1, 'b': 2}
```

## map_concat

Combines disjoint mappings and rejects any repeated key across inputs.

```text
map_concat(map(K,V),map(K,V),...) -> map(K,V)
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/variadic+generic` |
| Returns | `map(K,V)` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

Copies all input entries into a canonically ordered map without choosing a winner for duplicate keys. Duplicate keys across inputs raise INVALID_ARGUMENT, distinguishing this contract from duplicate-preserving map concatenation in other dialects. A NULL outer argument returns NULL, nullable values remain NULL, and incompatible key or value descriptors raise TYPE_MISMATCH.

**Example**

```sql
map_concat(map_cast('b', 2), map_cast('a', 1))
-- → {'a': 1, 'b': 2}
```

## map_contains

Checks whether a mapping stores a particular key regardless of its associated value.

```text
map_contains(map(K,V),K) -> bool
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/binary+generic` |
| Returns | `bool` |
| Aliases | `map_contains_key`, `mapContains` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

Returns true when the searched key is present, including when its stored value is NULL. A NULL map or search argument returns NULL, and an empty map returns false. The search descriptor must be compatible with the non-NULL ordered key type or TYPE_MISMATCH is raised; value inspection is unnecessary.

**Example**

```sql
map_contains(map_cast('a', 1, 'b', 2), 'b')
-- → true
```

## map_contains_key_like

Detects string keys matching a SQL LIKE pattern among eligible entries.

```text
map_contains_key_like(map(string,V),pattern:string) -> bool
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/binary+generic` |
| Returns | `bool` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

Applies SQL LIKE to string keys and returns whether a matching entry exists; percent matches a sequence and underscore matches one character. Entries whose values are NULL do not match under this contract, and a NULL map or pattern returns NULL. Empty maps return false, while non-string key descriptors raise TYPE_MISMATCH.

**Example**

```sql
map_contains_key_like(map_cast('sensor_a', 2, 'product_b', 3), 'sensor%')
-- → true
```

## map_contains_value_like

Searches stored text values for wildcard matches.

```text
map_contains_value_like(map(K,string),pattern:string) -> bool
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/binary+generic` |
| Returns | `bool` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

Returns true if any non-NULL string value satisfies the supplied SQL LIKE pattern, using percent and underscore wildcard semantics. NULL stored values never match; NULL map or pattern arguments return NULL. An empty map produces false, and a value descriptor other than string raises TYPE_MISMATCH.

**Example**

```sql
map_contains_value_like(map_cast('a', 'red', 'b', 'blue'), 'bl%')
-- → true
```

## map_exists

Finds at least one key-value entry accepted by a Boolean lambda.

```text
map_exists(lambda(K,V)->bool,map(K,V)) -> bool
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary+generic+lambda` |
| Returns | `bool` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | NULL map gives NULL; NULL predicate is false |

Invokes the predicate on map entries and succeeds when at least one result is true. NULL predicate results are false, empty maps return false, and NULL outer input returns NULL. Nullable values are supplied to the lambda under their bound descriptor; an incompatible predicate signature raises TYPE_MISMATCH and its volatility governs invocation restrictions.

**Example**

```sql
map_exists((k, v) -> v > 2, map_cast('a', 1, 'b', 3))
-- → true
```

## map_extract_key_like

Retains matching key entries as a canonically ordered submap.

```text
map_extract_key_like(map(string,V),pattern:string) -> map(string,V)
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/binary+generic` |
| Returns | `map(string,V)` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

Keeps entries whose string key satisfies SQL LIKE, preserving canonical key order and the original descriptors. Entries with NULL values do not match under the stated contract, and NULL outer map or pattern arguments return NULL. No match produces an empty map; non-string key descriptors raise TYPE_MISMATCH.

**Example**

```sql
map_extract_key_like(map_cast('sensor_a', 2, 'product_b', 3), 'sensor%')
-- → {'sensor_a': 2}
```

## map_extract_key_value_pairs

Parses delimited text into unique string-keyed string values.

```text
map_extract_key_value_pairs(text:string) -> map(string,string)
map_extract_key_value_pairs(text:string,key_value_delimiter:string) -> map(string,string)
map_extract_key_value_pairs(text:string,key_value_delimiter:string,pair_delimiters:string) -> map(string,string)
map_extract_key_value_pairs(text:string,key_value_delimiter:string,pair_delimiters:string,quote:string) -> map(string,string)
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/1..4-ary` |
| Returns | `map(string,string)` |
| Aliases | `extract_key_value_pairs` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

Reads key-value pairs from text, defaulting to colon between key and value, space/comma/semicolon between pairs and double quote for quoting. The resulting map has canonical key order; malformed syntax or duplicate keys raises INVALID_ARGUMENT. NULL arguments return NULL, and this basic parser does not provide the separate backslash-escape decoding contract.

**Example**

```sql
map_extract_key_value_pairs('a:1,b:2')
-- → {'a': '1', 'b': '2'}
```

## map_extract_key_value_pairs_with_escaping

Decodes backslash-escaped pair text into an ordered dictionary.

```text
map_extract_key_value_pairs_with_escaping(text:string) -> map(string,string)
map_extract_key_value_pairs_with_escaping(text:string,key_value_delimiter:string) -> map(string,string)
map_extract_key_value_pairs_with_escaping(text:string,key_value_delimiter:string,pair_delimiters:string) -> map(string,string)
map_extract_key_value_pairs_with_escaping(text:string,key_value_delimiter:string,pair_delimiters:string,quote:string) -> map(string,string)
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/1..4-ary` |
| Returns | `map(string,string)` |
| Aliases | `extract_key_value_pairs_with_escaping` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

Parses delimited key-value text while interpreting backslash escapes, then produces unique ordered string keys with string values. Defaults are colon for assignment, space/comma/semicolon for pair separation and double quote for quoting; duplicate keys or malformed escaped input raise INVALID_ARGUMENT. NULL text or delimiter arguments return NULL rather than an empty dictionary.

**Example**

```sql
map_extract_key_value_pairs_with_escaping('a:1,b:2')
-- → {'a': '1', 'b': '2'}
```

## map_extract_value_like

Selects entries by SQL wildcard matching on their textual payloads.

```text
map_extract_value_like(map(K,string),pattern:string) -> map(K,string)
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/binary+generic` |
| Returns | `map(K,string)` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

Retains the key-value pairs whose non-NULL string value satisfies the LIKE pattern and emits them in canonical key order. NULL stored values are excluded, NULL outer arguments propagate NULL, and no matches yield an empty map. A non-string value descriptor raises TYPE_MISMATCH; key ordering and value descriptors are preserved.

**Example**

```sql
map_extract_value_like(map_cast('a', 'red', 'b', 'blue'), 'bl%')
-- → {'b': 'blue'}
```

## map_filter

Keeps key-value pairs selected by an entry-wise Boolean condition.

```text
map_filter(lambda(K,V)->bool,map(K,V)) -> map(K,V)
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary+generic+lambda` |
| Returns | `map(K,V)` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | NULL map gives NULL; NULL predicate is false |

Evaluates the lambda against each original key-value entry and includes that entry only when the result is true. NULL results are false, NULL outer input returns NULL, and an empty map remains empty. Surviving entries retain canonical key order and original descriptors; incompatible predicate argument or result types raise TYPE_MISMATCH.

**Example**

```sql
map_filter((k, v) -> v > 1, map_cast('a', 1, 'b', 3))
-- → {'b': 3}
```

## map_from_arrays

Associates aligned key and value vectors into a sorted unique mapping.

```text
map_from_arrays(array(K),array(V)) -> map(K,V)
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/binary+generic` |
| Returns | `map(K,V)` |
| Aliases | `mapFromArrays` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

Pairs each key-array position with the corresponding value-array position and canonicalizes output key order. NULL keys, duplicate keys and unequal input lengths raise INVALID_ARGUMENT, while nullable value elements are retained. NULL outer array input returns NULL, and keys without ordered-key capability or incompatible descriptors raise TYPE_MISMATCH.

**Example**

```sql
map_from_arrays(['b', 'a'], [2, 1])
-- → {'a': 1, 'b': 2}
```

## map_keys

Extracts stored lookup keys in their canonical sorted order.

```text
map_keys(map(K,V)) -> array(K)
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary+generic` |
| Returns | `array(K)` |
| Aliases | `mapKeys` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

Returns an array of all map keys ordered by the key descriptor, independently of the values stored at those keys. Keys are non-NULL, even when corresponding values are NULL; a NULL outer map returns NULL. Empty maps yield an empty key array whose element type remains the bound key type.

**Example**

```sql
map_keys(map_cast('b', 2, 'a', 1))
-- → ['a', 'b']
```

## map_populate_series

Fills missing integer keys between range endpoints with default numeric values.

```text
map_populate_series(map(K:int*,V:number)) -> map(K,V)
map_populate_series(map(K:int*,V:number),maximum:K) -> map(K,V)
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/1..2-ary+generic` |
| Returns | `map(K,V)` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

Expands integer keys from the existing minimum through the maximum, optionally extending the upper endpoint to the supplied maximum. Missing positions receive default(V), existing entries retain their values and NULL outer input returns NULL. Noninteger keys raise TYPE_MISMATCH, and the resulting element count is checked before allocation with RESOURCE_LIMIT on excess.

**Example**

```sql
map_populate_series(map_cast(1, 5, 3, 7))
-- → {1: 5, 2: 0, 3: 7}
```

## map_subtract

Computes per-key differences by deducting later mappings from the first.

```text
map_subtract(map(K,V:number),map(K,V),...) -> map(K,sum_type(V))
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/variadic+generic` |
| Returns | `map(K,sum_type(V))` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | NULL map gives NULL; NULL value treated as numeric zero |

Forms the union of key domains and subtracts each later map contribution from the first map value, taking absent entries as zero. NULL values also contribute zero, but a NULL outer map makes the whole result NULL. Values use checked SQL sum widening and keys retain canonical order; descriptor incompatibility raises TYPE_MISMATCH and overflow raises NUMERIC_OVERFLOW.

**Example**

```sql
map_subtract(map_cast('a', 8), map_cast('a', 3, 'b', 2))
-- → {'a': 5, 'b': -2}
```

## map_update

Overlays right-hand entries onto a mapping, replacing matching left values.

```text
map_update(map(K,V),map(K,V)) -> map(K,V)
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/binary+generic` |
| Returns | `map(K,V)` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

Creates the unique union of both key sets and chooses the right-hand value wherever a key occurs in both arguments. Right-hand NULL values replace earlier values when the descriptor is nullable, and a NULL outer map returns NULL. Canonical key order is retained; incompatible key or value descriptors raise TYPE_MISMATCH.

**Example**

```sql
map_update(map_cast('a', 1, 'b', 2), map_cast('b', 9))
-- → {'a': 1, 'b': 9}
```

## map_values

Projects stored payloads in the same positional order as their sorted keys.

```text
map_values(map(K,V)) -> array(V)
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary+generic` |
| Returns | `array(V)` |
| Aliases | `mapValues` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

Returns map values ordered by their associated canonical keys, aligning positionally with the key projection. Nullable values remain NULL entries, while a NULL outer map returns NULL. An empty map yields an empty array with the existing value descriptor rather than inferring a type from absent data.

**Example**

```sql
map_values(map_cast('b', 2, 'a', 1))
-- → [1, 2]
```

---

Source: https://nyxdb.io/docs/functions/map/