Map 函数 | ClickHouse Docs

extractKeyValuePairs

引入版本：v23.4.0

从任意字符串中提取键值对。该字符串无需严格遵循键值对格式；

输入内容可以包含噪声 (例如日志文件) 。需要通过函数参数指定待解析的键值对格式。

键值对由一个键、一个 key_value_delimiter 和一个值组成。带引号的键和值也受支持。键值对之间必须用对分隔符分隔。

语法

extractKeyValuePairs(data, [key_value_delimiter], [pair_delimiter], [quoting_character], [unexpected_quoting_character_strategy])

参数

data - 用于提取键值对的字符串。String 或 FixedString。
key_value_delimiter - 用作键和值之间分隔符的字符。默认为 :。 String 或 FixedString。
pair_delimiters - 用作键值对之间分隔符的一组字符。默认为 \space、, 和 ;。 String 或 FixedString。
quoting_character - 用作引号字符的字符。默认为 "。 String 或 FixedString。
unexpected_quoting_character_strategy - 在 read_key 和 read_value 阶段，用于处理出现在非预期位置的引号字符的策略。可能的值：invalid、accept 和 promote。invalid 会丢弃键/值并切换回 WAITING_KEY 状态。accept 会将其视为普通字符。promote 会切换到 READ_QUOTED_{KEY/VALUE} 状态，并从下一个字符开始处理。默认值为 PROMOTE

返回值

提取出的键值对，存储在 Map(String, String) 中。

示例

查询：

简单示例

arthur :) select extractKeyValuePairs('name:neymar, age:31 team:psg,nationality:brazil') as kv

SELECT extractKeyValuePairs('name:neymar, age:31 team:psg,nationality:brazil') as kv

Query id: f9e0ca6f-3178-4ee2-aa2c-a5517abb9cee

┌

使用单引号作为引号字符

arthur :) select extractKeyValuePairs('name:\'neymar\';\'age\':31;team:psg;nationality:brazil,last_key:last_value', ':', ';,', '\'') as kv

SELECT extractKeyValuePairs('name:\'neymar\';\'age\':31;team:psg;nationality:brazil,last_key:last_value', ':', ';,', '\'') as kv

Query id: 0e22bf6b-9844-414a-99dc-32bf647abd5e

┌

unexpected_quoting_character_strategy 示例：

unexpected_quoting_character_strategy=invalid

SELECT extractKeyValuePairs('name"abc:5', ':', ' ,;', '\"', 'INVALID') as kv;

┌─kv────────────────┐
│ {'abc':'5'}       │
└───────────────────┘

SELECT extractKeyValuePairs('name"abc":5', ':', ' ,;', '\"', 'INVALID') as kv;

┌─kv──┐
│ {}  │
└─────┘

unexpected_quoting_character_strategy=accept

SELECT extractKeyValuePairs('name"abc:5', ':', ' ,;', '\"', 'ACCEPT') as kv;

┌─kv────────────────┐
│ {'name"abc':'5'}  │
└───────────────────┘

SELECT extractKeyValuePairs('name"abc":5', ':', ' ,;', '\"', 'ACCEPT') as kv;

┌─kv─────────────────┐
│ {'name"abc"':'5'}  │
└────────────────────┘

unexpected_quoting_character_strategy=promote

SELECT extractKeyValuePairs('name"abc:5', ':', ' ,;', '\"', 'PROMOTE') as kv;

┌─kv──┐
│ {}  │
└─────┘

SELECT extractKeyValuePairs('name"abc":5', ':', ' ,;', '\"', 'PROMOTE') as kv;

┌─kv───────────┐
│ {'abc':'5'}  │
└──────────────┘

不支持转义序列时的转义序列

arthur :) select extractKeyValuePairs('age:a\\x0A\\n\\0') as kv

SELECT extractKeyValuePairs('age:a\\x0A\\n\\0') AS kv

Query id: e9fd26ee-b41f-4a11-b17f-25af6fd5d356

┌

语法

extractKeyValuePairs(data, [key_value_delimiter], [pair_delimiter], [quoting_character], [unexpected_quoting_character_strategy])

别名: str_to_map, mapFromString

参数

无。

返回值

示例

extractKeyValuePairsWithEscaping

