# Map

`Map(K, V)` stores an ordered collection of key/value pairs. Every key has type `K` and every value has type `V`.

Keys are not required to be unique. Duplicate keys and insertion order are retained. Keys cannot be `NULL` or have a nullable type.

## Syntax

```text
Map(K, V)
```

## Creating maps

Use `map(key, value, ...)`, a JSON object, or a JSON array of `[key, value]` pairs. Pair arrays preserve duplicate keys and allow non-string key types. Results render as pair arrays.

Every key and value is checked against its declared type. Use `Nullable(V)` when map values may be missing.

## Looking up keys

`map_element(map, key)` returns the value at the first matching key. A missing key returns the value type's default, such as zero, an empty string or `NULL` for a nullable value.

Use `map_contains` when you must distinguish a missing key from a stored default. `map_keys` and `map_values` return arrays that retain pair order and duplicates.

## Examples

### Storing counters

```sql
CREATE TABLE pages(id UInt32, counters Map(String, UInt64));
INSERT INTO pages VALUES (1, '{"views":10,"likes":2}');
```

```sql
SELECT map_element(counters, 'views'),
       map_element(counters, 'shares'),
       map_contains(counters, 'shares')
FROM pages
FORMAT csv;
```

```text
10,0,false
```

### Retaining duplicate keys

```sql
SELECT map_keys(map('a', 1, 'a', 2)),
       map_values(map('a', 1, 'a', 2)),
       map_element(map('a', 1, 'a', 2), 'a')
FORMAT csv;
```

```text
"[""a"",""a""]","[1,2]",1
```

### Non-string keys

```sql
SELECT CAST('[[1,"one"],[2,"two"]]' AS Map(UInt8, String))
FORMAT csv;
```

```text
"[[1,""one""],[2,""two""]]"
```

See [map functions](https://coordinatordb.com/docs/reference/functions/regular-functions/tuple-map-functions) and the [Map quickstart](https://coordinatordb.com/docs/get-started/quickstarts/working-with-the-map-type).