This is an automated email from the ASF dual-hosted git repository.
morningman pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/doris-website.git
The following commit(s) were added to refs/heads/master by this push:
new 0fdf8bba80e [doc](sql-functions) numbered-example authoring format —
array-filter.md as demo (#3784)
0fdf8bba80e is described below
commit 0fdf8bba80e63f08c579d9bc35ca61c3ccf09377
Author: boluor <[email protected]>
AuthorDate: Wed May 27 19:15:44 2026 -0700
[doc](sql-functions) numbered-example authoring format — array-filter.md as
demo (#3784)
## Summary
**Demo PR** proposing a small authoring convention for
`sql-manual/sql-functions/` doc pages, applied here to `array-filter.md`
(EN + ZH) as a concrete example. Looking for maintainer feedback on the
shape before scaling to other pages.
## The convention in one paragraph
Inside `## Examples`, each runnable example becomes a numbered pair of
fenced blocks:
````
```sql {example="N"} ← SQL to execute (copy button, runnable)
```result {example="N"} ← expected output (no copy)
```error {example="N"} ← expected error (no copy)
````
One-time fixture data goes in ` ```sql {setup} `. The `## Syntax` block
stays unchanged. EN and ZH share the same `example="N"` numbers, so
cross-language drift becomes mechanically detectable.
## Why
1. **Machine-verifiable.** A doc-verify tool can match every `sql
{example="N"}` to its `result|error` block by ID — zero heuristic guessing
about where SQL ends and output begins.
2. **EN/ZH consistency.** Same example numbers across languages → missing
or drifted examples are detectable by tooling, not by manual review.
3. **UX.** Readers copy SQL safely; expected output stays visually distinct
and is not mis-copied as input.
4. **Backward compatible.** Pages that don't use the convention keep
working exactly as today. It's opt-in per page.
## What's in this PR
Just `array-filter.md`, both languages:
-
`versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions/array-filter.md`
-
`i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions/array-filter.md`
### Before / after (one example)
Before:
````markdown
Using lambda expression to filter elements in double_array greater than
or equal to 3:
```sql
SELECT array_filter(x -> x >= 3, double_array) FROM array_filter_test WHERE
id = 1;
+------------------------------------------+
| array_filter(x -> x >= 3, double_array) |
+------------------------------------------+
| [3.3, 4.4, 5.5] |
+------------------------------------------+
```
````
After:
````markdown
**Example 1** — Lambda over a DOUBLE array column: keep elements `>= 3`.
```sql {example="1"}
SELECT array_filter(x -> x >= 3, double_array) FROM array_filter_test WHERE
id = 1;
```
```result {example="1"}
+------------------------------------------+
| array_filter(x -> x >= 3, double_array) |
+------------------------------------------+
| [3.3, 4.4, 5.5] |
+------------------------------------------+
```
````
### Bundled fix
The original EN page had a code block at line ~164 with only the result
table (the `SELECT` statement was missing). Reconstructed the `SELECT` from the
result column header — it is now Example 9.
## Verification
Ran every example on a single-node Apache Doris 4.1.1 cluster:
- **EN**: 20 pass / 0 fail / 1 not_checked (Syntax illustrative block)
- **ZH**: 20 pass / 0 fail / 1 not_checked
- All 4 error examples carry `kind=error` expected output and match the
actual `errCode = …, detailMessage = …` from Doris, after stripping
environment-specific IP prefixes.
## Rendering
Without any theme changes, docusaurus renders:
- `sql` fences with syntax highlight + copy button (default behavior,
unchanged)
- `result` and `error` fences as plain code blocks (Prism doesn't know
these languages, so no highlight; copy button still present by default)
The convention's full UX (red-styled `error` block, no copy on
`result`/`error`) needs a small theme override, which would be a separate
follow-up PR. **This PR does not require any theme change** — the markdown is
valid and renders correctly today.
## Asking for
- Is the convention shape (`{example="N"}`, three fence types) OK?
- Where should the full authoring spec live? Suggestions:
`.docs-governance/` or `doc-tools/`. A separate spec-doc PR can follow.
- If approved, follow-ups will convert other `array-*` function pages in
the same style.
Co-authored-by: doris-verify
<https://github.com/apache/doris-website/pull/3781>
---
.../array-functions/array-filter.md | 153 +++++++++++++++------
.../array-functions/array-filter.md | 153 +++++++++++++++------
2 files changed, 216 insertions(+), 90 deletions(-)
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions/array-filter.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions/array-filter.md
index 2a77943d5a9..af9e6c82c00 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions/array-filter.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions/array-filter.md
@@ -57,7 +57,9 @@ array_filter(array1, array<boolean> filter_array)
### 示例
-```sql
+**Setup** — 建立 fixture 表并写入 4 行覆盖正常值、边界值、空数组和 NULL 的样本数据。后面所有 example 都引用这张表。
+
+```sql {setup}
CREATE TABLE array_filter_test (
id INT,
int_array ARRAY<INT>,
@@ -77,11 +79,13 @@ INSERT INTO array_filter_test VALUES
(4, NULL, NULL, NULL);
```
-**查询示例：**
+**Example 1** —— 对 DOUBLE 数组列应用 lambda：保留 `>= 3` 的元素。
-使用 lambda 表达式过滤 double_array 中大于等于 3 的元素：
-```sql
+```sql {example="1"}
SELECT array_filter(x -> x >= 3, double_array) FROM array_filter_test WHERE id
= 1;
+```
+
+```result {example="1"}
+------------------------------------------+
| array_filter(x -> x >= 3, double_array) |
+------------------------------------------+
@@ -89,9 +93,13 @@ SELECT array_filter(x -> x >= 3, double_array) FROM
array_filter_test WHERE id =
+------------------------------------------+
```
-使用 lambda 表达式过滤 string_array 中长度大于 2 的元素：
-```sql
+**Example 2** —— 对 STRING 数组列应用 lambda：保留 `length > 2` 的元素。
+
+```sql {example="2"}
SELECT array_filter(x -> length(x) > 2, string_array) FROM array_filter_test
WHERE id = 1;
+```
+
+```result {example="2"}
+--------------------------------------------------+
| array_filter(x -> length(x) > 2, string_array) |
+--------------------------------------------------+
@@ -99,9 +107,13 @@ SELECT array_filter(x -> length(x) > 2, string_array) FROM
array_filter_test WHE
+--------------------------------------------------+
```
-使用布尔数组过滤元素：
-```sql
+**Example 3** —— 布尔掩码形式：保留掩码为 `true` 对应位置的元素。
+
+```sql {example="3"}
SELECT array_filter(int_array, [false, true, false, true, true]) FROM
array_filter_test WHERE id = 1;
+```
+
+```result {example="3"}
+-----------------------------------------------------------+
| array_filter(int_array, [false, true, false, true, true]) |
+-----------------------------------------------------------+
@@ -109,10 +121,13 @@ SELECT array_filter(int_array, [false, true, false, true,
true]) FROM array_filt
+-----------------------------------------------------------+
```
-布尔数组过滤示例，根据布尔值决定是否保留对应位置的元素：
+**Example 4** —— 布尔掩码形式（数组字面量）。
-```sql
+```sql {example="4"}
SELECT array_filter([1,2,3], [true, false, true]);
+```
+
+```result {example="4"}
+--------------------------------------------+
| array_filter([1,2,3], [true, false, true]) |
+--------------------------------------------+
@@ -120,9 +135,13 @@ SELECT array_filter([1,2,3], [true, false, true]);
+--------------------------------------------+
```
-当布尔数组长度大于原数组时，多余的布尔值会被忽略：
-```sql
+**Example 5** —— 布尔数组比原数组长：多余的掩码位被忽略。
+
+```sql {example="5"}
SELECT array_filter([1,2,3], [true, false, true, false]);
+```
+
+```result {example="5"}
+---------------------------------------------------+
| array_filter([1,2,3], [true, false, true, false]) |
+---------------------------------------------------+
@@ -130,9 +149,13 @@ SELECT array_filter([1,2,3], [true, false, true, false]);
+---------------------------------------------------+
```
-当布尔数组长度小于原数组时，只处理布尔数组中对应位置的元素：
-```sql
+**Example 6** —— 布尔数组比原数组短：只处理掩码覆盖的位置。
+
+```sql {example="6"}
SELECT array_filter([1,2,3], [true, false]);
+```
+
+```result {example="6"}
+--------------------------------------+
| array_filter([1,2,3], [true, false]) |
+--------------------------------------+
@@ -140,9 +163,13 @@ SELECT array_filter([1,2,3], [true, false]);
+--------------------------------------+
```
-空数组返回空数组：
-```sql
+**Example 7** —— 空数组返回空数组（`id = 3`）。
+
+```sql {example="7"}
SELECT array_filter(x -> x > 0, int_array) FROM array_filter_test WHERE id = 3;
+```
+
+```result {example="7"}
+-------------------------------------+
| array_filter(x -> x > 0, int_array) |
+-------------------------------------+
@@ -150,9 +177,13 @@ SELECT array_filter(x -> x > 0, int_array) FROM
array_filter_test WHERE id = 3;
+-------------------------------------+
```
-NULL 数组返回 NULL：当输入数组为 NULL 时返回 NULL，不会抛出错误。
-```sql
+**Example 8** —— NULL 数组返回 NULL（`id = 4`）。
+
+```sql {example="8"}
SELECT array_filter(x -> x > 0, int_array) FROM array_filter_test WHERE id = 4;
+```
+
+```result {example="8"}
+-------------------------------------+
| array_filter(x -> x > 0, int_array) |
+-------------------------------------+
@@ -160,8 +191,13 @@ SELECT array_filter(x -> x > 0, int_array) FROM
array_filter_test WHERE id = 4;
+-------------------------------------+
```
-包含 null 的数组，lambda 可判断 null：
-```sql
+**Example 9** —— 数组里含 NULL 元素：可在 lambda 中用 `IS NOT NULL` 过滤掉。
+
+```sql {example="9"}
+SELECT array_filter(x -> x is not null, [null, 1, null, 2, null]);
+```
+
+```result {example="9"}
+------------------------------------------------------------+
| array_filter(x -> x is not null, [null, 1, null, 2, null]) |
+------------------------------------------------------------+
@@ -169,9 +205,13 @@ SELECT array_filter(x -> x > 0, int_array) FROM
array_filter_test WHERE id = 4;
+------------------------------------------------------------+
```
-多数组过滤，过滤 int_array > double_array 的元素：
-```sql
+**Example 10** —— 多参 lambda 在两个数组列上一起处理。
+
+```sql {example="10"}
SELECT array_filter((x, y) -> x > y, int_array, double_array) FROM
array_filter_test WHERE id = 1;
+```
+
+```result {example="10"}
+--------------------------------------------------------+
| array_filter((x, y) -> x > y, int_array, double_array) |
+--------------------------------------------------------+
@@ -179,11 +219,13 @@ SELECT array_filter((x, y) -> x > y, int_array,
double_array) FROM array_filter_
+--------------------------------------------------------+
```
-复杂类型示例：
+**Example 11** —— 嵌套数组字面量上过滤：保留 `size > 2` 的子数组。
-嵌套数组过滤，过滤每个子数组长度大于 2 的元素：
-```sql
+```sql {example="11"}
SELECT array_filter(x -> size(x) > 2, [[1,2], [3,4,5], [6], [7,8,9,10]]);
+```
+
+```result {example="11"}
+-------------------------------------------------------------------+
| array_filter(x -> size(x) > 2, [[1,2], [3,4,5], [6], [7,8,9,10]]) |
+-------------------------------------------------------------------+
@@ -191,9 +233,13 @@ SELECT array_filter(x -> size(x) > 2, [[1,2], [3,4,5],
[6], [7,8,9,10]]);
+-------------------------------------------------------------------+
```
-map 类型过滤，过滤 key 为 'a' 的 value 大于 10 的元素：
-```sql
+**Example 12** —— 对 MAP 数组过滤：保留 `x['a'] > 10` 的元素。
+
+```sql {example="12"}
SELECT array_filter(x -> x['a'] > 10, [{'a':5}, {'a':15}, {'a':20}]);
+```
+
+```result {example="12"}
+---------------------------------------------------------------+
| array_filter(x -> x['a'] > 10, [{'a':5}, {'a':15}, {'a':20}]) |
+---------------------------------------------------------------+
@@ -201,9 +247,13 @@ SELECT array_filter(x -> x['a'] > 10, [{'a':5}, {'a':15},
{'a':20}]);
+---------------------------------------------------------------+
```
-struct 类型过滤，过滤 age 大于 18 的元素：
-```sql
+**Example 13** —— 对 STRUCT 数组按字段值过滤。
+
+```sql {example="13"}
SELECT array_filter(x -> struct_element(x, 'age') > 18,
array(named_struct('name','Alice','age',20),named_struct('name','Bob','age',16),named_struct('name','Eve','age',30)));
+```
+
+```result {example="13"}
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| array_filter(x -> struct_element(x, 'age') > 18,
array(named_struct('name','Alice','age',20),named_struct('name','Bob','age',16),named_struct('name','Eve','age',30)))
|
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -211,32 +261,43 @@ SELECT array_filter(x -> struct_element(x, 'age') > 18,
array(named_struct('name
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
```
-参数数量错误：
-```sql
+**Example 14** —— lambda 参数个数必须和传入的数组数量一致。
+
+```sql {example="14"}
SELECT array_filter(x -> x > 0, [1,2,3], [4,5,6], [7,8,9]);
+```
+
+```error {example="14"}
ERROR 1105 (HY000): errCode = 2, detailMessage = lambda x -> (x > 0)
arguments' size is not equal parameters' size
```
-数组长度不一致会报错：
-```sql
+**Example 15** —— 多数组形式要求所有数组长度一致。
+
+```sql {example="15"}
SELECT array_filter((x, y) -> x > y, [1,2,3], [4,5]);
-ERROR 1105 (HY000): errCode = 2, detailMessage =
(10.16.10.6)[INVALID_ARGUMENT]in array map function, the input column size are
not equal completely, nested column data rows 1st size is 3, 2th size is 2.
```
-传入非数组类型时会报错：
-```sql
-SELECT array_filter(x -> x > 0, 'not_an_array');
-ERROR 1105 (HY000): errCode = 2, detailMessage = lambda argument must be array
but is 'not_an_array'
+```error {example="15"}
+ERROR 1105 (HY000): errCode = 2, detailMessage = [INVALID_ARGUMENT]in array
map function, the input column size are not equal completely, nested column
data rows 1st size is 3, 2th size is 2.
```
+**Example 16** —— 第一个参数必须是数组类型。
-**嵌套高阶函数示例：**
+```sql {example="16"}
+SELECT array_filter(x -> x > 0, 'not_an_array');
+```
-**正确示例：在 lambda 中调用返回标量的高阶函数**
+```error {example="16"}
+ERROR 1105 (HY000): errCode = 2, detailMessage = lambda argument must be array
but is 'not_an_array'
+```
-当前例子可以嵌套使用，因为内层的 array_count 返回标量值（INT64），array_filter 可以处理。
-```sql
+**Example 17** —— 高阶函数嵌套：内层 `array_count` 返回标量，外层 `array_filter` 的 lambda 可以使用。
+
+```sql {example="17"}
SELECT array_filter(x -> array_count(y -> y > 5, x) > 0,
[[1,2,3],[4,5,6],[7,8,9]]);
+```
+
+```result {example="17"}
+------------------------------------------------------------------------------+
| array_filter(x -> array_count(y -> y > 5, x) > 0, [[1,2,3],[4,5,6],[7,8,9]])
|
+------------------------------------------------------------------------------+
@@ -244,11 +305,13 @@ SELECT array_filter(x -> array_count(y -> y > 5, x) > 0,
[[1,2,3],[4,5,6],[7,8,9
+------------------------------------------------------------------------------+
```
-**错误示例：lambda 返回数组类型**
+**Example 18** —— 反例：外层 `array_filter` 的 lambda 不能返回数组类型（这里 `array_exists` 返回
ARRAY<BOOLEAN> 而非标量）。
-当前例子不能嵌套使用，因为内层的 array_exists 返回 ARRAY<BOOLEAN>，而外层的 array_filter 期望 lambda
返回标量值
-```sql
+```sql {example="18"}
SELECT array_filter(x -> array_exists(y -> y > 5, x), [[1,2,3],[4,5,6]]);
+```
+
+```error {example="18"}
ERROR 1105 (HY000): errCode = 2, detailMessage = Can not find the
compatibility function signature: array_filter(ARRAY<ARRAY<TINYINT>>,
ARRAY<ARRAY<BOOLEAN>>)
```
diff --git
a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions/array-filter.md
b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions/array-filter.md
index 6aa1997e7e1..a19567ca8e5 100644
---
a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions/array-filter.md
+++
b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions/array-filter.md
@@ -57,7 +57,9 @@ Usage notes:
### Examples
-```sql
+**Setup** — create a fixture table and load 4 rows covering normal, edge-case,
empty, and NULL scenarios. All later examples reference this fixture.
+
+```sql {setup}
CREATE TABLE array_filter_test (
id INT,
int_array ARRAY<INT>,
@@ -77,11 +79,13 @@ INSERT INTO array_filter_test VALUES
(4, NULL, NULL, NULL);
```
-**Query examples:**
+**Example 1** — Lambda over a DOUBLE array column: keep elements `>= 3`.
-Using lambda expression to filter elements in double_array greater than or
equal to 3:
-```sql
+```sql {example="1"}
SELECT array_filter(x -> x >= 3, double_array) FROM array_filter_test WHERE id
= 1;
+```
+
+```result {example="1"}
+------------------------------------------+
| array_filter(x -> x >= 3, double_array) |
+------------------------------------------+
@@ -89,9 +93,13 @@ SELECT array_filter(x -> x >= 3, double_array) FROM
array_filter_test WHERE id =
+------------------------------------------+
```
-Using lambda expression to filter elements in string_array with length greater
than 2:
-```sql
+**Example 2** — Lambda over a STRING array column: keep elements with `length
> 2`.
+
+```sql {example="2"}
SELECT array_filter(x -> length(x) > 2, string_array) FROM array_filter_test
WHERE id = 1;
+```
+
+```result {example="2"}
+--------------------------------------------------+
| array_filter(x -> length(x) > 2, string_array) |
+--------------------------------------------------+
@@ -99,9 +107,13 @@ SELECT array_filter(x -> length(x) > 2, string_array) FROM
array_filter_test WHE
+--------------------------------------------------+
```
-Using boolean array to filter elements:
-```sql
+**Example 3** — Boolean-mask form: keep positions where the mask is `true`.
+
+```sql {example="3"}
SELECT array_filter(int_array, [false, true, false, true, true]) FROM
array_filter_test WHERE id = 1;
+```
+
+```result {example="3"}
+-----------------------------------------------------------+
| array_filter(int_array, [false, true, false, true, true]) |
+-----------------------------------------------------------+
@@ -109,10 +121,13 @@ SELECT array_filter(int_array, [false, true, false, true,
true]) FROM array_filt
+-----------------------------------------------------------+
```
-Boolean array filtering example, deciding whether to keep elements at
corresponding positions based on boolean values:
+**Example 4** — Boolean-mask form with literal arrays.
-```sql
+```sql {example="4"}
SELECT array_filter([1,2,3], [true, false, true]);
+```
+
+```result {example="4"}
+--------------------------------------------+
| array_filter([1,2,3], [true, false, true]) |
+--------------------------------------------+
@@ -120,9 +135,13 @@ SELECT array_filter([1,2,3], [true, false, true]);
+--------------------------------------------+
```
-When the boolean array length is greater than the original array, excess
boolean values will be ignored:
-```sql
+**Example 5** — Boolean array longer than the value array: extra mask entries
are ignored.
+
+```sql {example="5"}
SELECT array_filter([1,2,3], [true, false, true, false]);
+```
+
+```result {example="5"}
+---------------------------------------------------+
| array_filter([1,2,3], [true, false, true, false]) |
+---------------------------------------------------+
@@ -130,9 +149,13 @@ SELECT array_filter([1,2,3], [true, false, true, false]);
+---------------------------------------------------+
```
-When the boolean array length is less than the original array, only elements
at corresponding positions in the boolean array will be processed:
-```sql
+**Example 6** — Boolean array shorter than the value array: only positions
covered by the mask are processed.
+
+```sql {example="6"}
SELECT array_filter([1,2,3], [true, false]);
+```
+
+```result {example="6"}
+--------------------------------------+
| array_filter([1,2,3], [true, false]) |
+--------------------------------------+
@@ -140,9 +163,13 @@ SELECT array_filter([1,2,3], [true, false]);
+--------------------------------------+
```
-Empty array returns empty array:
-```sql
+**Example 7** — Empty input array returns an empty array (row `id = 3`).
+
+```sql {example="7"}
SELECT array_filter(x -> x > 0, int_array) FROM array_filter_test WHERE id = 3;
+```
+
+```result {example="7"}
+-------------------------------------+
| array_filter(x -> x > 0, int_array) |
+-------------------------------------+
@@ -150,9 +177,13 @@ SELECT array_filter(x -> x > 0, int_array) FROM
array_filter_test WHERE id = 3;
+-------------------------------------+
```
-NULL array returns NULL: returning NULL when the input array is NULL without
throwing an error.
-```sql
+**Example 8** — NULL input array returns NULL (row `id = 4`).
+
+```sql {example="8"}
SELECT array_filter(x -> x > 0, int_array) FROM array_filter_test WHERE id = 4;
+```
+
+```result {example="8"}
+-------------------------------------+
| array_filter(x -> x > 0, int_array) |
+-------------------------------------+
@@ -160,8 +191,13 @@ SELECT array_filter(x -> x > 0, int_array) FROM
array_filter_test WHERE id = 4;
+-------------------------------------+
```
-Array containing null values, lambda can evaluate null:
-```sql
+**Example 9** — Array containing NULL elements: lambda can test for `IS NOT
NULL` to drop them.
+
+```sql {example="9"}
+SELECT array_filter(x -> x is not null, [null, 1, null, 2, null]);
+```
+
+```result {example="9"}
+------------------------------------------------------------+
| array_filter(x -> x is not null, [null, 1, null, 2, null]) |
+------------------------------------------------------------+
@@ -169,9 +205,13 @@ Array containing null values, lambda can evaluate null:
+------------------------------------------------------------+
```
-Multiple array filtering, filtering elements where int_array > double_array:
-```sql
+**Example 10** — Multi-argument lambda over two arrays from the fixture.
+
+```sql {example="10"}
SELECT array_filter((x, y) -> x > y, int_array, double_array) FROM
array_filter_test WHERE id = 1;
+```
+
+```result {example="10"}
+--------------------------------------------------------+
| array_filter((x, y) -> x > y, int_array, double_array) |
+--------------------------------------------------------+
@@ -179,11 +219,13 @@ SELECT array_filter((x, y) -> x > y, int_array,
double_array) FROM array_filter_
+--------------------------------------------------------+
```
-Complex type examples:
+**Example 11** — Filter over a nested array literal: keep sub-arrays with
`size > 2`.
-Nested array filtering, filtering elements where each sub-array length is
greater than 2:
-```sql
+```sql {example="11"}
SELECT array_filter(x -> size(x) > 2, [[1,2], [3,4,5], [6], [7,8,9,10]]);
+```
+
+```result {example="11"}
+-------------------------------------------------------------------+
| array_filter(x -> size(x) > 2, [[1,2], [3,4,5], [6], [7,8,9,10]]) |
+-------------------------------------------------------------------+
@@ -191,9 +233,13 @@ SELECT array_filter(x -> size(x) > 2, [[1,2], [3,4,5],
[6], [7,8,9,10]]);
+-------------------------------------------------------------------+
```
-Map type filtering, filtering elements where the value of key 'a' is greater
than 10:
-```sql
+**Example 12** — Filter over an array of MAPs: keep elements where `x['a'] >
10`.
+
+```sql {example="12"}
SELECT array_filter(x -> x['a'] > 10, [{'a':5}, {'a':15}, {'a':20}]);
+```
+
+```result {example="12"}
+---------------------------------------------------------------+
| array_filter(x -> x['a'] > 10, [{'a':5}, {'a':15}, {'a':20}]) |
+---------------------------------------------------------------+
@@ -201,9 +247,13 @@ SELECT array_filter(x -> x['a'] > 10, [{'a':5}, {'a':15},
{'a':20}]);
+---------------------------------------------------------------+
```
-Struct type filtering, filtering elements where age is greater than 18:
-```sql
+**Example 13** — Filter over an array of STRUCTs by a field value.
+
+```sql {example="13"}
SELECT array_filter(x -> struct_element(x, 'age') > 18,
array(named_struct('name','Alice','age',20),named_struct('name','Bob','age',16),named_struct('name','Eve','age',30)));
+```
+
+```result {example="13"}
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| array_filter(x -> struct_element(x, 'age') > 18,
array(named_struct('name','Alice','age',20),named_struct('name','Bob','age',16),named_struct('name','Eve','age',30)))
|
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -211,32 +261,43 @@ SELECT array_filter(x -> struct_element(x, 'age') > 18,
array(named_struct('name
+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
```
-Incorrect number of parameters:
-```sql
+**Example 14** — Lambda parameter count must match the number of arrays passed
in.
+
+```sql {example="14"}
SELECT array_filter(x -> x > 0, [1,2,3], [4,5,6], [7,8,9]);
+```
+
+```error {example="14"}
ERROR 1105 (HY000): errCode = 2, detailMessage = lambda x -> (x > 0)
arguments' size is not equal parameters' size
```
-Inconsistent array lengths will cause an error:
-```sql
+**Example 15** — Multi-array form requires equal length across all input
arrays.
+
+```sql {example="15"}
SELECT array_filter((x, y) -> x > y, [1,2,3], [4,5]);
-ERROR 1105 (HY000): errCode = 2, detailMessage =
(10.16.10.6)[INVALID_ARGUMENT]in array map function, the input column size are
not equal completely, nested column data rows 1st size is 3, 2th size is 2.
```
-Passing non-array type will cause an error:
-```sql
-SELECT array_filter(x -> x > 0, 'not_an_array');
-ERROR 1105 (HY000): errCode = 2, detailMessage = lambda argument must be array
but is 'not_an_array'
+```error {example="15"}
+ERROR 1105 (HY000): errCode = 2, detailMessage = [INVALID_ARGUMENT]in array
map function, the input column size are not equal completely, nested column
data rows 1st size is 3, 2th size is 2.
```
+**Example 16** — The first argument must be an array.
-**Nested higher-order function examples:**
+```sql {example="16"}
+SELECT array_filter(x -> x > 0, 'not_an_array');
+```
-**Correct example: calling higher-order functions that return scalars in
lambda**
+```error {example="16"}
+ERROR 1105 (HY000): errCode = 2, detailMessage = lambda argument must be array
but is 'not_an_array'
+```
-The current example can be nested because the inner array_count returns a
scalar value (INT64), which array_filter can handle.
-```sql
+**Example 17** — Nested higher-order function: inner `array_count` returns a
scalar that the outer `array_filter` lambda can use.
+
+```sql {example="17"}
SELECT array_filter(x -> array_count(y -> y > 5, x) > 0,
[[1,2,3],[4,5,6],[7,8,9]]);
+```
+
+```result {example="17"}
+------------------------------------------------------------------------------+
| array_filter(x -> array_count(y -> y > 5, x) > 0, [[1,2,3],[4,5,6],[7,8,9]])
|
+------------------------------------------------------------------------------+
@@ -244,11 +305,13 @@ SELECT array_filter(x -> array_count(y -> y > 5, x) > 0,
[[1,2,3],[4,5,6],[7,8,9
+------------------------------------------------------------------------------+
```
-**Error example: lambda returns array type**
+**Example 18** — Counter-example: the outer `array_filter` lambda cannot
return an array (`array_exists` returns ARRAY<BOOLEAN> here, not a scalar).
-The current example cannot be nested because the inner array_exists returns
ARRAY<BOOLEAN>, while the outer array_filter expects lambda to return a scalar
value
-```sql
+```sql {example="18"}
SELECT array_filter(x -> array_exists(y -> y > 5, x), [[1,2,3],[4,5,6]]);
+```
+
+```error {example="18"}
ERROR 1105 (HY000): errCode = 2, detailMessage = Can not find the
compatibility function signature: array_filter(ARRAY<ARRAY<TINYINT>>,
ARRAY<ARRAY<BOOLEAN>>)
```
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
