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 ​

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 ​

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

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

10,0,false

Retaining duplicate keys ​

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;

"[""a"",""a""]","[1,2]",1

Non-string keys ​

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

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

See map functions and the Map quickstart.