map

使用任意数量的 key/value 对构造 Map 列
语法

map(key1, value1 [, key2, value2, ...])

参数

• key1、key2：Map 列中的 key
• value1、value2：Map 列中的 value

返回值

• 构造的 Map 列

示例

SELECT map(1, 2, 3, 4), map('k1', 'v1', 'k2', 'v2');

查询结果

{1:2,3:4}    {'k1':'v1','k2':'v2'}

arrayElement

查询 Map 的某个 key 的数据，不包含此 key 的行将填充默认值，等价于 map[key]
语法

arrayElement(map, key)

参数

• map：需要查询的 Map 列
• key：待查询的 key 名

返回值

• key 名对应的 value

示例

WITH map('k1', 1) AS m 
SELECT arrayElement(m, 'k1'), m['k1'], m['k2'];

查询结果

1    1    0

注意
使用 arrayElement 时会先读取整个 map 列再进行筛选，因此对于隐式列 Map 查询性能较低。隐式列 Map 更推荐使用 ** mapElement (或者 {}) 方式查询key。

mapElement

查询 Map 的某个 key 的数据，不包含此 key 的行将填充 NULL，等价于 map{key}
语法

mapElement(map, key)

参数

• map：需要查询的 Map 列
• key：待查询的 key 名

返回值

• key 名对应的 value

示例

WITH map('k1', 1) AS m 
SELECT mapElement(m, 'k1'), m{'k1'}, m{'k2'};

查询结果

1    1    NULL

注意
隐式列 Map 使用此方式只需要读取对应隐式列，效率相比 arrayElement 更高；

mapKeys

获取 Map 数据每行的 key 并返回为 Array
语法

mapKeys(map)

参数

• map：需要查询的 Map 列

返回值

• 每行所包含的 key 的 Array

示例

WITH map('k1', 'v1', 'k2', 'v2') AS m
SELECT mapKeys(m);

查询结果

['k1','k2']

注意
对于隐式列 Map，此方法会先读取整个 map 列，然后提取其中的 key 返回。效率较低，建议使用下面的 getMapKeys **** 方法。

mapValues

获取 Map 数据每行的 value 并返回为 Array
语法

mapValues(map)

参数

• map：需要查询的 Map 列

返回值

• 每行所包含的 value 的 Array

示例

WITH map('k1', 'v1', 'k2', 'v2') AS m
SELECT mapValues(m);

查询结果

['v1','v2']

getMapKeys

获取 Map 列（在指定分区）中包含的 key 的列表，结果中每个 key 只会出现一次
语法

getMapKeys('database', 'table', 'map' [, 'partition_regex'])

参数

• database：库名，需要加引号写为字符串常量
• table：表名，需要加引号写为字符串常量
• map：Map 列名，需要加引号写为字符串常量
• partition_regex：分区的正则表达式

返回值

• 该 Map 列（在指定分区）中包含的 key 的 Array

示例

INSERT INTO some_db.map_table (m) VALUES {'k1': 'v1', 'k2': 'v2'};
SELECT getMapKeys('some_db', 'map_table', 'm');

查询结果

['k1','k2']  

注意
此函数通过读取每个 part 的元数据来查找 key，因此只适用于隐式列 Map。

mapContains

返回 Map 列的每行是否包含目标 key
语法

mapContains(map, key)

参数

• map： Map 列
• key ：待查询的 key 名

返回值

• 每行是否包含指定的 key，1 表示包含，0 表示不包含，类型为 UInt8

示例

WITH map('k1', 'v1', 'k2', 'v2') AS m
SELECT mapContains(m, 'k1'), mapContains(m, 'k3');

查询结果

1    0

str_to_map

使用指定的分隔符将 String 解析为 Map(String, String) 类型。
语法

str_to_map(pattern, pair_delimiter, key_value_delimiter)

参数

• pattern： 需要解析的 String
• key_value_delimiter：key-value 之间的分隔符
• pair_delimiter：key-value 对的分隔符

返回值

• 构造的 Map 列

示例

SELECT str_to_map('k1=v1, k2=v2', ',', '=');

查询结果

{'k1':'v1','k2':'v2'}

mapFromArrays

使用两个 Array 构造 Map 列，第一个 Array 为 key，第二个 Array 为 value。
语法

mapFromArrays(keys, values)

参数

• keys： 用作 key 的列表
• values：用作 value 的列表，需要与 keys 每行有相同的长度

返回值

• 构造的 Map 列

示例

SELECT mapFromArrays(['a', 'b', 'c'], [1, 2, 3]);

查询结果

{'a':1,'b':2,'c':3}

mapAdd

将多个 Map 列对应 key 的 value 相加
语法

mapAdd(map1, map2 [, ...])

参数

• map1、map2： 需要相加的 Map 列

返回值

• 求和后的 Map 列

示例

SELECT mapAdd(map(1,1), map(1,2), map(2,2));

查询结果

{1:3,2:2}