引入版本：v23.4.0

与 extractKeyValuePairs 相同，但支持转义。

支持的转义序列：\x、\N、\a、\b、\e、\f、\n、\r、\t、\v 和 \0。非标准转义序列会按原样返回 (包括反斜杠) ，除非它们属于以下之一： \\、'、"、backtick、/、= 或 ASCII 控制字符 (c <= 31) 。

当预转义和后转义都不适用时，此函数可以满足这类使用场景。例如，考虑以下输入字符串：a: "aaaa\"bbb"。预期输出为：a: aaaa\"bbbb。

预转义：如果先进行预转义，输出将为：a: "aaaa"bbb"，随后 extractKeyValuePairs 会输出：a: aaaa
后转义：extractKeyValuePairs 会输出 a: aaaa\，而后转义会将其保持原样。

键中的前导转义序列会被跳过，而在值中会被视为无效。

启用转义序列支持时的转义序列

arthur :) select extractKeyValuePairsWithEscaping('age:a\\x0A\\n\\0') as kv

SELECT extractKeyValuePairsWithEscaping('age:a\\x0A\\n\\0') AS kv

Query id: 44c114f0-5658-4c75-ab87-4574de3a1645

┌

语法

extractKeyValuePairsWithEscaping(data, [key_value_delimiter], [pair_delimiter], [quoting_character], [unexpected_quoting_character_strategy])

参数

无。

返回值

示例

map

引入版本：v21.1.0

根据键值对创建 Map(key, value) 类型的值。

语法

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

参数

key_n — Map 条目的键。Any
value_n — Map 条目的值。Any

返回值

返回一个包含 key:value 对的 Map。Map(Any, Any)

示例

使用示例

SELECT map('key1', number, 'key2', number * 2) FROM numbers(3)

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

mapAdd

引入版本：v20.7.0

收集所有键，并将对应的值相加。

语法

mapAdd(arg1[, arg2, ...])

参数

arg1[, arg2, ...] — Map 或由两个数组组成的Tuple，其中第一个数组中的元素表示键，第二个数组包含每个键对应的值。Map(K, V) 或 Tuple(Array(T), Array(T))

返回值

