From b36b93f9a3ea85430900a4d3630bac421e7c32c4 Mon Sep 17 00:00:00 2001 From: linzhenqi Date: Mon, 24 Aug 2026 11:00:09 +0800 Subject: [PATCH] [Feat](map) Support some map lambda functions --- .../scalar-functions/map-functions/map-all.md | 85 ++++++++++++++++ .../map-functions/map-apply.md | 75 +++++++++++++++ .../map-functions/map-exists.md | 85 ++++++++++++++++ .../map-functions/map-filter.md | 92 ++++++++++++++++++ .../map-functions/transform-keys.md | 74 ++++++++++++++ .../map-functions/transform-values.md | 75 +++++++++++++++ .../scalar-functions/map-functions/map-all.md | 85 ++++++++++++++++ .../map-functions/map-apply.md | 75 +++++++++++++++ .../map-functions/map-exists.md | 85 ++++++++++++++++ .../map-functions/map-filter.md | 92 ++++++++++++++++++ .../map-functions/transform-keys.md | 74 ++++++++++++++ .../map-functions/transform-values.md | 75 +++++++++++++++ .../scalar-functions/map-functions/map-all.md | 89 +++++++++++++++++ .../map-functions/map-apply.md | 79 +++++++++++++++ .../map-functions/map-exists.md | 89 +++++++++++++++++ .../map-functions/map-filter.md | 96 +++++++++++++++++++ .../map-functions/transform-keys.md | 78 +++++++++++++++ .../map-functions/transform-values.md | 79 +++++++++++++++ sidebars.ts | 6 ++ .../scalar-functions/map-functions/map-all.md | 89 +++++++++++++++++ .../map-functions/map-apply.md | 79 +++++++++++++++ .../map-functions/map-exists.md | 89 +++++++++++++++++ .../map-functions/map-filter.md | 96 +++++++++++++++++++ .../map-functions/transform-keys.md | 78 +++++++++++++++ .../map-functions/transform-values.md | 79 +++++++++++++++ versioned_sidebars/version-4.x-sidebars.json | 8 +- 26 files changed, 2005 insertions(+), 1 deletion(-) create mode 100644 docs/sql-manual/sql-functions/scalar-functions/map-functions/map-all.md create mode 100644 docs/sql-manual/sql-functions/scalar-functions/map-functions/map-apply.md create mode 100644 docs/sql-manual/sql-functions/scalar-functions/map-functions/map-exists.md create mode 100644 docs/sql-manual/sql-functions/scalar-functions/map-functions/map-filter.md create mode 100644 docs/sql-manual/sql-functions/scalar-functions/map-functions/transform-keys.md create mode 100644 docs/sql-manual/sql-functions/scalar-functions/map-functions/transform-values.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/map-functions/map-all.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/map-functions/map-apply.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/map-functions/map-exists.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/map-functions/map-filter.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/map-functions/transform-keys.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/map-functions/transform-values.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/map-all.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/map-apply.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/map-exists.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/map-filter.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/transform-keys.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/transform-values.md create mode 100644 versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/map-all.md create mode 100644 versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/map-apply.md create mode 100644 versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/map-exists.md create mode 100644 versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/map-filter.md create mode 100644 versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/transform-keys.md create mode 100644 versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/transform-values.md diff --git a/docs/sql-manual/sql-functions/scalar-functions/map-functions/map-all.md b/docs/sql-manual/sql-functions/scalar-functions/map-functions/map-all.md new file mode 100644 index 0000000000000..933355501f2b9 --- /dev/null +++ b/docs/sql-manual/sql-functions/scalar-functions/map-functions/map-all.md @@ -0,0 +1,85 @@ +--- +{ + "title": "MAP_ALL", + "language": "en", + "description": "Tests whether every entry in a map satisfies a condition" +} +--- + +## Description + +Tests every entry in a map with a lambda expression and returns whether all entries satisfy the specified condition. The lambda receives the key and value of each entry. + +## Syntax + +```sql +MAP_ALL((, ) -> , ) +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| `` | The lambda parameter representing the key of a map entry. | +| `` | The lambda parameter representing the value of a map entry. | +| `` | A Boolean expression evaluated for each map entry. | +| `` | A `MAP` expression. | + +## Return Value + +Returns a `BOOLEAN` value. + +- Returns `FALSE` if the predicate returns `FALSE` for any entry. +- Returns `TRUE` if the predicate returns `TRUE` for every entry, including when the map is empty. +- Returns `NULL` if no entry returns `FALSE` and at least one entry returns `NULL`. +- If `` is `NULL`, returns `NULL`. + +## Examples + +```sql +SELECT map_all((k, v) -> v >= 10, map(1, 10, 2, 20)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| 1 | ++--------+ +``` + +```sql +SELECT map_all((k, v) -> v > 10, map(1, 10, 2, 20)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| 0 | ++--------+ +``` + +```sql +SELECT map_all((k, v) -> CAST(NULL AS BOOLEAN), map(1, 10)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| NULL | ++--------+ +``` + +```sql +SELECT map_all((k, v) -> v > 0, CAST(NULL AS MAP)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| NULL | ++--------+ +``` diff --git a/docs/sql-manual/sql-functions/scalar-functions/map-functions/map-apply.md b/docs/sql-manual/sql-functions/scalar-functions/map-functions/map-apply.md new file mode 100644 index 0000000000000..ba1de7b9a1b89 --- /dev/null +++ b/docs/sql-manual/sql-functions/scalar-functions/map-functions/map-apply.md @@ -0,0 +1,75 @@ +--- +{ + "title": "MAP_APPLY", + "language": "en", + "description": "Transforms the keys and values of a map" +} +--- + +## Description + +Applies a lambda expression to every entry in a map and constructs a new map from the transformed keys and values. The lambda receives the key and value of each entry and returns a pair of expressions. The first expression is used as the new key and the second expression as the new value. + +## Syntax + +```sql +MAP_APPLY((, ) -> (, ), ) +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| `` | The lambda parameter representing the key of a map entry. | +| `` | The lambda parameter representing the value of a map entry. | +| `` | An expression that produces the key in the returned map. Its type must be supported by MAP keys. | +| `` | An expression that produces the value in the returned map. | +| `` | A `MAP` expression. | + +## Return Value + +Returns a `MAP`, where `K2` and `V2` are the types of the first and second fields returned by the lambda. + +- If `` is empty, returns an empty map. +- If `` is `NULL`, returns `NULL`. +- `NULL` fields returned by the lambda are retained as `NULL` keys or values. +- If multiple entries are transformed to the same key, the value from the last occurrence is retained. +- If the lambda does not return exactly two expressions, an analysis error is reported. + +## Examples + +```sql +SELECT map_apply((k, v) -> (k + 10, v * 2), map(1, 10, 2, 20)) AS result; +``` + +```text ++------------------+ +| result | ++------------------+ +| {11:20, 12:40} | ++------------------+ +``` + +```sql +SELECT map_apply((k, v) -> (1, v), map(1, 10, 2, 20)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| {1:20} | ++--------+ +``` + +```sql +SELECT map_apply((k, v) -> (k, v), CAST(NULL AS MAP)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| NULL | ++--------+ +``` diff --git a/docs/sql-manual/sql-functions/scalar-functions/map-functions/map-exists.md b/docs/sql-manual/sql-functions/scalar-functions/map-functions/map-exists.md new file mode 100644 index 0000000000000..2bb812b6afe04 --- /dev/null +++ b/docs/sql-manual/sql-functions/scalar-functions/map-functions/map-exists.md @@ -0,0 +1,85 @@ +--- +{ + "title": "MAP_EXISTS", + "language": "en", + "description": "Tests whether any entry in a map satisfies a condition" +} +--- + +## Description + +Tests every entry in a map with a lambda expression and returns whether at least one entry satisfies the specified condition. The lambda receives the key and value of each entry. + +## Syntax + +```sql +MAP_EXISTS((, ) -> , ) +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| `` | The lambda parameter representing the key of a map entry. | +| `` | The lambda parameter representing the value of a map entry. | +| `` | A Boolean expression evaluated for each map entry. | +| `` | A `MAP` expression. | + +## Return Value + +Returns a `BOOLEAN` value. + +- Returns `TRUE` if the predicate returns `TRUE` for any entry. +- Returns `FALSE` if the predicate returns `FALSE` for every entry, including when the map is empty. +- Returns `NULL` if no entry returns `TRUE` and at least one entry returns `NULL`. +- If `` is `NULL`, returns `NULL`. + +## Examples + +```sql +SELECT map_exists((k, v) -> v = 20, map(1, 10, 2, 20)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| 1 | ++--------+ +``` + +```sql +SELECT map_exists((k, v) -> v > 20, map(1, 10, 2, 20)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| 0 | ++--------+ +``` + +```sql +SELECT map_exists((k, v) -> CAST(NULL AS BOOLEAN), map(1, 10)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| NULL | ++--------+ +``` + +```sql +SELECT map_exists((k, v) -> v > 0, CAST(NULL AS MAP)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| NULL | ++--------+ +``` diff --git a/docs/sql-manual/sql-functions/scalar-functions/map-functions/map-filter.md b/docs/sql-manual/sql-functions/scalar-functions/map-functions/map-filter.md new file mode 100644 index 0000000000000..e86bb72b33461 --- /dev/null +++ b/docs/sql-manual/sql-functions/scalar-functions/map-functions/map-filter.md @@ -0,0 +1,92 @@ +--- +{ + "title": "MAP_FILTER", + "language": "en", + "description": "Filters map entries using a lambda expression or a Boolean array" +} +--- + +## Description + +Filters entries in a map and returns a map containing only the selected entries. + +The lambda form evaluates a Boolean expression for every entry. The lambda receives the key and value of each entry. The Boolean-array form selects entries by their corresponding positions. + +## Syntax + +```sql +MAP_FILTER((, ) -> , ) +MAP_FILTER(, ) +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| `` | The lambda parameter representing the key of a map entry. | +| `` | The lambda parameter representing the value of a map entry. | +| `` | A Boolean expression evaluated for each map entry. Entries for which it returns `TRUE` are retained. | +| `` | A `MAP` expression. | +| `` | An `ARRAY` expression. Each element selects the map entry at the same position. The array length must equal the number of entries in the map. | + +## Return Value + +Returns a `MAP` containing the selected entries. + +- In the lambda form, entries for which the predicate returns `FALSE` or `NULL` are removed. +- In the Boolean-array form, entries corresponding to `FALSE` or `NULL` elements are removed. +- If `` is empty, returns an empty map. +- If `` is `NULL`, returns `NULL`. +- In the Boolean-array form, if `` is `NULL`, returns `NULL`. + +## Examples + +```sql +SELECT map_filter((k, v) -> v >= 20, map(1, 10, 2, 20, 3, 30)) AS result; +``` + +```text ++--------------+ +| result | ++--------------+ +| {2:20, 3:30} | ++--------------+ +``` + +```sql +SELECT map_filter( + (k, v) -> if(k = 1, CAST(NULL AS BOOLEAN), TRUE), + map(1, 10, 2, 20)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| {2:20} | ++--------+ +``` + +```sql +SELECT map_filter(map(1, 10, 2, 20), [TRUE, FALSE]) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| {1:10} | ++--------+ +``` + +```sql +SELECT map_filter((k, v) -> TRUE, CAST(NULL AS MAP)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| NULL | ++--------+ +``` diff --git a/docs/sql-manual/sql-functions/scalar-functions/map-functions/transform-keys.md b/docs/sql-manual/sql-functions/scalar-functions/map-functions/transform-keys.md new file mode 100644 index 0000000000000..871bf9b9d1a0b --- /dev/null +++ b/docs/sql-manual/sql-functions/scalar-functions/map-functions/transform-keys.md @@ -0,0 +1,74 @@ +--- +{ + "title": "TRANSFORM_KEYS", + "language": "en", + "description": "Transforms every key in a map" +} +--- + +## Description + +Applies a lambda expression to every entry in a map and constructs a new map with the transformed keys and the original values. The lambda receives the key and value of each entry. + +## Syntax + +```sql +TRANSFORM_KEYS((, ) -> , ) +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| `` | The lambda parameter representing the key of a map entry. | +| `` | The lambda parameter representing the value of a map entry. | +| `` | An expression that produces the key in the returned map. Its type must be supported by MAP keys. | +| `` | A `MAP` expression. | + +## Return Value + +Returns a `MAP`, where `K2` is the type returned by the lambda. + +- The values in the input map are retained unchanged. +- If `` is empty, returns an empty map. +- If `` is `NULL`, returns `NULL`. +- A `NULL` key returned by the lambda is retained. +- If multiple entries are transformed to the same key, the value from the last occurrence is retained. + +## Examples + +```sql +SELECT transform_keys((k, v) -> k + 10, map(1, 10, 2, 20)) AS result; +``` + +```text ++----------------+ +| result | ++----------------+ +| {11:10, 12:20} | ++----------------+ +``` + +```sql +SELECT transform_keys((k, v) -> 1, map(1, 10, 2, 20)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| {1:20} | ++--------+ +``` + +```sql +SELECT transform_keys((k, v) -> k, CAST(NULL AS MAP)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| NULL | ++--------+ +``` diff --git a/docs/sql-manual/sql-functions/scalar-functions/map-functions/transform-values.md b/docs/sql-manual/sql-functions/scalar-functions/map-functions/transform-values.md new file mode 100644 index 0000000000000..03236868dbb9e --- /dev/null +++ b/docs/sql-manual/sql-functions/scalar-functions/map-functions/transform-values.md @@ -0,0 +1,75 @@ +--- +{ + "title": "TRANSFORM_VALUES", + "language": "en", + "description": "Transforms every value in a map" +} +--- + +## Description + +Applies a lambda expression to every entry in a map and constructs a new map with the original keys and the transformed values. The lambda receives the key and value of each entry. + +## Syntax + +```sql +TRANSFORM_VALUES((, ) -> , ) +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| `` | The lambda parameter representing the key of a map entry. | +| `` | The lambda parameter representing the value of a map entry. | +| `` | An expression that produces the value in the returned map. | +| `` | A `MAP` expression. | + +## Return Value + +Returns a `MAP`, where `V2` is the type returned by the lambda. + +- The keys in the input map are retained unchanged. +- If `` is empty, returns an empty map. +- If `` is `NULL`, returns `NULL`. +- A `NULL` value returned by the lambda is retained. + +## Examples + +```sql +SELECT transform_values((k, v) -> v + k, map(1, 10, 2, 20)) AS result; +``` + +```text ++--------------+ +| result | ++--------------+ +| {1:11, 2:22} | ++--------------+ +``` + +```sql +SELECT transform_values( + (k, v) -> if(k = 1, CAST(NULL AS INT), v), + map(1, 10, 2, 20)) AS result; +``` + +```text ++----------------+ +| result | ++----------------+ +| {1:null, 2:20} | ++----------------+ +``` + +```sql +SELECT transform_values((k, v) -> v, CAST(NULL AS MAP)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| NULL | ++--------+ +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/map-functions/map-all.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/map-functions/map-all.md new file mode 100644 index 0000000000000..8e8d2ef62fbc9 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/map-functions/map-all.md @@ -0,0 +1,85 @@ +--- +{ + "title": "MAP_ALL", + "language": "zh-CN", + "description": "判断 Map 中的所有元素是否都满足指定条件" +} +--- + +## 描述 + +使用 Lambda 表达式检查 Map 中的每一个键值对，并判断所有键值对是否都满足指定条件。Lambda 表达式接收每个键值对的键和值作为参数。 + +## 语法 + +```sql +MAP_ALL((, ) -> , ) +``` + +## 参数 + +| 参数 | 描述 | +| --- | --- | +| `` | Lambda 参数，表示 Map 元素的键。 | +| `` | Lambda 参数，表示 Map 元素的值。 | +| `` | 对每个 Map 元素求值的布尔表达式。 | +| `` | `MAP` 类型的表达式。 | + +## 返回值 + +返回 `BOOLEAN` 类型的值。 + +- 如果任意一个元素的判断结果为 `FALSE`，返回 `FALSE`。 +- 如果所有元素的判断结果均为 `TRUE`，返回 `TRUE`；空 Map 也返回 `TRUE`。 +- 如果没有元素的判断结果为 `FALSE`，但至少有一个元素的判断结果为 `NULL`，返回 `NULL`。 +- 如果 `` 为 `NULL`，返回 `NULL`。 + +## 示例 + +```sql +SELECT map_all((k, v) -> v >= 10, map(1, 10, 2, 20)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| 1 | ++--------+ +``` + +```sql +SELECT map_all((k, v) -> v > 10, map(1, 10, 2, 20)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| 0 | ++--------+ +``` + +```sql +SELECT map_all((k, v) -> CAST(NULL AS BOOLEAN), map(1, 10)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| NULL | ++--------+ +``` + +```sql +SELECT map_all((k, v) -> v > 0, CAST(NULL AS MAP)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| NULL | ++--------+ +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/map-functions/map-apply.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/map-functions/map-apply.md new file mode 100644 index 0000000000000..eb04829b57163 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/map-functions/map-apply.md @@ -0,0 +1,75 @@ +--- +{ + "title": "MAP_APPLY", + "language": "zh-CN", + "description": "同时转换 Map 中的键和值" +} +--- + +## 描述 + +对 Map 中的每一个键值对应用 Lambda 表达式，并使用转换后的键和值构造一个新的 Map。Lambda 表达式接收每个键值对的键和值，并返回一对表达式：第一个表达式作为新键，第二个表达式作为新值。 + +## 语法 + +```sql +MAP_APPLY((, ) -> (, ), ) +``` + +## 参数 + +| 参数 | 描述 | +| --- | --- | +| `` | Lambda 参数，表示 Map 元素的键。 | +| `` | Lambda 参数，表示 Map 元素的值。 | +| `` | 生成返回 Map 中键的表达式，其类型必须是 Map 键支持的类型。 | +| `` | 生成返回 Map 中值的表达式。 | +| `` | `MAP` 类型的表达式。 | + +## 返回值 + +返回 `MAP`。`K2` 和 `V2` 分别是 Lambda 返回的第一个字段和第二个字段的类型。 + +- 如果 `` 为空，返回空 Map。 +- 如果 `` 为 `NULL`，返回 `NULL`。 +- Lambda 返回字段中的 `NULL` 会保留为 Map 中的 `NULL` 键或值。 +- 如果多个元素转换为相同的新键，保留最后一次出现的值。 +- 如果 Lambda 没有返回两个表达式，则报告分析错误。 + +## 示例 + +```sql +SELECT map_apply((k, v) -> (k + 10, v * 2), map(1, 10, 2, 20)) AS result; +``` + +```text ++------------------+ +| result | ++------------------+ +| {11:20, 12:40} | ++------------------+ +``` + +```sql +SELECT map_apply((k, v) -> (1, v), map(1, 10, 2, 20)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| {1:20} | ++--------+ +``` + +```sql +SELECT map_apply((k, v) -> (k, v), CAST(NULL AS MAP)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| NULL | ++--------+ +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/map-functions/map-exists.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/map-functions/map-exists.md new file mode 100644 index 0000000000000..30dadab93262f --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/map-functions/map-exists.md @@ -0,0 +1,85 @@ +--- +{ + "title": "MAP_EXISTS", + "language": "zh-CN", + "description": "判断 Map 中是否存在满足指定条件的元素" +} +--- + +## 描述 + +使用 Lambda 表达式检查 Map 中的每一个键值对，并判断是否至少有一个键值对满足指定条件。Lambda 表达式接收每个键值对的键和值作为参数。 + +## 语法 + +```sql +MAP_EXISTS((, ) -> , ) +``` + +## 参数 + +| 参数 | 描述 | +| --- | --- | +| `` | Lambda 参数，表示 Map 元素的键。 | +| `` | Lambda 参数，表示 Map 元素的值。 | +| `` | 对每个 Map 元素求值的布尔表达式。 | +| `` | `MAP` 类型的表达式。 | + +## 返回值 + +返回 `BOOLEAN` 类型的值。 + +- 如果任意一个元素的判断结果为 `TRUE`，返回 `TRUE`。 +- 如果所有元素的判断结果均为 `FALSE`，返回 `FALSE`；空 Map 也返回 `FALSE`。 +- 如果没有元素的判断结果为 `TRUE`，但至少有一个元素的判断结果为 `NULL`，返回 `NULL`。 +- 如果 `` 为 `NULL`，返回 `NULL`。 + +## 示例 + +```sql +SELECT map_exists((k, v) -> v = 20, map(1, 10, 2, 20)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| 1 | ++--------+ +``` + +```sql +SELECT map_exists((k, v) -> v > 20, map(1, 10, 2, 20)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| 0 | ++--------+ +``` + +```sql +SELECT map_exists((k, v) -> CAST(NULL AS BOOLEAN), map(1, 10)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| NULL | ++--------+ +``` + +```sql +SELECT map_exists((k, v) -> v > 0, CAST(NULL AS MAP)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| NULL | ++--------+ +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/map-functions/map-filter.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/map-functions/map-filter.md new file mode 100644 index 0000000000000..e5d8dab968c07 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/map-functions/map-filter.md @@ -0,0 +1,92 @@ +--- +{ + "title": "MAP_FILTER", + "language": "zh-CN", + "description": "使用 Lambda 表达式或布尔数组过滤 Map 元素" +} +--- + +## 描述 + +过滤 Map 中的元素，并返回只包含选中元素的新 Map。 + +Lambda 形式对每一个键值对计算布尔表达式，Lambda 表达式接收每个键值对的键和值作为参数。布尔数组形式按照数组中的对应位置选择 Map 元素。 + +## 语法 + +```sql +MAP_FILTER((, ) -> , ) +MAP_FILTER(, ) +``` + +## 参数 + +| 参数 | 描述 | +| --- | --- | +| `` | Lambda 参数，表示 Map 元素的键。 | +| `` | Lambda 参数，表示 Map 元素的值。 | +| `` | 对每个 Map 元素求值的布尔表达式，结果为 `TRUE` 的元素会被保留。 | +| `` | `MAP` 类型的表达式。 | +| `` | `ARRAY` 类型的表达式。数组中的每个元素选择 Map 中对应位置的元素，数组长度必须与 Map 的元素数量相同。 | + +## 返回值 + +返回包含选中元素的 `MAP`。 + +- 在 Lambda 形式中，判断结果为 `FALSE` 或 `NULL` 的元素会被移除。 +- 在布尔数组形式中，对应元素为 `FALSE` 或 `NULL` 的 Map 元素会被移除。 +- 如果 `` 为空，返回空 Map。 +- 如果 `` 为 `NULL`，返回 `NULL`。 +- 在布尔数组形式中，如果 `` 为 `NULL`，返回 `NULL`。 + +## 示例 + +```sql +SELECT map_filter((k, v) -> v >= 20, map(1, 10, 2, 20, 3, 30)) AS result; +``` + +```text ++--------------+ +| result | ++--------------+ +| {2:20, 3:30} | ++--------------+ +``` + +```sql +SELECT map_filter( + (k, v) -> if(k = 1, CAST(NULL AS BOOLEAN), TRUE), + map(1, 10, 2, 20)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| {2:20} | ++--------+ +``` + +```sql +SELECT map_filter(map(1, 10, 2, 20), [TRUE, FALSE]) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| {1:10} | ++--------+ +``` + +```sql +SELECT map_filter((k, v) -> TRUE, CAST(NULL AS MAP)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| NULL | ++--------+ +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/map-functions/transform-keys.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/map-functions/transform-keys.md new file mode 100644 index 0000000000000..a28229285f9b1 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/map-functions/transform-keys.md @@ -0,0 +1,74 @@ +--- +{ + "title": "TRANSFORM_KEYS", + "language": "zh-CN", + "description": "转换 Map 中的每一个键" +} +--- + +## 描述 + +对 Map 中的每一个键值对应用 Lambda 表达式，并使用转换后的键和原始值构造一个新的 Map。Lambda 表达式接收每个键值对的键和值作为参数。 + +## 语法 + +```sql +TRANSFORM_KEYS((, ) -> , ) +``` + +## 参数 + +| 参数 | 描述 | +| --- | --- | +| `` | Lambda 参数，表示 Map 元素的键。 | +| `` | Lambda 参数，表示 Map 元素的值。 | +| `` | 生成返回 Map 中键的表达式，其类型必须是 Map 键支持的类型。 | +| `` | `MAP` 类型的表达式。 | + +## 返回值 + +返回 `MAP`，其中 `K2` 是 Lambda 返回值的类型。 + +- 输入 Map 中的值保持不变。 +- 如果 `` 为空，返回空 Map。 +- 如果 `` 为 `NULL`，返回 `NULL`。 +- Lambda 返回的 `NULL` 键会被保留。 +- 如果多个元素转换为相同的新键，保留最后一次出现的值。 + +## 示例 + +```sql +SELECT transform_keys((k, v) -> k + 10, map(1, 10, 2, 20)) AS result; +``` + +```text ++----------------+ +| result | ++----------------+ +| {11:10, 12:20} | ++----------------+ +``` + +```sql +SELECT transform_keys((k, v) -> 1, map(1, 10, 2, 20)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| {1:20} | ++--------+ +``` + +```sql +SELECT transform_keys((k, v) -> k, CAST(NULL AS MAP)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| NULL | ++--------+ +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/map-functions/transform-values.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/map-functions/transform-values.md new file mode 100644 index 0000000000000..99bc97477ad26 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/map-functions/transform-values.md @@ -0,0 +1,75 @@ +--- +{ + "title": "TRANSFORM_VALUES", + "language": "zh-CN", + "description": "转换 Map 中的每一个值" +} +--- + +## 描述 + +对 Map 中的每一个键值对应用 Lambda 表达式，并使用原始键和转换后的值构造一个新的 Map。Lambda 表达式接收每个键值对的键和值作为参数。 + +## 语法 + +```sql +TRANSFORM_VALUES((, ) -> , ) +``` + +## 参数 + +| 参数 | 描述 | +| --- | --- | +| `` | Lambda 参数，表示 Map 元素的键。 | +| `` | Lambda 参数，表示 Map 元素的值。 | +| `` | 生成返回 Map 中值的表达式。 | +| `` | `MAP` 类型的表达式。 | + +## 返回值 + +返回 `MAP`，其中 `V2` 是 Lambda 返回值的类型。 + +- 输入 Map 中的键保持不变。 +- 如果 `` 为空，返回空 Map。 +- 如果 `` 为 `NULL`，返回 `NULL`。 +- Lambda 返回的 `NULL` 值会被保留。 + +## 示例 + +```sql +SELECT transform_values((k, v) -> v + k, map(1, 10, 2, 20)) AS result; +``` + +```text ++--------------+ +| result | ++--------------+ +| {1:11, 2:22} | ++--------------+ +``` + +```sql +SELECT transform_values( + (k, v) -> if(k = 1, CAST(NULL AS INT), v), + map(1, 10, 2, 20)) AS result; +``` + +```text ++----------------+ +| result | ++----------------+ +| {1:null, 2:20} | ++----------------+ +``` + +```sql +SELECT transform_values((k, v) -> v, CAST(NULL AS MAP)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| NULL | ++--------+ +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/map-all.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/map-all.md new file mode 100644 index 0000000000000..cdaef32c38b01 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/map-all.md @@ -0,0 +1,89 @@ +--- +{ + "title": "MAP_ALL", + "language": "zh-CN", + "description": "判断 Map 中的所有元素是否都满足指定条件" +} +--- + +## 描述 + +使用 Lambda 表达式检查 Map 中的每一个键值对，并判断所有键值对是否都满足指定条件。Lambda 表达式接收每个键值对的键和值作为参数。 + +:::note +自 Apache Doris 4.2 起支持该函数。 +::: + +## 语法 + +```sql +MAP_ALL((, ) -> , ) +``` + +## 参数 + +| 参数 | 描述 | +| --- | --- | +| `` | Lambda 参数，表示 Map 元素的键。 | +| `` | Lambda 参数，表示 Map 元素的值。 | +| `` | 对每个 Map 元素求值的布尔表达式。 | +| `` | `MAP` 类型的表达式。 | + +## 返回值 + +返回 `BOOLEAN` 类型的值。 + +- 如果任意一个元素的判断结果为 `FALSE`，返回 `FALSE`。 +- 如果所有元素的判断结果均为 `TRUE`，返回 `TRUE`；空 Map 也返回 `TRUE`。 +- 如果没有元素的判断结果为 `FALSE`，但至少有一个元素的判断结果为 `NULL`，返回 `NULL`。 +- 如果 `` 为 `NULL`，返回 `NULL`。 + +## 示例 + +```sql +SELECT map_all((k, v) -> v >= 10, map(1, 10, 2, 20)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| 1 | ++--------+ +``` + +```sql +SELECT map_all((k, v) -> v > 10, map(1, 10, 2, 20)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| 0 | ++--------+ +``` + +```sql +SELECT map_all((k, v) -> CAST(NULL AS BOOLEAN), map(1, 10)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| NULL | ++--------+ +``` + +```sql +SELECT map_all((k, v) -> v > 0, CAST(NULL AS MAP)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| NULL | ++--------+ +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/map-apply.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/map-apply.md new file mode 100644 index 0000000000000..ef31a9966f3d5 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/map-apply.md @@ -0,0 +1,79 @@ +--- +{ + "title": "MAP_APPLY", + "language": "zh-CN", + "description": "同时转换 Map 中的键和值" +} +--- + +## 描述 + +对 Map 中的每一个键值对应用 Lambda 表达式，并使用转换后的键和值构造一个新的 Map。Lambda 表达式接收每个键值对的键和值，并返回一对表达式：第一个表达式作为新键，第二个表达式作为新值。 + +:::note +自 Apache Doris 4.2 起支持该函数。 +::: + +## 语法 + +```sql +MAP_APPLY((, ) -> (, ), ) +``` + +## 参数 + +| 参数 | 描述 | +| --- | --- | +| `` | Lambda 参数，表示 Map 元素的键。 | +| `` | Lambda 参数，表示 Map 元素的值。 | +| `` | 生成返回 Map 中键的表达式，其类型必须是 Map 键支持的类型。 | +| `` | 生成返回 Map 中值的表达式。 | +| `` | `MAP` 类型的表达式。 | + +## 返回值 + +返回 `MAP`。`K2` 和 `V2` 分别是 Lambda 返回的第一个字段和第二个字段的类型。 + +- 如果 `` 为空，返回空 Map。 +- 如果 `` 为 `NULL`，返回 `NULL`。 +- Lambda 返回字段中的 `NULL` 会保留为 Map 中的 `NULL` 键或值。 +- 如果多个元素转换为相同的新键，保留最后一次出现的值。 +- 如果 Lambda 没有返回两个表达式，则报告分析错误。 + +## 示例 + +```sql +SELECT map_apply((k, v) -> (k + 10, v * 2), map(1, 10, 2, 20)) AS result; +``` + +```text ++------------------+ +| result | ++------------------+ +| {11:20, 12:40} | ++------------------+ +``` + +```sql +SELECT map_apply((k, v) -> (1, v), map(1, 10, 2, 20)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| {1:20} | ++--------+ +``` + +```sql +SELECT map_apply((k, v) -> (k, v), CAST(NULL AS MAP)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| NULL | ++--------+ +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/map-exists.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/map-exists.md new file mode 100644 index 0000000000000..1ad9a6cf7d157 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/map-exists.md @@ -0,0 +1,89 @@ +--- +{ + "title": "MAP_EXISTS", + "language": "zh-CN", + "description": "判断 Map 中是否存在满足指定条件的元素" +} +--- + +## 描述 + +使用 Lambda 表达式检查 Map 中的每一个键值对，并判断是否至少有一个键值对满足指定条件。Lambda 表达式接收每个键值对的键和值作为参数。 + +:::note +自 Apache Doris 4.2 起支持该函数。 +::: + +## 语法 + +```sql +MAP_EXISTS((, ) -> , ) +``` + +## 参数 + +| 参数 | 描述 | +| --- | --- | +| `` | Lambda 参数，表示 Map 元素的键。 | +| `` | Lambda 参数，表示 Map 元素的值。 | +| `` | 对每个 Map 元素求值的布尔表达式。 | +| `` | `MAP` 类型的表达式。 | + +## 返回值 + +返回 `BOOLEAN` 类型的值。 + +- 如果任意一个元素的判断结果为 `TRUE`，返回 `TRUE`。 +- 如果所有元素的判断结果均为 `FALSE`，返回 `FALSE`；空 Map 也返回 `FALSE`。 +- 如果没有元素的判断结果为 `TRUE`，但至少有一个元素的判断结果为 `NULL`，返回 `NULL`。 +- 如果 `` 为 `NULL`，返回 `NULL`。 + +## 示例 + +```sql +SELECT map_exists((k, v) -> v = 20, map(1, 10, 2, 20)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| 1 | ++--------+ +``` + +```sql +SELECT map_exists((k, v) -> v > 20, map(1, 10, 2, 20)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| 0 | ++--------+ +``` + +```sql +SELECT map_exists((k, v) -> CAST(NULL AS BOOLEAN), map(1, 10)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| NULL | ++--------+ +``` + +```sql +SELECT map_exists((k, v) -> v > 0, CAST(NULL AS MAP)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| NULL | ++--------+ +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/map-filter.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/map-filter.md new file mode 100644 index 0000000000000..529e0728b79ba --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/map-filter.md @@ -0,0 +1,96 @@ +--- +{ + "title": "MAP_FILTER", + "language": "zh-CN", + "description": "使用 Lambda 表达式或布尔数组过滤 Map 元素" +} +--- + +## 描述 + +过滤 Map 中的元素，并返回只包含选中元素的新 Map。 + +Lambda 形式对每一个键值对计算布尔表达式，Lambda 表达式接收每个键值对的键和值作为参数。布尔数组形式按照数组中的对应位置选择 Map 元素。 + +:::note +自 Apache Doris 4.2 起支持该函数。 +::: + +## 语法 + +```sql +MAP_FILTER((, ) -> , ) +MAP_FILTER(, ) +``` + +## 参数 + +| 参数 | 描述 | +| --- | --- | +| `` | Lambda 参数，表示 Map 元素的键。 | +| `` | Lambda 参数，表示 Map 元素的值。 | +| `` | 对每个 Map 元素求值的布尔表达式，结果为 `TRUE` 的元素会被保留。 | +| `` | `MAP` 类型的表达式。 | +| `` | `ARRAY` 类型的表达式。数组中的每个元素选择 Map 中对应位置的元素，数组长度必须与 Map 的元素数量相同。 | + +## 返回值 + +返回包含选中元素的 `MAP`。 + +- 在 Lambda 形式中，判断结果为 `FALSE` 或 `NULL` 的元素会被移除。 +- 在布尔数组形式中，对应元素为 `FALSE` 或 `NULL` 的 Map 元素会被移除。 +- 如果 `` 为空，返回空 Map。 +- 如果 `` 为 `NULL`，返回 `NULL`。 +- 在布尔数组形式中，如果 `` 为 `NULL`，返回 `NULL`。 + +## 示例 + +```sql +SELECT map_filter((k, v) -> v >= 20, map(1, 10, 2, 20, 3, 30)) AS result; +``` + +```text ++--------------+ +| result | ++--------------+ +| {2:20, 3:30} | ++--------------+ +``` + +```sql +SELECT map_filter( + (k, v) -> if(k = 1, CAST(NULL AS BOOLEAN), TRUE), + map(1, 10, 2, 20)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| {2:20} | ++--------+ +``` + +```sql +SELECT map_filter(map(1, 10, 2, 20), [TRUE, FALSE]) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| {1:10} | ++--------+ +``` + +```sql +SELECT map_filter((k, v) -> TRUE, CAST(NULL AS MAP)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| NULL | ++--------+ +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/transform-keys.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/transform-keys.md new file mode 100644 index 0000000000000..e008a13ea3a99 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/transform-keys.md @@ -0,0 +1,78 @@ +--- +{ + "title": "TRANSFORM_KEYS", + "language": "zh-CN", + "description": "转换 Map 中的每一个键" +} +--- + +## 描述 + +对 Map 中的每一个键值对应用 Lambda 表达式，并使用转换后的键和原始值构造一个新的 Map。Lambda 表达式接收每个键值对的键和值作为参数。 + +:::note +自 Apache Doris 4.2 起支持该函数。 +::: + +## 语法 + +```sql +TRANSFORM_KEYS((, ) -> , ) +``` + +## 参数 + +| 参数 | 描述 | +| --- | --- | +| `` | Lambda 参数，表示 Map 元素的键。 | +| `` | Lambda 参数，表示 Map 元素的值。 | +| `` | 生成返回 Map 中键的表达式，其类型必须是 Map 键支持的类型。 | +| `` | `MAP` 类型的表达式。 | + +## 返回值 + +返回 `MAP`，其中 `K2` 是 Lambda 返回值的类型。 + +- 输入 Map 中的值保持不变。 +- 如果 `` 为空，返回空 Map。 +- 如果 `` 为 `NULL`，返回 `NULL`。 +- Lambda 返回的 `NULL` 键会被保留。 +- 如果多个元素转换为相同的新键，保留最后一次出现的值。 + +## 示例 + +```sql +SELECT transform_keys((k, v) -> k + 10, map(1, 10, 2, 20)) AS result; +``` + +```text ++----------------+ +| result | ++----------------+ +| {11:10, 12:20} | ++----------------+ +``` + +```sql +SELECT transform_keys((k, v) -> 1, map(1, 10, 2, 20)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| {1:20} | ++--------+ +``` + +```sql +SELECT transform_keys((k, v) -> k, CAST(NULL AS MAP)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| NULL | ++--------+ +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/transform-values.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/transform-values.md new file mode 100644 index 0000000000000..bca92db4fdead --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/transform-values.md @@ -0,0 +1,79 @@ +--- +{ + "title": "TRANSFORM_VALUES", + "language": "zh-CN", + "description": "转换 Map 中的每一个值" +} +--- + +## 描述 + +对 Map 中的每一个键值对应用 Lambda 表达式，并使用原始键和转换后的值构造一个新的 Map。Lambda 表达式接收每个键值对的键和值作为参数。 + +:::note +自 Apache Doris 4.2 起支持该函数。 +::: + +## 语法 + +```sql +TRANSFORM_VALUES((, ) -> , ) +``` + +## 参数 + +| 参数 | 描述 | +| --- | --- | +| `` | Lambda 参数，表示 Map 元素的键。 | +| `` | Lambda 参数，表示 Map 元素的值。 | +| `` | 生成返回 Map 中值的表达式。 | +| `` | `MAP` 类型的表达式。 | + +## 返回值 + +返回 `MAP`，其中 `V2` 是 Lambda 返回值的类型。 + +- 输入 Map 中的键保持不变。 +- 如果 `` 为空，返回空 Map。 +- 如果 `` 为 `NULL`，返回 `NULL`。 +- Lambda 返回的 `NULL` 值会被保留。 + +## 示例 + +```sql +SELECT transform_values((k, v) -> v + k, map(1, 10, 2, 20)) AS result; +``` + +```text ++--------------+ +| result | ++--------------+ +| {1:11, 2:22} | ++--------------+ +``` + +```sql +SELECT transform_values( + (k, v) -> if(k = 1, CAST(NULL AS INT), v), + map(1, 10, 2, 20)) AS result; +``` + +```text ++----------------+ +| result | ++----------------+ +| {1:null, 2:20} | ++----------------+ +``` + +```sql +SELECT transform_values((k, v) -> v, CAST(NULL AS MAP)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| NULL | ++--------+ +``` diff --git a/sidebars.ts b/sidebars.ts index 437392d815f4c..6642cd9c084af 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -1801,16 +1801,22 @@ const sidebars: SidebarsConfig = { items: [ 'sql-manual/sql-functions/scalar-functions/map-functions/deduplicate-map', 'sql-manual/sql-functions/scalar-functions/map-functions/map', + 'sql-manual/sql-functions/scalar-functions/map-functions/map-all', + 'sql-manual/sql-functions/scalar-functions/map-functions/map-apply', 'sql-manual/sql-functions/scalar-functions/map-functions/map-contains-entry', 'sql-manual/sql-functions/scalar-functions/map-functions/map-contains-key', 'sql-manual/sql-functions/scalar-functions/map-functions/map-contains-value', 'sql-manual/sql-functions/scalar-functions/map-functions/map-entries', + "sql-manual/sql-functions/scalar-functions/map-functions/map-exists", + 'sql-manual/sql-functions/scalar-functions/map-functions/map-filter', 'sql-manual/sql-functions/scalar-functions/map-functions/map-from-arrays', 'sql-manual/sql-functions/scalar-functions/map-functions/map-from-entries', 'sql-manual/sql-functions/scalar-functions/map-functions/map-keys', 'sql-manual/sql-functions/scalar-functions/map-functions/map-size', 'sql-manual/sql-functions/scalar-functions/map-functions/map-values', 'sql-manual/sql-functions/scalar-functions/map-functions/str-to-map', + 'sql-manual/sql-functions/scalar-functions/map-functions/transform-keys', + 'sql-manual/sql-functions/scalar-functions/map-functions/transform-values', ], }, { diff --git a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/map-all.md b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/map-all.md new file mode 100644 index 0000000000000..3d5dbc29da646 --- /dev/null +++ b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/map-all.md @@ -0,0 +1,89 @@ +--- +{ + "title": "MAP_ALL", + "language": "en", + "description": "Tests whether every entry in a map satisfies a condition" +} +--- + +## Description + +Tests every entry in a map with a lambda expression and returns whether all entries satisfy the specified condition. The lambda receives the key and value of each entry. + +:::note +This function is supported since Apache Doris 4.2. +::: + +## Syntax + +```sql +MAP_ALL((, ) -> , ) +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| `` | The lambda parameter representing the key of a map entry. | +| `` | The lambda parameter representing the value of a map entry. | +| `` | A Boolean expression evaluated for each map entry. | +| `` | A `MAP` expression. | + +## Return Value + +Returns a `BOOLEAN` value. + +- Returns `FALSE` if the predicate returns `FALSE` for any entry. +- Returns `TRUE` if the predicate returns `TRUE` for every entry, including when the map is empty. +- Returns `NULL` if no entry returns `FALSE` and at least one entry returns `NULL`. +- If `` is `NULL`, returns `NULL`. + +## Examples + +```sql +SELECT map_all((k, v) -> v >= 10, map(1, 10, 2, 20)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| 1 | ++--------+ +``` + +```sql +SELECT map_all((k, v) -> v > 10, map(1, 10, 2, 20)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| 0 | ++--------+ +``` + +```sql +SELECT map_all((k, v) -> CAST(NULL AS BOOLEAN), map(1, 10)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| NULL | ++--------+ +``` + +```sql +SELECT map_all((k, v) -> v > 0, CAST(NULL AS MAP)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| NULL | ++--------+ +``` diff --git a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/map-apply.md b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/map-apply.md new file mode 100644 index 0000000000000..6bd2b2a08086d --- /dev/null +++ b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/map-apply.md @@ -0,0 +1,79 @@ +--- +{ + "title": "MAP_APPLY", + "language": "en", + "description": "Transforms the keys and values of a map" +} +--- + +## Description + +Applies a lambda expression to every entry in a map and constructs a new map from the transformed keys and values. The lambda receives the key and value of each entry and returns a pair of expressions. The first expression is used as the new key and the second expression as the new value. + +:::note +This function is supported since Apache Doris 4.2. +::: + +## Syntax + +```sql +MAP_APPLY((, ) -> (, ), ) +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| `` | The lambda parameter representing the key of a map entry. | +| `` | The lambda parameter representing the value of a map entry. | +| `` | An expression that produces the key in the returned map. Its type must be supported by MAP keys. | +| `` | An expression that produces the value in the returned map. | +| `` | A `MAP` expression. | + +## Return Value + +Returns a `MAP`, where `K2` and `V2` are the types of the first and second fields returned by the lambda. + +- If `` is empty, returns an empty map. +- If `` is `NULL`, returns `NULL`. +- `NULL` fields returned by the lambda are retained as `NULL` keys or values. +- If multiple entries are transformed to the same key, the value from the last occurrence is retained. +- If the lambda does not return exactly two expressions, an analysis error is reported. + +## Examples + +```sql +SELECT map_apply((k, v) -> (k + 10, v * 2), map(1, 10, 2, 20)) AS result; +``` + +```text ++------------------+ +| result | ++------------------+ +| {11:20, 12:40} | ++------------------+ +``` + +```sql +SELECT map_apply((k, v) -> (1, v), map(1, 10, 2, 20)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| {1:20} | ++--------+ +``` + +```sql +SELECT map_apply((k, v) -> (k, v), CAST(NULL AS MAP)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| NULL | ++--------+ +``` diff --git a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/map-exists.md b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/map-exists.md new file mode 100644 index 0000000000000..e203ec2da9769 --- /dev/null +++ b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/map-exists.md @@ -0,0 +1,89 @@ +--- +{ + "title": "MAP_EXISTS", + "language": "en", + "description": "Tests whether any entry in a map satisfies a condition" +} +--- + +## Description + +Tests every entry in a map with a lambda expression and returns whether at least one entry satisfies the specified condition. The lambda receives the key and value of each entry. + +:::note +This function is supported since Apache Doris 4.2. +::: + +## Syntax + +```sql +MAP_EXISTS((, ) -> , ) +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| `` | The lambda parameter representing the key of a map entry. | +| `` | The lambda parameter representing the value of a map entry. | +| `` | A Boolean expression evaluated for each map entry. | +| `` | A `MAP` expression. | + +## Return Value + +Returns a `BOOLEAN` value. + +- Returns `TRUE` if the predicate returns `TRUE` for any entry. +- Returns `FALSE` if the predicate returns `FALSE` for every entry, including when the map is empty. +- Returns `NULL` if no entry returns `TRUE` and at least one entry returns `NULL`. +- If `` is `NULL`, returns `NULL`. + +## Examples + +```sql +SELECT map_exists((k, v) -> v = 20, map(1, 10, 2, 20)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| 1 | ++--------+ +``` + +```sql +SELECT map_exists((k, v) -> v > 20, map(1, 10, 2, 20)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| 0 | ++--------+ +``` + +```sql +SELECT map_exists((k, v) -> CAST(NULL AS BOOLEAN), map(1, 10)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| NULL | ++--------+ +``` + +```sql +SELECT map_exists((k, v) -> v > 0, CAST(NULL AS MAP)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| NULL | ++--------+ +``` diff --git a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/map-filter.md b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/map-filter.md new file mode 100644 index 0000000000000..9d41de242ef11 --- /dev/null +++ b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/map-filter.md @@ -0,0 +1,96 @@ +--- +{ + "title": "MAP_FILTER", + "language": "en", + "description": "Filters map entries using a lambda expression or a Boolean array" +} +--- + +## Description + +Filters entries in a map and returns a map containing only the selected entries. + +The lambda form evaluates a Boolean expression for every entry. The lambda receives the key and value of each entry. The Boolean-array form selects entries by their corresponding positions. + +:::note +This function is supported since Apache Doris 4.2. +::: + +## Syntax + +```sql +MAP_FILTER((, ) -> , ) +MAP_FILTER(, ) +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| `` | The lambda parameter representing the key of a map entry. | +| `` | The lambda parameter representing the value of a map entry. | +| `` | A Boolean expression evaluated for each map entry. Entries for which it returns `TRUE` are retained. | +| `` | A `MAP` expression. | +| `` | An `ARRAY` expression. Each element selects the map entry at the same position. The array length must equal the number of entries in the map. | + +## Return Value + +Returns a `MAP` containing the selected entries. + +- In the lambda form, entries for which the predicate returns `FALSE` or `NULL` are removed. +- In the Boolean-array form, entries corresponding to `FALSE` or `NULL` elements are removed. +- If `` is empty, returns an empty map. +- If `` is `NULL`, returns `NULL`. +- In the Boolean-array form, if `` is `NULL`, returns `NULL`. + +## Examples + +```sql +SELECT map_filter((k, v) -> v >= 20, map(1, 10, 2, 20, 3, 30)) AS result; +``` + +```text ++--------------+ +| result | ++--------------+ +| {2:20, 3:30} | ++--------------+ +``` + +```sql +SELECT map_filter( + (k, v) -> if(k = 1, CAST(NULL AS BOOLEAN), TRUE), + map(1, 10, 2, 20)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| {2:20} | ++--------+ +``` + +```sql +SELECT map_filter(map(1, 10, 2, 20), [TRUE, FALSE]) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| {1:10} | ++--------+ +``` + +```sql +SELECT map_filter((k, v) -> TRUE, CAST(NULL AS MAP)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| NULL | ++--------+ +``` diff --git a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/transform-keys.md b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/transform-keys.md new file mode 100644 index 0000000000000..75d2f37814274 --- /dev/null +++ b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/transform-keys.md @@ -0,0 +1,78 @@ +--- +{ + "title": "TRANSFORM_KEYS", + "language": "en", + "description": "Transforms every key in a map" +} +--- + +## Description + +Applies a lambda expression to every entry in a map and constructs a new map with the transformed keys and the original values. The lambda receives the key and value of each entry. + +:::note +This function is supported since Apache Doris 4.2. +::: + +## Syntax + +```sql +TRANSFORM_KEYS((, ) -> , ) +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| `` | The lambda parameter representing the key of a map entry. | +| `` | The lambda parameter representing the value of a map entry. | +| `` | An expression that produces the key in the returned map. Its type must be supported by MAP keys. | +| `` | A `MAP` expression. | + +## Return Value + +Returns a `MAP`, where `K2` is the type returned by the lambda. + +- The values in the input map are retained unchanged. +- If `` is empty, returns an empty map. +- If `` is `NULL`, returns `NULL`. +- A `NULL` key returned by the lambda is retained. +- If multiple entries are transformed to the same key, the value from the last occurrence is retained. + +## Examples + +```sql +SELECT transform_keys((k, v) -> k + 10, map(1, 10, 2, 20)) AS result; +``` + +```text ++----------------+ +| result | ++----------------+ +| {11:10, 12:20} | ++----------------+ +``` + +```sql +SELECT transform_keys((k, v) -> 1, map(1, 10, 2, 20)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| {1:20} | ++--------+ +``` + +```sql +SELECT transform_keys((k, v) -> k, CAST(NULL AS MAP)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| NULL | ++--------+ +``` diff --git a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/transform-values.md b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/transform-values.md new file mode 100644 index 0000000000000..30803fff2f12d --- /dev/null +++ b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/map-functions/transform-values.md @@ -0,0 +1,79 @@ +--- +{ + "title": "TRANSFORM_VALUES", + "language": "en", + "description": "Transforms every value in a map" +} +--- + +## Description + +Applies a lambda expression to every entry in a map and constructs a new map with the original keys and the transformed values. The lambda receives the key and value of each entry. + +:::note +This function is supported since Apache Doris 4.2. +::: + +## Syntax + +```sql +TRANSFORM_VALUES((, ) -> , ) +``` + +## Parameters + +| Parameter | Description | +| --- | --- | +| `` | The lambda parameter representing the key of a map entry. | +| `` | The lambda parameter representing the value of a map entry. | +| `` | An expression that produces the value in the returned map. | +| `` | A `MAP` expression. | + +## Return Value + +Returns a `MAP`, where `V2` is the type returned by the lambda. + +- The keys in the input map are retained unchanged. +- If `` is empty, returns an empty map. +- If `` is `NULL`, returns `NULL`. +- A `NULL` value returned by the lambda is retained. + +## Examples + +```sql +SELECT transform_values((k, v) -> v + k, map(1, 10, 2, 20)) AS result; +``` + +```text ++--------------+ +| result | ++--------------+ +| {1:11, 2:22} | ++--------------+ +``` + +```sql +SELECT transform_values( + (k, v) -> if(k = 1, CAST(NULL AS INT), v), + map(1, 10, 2, 20)) AS result; +``` + +```text ++----------------+ +| result | ++----------------+ +| {1:null, 2:20} | ++----------------+ +``` + +```sql +SELECT transform_values((k, v) -> v, CAST(NULL AS MAP)) AS result; +``` + +```text ++--------+ +| result | ++--------+ +| NULL | ++--------+ +``` diff --git a/versioned_sidebars/version-4.x-sidebars.json b/versioned_sidebars/version-4.x-sidebars.json index f4306a6a91d27..94f3530484edd 100644 --- a/versioned_sidebars/version-4.x-sidebars.json +++ b/versioned_sidebars/version-4.x-sidebars.json @@ -1976,16 +1976,22 @@ "items": [ "sql-manual/sql-functions/scalar-functions/map-functions/deduplicate-map", "sql-manual/sql-functions/scalar-functions/map-functions/map", + "sql-manual/sql-functions/scalar-functions/map-functions/map-all", + "sql-manual/sql-functions/scalar-functions/map-functions/map-apply", "sql-manual/sql-functions/scalar-functions/map-functions/map-contains-entry", "sql-manual/sql-functions/scalar-functions/map-functions/map-contains-key", "sql-manual/sql-functions/scalar-functions/map-functions/map-contains-value", "sql-manual/sql-functions/scalar-functions/map-functions/map-entries", + "sql-manual/sql-functions/scalar-functions/map-functions/map-exists", + "sql-manual/sql-functions/scalar-functions/map-functions/map-filter", "sql-manual/sql-functions/scalar-functions/map-functions/map-from-arrays", "sql-manual/sql-functions/scalar-functions/map-functions/map-from-entries", "sql-manual/sql-functions/scalar-functions/map-functions/map-keys", "sql-manual/sql-functions/scalar-functions/map-functions/map-size", "sql-manual/sql-functions/scalar-functions/map-functions/map-values", - "sql-manual/sql-functions/scalar-functions/map-functions/str-to-map" + "sql-manual/sql-functions/scalar-functions/map-functions/str-to-map", + "sql-manual/sql-functions/scalar-functions/map-functions/transform-keys", + "sql-manual/sql-functions/scalar-functions/map-functions/transform-values" ] }, {