mapSubtract

将多个 Map 列对应 key 的 value 相减（第一个值减去之后所有的值）
语法

mapAdd(map1, map2 [, ...])

参数

• map1： 作为被减数的 Map 列
• map2： 作为减数的 Map 列

返回值

• 求差后的 Map 列

示例

SELECT mapSubtract(map(1, 2)::Map(Int16,Int16), map(1, 1)::Map(Int16,Int16), map(2, -2)::Map(Int16,Int16));

查询结果

{1:1,2:2}

mapPopulateSeries

要求 Map key 类型为 Integer，填充该 Map 从最小的 key 到最大的 key 之间的所有 key 值，填充的 value 为对应类型的默认值。最大 key 也可由第二个参数指定。
该函数也可以传入两个 Array，第一个作为 key，第二个作为 value。
语法

mapPopulateSeries(map[, max])
mapPopulateSeries(keys, values[, max])

参数

• map： 需要填充的 Map 列，key 类型需要为 Integer
• keys：需要填充的 key 的列表，类型为 Array(Integer)
• values：需要填充的 value 的列表，类型为 Array
• max：指定的需要填充的最大的 key 的值

返回值

• 若第一个参数传入 Map，返回填充后的 Map 列
• 若前两个参数为 keys 和 values，返回填充后的 Array，并置于 Tuple 中。类型为 Tuple(Array, Array)

示例

SELECT mapPopulateSeries(map(2, 10, 5, 20)), mapPopulateSeries(map(2, 10, 5, 20), 3);
SELECT mapPopulateSeries([1, 5], [5, 20], 6);

查询结果

{2:10,3:0,4:0,5:20}    {2:10,3:0}
([1,2,3,4,5,6],[5,0,0,0,20,0])

mapContainsKeyLike

返回 Map 列的每行是否包含符合指定 pattern 的 key
语法

mapContainsKeyLike(map, pattern)

参数

• map：需要查询的 Map 列，key 需要为 String 或 FixedString 类型
• pattern：指定的 key 的 pattern，语法同 like 子句

返回值

• 每行是否包含符合指定 pattern 的 key，1 表示包含，0 表示不包含，类型为 UInt8

示例

WITH map('k1', 'v1', 'k2', 'v2') AS m
SELECT mapContainsKeyLike(m, 'k%'), mapContainsKeyLike(m, 'm%');

查询结果

1    0

mapExtractKeyLike

筛选 Map 列中符合指定 pattern 的 key 及其对应 value
语法

mapExtractKeyLike(map, pattern)

参数

• map：需要查询的 Map 列，key 需要为 String 或 FixedString 类型
• pattern：指定的 key 的 pattern，语法同 like 子句

返回值

• 筛选后的 Map 列

示例

WITH map('k1', 'v1', 'k2', 'v2') AS m
SELECT mapExtractKeyLike(m, 'k%'), mapExtractKeyLike(m, 'm%');

查询结果

{'k1':'v1','k2':'v2'}    {}

mapApply

对 Map 中每个 key-value 对执行指定的 lambda 表达式。
语法

mapApply(lambda, map)

参数

• lambda：以 key-value 对为参数的 lambda 表达式
• map：Map 列

返回值

• 以 lambda 返回的 key-value 对组成的新 Map 列

示例

WITH map(1, 1, 2, 2) AS m
SELECT mapApply((k, v) -> (toString(k), v * 2), m);

查询结果

{'1':2,'2':4}

mapFilter

使用传入的条件过滤 Map 中的 key-value 对。
语法

mapFilter(lambda, map)

参数

• lambda：以 key-value 对为参数的 lambda 表达式，返回 UInt8 或 Nullable(UInt8) 类型，0 和 NULL 表示删除，> 0 表示保留。
• map：需要过滤的 Map 列

返回值

• 过滤后的 Map 列

示例

SELECT _map, mapFilter((k, v) -> ((v % 2) = 0), _map)
FROM
(
    SELECT map('key1', number, 'key2', number * 2) AS _map
    FROM numbers(3)
)

查询结果

{'key1':0,'key2':0}    {'key1':0,'key2':0}
{'key1':1,'key2':2}    {'key2':2}
{'key1':2,'key2':4}    {'key1':2,'key2':4}

mapUpdate

复制 map1，并使用 map2 中的 value 更新到复制的 Map 列中并返回。对于 map1 和 map2 都存在的 key，将会保留 map2 中对应的 value。
语法

mapUpdate(map1, map2)

参数

• map1：被更新（复制）的 Map 列
• map2：用来更新 map1 的 Map 列

返回值

• 更新后的 Map 列

示例

WITH map('k1', 1, 'k2', 1) AS m1, map('k1', 2, 'k3', 2) AS m2
SELECT mapUpdate(m1, m2), mapUpdate(m2, m1);

查询结果

{'k1':2,'k2':1,'k3':2}    {'k1':1,'k2':1,'k3':2}