返回一个 Map 或元组，其中第一个数组包含已排序的键，第二个数组包含对应的值。Map(K, V) 或 Tuple(Array(T), Array(T)

示例

使用 Map 类型

SELECT mapAdd(map(1, 1), map(1, 1))

{1:2}

使用 Tuple

SELECT mapAdd(([toUInt8(1), 2], [1, 1]), ([toUInt8(1), 2], [1, 1]))

([1,2],[2,2])

mapAll

引入于：v23.4.0

用于测试某个条件是否对 map 中的所有键值对都成立。 mapAll 是一个高阶函数。你可以将 lambda 函数作为第一个参数传递给它。

语法

mapAll([func,] map)

参数

func — Lambda 函数。Lambda 函数
map — 待检查的 Map。Map(K, V)

返回值

如果所有键值对都满足条件，则返回 1；否则返回 0。UInt8

示例

使用示例

SELECT mapAll((k, v) -> v = 1, map('k1', 1, 'k2', 2))

mapApply

引入版本：v22.3.0

将函数应用于 map 的每个元素。

语法

mapApply(func, map)

参数

func — Lambda 函数。Lambda 函数
map — 要对其应用该函数的 Map。Map(K, V)

返回值

返回一个新 Map，它是对原始 Map 的每个元素应用 func 后得到的。Map(K, V)

示例

用法示例

SELECT mapApply((k, v) -> (k, v * 2), map('k1', 1, 'k2', 2))

{'k1':2,'k2':4}

mapConcat

引入版本：v23.4.0

根据键是否相同拼接多个 Map。如果多个输入 Map 中存在键相同的元素，则所有元素都会被添加到结果 Map 中，但只有第一个元素可通过运算符 [] 访问。

语法

mapConcat(maps)

参数

maps — 任意数量的 Map。Map

返回值

返回一个由作为参数传入的多个 Map 拼接而成的 Map。Map

示例

使用示例

SELECT mapConcat(map('k1', 'v1'), map('k2', 'v2'))

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

mapContainsKey

引入版本：v21.2.0

判断 map 中是否包含指定键。

语法

mapContainsKey(map, key)

别名: mapContains

参数

map — 要在其中搜索的 Map。Map(K, V)
key — 要搜索的键。其类型必须与 map 的键类型一致。Any

返回值

如果 map 包含该键，则返回 1，否则返回 0。UInt8

示例

用法示例

SELECT mapContainsKey(map('k1', 'v1', 'k2', 'v2'), 'k1')

mapContainsKeyLike

引入版本：v23.4.0

检查 map 是否包含匹配 LIKE 指定模式的键。

语法

mapContainsKeyLike(map, pattern)

参数

map — 要在其中搜索的 Map。 Map(K, V)
pattern — 用于匹配键名的模式。 const String

返回值

如果 map 包含与 pattern 匹配的键，则返回 1；否则返回 0。 UInt8

示例

使用示例

CREATE TABLE tab (a Map(String, String))
ENGINE = MergeTree
ORDER BY tuple();

INSERT INTO tab VALUES ({'abc':'abc','def':'def'}), ({'hij':'hij','klm':'klm'});

SELECT mapContainsKeyLike(a, 'a%') FROM tab;

┌─mapContainsKeyLike(a, 'a%')─┐
│                           1 │
│                           0 │
└─────────────────────────────┘

mapContainsValue

引入版本：v25.6.0

判断某个值是否包含在 Map 中。

语法

mapContainsValue(map, value)

参数

map — 要在其中搜索的 Map。Map(K, V)
value — 要搜索的值。其类型必须与 Map 的值类型一致。Any

返回值

如果 Map 包含该值，则返回 1；否则返回 0。UInt8

示例

使用示例

SELECT mapContainsValue(map('k1', 'v1', 'k2', 'v2'), 'v1')

mapContainsValueLike

引入版本：v25.5.0

检查 Map 中是否包含与指定模式 LIKE 匹配的值。

语法

mapContainsValueLike(map, pattern)

参数

map — 要搜索的 Map。Map(K, V)
pattern — 用于匹配值的模式。const String

返回值

如果 map 包含与 pattern 匹配的值，则返回 1；否则返回 0。UInt8

示例

用法示例

CREATE TABLE tab (a Map(String, String))
ENGINE = MergeTree
ORDER BY tuple();

INSERT INTO tab VALUES ({'abc':'abc','def':'def'}), ({'hij':'hij','klm':'klm'});

SELECT mapContainsValueLike(a, 'a%') FROM tab;

┌─mapContainsValueLike(a, 'a%')─┐
│                             1 │
│                             0 │
└───────────────────────────────┘

mapExists

引入版本：v23.4.0

检查映射中是否至少有一个键值对满足某个条件。 mapExists 是一个高阶函数。你可以将 lambda function 作为它的第一个参数传入。

语法

mapExists([func,] map)

参数

func — 可选。Lambda function。Lambda function
map — 要检查的 Map。Map(K, V)

返回值

如果至少有一个键值对满足条件，则返回 1；否则返回 0。UInt8

示例

使用示例

SELECT mapExists((k, v) -> v = 1, map('k1', 1, 'k2', 2))

mapExtractKeyLike

引入版本：v23.4.0

给定一个键为字符串的 map 和一个 LIKE 模式，该函数会返回一个 map，其中包含键与该模式匹配的元素。

语法

mapExtractKeyLike(map, pattern)

参数

map — 要从中提取内容的 Map。Map(K, V)
pattern — 用于匹配键名的模式。const String

返回值

返回一个 map，其中包含键名与指定模式匹配的元素。如果没有元素匹配该模式，则返回空 map。Map(K, V)

示例

用法示例

CREATE TABLE tab (a Map(String, String))
ENGINE = MergeTree
ORDER BY tuple();

INSERT INTO tab VALUES ({'abc':'abc','def':'def'}), ({'hij':'hij','klm':'klm'});

SELECT mapExtractKeyLike(a, 'a%') FROM tab;

┌─mapExtractKeyLike(a, 'a%')─┐
│ {'abc':'abc'}              │
│ {}                         │
└────────────────────────────┘

mapExtractValueLike

引入版本：v25.5.0

给定一个值为字符串的 map 和一个 LIKE 模式，此函数返回一个 map，其中包含值与该模式匹配的元素。

语法

mapExtractValueLike(map, pattern)

参数

map — 要从中提取元素的 Map。Map(K, V)
pattern — 用于匹配值的模式。const String

返回值

返回一个包含值符合指定模式的元素的 Map。如果没有元素匹配该模式，则返回空 Map。Map(K, V)

示例

用法示例

CREATE TABLE tab (a Map(String, String))
ENGINE = MergeTree
ORDER BY tuple();

INSERT INTO tab VALUES ({'abc':'abc','def':'def'}), ({'hij':'hij','klm':'klm'});

SELECT mapExtractValueLike(a, 'a%') FROM tab;

┌─mapExtractValueLike(a, 'a%')─┐
│ {'abc':'abc'}                │
│ {}                           │
└──────────────────────────────┘

mapFilter

引入版本：v22.3.0

通过对 map 中的每个元素应用函数，对 map 进行过滤。

语法

mapFilter(func, map)

参数

func — lambda 函数。lambda 函数
map — 要过滤的 Map。Map(K, V)

返回值

返回一个 Map，仅包含 func 返回值不为 0 的元素。Map(K, V)

示例

使用示例

SELECT mapFilter((k, v) -> v > 1, map('k1', 1, 'k2', 2))

{'k2':2}

mapFromArrays

引入版本：v23.3.0

根据键的 Array 或 map 以及值的 Array 或 map 创建一个 map。该函数是语法 CAST([...], 'Map(key_type, value_type)') 的一种便捷替代方案。

语法

mapFromArrays(keys, values)

别名: MAP_FROM_ARRAYS

参数

keys — 用于创建 Map 的键数组或键映射。Array 或 Map
values — 用于创建 Map 的值数组或值映射。Array 或 Map

返回值

返回一个 Map，其键和值由键数组和值数组/映射构造而成。Map

示例

基本用法

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

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

使用 Map 类型输入

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

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

mapKeys

引入版本：v21.2.0

返回给定 map 的键。启用设置 optimize_functions_to_subcolumns 后，可对此函数进行优化。启用该设置后，此函数仅读取 keys 子列，而不是整个 map。查询 SELECT mapKeys(m) FROM table 会被转换为 SELECT m.keys FROM table。

语法

mapKeys(map)

参数

map — 待提取键的 Map。Map(K, V)

返回值

返回包含该 Map 中所有键的数组。Array(T)

示例

用法示例

SELECT mapKeys(map('k1', 'v1', 'k2', 'v2'))

['k1','k2']

mapPartialReverseSort

引入版本：v23.4.0

将 map 中的元素按降序排列，并通过额外的 limit 参数支持部分排序。如果指定了 func 函数，则排序顺序由 func 函数应用于 map 的键和值后得到的结果决定。

语法

mapPartialReverseSort([func,] limit, map)

参数

func — 可选。Lambda 函数。Lambda function
limit — 对范围 [1..limit] 内的元素进行排序。(U)Int*
map — 要排序的 Map。Map(K, V)

返回值

返回按降序进行部分排序后的 Map。Map(K, V)

示例

使用示例

SELECT mapPartialReverseSort((k, v) -> v, 2, map('k1', 3, 'k2', 1, 'k3', 2))

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

mapPartialSort

引入版本：v23.4.0

按升序对 map 中的元素进行排序，并通过额外的 limit 参数支持部分排序。如果指定了 func 函数，则排序顺序由 func 函数应用于 map 的键和值后所得的结果决定。

语法

mapPartialSort([func,] limit, map)

参数

func — 可选。Lambda 函数。Lambda function
limit — 对范围 [1..limit] 内的元素进行排序。(U)Int*
map — 要排序的 Map。Map(K, V)

返回值

返回一个部分排序后的 Map。Map(K, V)

示例

使用示例

SELECT mapPartialSort((k, v) -> v, 2, map('k1', 3, 'k2', 1, 'k3', 2))

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

mapPopulateSeries

Introduced in: v20.10.0

用整数键补齐映射中缺失的键值对。如需将键扩展到超过当前最大值的位置，可以指定一个最大键。更具体地说，该函数返回一个映射，其中键按步长 1 形成从最小键到最大键 (如果指定，则到 max 参数) 的连续序列，并具有对应的值。如果某个键没有指定值，则使用默认值作为其值。如果键重复，则只有第一个值 (按出现顺序) 会与该键关联。

Syntax

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

参数

map — 键为整数的 Map。Map((U)Int*, V)
keys — 键数组。Array(T)
values — 值数组。Array(T)
max — 可选。最大键值。Int8 或 Int16 或 Int32 或 Int64 或 Int128 或 Int256

返回值

返回一个 Map，或一个由两个数组组成的 Tuple：第一个数组包含按排序顺序排列的键，第二个数组包含对应键的值。Map(K, V) 或 Tuple(Array(UInt*), Array(Any))

示例

使用 Map 类型

SELECT mapPopulateSeries(map(1, 10, 5, 20), 6)

{1:10,2:0,3:0,4:0,5:20,6:0}

使用映射数组

SELECT mapPopulateSeries([1, 2, 4], [11, 22, 44], 5)

([1,2,3,4,5],[11,22,0,44,0])

mapReverseSort

引入版本：v23.4.0

按降序对 map 中的元素进行排序。如果指定了 func 函数，则排序顺序由 func 函数作用于 map 的键和值后得到的结果决定。

语法

mapReverseSort([func,] map)

参数

func — 可选。Lambda 函数。Lambda function
map — 要排序的 Map。Map(K, V)

返回值

返回按降序排序后的 Map。Map(K, V)

示例

用法示例

SELECT mapReverseSort((k, v) -> v, map('k1', 3, 'k2', 1, 'k3', 2))

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

mapSort

引入版本：v23.4.0

按升序对 map 中的元素进行排序。如果指定了 func 函数，排序顺序将由 func 函数作用于 map 的键和值后得到的结果决定。

语法

mapSort([func,] map)

参数

func — 可选。lambda 函数。Lambda function
map — 待排序的 Map。Map(K, V)

返回值

返回按升序排序后的 Map。Map(K, V)

示例

使用示例

SELECT mapSort((k, v) -> v, map('k1', 3, 'k2', 1, 'k3', 2))

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

mapSubtract

引入版本：v20.7.0

收集所有键，并将对应的值相减。

语法

mapSubtract(arg1[, arg2, ...])

参数

arg1[, arg2, ...] — 由两个数组组成的 Map 或 Tuple，其中第一个数组中的元素表示键，第二个数组包含每个键对应的值。Map(K, V) 或 Tuple(Array(T), Array(T))

返回值

返回一个 Map 或 Tuple，其中第一个数组包含已排序的键，第二个数组包含对应的值。Map(K, V) 或 Tuple(Array(T), Array(T))

示例

使用 Map 类型

SELECT mapSubtract(map(1, 1), map(1, 1))

{1:0}

使用 Tuple map

SELECT mapSubtract(([toUInt8(1), 2], [toInt32(1), 1]), ([toUInt8(1), 2], [toInt32(2), 1]))

([1,2],[-1,0])

mapUpdate

引入版本：v22.3.0

对于两个 Map，返回第一个 Map，并将其中的值按第二个 Map 中对应键的值更新。

语法

mapUpdate(map1, map2)

参数

map1 — 要更新的映射。Map(K, V)
map2 — 用于执行更新的映射。Map(K, V)

返回值

返回 map1，其中的值会被 map2 中对应键的值更新。Map(K, V)

示例

基本用法

SELECT mapUpdate(map('key1', 0, 'key3', 0), map('key1', 10, 'key2', 10))

{'key3':0,'key1':10,'key2':10}

mapValues

引入版本：v21.2.0

返回给定 map 的值。启用设置 optimize_functions_to_subcolumns 后，此函数可得到优化。启用该设置后，该函数只会读取 values 子列，而不是整个 map。查询 SELECT mapValues(m) FROM table 会被转换为 SELECT m.values FROM table。

语法

mapValues(map)

参数

map — 要从中提取值的 Map。Map(K, V)

返回值

返回一个数组，包含该 map 中的所有值。Array(T)

示例

使用示例

SELECT mapValues(map('k1', 'v1', 'k2', 'v2'))

['v1','v2']