From a6acb7584b3b0b4091f6ad81d857d87b7cdfe8c2 Mon Sep 17 00:00:00 2001 From: yujun Date: Fri, 4 Sep 2026 19:16:29 +0800 Subject: [PATCH] docs: add array_agg_if aggregate function doc Add English and Chinese current-version docs for the new array_agg_if aggregate function (cond-first, keeps NULL elements, empty array when no row matches), with examples. --- .../aggregate-functions/array-agg-if.md | 74 +++++++++++++++++++ .../aggregate-functions/array-agg-if.md | 74 +++++++++++++++++++ 2 files changed, 148 insertions(+) create mode 100644 docs/sql-manual/sql-functions/aggregate-functions/array-agg-if.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/aggregate-functions/array-agg-if.md diff --git a/docs/sql-manual/sql-functions/aggregate-functions/array-agg-if.md b/docs/sql-manual/sql-functions/aggregate-functions/array-agg-if.md new file mode 100644 index 0000000000000..7fdbd34de87cf --- /dev/null +++ b/docs/sql-manual/sql-functions/aggregate-functions/array-agg-if.md @@ -0,0 +1,74 @@ +--- +{ + "title": "ARRAY_AGG_IF", + "language": "en", + "description": "Concatenates the values of rows that meet a condition into an array, which can be used for conditional pivoting of rows into columns." +} +--- + +## Description + +Concatenates the values (including null values) in a column into an array for the rows whose condition is true. Rows whose condition is false or null are skipped entirely. + +## Syntax + +```sql +ARRAY_AGG_IF(, ) +``` + +## Parameters + +| Parameter | Description | +| -- | -- | +| `` | A BOOLEAN expression that determines whether a row is collected. Rows where the condition is false or null are skipped. | +| `` | An expression that determines the values to be placed into the array. Supported types: Bool, TinyInt, SmallInt, Integer, BigInt, LargeInt, Float, Double, Decimal, Date, Datetime, TimestampNs, Timestamptz, IPV4, IPV6, String, Array, Map, Struct. | + +## Return Value + +Returns a value of ARRAY type. Special cases: + +- The order of elements in the array is not guaranteed. +- Null elements are kept: when the condition is true, a null value in `` still becomes a null element in the result. +- Returns an empty array when no row satisfies the condition. + +## Example + +```sql +-- setup +CREATE TABLE test_doris_array_agg_if ( + c1 INT, + c2 INT +) DISTRIBUTED BY HASH(c1) BUCKETS 1 +PROPERTIES ("replication_num" = "1"); +INSERT INTO test_doris_array_agg_if VALUES (1, 10), (1, 20), (1, 30), (2, 100), (2, 200), (3, NULL); +``` + +```sql +-- collect the values greater than 15 per group; the NULL-valued row of c1=3 is skipped +select c1, array_agg_if(c2 > 15, c2) from test_doris_array_agg_if group by c1; +``` + +```text ++------+------------------------+ +| c1 | array_agg_if(c2 > 15, c2) | ++------+------------------------+ +| 1 | [20, 30] | +| 2 | [100, 200] | +| 3 | [] | ++------+------------------------+ +``` + +```sql +-- a null element is kept when its row satisfies the condition +select c1, array_agg_if(c1 > 0, c2) from test_doris_array_agg_if group by c1; +``` + +```text ++------+----------------------+ +| c1 | array_agg_if(c1 > 0, c2) | ++------+----------------------+ +| 1 | [10, 20, 30] | +| 2 | [100, 200] | +| 3 | [null] | ++------+----------------------+ +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/aggregate-functions/array-agg-if.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/aggregate-functions/array-agg-if.md new file mode 100644 index 0000000000000..a87385d68a8c9 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/aggregate-functions/array-agg-if.md @@ -0,0 +1,74 @@ +--- +{ + "title": "ARRAY_AGG_IF", + "language": "zh-CN", + "description": "将满足条件的行中的值串联成一个数组，可以用于多行转一行（行转列）的条件过滤。" +} +--- + +## 描述 + +对于满足条件的行，将其一列中的值（包括空值 null）串联成一个数组。条件为 false 或 null 的行会被整体跳过（不贡献元素，也不贡献 null）。 + +## 语法 + +```sql +ARRAY_AGG_IF(, ) +``` + +## 参数 + +| 参数 | 说明 | +| -- | -- | +| `` | BOOLEAN 类型表达式，决定该行是否被收集。条件为 false 或 null 时该行被跳过。 | +| `` | 确定要放入数组的值的表达式，支持类型为 Bool，TinyInt，SmallInt，Integer，BigInt，LargeInt，Float，Double，Decimal，Date，Datetime，TimestampNs，Timestamptz，IPV4，IPV6，String，Array，Map，Struct。| + +## 返回值 + +返回 ARRAY 类型的值，特殊情况： + +- 数组中元素不保证顺序。 +- 保留 null 元素：当条件为 true 时，`` 的 null 值仍会成为结果数组中的一个 null 元素。 +- 没有任何行满足条件时，返回空数组。 + +## 举例 + +```sql +-- setup +CREATE TABLE test_doris_array_agg_if ( + c1 INT, + c2 INT +) DISTRIBUTED BY HASH(c1) BUCKETS 1 +PROPERTIES ("replication_num" = "1"); +INSERT INTO test_doris_array_agg_if VALUES (1, 10), (1, 20), (1, 30), (2, 100), (2, 200), (3, NULL); +``` + +```sql +-- 每组收集大于 15 的值；c1=3 的行条件为 null，被跳过 +select c1, array_agg_if(c2 > 15, c2) from test_doris_array_agg_if group by c1; +``` + +```text ++------+------------------------+ +| c1 | array_agg_if(c2 > 15, c2) | ++------+------------------------+ +| 1 | [20, 30] | +| 2 | [100, 200] | +| 3 | [] | ++------+------------------------+ +``` + +```sql +-- 行满足条件时，null 元素被保留 +select c1, array_agg_if(c1 > 0, c2) from test_doris_array_agg_if group by c1; +``` + +```text ++------+----------------------+ +| c1 | array_agg_if(c1 > 0, c2) | ++------+----------------------+ +| 1 | [10, 20, 30] | +| 2 | [100, 200] | +| 3 | [null] | ++------+----------------------+ +```