> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8a08bda2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Tuple 和 Map 函数文档

# Map 函数

{/*AUTOGENERATED_START*/}

<div id="extractKeyValuePairs">
  ## extractKeyValuePairs
</div>

引入版本：v23.4.0

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

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

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

**语法**

```sql theme={null}
extractKeyValuePairs(data, [key_value_delimiter], [pair_delimiter], [quoting_character])
```

**参数**

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

**返回值**

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

**示例**

查询：

**简单示例**

```sql theme={null}
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

            ┌─kv──────────────────────────────────────────────────────────────────────┐
            │ {'name':'neymar','age':'31','team':'psg','nationality':'brazil'}        │
            └─────────────────────────────────────────────────────────────────────────┘
```

**使用单引号作为引号字符**

```sql theme={null}
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

            ┌─kv───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
            │ {'name':'neymar','age':'31','team':'psg','nationality':'brazil','last_key':'last_value'}                                 │
            └──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
```

unexpected\_quoting\_character\_strategy 示例：

unexpected\_quoting\_character\_strategy=invalid

```sql theme={null}
SELECT extractKeyValuePairs('name"abc:5', ':', ' ,;', '\"', 'INVALID') as kv;
```

```text theme={null}
┌─kv────────────────┐
            │ {'abc':'5'}  │
            └───────────────────┘
```

```sql theme={null}
SELECT extractKeyValuePairs('name"abc":5', ':', ' ,;', '\"', 'INVALID') as kv;
```

```text theme={null}
┌─kv──┐
            │ {}  │
            └─────┘
```

unexpected\_quoting\_character\_strategy=accept

```sql theme={null}
SELECT extractKeyValuePairs('name"abc:5', ':', ' ,;', '\"', 'ACCEPT') as kv;
```

```text theme={null}
┌─kv────────────────┐
            │ {'name"abc':'5'}  │
            └───────────────────┘
```

```sql theme={null}
            SELECT extractKeyValuePairs('name"abc":5', ':', ' ,;', '\"', 'ACCEPT') as kv;
```

```text theme={null}
            ┌─kv─────────────────┐
            │ {'name"abc"':'5'}  │
            └────────────────────┘
```

unexpected\_quoting\_character\_strategy=promote

```sql theme={null}
            SELECT extractKeyValuePairs('name"abc:5', ':', ' ,;', '\"', 'PROMOTE') as kv;
```

```text theme={null}
            ┌─kv──┐
            │ {}  │
            └─────┘
```

```sql theme={null}
            SELECT extractKeyValuePairs('name"abc":5', ':', ' ,;', '\"', 'PROMOTE') as kv;
```

```text theme={null}
            ┌─kv───────────┐
            │ {'abc':'5'}  │
            └──────────────┘
```

**不支持转义序列时的转义写法**

```sql theme={null}
            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

            ┌─kv────────────────────┐
            │ {'age':'a\\x0A\\n\\0'} │
            └───────────────────────┘
```

**语法**

```sql theme={null}
extractKeyValuePairs(input)
```

**别名**: `str_to_map`, `mapFromString`

**参数**

* 无。

**返回值**

**示例**

<div id="extractKeyValuePairsWithEscaping">
  ## extractKeyValuePairsWithEscaping
</div>

引入版本：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\`，而后转义会将其保持原样。

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

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

```sql theme={null}
            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

            ┌─kv───────────────┐
            │ {'age':'a\n\n\0'} │
            └──────────────────┘
```

**语法**

```sql theme={null}
extractKeyValuePairsWithEscaping(input)
```

**参数**

* 无。

**返回值**

**示例**

<div id="map">
  ## map
</div>

引入版本：v21.1.0

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

**语法**

```sql theme={null}
map(key1, value1[, key2, value2, ...])
```

**参数**

* `key_n` — Map 条目的键。[`Any`](/zh/reference/data-types)
* `value_n` — Map 条目的值。[`Any`](/zh/reference/data-types)

**返回值**

返回一个包含 key:value 对的 Map。[`Map(Any, Any)`](/zh/reference/data-types/map)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT map('key1', number, 'key2', number * 2) FROM numbers(3)
```

```response title=Response theme={null}
{'key1':0,'key2':0}
{'key1':1,'key2':2}
{'key1':2,'key2':4}
```

<div id="mapAdd">
  ## mapAdd
</div>

引入版本：v20.7.0

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

**语法**

```sql theme={null}
mapAdd(arg1[, arg2, ...])
```

**参数**

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

**返回值**

返回一个 Map 或元组，其中第一个数组包含已排序的键，第二个数组包含对应的值。[`Map(K, V)`](/zh/reference/data-types/map) 或 [`Tuple(Array(T), Array(T))`](/zh/reference/data-types/tuple)

**示例**

**使用 Map 类型**

```sql title=Query theme={null}
SELECT mapAdd(map(1, 1), map(1, 1))
```

```response title=Response theme={null}
{1:2}
```

**使用 Tuple**

```sql title=Query theme={null}
SELECT mapAdd(([toUInt8(1), 2], [1, 1]), ([toUInt8(1), 2], [1, 1]))
```

```response title=Response theme={null}
([1, 2], [2, 2])
```

<div id="mapAll">
  ## mapAll
</div>

引入于：v23.4.0

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

**语法**

```sql theme={null}
mapAll([func,] map)
```

**参数**

* `func` — Lambda 函数。[`Lambda 函数`](/zh/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `map` — 待检查的 Map。[`Map(K, V)`](/zh/reference/data-types/map)

**返回值**

如果所有键值对都满足条件，则返回 `1`；否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT mapAll((k, v) -> v = 1, map('k1', 1, 'k2', 2))
```

```response title=Response theme={null}
0
```

<div id="mapApply">
  ## mapApply
</div>

引入版本：v22.3.0

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

**语法**

```sql theme={null}
mapApply(func, map)
```

**参数**

* `func` — Lambda 函数。[`Lambda 函数`](/zh/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `map` — 要对其应用该函数的 Map。[`Map(K, V)`](/zh/reference/data-types/map)

**返回值**

返回一个新 Map，它是对原始 Map 的每个元素应用 `func` 后得到的。[`Map(K, V)`](/zh/reference/data-types/map)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT mapApply((k, v) -> (k, v * 2), map('k1', 1, 'k2', 2))
```

```response title=Response theme={null}
{'k1':2,'k2':4}
```

<div id="mapConcat">
  ## mapConcat
</div>

引入版本：v23.4.0

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

**语法**

```sql theme={null}
mapConcat(maps)
```

**参数**

* `maps` — 任意数量的 Map。[`Map`](/zh/reference/data-types/map)

**返回值**

返回一个由作为参数传入的多个 Map 拼接而成的 Map。[`Map`](/zh/reference/data-types/map)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT mapConcat(map('k1', 'v1'), map('k2', 'v2'))
```

```response title=Response theme={null}
{'k1':'v1','k2':'v2'}
```

<div id="mapContainsKey">
  ## mapContainsKey
</div>

引入版本：v21.2.0

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

**语法**

```sql theme={null}
mapContainsKey(map, key)
```

**别名**: `mapContains`

**参数**

* `map` — 要在其中搜索的 Map。[`Map(K, V)`](/zh/reference/data-types/map)
* `key` — 要搜索的键。其类型必须与 map 的键类型一致。[`Any`](/zh/reference/data-types)

**返回值**

如果 map 包含该键，则返回 1，否则返回 0。[`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT mapContainsKey(map('k1', 'v1', 'k2', 'v2'), 'k1')
```

```response title=Response theme={null}
1
```

<div id="mapContainsKeyLike">
  ## mapContainsKeyLike
</div>

引入版本：v23.4.0

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

**语法**

```sql theme={null}
mapContainsKeyLike(map, pattern)
```

**参数**

* `map` — 要在其中搜索的 Map。 [`Map(K, V)`](/zh/reference/data-types/map)
* `pattern` — 用于匹配键名的模式。 [`const String`](/zh/reference/data-types/string)

**返回值**

如果 `map` 包含与 `pattern` 匹配的键，则返回 `1`；否则返回 `0`。 [`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**使用示例**

```sql title=Query theme={null}
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;
```

```response title=Response theme={null}
┌─mapContainsKeyLike(a, 'a%')─┐
│                           1 │
│                           0 │
└─────────────────────────────┘
```

<div id="mapContainsValue">
  ## mapContainsValue
</div>

引入版本：v25.6.0

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

**语法**

```sql theme={null}
mapContainsValue(map, value)
```

**参数**

* `map` — 要在其中搜索的 Map。[`Map(K, V)`](/zh/reference/data-types/map)
* `value` — 要搜索的值。其类型必须与 map 的值类型一致。[`Any`](/zh/reference/data-types)

**返回值**

如果 map 包含该值，则返回 `1`；否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT mapContainsValue(map('k1', 'v1', 'k2', 'v2'), 'v1')
```

```response title=Response theme={null}
1
```

<div id="mapContainsValueLike">
  ## mapContainsValueLike
</div>

引入版本：v25.5.0

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

**语法**

```sql theme={null}
mapContainsValueLike(map, pattern)
```

**参数**

* `map` — 要搜索的 Map。[`Map(K, V)`](/zh/reference/data-types/map)
* `pattern` — 用于匹配值的模式。[`const String`](/zh/reference/data-types/string)

**返回值**

如果 `map` 包含与 `pattern` 匹配的值，则返回 `1`；否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**用法示例**

```sql title=Query theme={null}
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;
```

```response title=Response theme={null}
┌─mapContainsV⋯ke(a, 'a%')─┐
│                        1 │
│                        0 │
└──────────────────────────┘
```

<div id="mapExists">
  ## mapExists
</div>

引入版本：v23.4.0

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

**语法**

```sql theme={null}
mapExists([func,] map)
```

**参数**

* `func` — 可选。Lambda function。[`Lambda function`](/zh/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `map` — 要检查的 Map。[`Map(K, V)`](/zh/reference/data-types/map)

**返回值**

如果至少有一个键值对满足条件，则返回 `1`；否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT mapExists((k, v) -> v = 1, map('k1', 1, 'k2', 2))
```

```response title=Response theme={null}
1
```

<div id="mapExtractKeyLike">
  ## mapExtractKeyLike
</div>

引入版本：v23.4.0

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

**语法**

```sql theme={null}
mapExtractKeyLike(map, pattern)
```

**参数**

* `map` — 要从中提取内容的 Map。[`Map(K, V)`](/zh/reference/data-types/map)
* `pattern` — 用于匹配键名的模式。[`const String`](/zh/reference/data-types/string)

**返回值**

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

**示例**

**用法示例**

```sql title=Query theme={null}
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;
```

```response title=Response theme={null}
┌─mapExtractKeyLike(a, 'a%')─┐
│ {'abc':'abc'}              │
│ {}                         │
└────────────────────────────┘
```

<div id="mapExtractValueLike">
  ## mapExtractValueLike
</div>

引入版本：v25.5.0

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

**语法**

```sql theme={null}
mapExtractValueLike(map, pattern)
```

**参数**

* `map` — 要从中提取元素的 Map。[`Map(K, V)`](/zh/reference/data-types/map)
* `pattern` — 用于匹配值的模式。[`const String`](/zh/reference/data-types/string)

**返回值**

返回一个包含值符合指定模式的元素的 Map。如果没有元素匹配该模式，则返回空 Map。[`Map(K, V)`](/zh/reference/data-types/map)

**示例**

**用法示例**

```sql title=Query theme={null}
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;
```

```response title=Response theme={null}
┌─mapExtractValueLike(a, 'a%')─┐
│ {'abc':'abc'}                │
│ {}                           │
└──────────────────────────────┘
```

<div id="mapFilter">
  ## mapFilter
</div>

引入版本：v22.3.0

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

**语法**

```sql theme={null}
mapFilter(func, map)
```

**参数**

* `func` — lambda 函数。[`lambda 函数`](/zh/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `map` — 要过滤的 Map。[`Map(K, V)`](/zh/reference/data-types/map)

**返回值**

返回一个 Map，仅包含 `func` 返回值不为 `0` 的元素。[`Map(K, V)`](/zh/reference/data-types/map)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT mapFilter((k, v) -> v > 1, map('k1', 1, 'k2', 2))
```

```response title=Response theme={null}
{'k2':2}
```

<div id="mapFromArrays">
  ## mapFromArrays
</div>

引入版本：v23.3.0

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

**语法**

```sql theme={null}
mapFromArrays(keys, values)
```

**别名**: `MAP_FROM_ARRAYS`

**参数**

* `keys` — 用于创建 Map 的键数组或键映射。[`Array`](/zh/reference/data-types/array) 或 [`Map`](/zh/reference/data-types/map)
* `values` — 用于创建 Map 的值数组或值映射。[`Array`](/zh/reference/data-types/array) 或 [`Map`](/zh/reference/data-types/map)

**返回值**

返回一个 Map，其键和值由键数组和值数组/映射构造而成。[`Map`](/zh/reference/data-types/map)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT mapFromArrays(['a', 'b', 'c'], [1, 2, 3])
```

```response title=Response theme={null}
{'a':1,'b':2,'c':3}
```

**使用 Map 类型输入**

```sql title=Query theme={null}
SELECT mapFromArrays([1, 2, 3], map('a', 1, 'b', 2, 'c', 3))
```

```response title=Response theme={null}
{1:('a', 1), 2:('b', 2), 3:('c', 3)}
```

<div id="mapKeys">
  ## mapKeys
</div>

引入版本：v21.2.0

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

**语法**

```sql theme={null}
mapKeys(map)
```

**参数**

* `map` — 待提取键的 Map。[`Map(K, V)`](/zh/reference/data-types/map)

**返回值**

返回包含该 Map 中所有键的数组。[`Array(T)`](/zh/reference/data-types/array)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT mapKeys(map('k1', 'v1', 'k2', 'v2'))
```

```response title=Response theme={null}
['k1','k2']
```

<div id="mapPartialReverseSort">
  ## mapPartialReverseSort
</div>

引入版本：v23.4.0

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

**语法**

```sql theme={null}
mapPartialReverseSort([func,] limit, map)
```

**参数**

* `func` — 可选。Lambda 函数。[`Lambda function`](/zh/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `limit` — 对范围 `[1..limit]` 内的元素进行排序。[`(U)Int*`](/zh/reference/data-types/int-uint)
* `map` — 要排序的 Map。[`Map(K, V)`](/zh/reference/data-types/map)

**返回值**

返回按降序进行部分排序后的 Map。[`Map(K, V)`](/zh/reference/data-types/map)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT mapPartialReverseSort((k, v) -> v, 2, map('k1', 3, 'k2', 1, 'k3', 2))
```

```response title=Response theme={null}
{'k1':3,'k3':2,'k2':1}
```

<div id="mapPartialSort">
  ## mapPartialSort
</div>

引入版本：v23.4.0

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

**语法**

```sql theme={null}
mapPartialSort([func,] limit, map)
```

**参数**

* `func` — 可选。Lambda 函数。[`Lambda function`](/zh/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `limit` — 对范围 `[1..limit]` 内的元素进行排序。[`(U)Int*`](/zh/reference/data-types/int-uint)
* `map` — 要排序的 Map。[`Map(K, V)`](/zh/reference/data-types/map)

**返回值**

返回一个部分排序后的 Map。[`Map(K, V)`](/zh/reference/data-types/map)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT mapPartialSort((k, v) -> v, 2, map('k1', 3, 'k2', 1, 'k3', 2))
```

```response title=Response theme={null}
{'k2':1,'k3':2,'k1':3}
```

<div id="mapPopulateSeries">
  ## mapPopulateSeries
</div>

Introduced in: v20.10.0

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

**Syntax**

```sql theme={null}
mapPopulateSeries(map[, max]) | mapPopulateSeries(keys, values[, max])
```

**参数**

* `map` — 键为整数的 Map。[`Map((U)Int*, V)`](/zh/reference/data-types/map)
* `keys` — 键数组。[`Array(T)`](/zh/reference/data-types/array)
* `values` — 值数组。[`Array(T)`](/zh/reference/data-types/array)
* `max` — 可选。最大键值。[`Int8`](/zh/reference/data-types/int-uint) 或 [`Int16`](/zh/reference/data-types/int-uint) 或 [`Int32`](/zh/reference/data-types/int-uint) 或 [`Int64`](/zh/reference/data-types/int-uint) 或 [`Int128`](/zh/reference/data-types/int-uint) 或 [`Int256`](/zh/reference/data-types/int-uint)

**返回值**

返回一个 Map，或一个由两个数组组成的 Tuple：第一个数组包含按排序顺序排列的键，第二个数组包含对应键的值。[`Map(K, V)`](/zh/reference/data-types/map) 或 [`Tuple(Array(UInt*), Array(Any))`](/zh/reference/data-types/tuple)

**示例**

**使用 Map 类型**

```sql title=Query theme={null}
SELECT mapPopulateSeries(map(1, 10, 5, 20), 6)
```

```response title=Response theme={null}
{1:10, 2:0, 3:0, 4:0, 5:20, 6:0}
```

**配合映射后的数组**

```sql title=Query theme={null}
SELECT mapPopulateSeries([1, 2, 4], [11, 22, 44], 5)
```

```response title=Response theme={null}
([1, 2, 3, 4, 5], [11, 22, 0, 44, 0])
```

<div id="mapReverseSort">
  ## mapReverseSort
</div>

引入版本：v23.4.0

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

**语法**

```sql theme={null}
mapReverseSort([func,] map)
```

**参数**

* `func` — 可选。Lambda 函数。[`Lambda function`](/zh/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `map` — 要排序的 Map。[`Map(K, V)`](/zh/reference/data-types/map)

**返回值**

返回按降序排序后的 Map。[`Map(K, V)`](/zh/reference/data-types/map)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT mapReverseSort((k, v) -> v, map('k1', 3, 'k2', 1, 'k3', 2))
```

```response title=Response theme={null}
{'k1':3,'k3':2,'k2':1}
```

<div id="mapSort">
  ## mapSort
</div>

引入版本：v23.4.0

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

**语法**

```sql theme={null}
mapSort([func,] map)
```

**参数**

* `func` — 可选。lambda 函数。[`Lambda function`](/zh/reference/functions/regular-functions/overview#arrow-operator-and-lambda)
* `map` — 待排序的 Map。[`Map(K, V)`](/zh/reference/data-types/map)

**返回值**

返回按升序排序后的 Map。[`Map(K, V)`](/zh/reference/data-types/map)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT mapSort((k, v) -> v, map('k1', 3, 'k2', 1, 'k3', 2))
```

```response title=Response theme={null}
{'k2':1,'k3':2,'k1':3}
```

<div id="mapSubtract">
  ## mapSubtract
</div>

引入版本：v20.7.0

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

**语法**

```sql theme={null}
mapSubtract(arg1[, arg2, ...])
```

**参数**

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

**返回值**

返回一个 Map 或 Tuple，其中第一个数组包含已排序的键，第二个数组包含对应的值。[`Map(K, V)`](/zh/reference/data-types/map) 或 [`Tuple(Array(T), Array(T))`](/zh/reference/data-types/tuple)

**示例**

**使用 Map 类型**

```sql title=Query theme={null}
SELECT mapSubtract(map(1, 1), map(1, 1))
```

```response title=Response theme={null}
{1:0}
```

**使用 Tuple map**

```sql title=Query theme={null}
SELECT mapSubtract(([toUInt8(1), 2], [toInt32(1), 1]), ([toUInt8(1), 2], [toInt32(2), 1]))
```

```response title=Response theme={null}
([1, 2], [-1, 0])
```

<div id="mapUpdate">
  ## mapUpdate
</div>

引入版本：v22.3.0

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

**语法**

```sql theme={null}
mapUpdate(map1, map2)
```

**参数**

* `map1` — 要更新的映射。[`Map(K, V)`](/zh/reference/data-types/map)
* `map2` — 用于执行更新的映射。[`Map(K, V)`](/zh/reference/data-types/map)

**返回值**

返回 `map1`，其中的值会被 `map2` 中对应键的值更新。[`Map(K, V)`](/zh/reference/data-types/map)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT mapUpdate(map('key1', 0, 'key3', 0), map('key1', 10, 'key2', 10))
```

```response title=Response theme={null}
{'key3':0,'key1':10,'key2':10}
```

<div id="mapValues">
  ## mapValues
</div>

引入版本：v21.2.0

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

**语法**

```sql theme={null}
mapValues(map)
```

**参数**

* `map` — 要从中提取值的 Map。[`Map(K, V)`](/zh/reference/data-types/map)

**返回值**

返回一个数组，包含该 map 中的所有值。[`Array(T)`](/zh/reference/data-types/array)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT mapValues(map('k1', 'v1', 'k2', 'v2'))
```

```response title=Response theme={null}
['v1','v2']
```