diff --git a/docs/cn/sql-reference/20-sql-functions/07-aggregate-functions/aggregate-json-array-agg.md b/docs/cn/sql-reference/20-sql-functions/07-aggregate-functions/aggregate-json-array-agg.md index b14ebd9815..6e27e3fe86 100644 --- a/docs/cn/sql-reference/20-sql-functions/07-aggregate-functions/aggregate-json-array-agg.md +++ b/docs/cn/sql-reference/20-sql-functions/07-aggregate-functions/aggregate-json-array-agg.md @@ -1,5 +1,6 @@ --- -title: JSON_ARRAY_AGG +title: JSON_ARRAY_AGG +title_includes: JSON_AGG --- import FunctionDescription from '@site/src/components/FunctionDescription'; @@ -53,4 +54,4 @@ aggregated_b: ["abc","de","xyz"] aggregated_c: [100,200,300] aggregated_d: [{"k":"v"},null,"uvw",[1,2,3]] aggregated_e: [["a","b"],[],["x","y"],["z"]] -``` \ No newline at end of file +``` diff --git a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/get-by-keypath.md b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/get-by-keypath.md new file mode 100644 index 0000000000..5d4a0ae404 --- /dev/null +++ b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/get-by-keypath.md @@ -0,0 +1,72 @@ +--- +title: GET_BY_KEYPATH +--- + +使用“键路径”(key path) 字符串从 `VARIANT` 中提取嵌套值： + +- `GET_BY_KEYPATH` 返回 `VARIANT`。 +- `GET_BY_KEYPATH_STRING` 返回 `STRING`。 + +键路径采用 Postgres 风格的 `{segment}` 语法，多个段之间用逗号分隔，例如 `'{user,profile,name}'`，数组索引用数字表示，如 `'{items,0}'`。 + +## 语法 + +```sql +GET_BY_KEYPATH(, ) +GET_BY_KEYPATH_STRING(, ) +``` + +## 返回类型 + +- `GET_BY_KEYPATH`：`VARIANT` +- `GET_BY_KEYPATH_STRING`：`STRING` + +## 示例 + +```sql +SELECT GET_BY_KEYPATH(PARSE_JSON('{"user":{"name":"Ada","tags":["a","b"]}}'), '{user,name}') AS profile_name; +``` + +``` ++--------------+ +| profile_name | ++--------------+ +| "Ada" | ++--------------+ +``` + +```sql +SELECT GET_BY_KEYPATH(PARSE_JSON('[10,{"a":{"k1":[1,2,3]}}]'), '{1,a,k1}') AS inner_array; +``` + +``` ++-------------+ +| inner_array | ++-------------+ +| [1,2,3] | ++-------------+ +``` + +```sql +SELECT GET_BY_KEYPATH_STRING(PARSE_JSON('{"user":{"name":"Ada"}}'), '{user,name}') AS name_text; +``` + +``` ++-----------+ +| name_text | ++-----------+ +| Ada | ++-----------+ +``` + +```sql +SELECT GET_BY_KEYPATH_STRING(PARSE_JSON('[10,{"a":{"scores":[100,98]}}]'), '{1,a,scores,0}') AS first_score; +``` + +``` ++-------------+ +| first_score | ++-------------+ +| 100 | ++-------------+ +``` diff --git a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/get.md b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/get.md index 8159991f82..98fabfef61 100644 --- a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/get.md +++ b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/get.md @@ -1,5 +1,6 @@ --- title: GET +title_includes: GET_STRING --- 通过 `index` 从包含 `ARRAY` 的 `Variant` 中提取值，或通过 `field_name` 从包含 `OBJECT` 的 `Variant` 中提取值。 @@ -50,4 +51,4 @@ SELECT get(parse_json('{"aa":1, "aA":2, "Aa":3}'), 'AA'); +---------------------------------------------------+ | NULL | +---------------------------------------------------+ -``` \ No newline at end of file +``` diff --git a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/index.md b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/index.md index 1c8d7f53ce..439f8005b2 100644 --- a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/index.md +++ b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/index.md @@ -39,6 +39,7 @@ title: JSON 函数 |----------|-------------|---------| | [GET](get) | 按索引或字段名从 JSON 提取值 | `GET('{"name":"John"}', 'name')` → `"John"` | | [GET_IGNORE_CASE](get-ignore-case) | 以不区分大小写的方式按字段名提取值 | `GET_IGNORE_CASE('{"Name":"John"}', 'name')` → `"John"` | +| [GET_BY_KEYPATH](get-by-keypath) | 使用 `{segment}` 键路径提取嵌套值 | `GET_BY_KEYPATH('{"user":{"name":"Ada"}}', '{user,name}')` → `"Ada"` | | [GET_PATH](get-path) | 使用路径表示法提取值 | `GET_PATH('{"user":{"name":"John"}}', 'user.name')` → `"John"` | | [JSON_EXTRACT_PATH_TEXT](json-extract-path-text) | 使用路径从 JSON 提取文本值 | `JSON_EXTRACT_PATH_TEXT('{"name":"John"}', 'name')` → `'John'` | | [JSON_EACH](json-each) | 将 JSON 对象展开为键值对 | `JSON_EACH('{"a":1,"b":2}')` → `[("a",1),("b",2)]` | @@ -50,4 +51,13 @@ title: JSON 函数 |----------|-------------|---------| | [JSON_PRETTY](json-pretty) | 以适当缩进格式化 JSON | `JSON_PRETTY('{"a":1}')` → 格式化后的 JSON 字符串 | | [STRIP_NULL_VALUE](strip-null-value) | 从 JSON 中移除 null 值 | `STRIP_NULL_VALUE('{"a":1,"b":null}')` → `{"a":1}` | -| [JQ](jq) | 使用 jq 风格查询处理 JSON | `JQ('{"name":"John"}', '.name')` → `"John"` | \ No newline at end of file +| [JQ](jq) | 使用 jq 风格查询处理 JSON | `JQ('{"name":"John"}', '.name')` → `"John"` | + +## JSON 包含与键检测 + +| 函数 | 描述 | 示例 | +|----------|-------------|---------| +| [JSON_CONTAINS_IN_LEFT](json-contains) | 判断左侧 JSON 是否包含右侧 JSON | `JSON_CONTAINS_IN_LEFT('{"a":1,"b":2}', '{"b":2}')` → `true` | +| [JSON_EXISTS_KEY](json-exists-keys) | 检查单个键是否存在 | `JSON_EXISTS_KEY('{"a":1}', 'a')` → `true` | +| [JSON_EXISTS_ANY_KEYS](json-exists-keys) | 只要键列表中任意一个存在即返回 `true` | `JSON_EXISTS_ANY_KEYS('{"a":1}', ['x','a'])` → `true` | +| [JSON_EXISTS_ALL_KEYS](json-exists-keys) | 仅当所有键都存在时返回 `true` | `JSON_EXISTS_ALL_KEYS('{"a":1,"b":2}', ['a','b'])` → `true` | diff --git a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/json-contains.md b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/json-contains.md new file mode 100644 index 0000000000..5b83b7f2ee --- /dev/null +++ b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/json-contains.md @@ -0,0 +1,72 @@ +--- +title: JSON_CONTAINS_IN_LEFT +--- + +判断两个 JSON 值的包含关系： + +- `JSON_CONTAINS_IN_LEFT(left, right)`：当 `left` 包含 `right`（即 `left` 是 `right` 的超集）时返回 `TRUE`。 +- `JSON_CONTAINS_IN_RIGHT(left, right)`：当 `right` 包含 `left` 时返回 `TRUE`。 + +适用于对象和数组。 + +## 语法 + +```sql +JSON_CONTAINS_IN_LEFT(, ) +JSON_CONTAINS_IN_RIGHT(, ) +``` + +## 返回类型 + +`BOOLEAN` + +## 示例 + +```sql +SELECT JSON_CONTAINS_IN_LEFT(PARSE_JSON('{"a":1,"b":{"c":2}}'), + PARSE_JSON('{"b":{"c":2}}')) AS left_contains; +``` + +``` ++--------------+ +| left_contains| ++--------------+ +| true | ++--------------+ +``` + +```sql +SELECT JSON_CONTAINS_IN_LEFT(PARSE_JSON('[1,2,3]'), PARSE_JSON('[2,3]')) AS left_contains; +``` + +``` ++--------------+ +| left_contains| ++--------------+ +| true | ++--------------+ +``` + +```sql +SELECT JSON_CONTAINS_IN_LEFT(PARSE_JSON('[1,2]'), PARSE_JSON('[2,4]')) AS left_contains; +``` + +``` ++--------------+ +| left_contains| ++--------------+ +| false | ++--------------+ +``` + +```sql +SELECT JSON_CONTAINS_IN_RIGHT(PARSE_JSON('{"a":1}'), PARSE_JSON('{"a":1,"b":2}')) AS right_contains; +``` + +``` ++---------------+ +| right_contains| ++---------------+ +| true | ++---------------+ +``` diff --git a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/json-exists-keys.md b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/json-exists-keys.md new file mode 100644 index 0000000000..0d7f842173 --- /dev/null +++ b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/json-exists-keys.md @@ -0,0 +1,71 @@ +--- +title: JSON_EXISTS_KEY +--- + +检测 JSON 对象中是否存在指定键： + +- `JSON_EXISTS_KEY`：检查单个键。 +- `JSON_EXISTS_ANY_KEYS`：传入键数组，只要其中任意一个存在即返回 `TRUE`。 +- `JSON_EXISTS_ALL_KEYS`：仅当数组中的每个键都存在时返回 `TRUE`。 + +## 语法 + +```sql +JSON_EXISTS_KEY(, ) +JSON_EXISTS_ANY_KEYS(, ) +JSON_EXISTS_ALL_KEYS(, ) +``` + +## 返回类型 + +`BOOLEAN` + +## 示例 + +```sql +SELECT JSON_EXISTS_KEY(PARSE_JSON('{"a":1,"b":2}'), 'b') AS has_b; +``` + +``` ++-------+ +| has_b | ++-------+ +| true | ++-------+ +``` + +```sql +SELECT JSON_EXISTS_ANY_KEYS(PARSE_JSON('{"a":1,"b":2}'), ['x','b']) AS any_key; +``` + +``` ++---------+ +| any_key | ++---------+ +| true | ++---------+ +``` + +```sql +SELECT JSON_EXISTS_ALL_KEYS(PARSE_JSON('{"a":1,"b":2}'), ['a','b','c']) AS all_keys; +``` + +``` ++---------+ +| all_keys| ++---------+ +| false | ++---------+ +``` + +```sql +SELECT JSON_EXISTS_ALL_KEYS(PARSE_JSON('{"a":1,"b":2}'), ['a','b']) AS all_keys; +``` + +``` ++---------+ +| all_keys| ++---------+ +| true | ++---------+ +``` diff --git a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/strip-null-value.md b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/strip-null-value.md index a5e66a78dc..07bd5bc1c8 100644 --- a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/strip-null-value.md +++ b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/strip-null-value.md @@ -1,5 +1,6 @@ --- title: STRIP_NULL_VALUE +title_includes: JSON_STRIP_NULLS --- import FunctionDescription from '@site/src/components/FunctionDescription'; @@ -25,4 +26,4 @@ SELECT STRIP_NULL_VALUE(PARSE_JSON('{"name": "Alice", "age": 30, "city": null}') strip_null_value(parse_json('{"name": "alice", "age": 30, "city": null}'))| --------------------------------------------------------------------------+ {"age":30,"name":"Alice"} | -``` \ No newline at end of file +``` diff --git a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-any.md b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-any.md new file mode 100644 index 0000000000..57ecb45889 --- /dev/null +++ b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-any.md @@ -0,0 +1,59 @@ +--- +title: ARRAY_ANY +--- + +返回数组中第一个非 NULL 的元素。等价于 `ARRAY_AGGREGATE(array, 'ANY')`。 + +## 语法 + +```sql +ARRAY_ANY() +``` + +## 返回类型 + +与数组元素类型相同。 + +## 示例 + +```sql +SELECT ARRAY_ANY(['a', 'b', 'c']) AS first_item; +``` + +结果： + +``` ++------------+ +| first_item | ++------------+ +| a | ++------------+ +``` + +```sql +SELECT ARRAY_ANY([NULL, 'x', 'y']) AS first_non_null; +``` + +结果： + +``` ++----------------+ +| first_non_null | ++----------------+ +| x | ++----------------+ +``` + +```sql +SELECT ARRAY_ANY([NULL, 10, 20]) AS first_number; +``` + +结果： + +``` ++--------------+ +| first_number | ++--------------+ +| 10 | ++--------------+ +``` diff --git a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-approx-count-distinct.md b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-approx-count-distinct.md new file mode 100644 index 0000000000..a8481fdfda --- /dev/null +++ b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-approx-count-distinct.md @@ -0,0 +1,41 @@ +--- +title: ARRAY_APPROX_COUNT_DISTINCT +--- + +返回数组中不同元素数量的近似值（忽略 NULL）。实现基于与 [`APPROX_COUNT_DISTINCT`](../../07-aggregate-functions/aggregate-approx-count-distinct.md) 相同的 HyperLogLog 算法。 + +## 语法 + +```sql +ARRAY_APPROX_COUNT_DISTINCT() +``` + +## 返回类型 + +`BIGINT` + +## 示例 + +```sql +SELECT ARRAY_APPROX_COUNT_DISTINCT([1, 1, 2, 3, 3, 3]) AS approx_cnt; +``` + +``` ++------------+ +| approx_cnt | ++------------+ +| 3 | ++------------+ +``` + +```sql +SELECT ARRAY_APPROX_COUNT_DISTINCT([NULL, 'a', 'a', 'b']) AS approx_cnt_text; +``` + +``` ++------------------+ +| approx_cnt_text | ++------------------+ +| 2 | ++------------------+ +``` diff --git a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-avg.md b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-avg.md new file mode 100644 index 0000000000..a328e94982 --- /dev/null +++ b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-avg.md @@ -0,0 +1,53 @@ +--- +title: ARRAY_AVG +--- + +计算数组中数值元素的平均值。NULL 元素会被忽略，若数组包含非数值类型将报错。 + +## 语法 + +```sql +ARRAY_AVG() +``` + +## 返回类型 + +数值类型（使用能够容纳结果的最小数值精度）。 + +## 示例 + +```sql +SELECT ARRAY_AVG([1, 2, 3, 4]) AS avg_int; +``` + +``` ++---------+ +| avg_int | ++---------+ +| 2.5 | ++---------+ +``` + +```sql +SELECT ARRAY_AVG([1.5, 2.5, 3.5]) AS avg_decimal; +``` + +``` ++-------------+ +| avg_decimal | ++-------------+ +| 2.5000 | ++-------------+ +``` + +```sql +SELECT ARRAY_AVG([10, NULL, 4]) AS avg_with_null; +``` + +``` ++---------------+ +| avg_with_null | ++---------------+ +| 7.0 | ++---------------+ +``` diff --git a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-construct.md b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-construct.md index 958da041e1..a5c88102f5 100644 --- a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-construct.md +++ b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-construct.md @@ -1,5 +1,6 @@ --- title: ARRAY_CONSTRUCT +title_includes: JSON_ARRAY --- import FunctionDescription from '@site/src/components/FunctionDescription'; @@ -60,4 +61,4 @@ array_construct(productname, price)| ["Apple",1.2] | ["Banana",0.5] | ["Orange",0.8] | -``` \ No newline at end of file +``` diff --git a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-count.md b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-count.md new file mode 100644 index 0000000000..d3f94be9f7 --- /dev/null +++ b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-count.md @@ -0,0 +1,53 @@ +--- +title: ARRAY_COUNT +--- + +统计数组中非 NULL 元素的个数。 + +## 语法 + +```sql +ARRAY_COUNT() +``` + +## 返回类型 + +`BIGINT` + +## 示例 + +```sql +SELECT ARRAY_COUNT([1, 2, 3]) AS cnt; +``` + +``` ++-----+ +| cnt | ++-----+ +| 3 | ++-----+ +``` + +```sql +SELECT ARRAY_COUNT([1, NULL, 3]) AS cnt_with_null; +``` + +``` ++----------------+ +| cnt_with_null | ++----------------+ +| 2 | ++----------------+ +``` + +```sql +SELECT ARRAY_COUNT(['a', 'b', NULL]) AS cnt_text; +``` + +``` ++----------+ +| cnt_text | ++----------+ +| 2 | ++----------+ +``` diff --git a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-distinct.md b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-distinct.md index 65a6658948..2f2d71f7af 100644 --- a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-distinct.md +++ b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-distinct.md @@ -1,5 +1,6 @@ --- title: ARRAY_DISTINCT +title_includes: JSON_ARRAY_DISTINCT --- import FunctionDescription from '@site/src/components/FunctionDescription'; @@ -28,4 +29,4 @@ SELECT ARRAY_DISTINCT('["apple", "banana", "apple", "orange", "banana"]'::VARIAN -[ RECORD 1 ]----------------------------------- array_distinct('["apple", "banana", "apple", "orange", "banana"]'::VARIANT): ["apple","banana","orange"] -``` \ No newline at end of file +``` diff --git a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-except.md b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-except.md index c94f27d536..281d8e56a8 100644 --- a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-except.md +++ b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-except.md @@ -1,5 +1,6 @@ --- title: ARRAY_EXCEPT +title_includes: JSON_ARRAY_EXCEPT --- import FunctionDescription from '@site/src/components/FunctionDescription'; @@ -37,4 +38,4 @@ SELECT ARRAY_EXCEPT('["apple", "banana", "orange"]'::VARIANT, '["apple", "banana -[ RECORD 1 ]----------------------------------- array_except('["apple", "banana", "orange"]'::VARIANT, '["apple", "banana", "orange"]'::VARIANT): [] -``` \ No newline at end of file +``` diff --git a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-generate-range.md b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-generate-range.md new file mode 100644 index 0000000000..1b859a6937 --- /dev/null +++ b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-generate-range.md @@ -0,0 +1,57 @@ +--- +title: ARRAY_GENERATE_RANGE +--- + +生成一个等差整数序列数组，终点为开区间。 + +## 语法 + +```sql +ARRAY_GENERATE_RANGE(, [, ]) +``` + +- ``：区间起点。 +- ``：终点（不包含）。 +- ``：步长，默认为 1，可为负数以生成降序序列。 + +## 返回类型 + +`ARRAY` + +## 示例 + +```sql +SELECT ARRAY_GENERATE_RANGE(1, 5) AS seq; +``` + +``` ++---------+ +| seq | ++---------+ +| [1,2,3,4] | ++---------+ +``` + +```sql +SELECT ARRAY_GENERATE_RANGE(0, 6, 2) AS seq_step; +``` + +``` ++-----------+ +| seq_step | ++-----------+ +| [0,2,4] | ++-----------+ +``` + +```sql +SELECT ARRAY_GENERATE_RANGE(5, 0, -2) AS seq_down; +``` + +``` ++-----------+ +| seq_down | ++-----------+ +| [5,3,1] | ++-----------+ +``` diff --git a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-insert.md b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-insert.md index 0b595f9bfb..dab94e3666 100644 --- a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-insert.md +++ b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-insert.md @@ -1,5 +1,6 @@ --- title: ARRAY_INSERT +title_includes: JSON_ARRAY_INSERT --- import FunctionDescription from '@site/src/components/FunctionDescription'; @@ -65,4 +66,4 @@ SELECT ARRAY_INSERT('["task1", "task2", "task3"]'::VARIANT, -6, '"new_task"'::VA -[ RECORD 1 ]----------------------------------- array_insert('["task1", "task2", "task3"]'::VARIANT, - 6, '"new_task"'::VARIANT): ["new_task","task1","task2","task3"] -``` \ No newline at end of file +``` diff --git a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-intersection.md b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-intersection.md index 1aab7b864b..1855435530 100644 --- a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-intersection.md +++ b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-intersection.md @@ -1,5 +1,6 @@ --- title: ARRAY_INTERSECTION +title_includes: JSON_ARRAY_INTERSECTION --- import FunctionDescription from '@site/src/components/FunctionDescription'; @@ -38,4 +39,4 @@ SELECT ARRAY_INTERSECTION( -[ RECORD 1 ]----------------------------------- array_intersection(array_intersection('["Electronics", "Books", "Toys"]'::VARIANT, '["Books", "Fashion", "Electronics"]'::VARIANT), '["Electronics", "Books", "Clothing"]'::VARIANT): ["Electronics","Books"] -``` \ No newline at end of file +``` diff --git a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-kurtosis.md b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-kurtosis.md new file mode 100644 index 0000000000..a34f6cc5b8 --- /dev/null +++ b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-kurtosis.md @@ -0,0 +1,41 @@ +--- +title: ARRAY_KURTOSIS +--- + +返回数组中数值的超峰度（excess kurtosis）。NULL 元素会被忽略，若存在非数值类型则报错。 + +## 语法 + +```sql +ARRAY_KURTOSIS() +``` + +## 返回类型 + +浮点型。 + +## 示例 + +```sql +SELECT ARRAY_KURTOSIS([1, 2, 3, 4]) AS kurt; +``` + +``` ++------------------+ +| kurt | ++------------------+ +| -1.200000000000001 | ++------------------+ +``` + +```sql +SELECT ARRAY_KURTOSIS([NULL, 2, 3, 4]) AS kurt_null; +``` + +``` ++-----------+ +| kurt_null | ++-----------+ +| 0 | ++-----------+ +``` diff --git a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-max.md b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-max.md new file mode 100644 index 0000000000..7f873771ea --- /dev/null +++ b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-max.md @@ -0,0 +1,41 @@ +--- +title: ARRAY_MAX +--- + +返回数组中的最大数值。NULL 会被忽略，若包含非数值类型则报错。 + +## 语法 + +```sql +ARRAY_MAX() +``` + +## 返回类型 + +与数组元素一致的数值类型。 + +## 示例 + +```sql +SELECT ARRAY_MAX([5, 2, 9, -1]) AS max_int; +``` + +``` ++---------+ +| max_int | ++---------+ +| 9 | ++---------+ +``` + +```sql +SELECT ARRAY_MAX([NULL, 10, 4]) AS max_with_null; +``` + +``` ++---------------+ +| max_with_null | ++---------------+ +| 10 | ++---------------+ +``` diff --git a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-median.md b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-median.md new file mode 100644 index 0000000000..a57c791982 --- /dev/null +++ b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-median.md @@ -0,0 +1,53 @@ +--- +title: ARRAY_MEDIAN +--- + +计算数组中数值的中位数。NULL 元素会被忽略；当数组长度为偶数时，返回两个中间值的平均数。 + +## 语法 + +```sql +ARRAY_MEDIAN() +``` + +## 返回类型 + +数值型。 + +## 示例 + +```sql +SELECT ARRAY_MEDIAN([1, 3, 2, 4]) AS med_even; +``` + +``` ++----------+ +| med_even | ++----------+ +| 2.5 | ++----------+ +``` + +```sql +SELECT ARRAY_MEDIAN([1, 3, 5]) AS med_odd; +``` + +``` ++--------+ +| med_odd| ++--------+ +| 3.0 | ++--------+ +``` + +```sql +SELECT ARRAY_MEDIAN([NULL, 10, 20, 30]) AS med_null; +``` + +``` ++---------+ +| med_null| ++---------+ +| 20.0 | ++---------+ +``` diff --git a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-min.md b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-min.md new file mode 100644 index 0000000000..78c46774c8 --- /dev/null +++ b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-min.md @@ -0,0 +1,41 @@ +--- +title: ARRAY_MIN +--- + +返回数组中的最小数值。NULL 会被忽略，若包含非数值类型则报错。 + +## 语法 + +```sql +ARRAY_MIN() +``` + +## 返回类型 + +与数组元素一致的数值类型。 + +## 示例 + +```sql +SELECT ARRAY_MIN([5, 2, 9, -1]) AS min_int; +``` + +``` ++---------+ +| min_int | ++---------+ +| -1 | ++---------+ +``` + +```sql +SELECT ARRAY_MIN([NULL, 10, 4]) AS min_with_null; +``` + +``` ++---------------+ +| min_with_null | ++---------------+ +| 4 | ++---------------+ +``` diff --git a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-overlap.md b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-overlap.md index f18cb49b9b..10544bcde2 100644 --- a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-overlap.md +++ b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-overlap.md @@ -1,5 +1,6 @@ --- title: ARRAY_OVERLAP +title_includes: JSON_ARRAY_OVERLAP --- import FunctionDescription from '@site/src/components/FunctionDescription'; @@ -44,4 +45,4 @@ SELECT ARRAY_OVERLAP( -[ RECORD 1 ]----------------------------------- array_overlap('["grape", "orange"]'::VARIANT, '["apple", "kiwi"]'::VARIANT): false -``` \ No newline at end of file +``` diff --git a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-size.md b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-size.md new file mode 100644 index 0000000000..9ff5d75b2b --- /dev/null +++ b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-size.md @@ -0,0 +1,41 @@ +--- +title: ARRAY_SIZE +--- + +返回数组长度，包含 NULL 元素。别名：`ARRAY_LENGTH`。 + +## 语法 + +```sql +ARRAY_SIZE() +``` + +## 返回类型 + +`BIGINT` + +## 示例 + +```sql +SELECT ARRAY_SIZE([1, 2, 3]) AS size_plain; +``` + +``` ++-------------+ +| size_plain | ++-------------+ +| 3 | ++-------------+ +``` + +```sql +SELECT ARRAY_SIZE([1, NULL, 3]) AS size_with_null; +``` + +``` ++---------------+ +| size_with_null| ++---------------+ +| 3 | ++---------------+ +``` diff --git a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-skewness.md b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-skewness.md new file mode 100644 index 0000000000..b3a8cb860f --- /dev/null +++ b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-skewness.md @@ -0,0 +1,41 @@ +--- +title: ARRAY_SKEWNESS +--- + +返回数组中数值的偏度。NULL 元素会被忽略，若存在非数值类型则报错。 + +## 语法 + +```sql +ARRAY_SKEWNESS() +``` + +## 返回类型 + +浮点型。 + +## 示例 + +```sql +SELECT ARRAY_SKEWNESS([1, 2, 3, 4]) AS skew; +``` + +``` ++------+ +| skew | ++------+ +| 0 | ++------+ +``` + +```sql +SELECT ARRAY_SKEWNESS([NULL, 2, 3, 10]) AS skew_null; +``` + +``` ++-----------+ +| skew_null | ++-----------+ +| 1.63005916| ++-----------+ +``` diff --git a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-sort.md b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-sort.md new file mode 100644 index 0000000000..4a43f824f0 --- /dev/null +++ b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-sort.md @@ -0,0 +1,86 @@ +--- +title: ARRAY_SORT +--- + +对数组进行排序。默认情况下结果按升序排列，NULL 位于末尾。可使用下列变体控制顺序和 NULL 位置： + +- `ARRAY_SORT_ASC_NULL_FIRST` +- `ARRAY_SORT_ASC_NULL_LAST` +- `ARRAY_SORT_DESC_NULL_FIRST` +- `ARRAY_SORT_DESC_NULL_LAST` + +## 语法 + +```sql +ARRAY_SORT() +ARRAY_SORT_ASC_NULL_FIRST() +ARRAY_SORT_ASC_NULL_LAST() +ARRAY_SORT_DESC_NULL_FIRST() +ARRAY_SORT_DESC_NULL_LAST() +``` + +## 返回类型 + +`ARRAY` + +## 示例 + +```sql +SELECT ARRAY_SORT([3, 1, 2]) AS sort_default; +``` + +``` ++--------------+ +| sort_default | ++--------------+ +| [1,2,3] | ++--------------+ +``` + +```sql +SELECT ARRAY_SORT([NULL, 2, 1]) AS sort_with_nulls; +``` + +``` ++----------------+ +| sort_with_nulls| ++----------------+ +| [1,2,NULL] | ++----------------+ +``` + +```sql +SELECT ARRAY_SORT_ASC_NULL_FIRST([NULL, 2, 1]) AS asc_null_first; +``` + +``` ++----------------+ +| asc_null_first | ++----------------+ +| [NULL,1,2] | ++----------------+ +``` + +```sql +SELECT ARRAY_SORT_DESC_NULL_LAST([NULL, 2, 1]) AS desc_null_last; +``` + +``` ++----------------+ +| desc_null_last | ++----------------+ +| [2,1,NULL] | ++----------------+ +``` + +```sql +SELECT ARRAY_SORT_DESC_NULL_FIRST([NULL, 2, 1]) AS desc_null_first; +``` + +``` ++-----------------+ +| desc_null_first | ++-----------------+ +| [NULL,2,1] | ++-----------------+ +``` diff --git a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-stddev-pop.md b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-stddev-pop.md new file mode 100644 index 0000000000..025e3987f4 --- /dev/null +++ b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-stddev-pop.md @@ -0,0 +1,41 @@ +--- +title: ARRAY_STDDEV_POP +--- + +计算数组中数值的总体标准差。NULL 元素会被忽略。别名：`ARRAY_STD`。 + +## 语法 + +```sql +ARRAY_STDDEV_POP() +``` + +## 返回类型 + +浮点型。 + +## 示例 + +```sql +SELECT ARRAY_STDDEV_POP([2, 4, 4, 4, 5, 5, 7, 9]) AS stddev_pop; +``` + +``` ++------------+ +| stddev_pop | ++------------+ +| 2 | ++------------+ +``` + +```sql +SELECT ARRAY_STDDEV_POP([1.5, 2.5, NULL, 3.5]) AS stddev_pop_null; +``` + +``` ++------------------+ +| stddev_pop_null | ++------------------+ +| 0.816496580927726| ++------------------+ +``` diff --git a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-stddev-samp.md b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-stddev-samp.md new file mode 100644 index 0000000000..5bd9d09a05 --- /dev/null +++ b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-stddev-samp.md @@ -0,0 +1,41 @@ +--- +title: ARRAY_STDDEV_SAMP +--- + +计算数组中数值的样本标准差。NULL 元素会被忽略。别名：`ARRAY_STDDEV`。 + +## 语法 + +```sql +ARRAY_STDDEV_SAMP() +``` + +## 返回类型 + +浮点型。 + +## 示例 + +```sql +SELECT ARRAY_STDDEV_SAMP([2, 4, 4, 4, 5, 5, 7, 9]) AS stddev_samp; +``` + +``` ++-------------+ +| stddev_samp | ++-------------+ +| 2.1380899353| ++-------------+ +``` + +```sql +SELECT ARRAY_STDDEV_SAMP([1.5, 2.5, NULL, 3.5]) AS stddev_samp_null; +``` + +``` ++------------------+ +| stddev_samp_null | ++------------------+ +| 1 | ++------------------+ +``` diff --git a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-sum.md b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-sum.md new file mode 100644 index 0000000000..0d5f6e26f2 --- /dev/null +++ b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-sum.md @@ -0,0 +1,53 @@ +--- +title: ARRAY_SUM +--- + +求数组中数值元素的总和。NULL 项会被忽略，若存在非数值类型则报错。 + +## 语法 + +```sql +ARRAY_SUM() +``` + +## 返回类型 + +与数组中最高精度的数值类型一致。 + +## 示例 + +```sql +SELECT ARRAY_SUM([1, 2, 3, 4]) AS total; +``` + +``` ++-------+ +| total | ++-------+ +| 10 | ++-------+ +``` + +```sql +SELECT ARRAY_SUM([1.5, 2.25, 3.0]) AS total; +``` + +``` ++-------+ +| total | ++-------+ +| 6.75 | ++-------+ +``` + +```sql +SELECT ARRAY_SUM([10, NULL, -3]) AS total; +``` + +``` ++-------+ +| total | ++-------+ +| 7 | ++-------+ +``` diff --git a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-to-string.md b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-to-string.md new file mode 100644 index 0000000000..8b576c258c --- /dev/null +++ b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-to-string.md @@ -0,0 +1,41 @@ +--- +title: ARRAY_TO_STRING +--- + +将字符串数组按照给定分隔符拼接成单个字符串，NULL 元素会被跳过。 + +## 语法 + +```sql +ARRAY_TO_STRING(, ) +``` + +## 返回类型 + +`STRING` + +## 示例 + +```sql +SELECT ARRAY_TO_STRING(['a', 'b', 'c'], ',') AS joined; +``` + +``` ++--------+ +| joined | ++--------+ +| a,b,c | ++--------+ +``` + +```sql +SELECT ARRAY_TO_STRING([NULL, 'x', 'y'], '-') AS joined_no_nulls; +``` + +``` ++------------------+ +| joined_no_nulls | ++------------------+ +| x-y | ++------------------+ +``` diff --git a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array.md b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array.md new file mode 100644 index 0000000000..d393977d59 --- /dev/null +++ b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array.md @@ -0,0 +1,53 @@ +--- +title: ARRAY +--- + +根据给定表达式按顺序构造数组。所有参数必须可以转换为同一数据类型。 + +## 语法 + +```sql +ARRAY(, , ...) +``` + +## 返回类型 + +`ARRAY` + +## 示例 + +```sql +SELECT ARRAY(1, 2, 3) AS arr_int; +``` + +``` ++---------+ +| arr_int | ++---------+ +| [1,2,3] | ++---------+ +``` + +```sql +SELECT ARRAY('alpha', UPPER('beta')) AS arr_text; +``` + +``` ++----------+ +| arr_text | ++----------+ +| ["alpha","BETA"] | ++----------+ +``` + +```sql +SELECT ARRAY(1, NULL, 3) AS arr_with_null; +``` + +``` ++--------------+ +| arr_with_null| ++--------------+ +| [1,NULL,3] | ++--------------+ +``` diff --git a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/index.md b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/index.md index 442e395b06..76ef22fc46 100644 --- a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/index.md +++ b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/index.md @@ -8,8 +8,10 @@ title: 数组函数 | 函数 | 描述 | 示例 | |----------|-------------|---------| +| [ARRAY](array) | 直接根据表达式构造数组 | `ARRAY(1, 2, 3)` → `[1,2,3]` | | [ARRAY_CONSTRUCT](array-construct) | 根据单个值创建数组 | `ARRAY_CONSTRUCT(1, 2, 3)` → `[1,2,3]` | | [RANGE](range) | 生成连续数字序列数组 | `RANGE(1, 5)` → `[1,2,3,4]` | +| [ARRAY_GENERATE_RANGE](array-generate-range) | 带步长地生成整数序列 | `ARRAY_GENERATE_RANGE(0, 6, 2)` → `[0,2,4]` | ## 数组访问与信息 @@ -19,6 +21,9 @@ title: 数组函数 | [ARRAY_GET](array-get) | GET 函数的别名 | `ARRAY_GET([1,2,3], 1)` → `1` | | [CONTAINS](contains) | 检查数组是否包含特定值 | `CONTAINS([1,2,3], 2)` → `true` | | [ARRAY_CONTAINS](array-contains) | 检查数组是否包含特定值 | `ARRAY_CONTAINS([1,2,3], 2)` → `true` | +| [ARRAY_SIZE](array-size) | 返回数组长度（别名：`ARRAY_LENGTH`） | `ARRAY_SIZE([1,2,3])` → `3` | +| [ARRAY_COUNT](array-count) | 统计非 NULL 元素个数 | `ARRAY_COUNT([1,NULL,2])` → `2` | +| [ARRAY_ANY](array-any) | 返回首个非 NULL 元素 | `ARRAY_ANY([NULL,'a','b'])` → `'a'` | ## 数组修改 @@ -49,6 +54,7 @@ title: 数组函数 | [ARRAY_INTERSECTION](array-intersection) | 返回数组交集元素 | `ARRAY_INTERSECTION([1,2,3], [2,3,4])` → `[2,3]` | | [ARRAY_EXCEPT](array-except) | 返回数组差集元素 | `ARRAY_EXCEPT([1,2,3], [2,4])` → `[1,3]` | | [ARRAY_OVERLAP](array-overlap) | 检查数组是否存在交集 | `ARRAY_OVERLAP([1,2,3], [3,4,5])` → `true` | +| [ARRAY_SORT](array-sort) | 排序数组；可控制顺序与 NULL 位置 | `ARRAY_SORT([3,1,2])` → `[1,2,3]` | ## 数组处理与转换 @@ -59,6 +65,21 @@ title: 数组函数 | [ARRAY_REDUCE](array-reduce) | 使用聚合函数归约数组 | `ARRAY_REDUCE([1,2,3], 0, (acc,x) -> acc + x)` → `6` | | [ARRAY_AGGREGATE](array-aggregate) | 使用函数聚合数组元素 | `ARRAY_AGGREGATE([1,2,3], 'sum')` → `6` | +## 数组统计函数 + +| 函数 | 描述 | 示例 | +|----------|-------------|---------| +| [ARRAY_SUM](array-sum) | 求和 | `ARRAY_SUM([1,2,3])` → `6` | +| [ARRAY_AVG](array-avg) | 求平均值 | `ARRAY_AVG([1,2,3])` → `2` | +| [ARRAY_MEDIAN](array-median) | 求中位数 | `ARRAY_MEDIAN([1,3,2])` → `2` | +| [ARRAY_MIN](array-min) | 最小值 | `ARRAY_MIN([3,1,2])` → `1` | +| [ARRAY_MAX](array-max) | 最大值 | `ARRAY_MAX([3,1,2])` → `3` | +| [ARRAY_STDDEV_POP](array-stddev-pop) | 总体标准差（别名：`ARRAY_STD`） | `ARRAY_STDDEV_POP([1,2,3])` | +| [ARRAY_STDDEV_SAMP](array-stddev-samp) | 样本标准差（别名：`ARRAY_STDDEV`） | `ARRAY_STDDEV_SAMP([1,2,3])` | +| [ARRAY_KURTOSIS](array-kurtosis) | 超峰度 | `ARRAY_KURTOSIS([1,2,3,4])` | +| [ARRAY_SKEWNESS](array-skewness) | 偏度 | `ARRAY_SKEWNESS([1,2,3,10])` | +| [ARRAY_APPROX_COUNT_DISTINCT](array-approx-count-distinct) | 近似去重计数 | `ARRAY_APPROX_COUNT_DISTINCT([1,1,2])` → `2` | + ## 数组工具函数 | 函数 | 描述 | 示例 | @@ -67,4 +88,5 @@ title: 数组函数 | [ARRAY_FLATTEN](array-flatten) | 展平嵌套数组 | `ARRAY_FLATTEN([[1,2],[3,4]])` → `[1,2,3,4]` | | [ARRAY_REVERSE](array-reverse) | 反转数组元素顺序 | `ARRAY_REVERSE([1,2,3])` → `[3,2,1]` | | [ARRAY_INDEXOF](array-indexof) | 返回元素首次出现的索引 | `ARRAY_INDEXOF([1,2,3,2], 2)` → `1` | -| [UNNEST](unnest) | 将数组展开为独立行 | `UNNEST([1,2,3])` → `1, 2, 3` (作为独立行) | \ No newline at end of file +| [ARRAY_TO_STRING](array-to-string) | 将字符串数组拼接为文本 | `ARRAY_TO_STRING(['a','b'], ',')` → `'a,b'` | +| [UNNEST](unnest) | 将数组展开为独立行 | `UNNEST([1,2,3])` → `1, 2, 3` (作为独立行) | diff --git a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-construct-keep-null.md b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-construct-keep-null.md index 72b2c43d22..c4f750752d 100644 --- a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-construct-keep-null.md +++ b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-construct-keep-null.md @@ -1,6 +1,6 @@ --- title: OBJECT_CONSTRUCT_KEEP_NULL -title_includes: TRY_OBJECT_CONSTRUCT_KEEP_NULL +title_includes: TRY_OBJECT_CONSTRUCT_KEEP_NULL, JSON_OBJECT_KEEP_NULL, TRY_JSON_OBJECT_KEEP_NULL --- import FunctionDescription from '@site/src/components/FunctionDescription'; @@ -68,4 +68,4 @@ SELECT TRY_OBJECT_CONSTRUCT_KEEP_NULL('key'); ├─────────────────────────────────────┤ │ NULL │ └─────────────────────────────────────┘ -``` \ No newline at end of file +``` diff --git a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-construct.md b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-construct.md index 24e0efc468..28957fbd8d 100644 --- a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-construct.md +++ b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-construct.md @@ -1,6 +1,6 @@ --- title: OBJECT_CONSTRUCT -title_includes: TRY_OBJECT_CONSTRUCT +title_includes: TRY_OBJECT_CONSTRUCT, JSON_OBJECT, TRY_JSON_OBJECT --- import FunctionDescription from '@site/src/components/FunctionDescription'; @@ -68,4 +68,4 @@ SELECT TRY_OBJECT_CONSTRUCT('key'); ├───────────────────────────┤ │ NULL │ └───────────────────────────┘ -``` \ No newline at end of file +``` diff --git a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-delete.md b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-delete.md index 7758ad5570..6038270a6b 100644 --- a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-delete.md +++ b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-delete.md @@ -1,5 +1,6 @@ --- title: OBJECT_DELETE +title_includes: JSON_OBJECT_DELETE --- import FunctionDescription from '@site/src/components/FunctionDescription'; @@ -46,4 +47,4 @@ SELECT OBJECT_DELETE('{"a":1,"b":2,"d":4}'::VARIANT, 'a', 'c'); ```sql SELECT OBJECT_DELETE('{"a":1,"b":2}'::VARIANT, 'x'); -- Result: {"a":1,"b":2} -``` \ No newline at end of file +``` diff --git a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-insert.md b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-insert.md index dad9eeac5b..cded33a637 100644 --- a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-insert.md +++ b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-insert.md @@ -1,5 +1,6 @@ --- title: OBJECT_INSERT +title_includes: JSON_OBJECT_INSERT --- import FunctionDescription from '@site/src/components/FunctionDescription'; @@ -60,4 +61,4 @@ SELECT OBJECT_INSERT('{"a":1,"b":2,"d":4}'::variant, 'a', 10, true); SELECT OBJECT_INSERT('{"a":1,"b":2,"d":4}'::variant, 'a', 10); error: APIError: ResponseError with 1006: ObjectDuplicateKey while evaluating function `object_insert('{"a":1,"b":2,"d":4}', 'a', 10)` in expr `object_insert('{"a":1,"b":2,"d":4}', 'a', 10)` -``` \ No newline at end of file +``` diff --git a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-keys.md b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-keys.md index fedf69fdd7..adcd692582 100644 --- a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-keys.md +++ b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-keys.md @@ -1,5 +1,6 @@ --- title: OBJECT_KEYS +title_includes: JSON_OBJECT_KEYS --- import FunctionDescription from '@site/src/components/FunctionDescription'; @@ -41,4 +42,4 @@ SELECT id, object_keys(var), json_object_keys(var) FROM t; │ 1 │ ["a","b"] │ ["a","b"] │ │ 2 │ ["x","y"] │ ["x","y"] │ └───────────┴──────────────────┴───────────────────────┘ -``` \ No newline at end of file +``` diff --git a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-pick.md b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-pick.md index 03e5a6a832..37b04ffa57 100644 --- a/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-pick.md +++ b/docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-pick.md @@ -1,5 +1,6 @@ --- title: OBJECT_PICK +title_includes: JSON_OBJECT_PICK --- import FunctionDescription from '@site/src/components/FunctionDescription'; @@ -46,4 +47,4 @@ SELECT OBJECT_PICK('{"a":1,"b":2,"d":4}'::VARIANT, 'a', 'b'); ```sql SELECT OBJECT_PICK('{"a":1,"b":2,"d":4}'::VARIANT, 'a', 'c'); -- 结果: {"a":1} -``` \ No newline at end of file +``` diff --git a/docs/en/sql-reference/20-sql-functions/05-datetime-functions/to-timestamp-tz.md b/docs/en/sql-reference/20-sql-functions/05-datetime-functions/to-timestamp-tz.md new file mode 100644 index 0000000000..8583765fbd --- /dev/null +++ b/docs/en/sql-reference/20-sql-functions/05-datetime-functions/to-timestamp-tz.md @@ -0,0 +1,55 @@ +--- +title: TO_TIMESTAMP_TZ +--- + +Converts a value to [`TIMESTAMP_TZ`](../../00-sql-reference/10-data-types/datetime.md#timestamp_tz), keeping both the UTC moment and the timezone offset. Use `TRY_TO_TIMESTAMP_TZ` if you prefer `NULL` instead of an error. + +## Syntax + +```sql +TO_TIMESTAMP_TZ() +``` + +`` can be a string in ISO-8601 style (`YYYY-MM-DD`, `YYYY-MM-DDTHH:MM:SS[.fraction][±offset]`), a `TIMESTAMP`, or a `DATE`. + +## Return Type + +`TIMESTAMP_TZ` + +## Examples + +### Parse a string with an explicit offset + +```sql +SELECT TO_TIMESTAMP_TZ('2021-12-20 17:01:01.000000 +0000')::STRING AS utc_example; + +┌──────────────────────────────────────────┐ +│ utc_example │ +├──────────────────────────────────────────┤ +│ 2021-12-20 17:01:01.000000 +0000 │ +└──────────────────────────────────────────┘ +``` + +### Promote a TIMESTAMP + +```sql +SELECT TO_TIMESTAMP_TZ(TO_TIMESTAMP('2021-12-20 17:01:01.000000'))::STRING AS from_timestamp; + +┌──────────────────────────────────────────┐ +│ from_timestamp │ +├──────────────────────────────────────────┤ +│ 2021-12-20 17:01:01.000000 +0000 │ +└──────────────────────────────────────────┘ +``` + +### Convert back to TIMESTAMP + +```sql +SELECT TO_TIMESTAMP(TO_TIMESTAMP_TZ('2021-12-20 17:01:01.000000 +0800')) AS back_to_timestamp; + +┌────────────────────────┐ +│ back_to_timestamp │ +├────────────────────────┤ +│ 2021-12-20T09:01:01 │ +└────────────────────────┘ +``` diff --git a/docs/en/sql-reference/20-sql-functions/07-aggregate-functions/aggregate-json-array-agg.md b/docs/en/sql-reference/20-sql-functions/07-aggregate-functions/aggregate-json-array-agg.md index bc29b829fa..358786b0e2 100644 --- a/docs/en/sql-reference/20-sql-functions/07-aggregate-functions/aggregate-json-array-agg.md +++ b/docs/en/sql-reference/20-sql-functions/07-aggregate-functions/aggregate-json-array-agg.md @@ -1,5 +1,6 @@ --- -title: JSON_ARRAY_AGG +title: JSON_ARRAY_AGG +title_includes: JSON_AGG --- import FunctionDescription from '@site/src/components/FunctionDescription'; @@ -53,4 +54,4 @@ aggregated_b: ["abc","de","xyz"] aggregated_c: [100,200,300] aggregated_d: [{"k":"v"},null,"uvw",[1,2,3]] aggregated_e: [["a","b"],[],["x","y"],["z"]] -``` \ No newline at end of file +``` diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/get-by-keypath.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/get-by-keypath.md new file mode 100644 index 0000000000..351418557c --- /dev/null +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/get-by-keypath.md @@ -0,0 +1,64 @@ +--- +title: GET_BY_KEYPATH +title_includes: GET_BY_KEYPATH_STRING +--- + +Extracts a nested value from a `VARIANT` using a **key path** string. `GET_BY_KEYPATH` returns the result as `VARIANT`, while `GET_BY_KEYPATH_STRING` returns a `STRING`. + +Key paths follow the Postgres-style braces syntax: each segment is wrapped in `{}` and segments are separated by commas, for example `'{user,profile,name}'`. Array indexes can be specified as numbers, e.g. `'{items,0}'`. + +## Syntax + +```sql +GET_BY_KEYPATH(, ) +GET_BY_KEYPATH_STRING(, ) +``` + +## Return Type + +- `GET_BY_KEYPATH`: `VARIANT` +- `GET_BY_KEYPATH_STRING`: `STRING` + +## Examples + +```sql +SELECT GET_BY_KEYPATH(PARSE_JSON('{"user":{"name":"Ada","tags":["a","b"]}}'), '{user,name}') AS profile_name; + +┌──────────────┐ +│ profile_name │ +├──────────────┤ +│ "Ada" │ +└──────────────┘ +``` + +```sql +SELECT GET_BY_KEYPATH(PARSE_JSON('[10, {"a":{"k1":[1,2,3]}}]'), '{1,a,k1}') AS inner_array; + +┌─────────────┐ +│ inner_array │ +├─────────────┤ +│ [1,2,3] │ +└─────────────┘ +``` + +```sql +SELECT GET_BY_KEYPATH_STRING(PARSE_JSON('{"user":{"name":"Ada"}}'), '{user,name}') AS name_text; + +┌──────────┐ +│ name_text│ +├──────────┤ +│ Ada │ +└──────────┘ +``` + +```sql +SELECT GET_BY_KEYPATH_STRING(PARSE_JSON('[10, {"scores":[100,98]}]'), '{1,scores,0}') AS first_score; + +┌──────────────┐ +│ first_score │ +├──────────────┤ +│ 100 │ +└──────────────┘ +``` + +If the key path cannot be resolved, both functions return `NULL`. diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/get.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/get.md index bc12696dda..88a12ac60f 100644 --- a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/get.md +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/get.md @@ -1,5 +1,6 @@ --- title: GET +title_includes: GET_STRING --- Extracts value from a `Variant` that contains `ARRAY` by `index`, or a `Variant` that contains `OBJECT` by `field_name`. diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/index.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/index.md index af024bbf08..90f7ceb0d7 100644 --- a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/index.md +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/index.md @@ -39,6 +39,7 @@ This section provides reference information for JSON functions in Databend. JSON |----------|-------------|---------| | [GET](get) | Extracts value from JSON by index or field name | `GET('{"name":"John"}', 'name')` → `"John"` | | [GET_IGNORE_CASE](get-ignore-case) | Extracts value with case-insensitive field matching | `GET_IGNORE_CASE('{"Name":"John"}', 'name')` → `"John"` | +| [GET_BY_KEYPATH](get-by-keypath) | Extracts nested value using brace key paths | `GET_BY_KEYPATH('{"user":{"name":"Ada"}}', '{user,name}')` → `"Ada"` | | [GET_PATH](get-path) | Extracts value using path notation | `GET_PATH('{"user":{"name":"John"}}', 'user.name')` → `"John"` | | [JSON_EXTRACT_PATH_TEXT](json-extract-path-text) | Extracts text value from JSON using path | `JSON_EXTRACT_PATH_TEXT('{"name":"John"}', 'name')` → `'John'` | | [JSON_EACH](json-each) | Expands JSON object into key-value pairs | `JSON_EACH('{"a":1,"b":2}')` → `[("a",1),("b",2)]` | @@ -51,3 +52,12 @@ This section provides reference information for JSON functions in Databend. JSON | [JSON_PRETTY](json-pretty) | Formats JSON with proper indentation | `JSON_PRETTY('{"a":1}')` → Formatted JSON string | | [STRIP_NULL_VALUE](strip-null-value) | Removes null values from JSON | `STRIP_NULL_VALUE('{"a":1,"b":null}')` → `{"a":1}` | | [JQ](jq) | Processes JSON using jq-style queries | `JQ('{"name":"John"}', '.name')` → `"John"` | + +## JSON Containment & Existence + +| Function | Description | Example | +|----------|-------------|---------| +| [JSON_CONTAINS_IN_LEFT](json-contains) | Tests whether the left JSON contains the right JSON | `JSON_CONTAINS_IN_LEFT('{"a":1,"b":2}', '{"b":2}')` → `true` | +| [JSON_EXISTS_KEY](json-exists-keys) | Checks whether specific keys exist | `JSON_EXISTS_KEY('{"a":1}', 'a')` → `true` | +| [JSON_EXISTS_ANY_KEYS](json-exists-keys) | Returns `true` if any key in the list exists | `JSON_EXISTS_ANY_KEYS('{"a":1}', ['x','a'])` → `true` | +| [JSON_EXISTS_ALL_KEYS](json-exists-keys) | Returns `true` only if all keys exist | `JSON_EXISTS_ALL_KEYS('{"a":1,"b":2}', ['a','b'])` → `true` | diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/json-contains.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/json-contains.md new file mode 100644 index 0000000000..310d71cd26 --- /dev/null +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/json-contains.md @@ -0,0 +1,68 @@ +--- +title: JSON_CONTAINS_IN_LEFT +title_includes: JSON_CONTAINS_IN_RIGHT +--- + +Tests containment relationships between two `VARIANT` values: + +- `JSON_CONTAINS_IN_LEFT(left, right)` returns `TRUE` when *left* contains *right* (i.e., *left* is a superset). +- `JSON_CONTAINS_IN_RIGHT(left, right)` returns `TRUE` when *right* contains *left*. + +Containment works for both JSON objects and arrays. + +## Syntax + +```sql +JSON_CONTAINS_IN_LEFT(, ) +JSON_CONTAINS_IN_RIGHT(, ) +``` + +## Return Type + +`BOOLEAN` + +## Examples + +```sql +SELECT JSON_CONTAINS_IN_LEFT(PARSE_JSON('{"a":1,"b":{"c":2}}'), + PARSE_JSON('{"b":{"c":2}}')) AS left_contains; + +┌──────────────┐ +│ left_contains│ +├──────────────┤ +│ true │ +└──────────────┘ +``` + +```sql +SELECT JSON_CONTAINS_IN_LEFT(PARSE_JSON('[1,2,3]'), + PARSE_JSON('[2,3]')) AS left_contains; + +┌──────────────┐ +│ left_contains│ +├──────────────┤ +│ true │ +└──────────────┘ +``` + +```sql +SELECT JSON_CONTAINS_IN_LEFT(PARSE_JSON('[1,2]'), + PARSE_JSON('[2,4]')) AS left_contains; + +┌──────────────┐ +│ left_contains│ +├──────────────┤ +│ false │ +└──────────────┘ +``` + +```sql +SELECT JSON_CONTAINS_IN_RIGHT(PARSE_JSON('{"a":1}'), + PARSE_JSON('{"a":1,"b":2}')) AS right_contains; + +┌───────────────┐ +│ right_contains│ +├───────────────┤ +│ true │ +└───────────────┘ +``` diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/json-exists-keys.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/json-exists-keys.md new file mode 100644 index 0000000000..4f6e79fe56 --- /dev/null +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/json-exists-keys.md @@ -0,0 +1,64 @@ +--- +title: JSON_EXISTS_KEY +title_includes: JSON_EXISTS_ANY_KEYS, JSON_EXISTS_ALL_KEYS +--- + +Checks whether a JSON object contains one or more keys. + +- `JSON_EXISTS_KEY` tests a single key. +- `JSON_EXISTS_ANY_KEYS` accepts an array of keys and returns `TRUE` when at least one key exists. +- `JSON_EXISTS_ALL_KEYS` returns `TRUE` only when every key in the array exists. + +## Syntax + +```sql +JSON_EXISTS_KEY(, ) +JSON_EXISTS_ANY_KEYS(, ) +JSON_EXISTS_ALL_KEYS(, ) +``` + +## Return Type + +`BOOLEAN` + +## Examples + +```sql +SELECT JSON_EXISTS_KEY(PARSE_JSON('{"a":1,"b":2}'), 'b') AS has_b; + +┌──────┐ +│ has_b│ +├──────┤ +│ true │ +└──────┘ +``` + +```sql +SELECT JSON_EXISTS_ANY_KEYS(PARSE_JSON('{"a":1,"b":2}'), ['x','b']) AS any_key; + +┌────────┐ +│ any_key│ +├────────┤ +│ true │ +└────────┘ +``` + +```sql +SELECT JSON_EXISTS_ALL_KEYS(PARSE_JSON('{"a":1,"b":2}'), ['a','b','c']) AS all_keys; + +┌────────┐ +│ all_keys│ +├────────┤ +│ false │ +└────────┘ +``` + +```sql +SELECT JSON_EXISTS_ALL_KEYS(PARSE_JSON('{"a":1,"b":2}'), ['a','b']) AS all_keys; + +┌────────┐ +│ all_keys│ +├────────┤ +│ true │ +└────────┘ +``` diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/strip-null-value.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/strip-null-value.md index d40e92da55..ef990c7518 100644 --- a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/strip-null-value.md +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/strip-null-value.md @@ -1,5 +1,6 @@ --- title: STRIP_NULL_VALUE +title_includes: JSON_STRIP_NULLS --- import FunctionDescription from '@site/src/components/FunctionDescription'; @@ -25,4 +26,4 @@ SELECT STRIP_NULL_VALUE(PARSE_JSON('{"name": "Alice", "age": 30, "city": null}') strip_null_value(parse_json('{"name": "alice", "age": 30, "city": null}'))| --------------------------------------------------------------------------+ {"age":30,"name":"Alice"} | -``` \ No newline at end of file +``` diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-any.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-any.md new file mode 100644 index 0000000000..e68f1ba813 --- /dev/null +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-any.md @@ -0,0 +1,47 @@ +--- +title: ARRAY_ANY +--- + +Returns the first non-`NULL` element from an array. Equivalent to `ARRAY_AGGREGATE(, 'ANY')`. + +## Syntax + +```sql +ARRAY_ANY() +``` + +## Return Type + +Same as the array element type. + +## Examples + +```sql +SELECT ARRAY_ANY(['a', 'b', 'c']) AS first_item; + +┌────────────┐ +│ first_item │ +├────────────┤ +│ a │ +└────────────┘ +``` + +```sql +SELECT ARRAY_ANY([NULL, 'x', 'y']) AS first_non_null; + +┌────────────────┐ +│ first_non_null │ +├────────────────┤ +│ x │ +└────────────────┘ +``` + +```sql +SELECT ARRAY_ANY([NULL, 10, 20]) AS first_number; + +┌──────────────┐ +│ first_number │ +├──────────────┤ +│ 10 │ +└──────────────┘ +``` diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-approx-count-distinct.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-approx-count-distinct.md new file mode 100644 index 0000000000..ab0a10e760 --- /dev/null +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-approx-count-distinct.md @@ -0,0 +1,37 @@ +--- +title: ARRAY_APPROX_COUNT_DISTINCT +--- + +Returns an approximate count of distinct elements in an array, ignoring `NULL` values. This uses the same HyperLogLog-based estimator as [`APPROX_COUNT_DISTINCT`](../../07-aggregate-functions/aggregate-approx-count-distinct.md). + +## Syntax + +```sql +ARRAY_APPROX_COUNT_DISTINCT() +``` + +## Return Type + +`BIGINT` + +## Examples + +```sql +SELECT ARRAY_APPROX_COUNT_DISTINCT([1, 1, 2, 3, 3, 3]) AS approx_cnt; + +┌────────────┐ +│ approx_cnt │ +├────────────┤ +│ 3 │ +└────────────┘ +``` + +```sql +SELECT ARRAY_APPROX_COUNT_DISTINCT([NULL, 'a', 'a', 'b']) AS approx_cnt_text; + +┌──────────────────┐ +│ approx_cnt_text │ +├──────────────────┤ +│ 2 │ +└──────────────────┘ +``` diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-avg.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-avg.md new file mode 100644 index 0000000000..a380a97d4c --- /dev/null +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-avg.md @@ -0,0 +1,47 @@ +--- +title: ARRAY_AVG +--- + +Returns the average of the numeric items in an array. `NULL` elements are ignored; non-numeric values raise an error. + +## Syntax + +```sql +ARRAY_AVG() +``` + +## Return Type + +Numeric (uses the smallest numeric type that can represent the result). + +## Examples + +```sql +SELECT ARRAY_AVG([1, 2, 3, 4]) AS avg_int; + +┌─────────┐ +│ avg_int │ +├─────────┤ +│ 2.5 │ +└─────────┘ +``` + +```sql +SELECT ARRAY_AVG([1.5, 2.5, 3.5]) AS avg_decimal; + +┌──────────────┐ +│ avg_decimal │ +├──────────────┤ +│ 2.5000 │ +└──────────────┘ +``` + +```sql +SELECT ARRAY_AVG([10, NULL, 4]) AS avg_with_null; + +┌──────────────┐ +│ avg_with_null│ +├──────────────┤ +│ 7.0 │ +└──────────────┘ +``` diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-construct.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-construct.md index 9f3910282f..feabd25106 100644 --- a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-construct.md +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-construct.md @@ -1,5 +1,6 @@ --- title: ARRAY_CONSTRUCT +title_includes: JSON_ARRAY --- import FunctionDescription from '@site/src/components/FunctionDescription'; @@ -60,4 +61,4 @@ array_construct(productname, price)| ["Apple",1.2] | ["Banana",0.5] | ["Orange",0.8] | -``` \ No newline at end of file +``` diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-count.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-count.md new file mode 100644 index 0000000000..939b576f2d --- /dev/null +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-count.md @@ -0,0 +1,47 @@ +--- +title: ARRAY_COUNT +--- + +Counts the non-`NULL` elements in an array. + +## Syntax + +```sql +ARRAY_COUNT() +``` + +## Return Type + +`BIGINT` + +## Examples + +```sql +SELECT ARRAY_COUNT([1, 2, 3]) AS cnt; + +┌─────┐ +│ cnt │ +├─────┤ +│ 3 │ +└─────┘ +``` + +```sql +SELECT ARRAY_COUNT([1, NULL, 3]) AS cnt_with_null; + +┌──────────────┐ +│ cnt_with_null│ +├──────────────┤ +│ 2 │ +└──────────────┘ +``` + +```sql +SELECT ARRAY_COUNT(['a', 'b', NULL]) AS cnt_text; + +┌─────────┐ +│ cnt_text│ +├─────────┤ +│ 2 │ +└─────────┘ +``` diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-distinct.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-distinct.md index 98f839e8e0..c530ea447d 100644 --- a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-distinct.md +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-distinct.md @@ -1,5 +1,6 @@ --- title: ARRAY_DISTINCT +title_includes: JSON_ARRAY_DISTINCT --- import FunctionDescription from '@site/src/components/FunctionDescription'; diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-except.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-except.md index e8c80f86d7..3ebf949e64 100644 --- a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-except.md +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-except.md @@ -1,5 +1,6 @@ --- title: ARRAY_EXCEPT +title_includes: JSON_ARRAY_EXCEPT --- import FunctionDescription from '@site/src/components/FunctionDescription'; diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-generate-range.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-generate-range.md new file mode 100644 index 0000000000..8bcbfcc5f8 --- /dev/null +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-generate-range.md @@ -0,0 +1,51 @@ +--- +title: ARRAY_GENERATE_RANGE +--- + +Builds an array of evenly spaced integers between a start and end value. The `end` bound is exclusive. + +## Syntax + +```sql +ARRAY_GENERATE_RANGE(, [, ]) +``` + +- ``: First value to include. +- ``: Exclusive upper (or lower) bound. +- ``: Optional increment (default `1`). Negative steps produce descending sequences. + +## Return Type + +`ARRAY` + +## Examples + +```sql +SELECT ARRAY_GENERATE_RANGE(1, 5) AS seq; + +┌──────────┐ +│ seq │ +├──────────┤ +│ [1,2,3,4]│ +└──────────┘ +``` + +```sql +SELECT ARRAY_GENERATE_RANGE(0, 6, 2) AS seq_step; + +┌────────────┐ +│ seq_step │ +├────────────┤ +│ [0,2,4] │ +└────────────┘ +``` + +```sql +SELECT ARRAY_GENERATE_RANGE(5, 0, -2) AS seq_down; + +┌────────────┐ +│ seq_down │ +├────────────┤ +│ [5,3,1] │ +└────────────┘ +``` diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-insert.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-insert.md index 2453b64d3a..3605a6ab63 100644 --- a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-insert.md +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-insert.md @@ -1,5 +1,6 @@ --- title: ARRAY_INSERT +title_includes: JSON_ARRAY_INSERT --- import FunctionDescription from '@site/src/components/FunctionDescription'; @@ -65,4 +66,4 @@ SELECT ARRAY_INSERT('["task1", "task2", "task3"]'::VARIANT, -6, '"new_task"'::VA -[ RECORD 1 ]----------------------------------- array_insert('["task1", "task2", "task3"]'::VARIANT, - 6, '"new_task"'::VARIANT): ["new_task","task1","task2","task3"] -``` \ No newline at end of file +``` diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-intersection.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-intersection.md index 57a9c0393c..40894fa1ad 100644 --- a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-intersection.md +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-intersection.md @@ -1,5 +1,6 @@ --- title: ARRAY_INTERSECTION +title_includes: JSON_ARRAY_INTERSECTION --- import FunctionDescription from '@site/src/components/FunctionDescription'; @@ -38,4 +39,4 @@ SELECT ARRAY_INTERSECTION( -[ RECORD 1 ]----------------------------------- array_intersection(array_intersection('["Electronics", "Books", "Toys"]'::VARIANT, '["Books", "Fashion", "Electronics"]'::VARIANT), '["Electronics", "Books", "Clothing"]'::VARIANT): ["Electronics","Books"] -``` \ No newline at end of file +``` diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-kurtosis.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-kurtosis.md new file mode 100644 index 0000000000..51b797076c --- /dev/null +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-kurtosis.md @@ -0,0 +1,47 @@ +--- +title: ARRAY_KURTOSIS +--- + +Returns the excess kurtosis of the numeric values in an array. `NULL` elements are ignored; non-numeric elements raise an error. + +## Syntax + +```sql +ARRAY_KURTOSIS() +``` + +## Return Type + +Floating-point. + +## Examples + +```sql +SELECT ARRAY_KURTOSIS([1, 2, 3, 4]) AS kurt; + +┌────────────────────────┐ +│ kurt │ +├────────────────────────┤ +│ -1.200000000000001 │ +└────────────────────────┘ +``` + +```sql +SELECT ARRAY_KURTOSIS([1.5, 2.5, 3.5, 4.5]) AS kurt_decimal; + +┌────────────────────────┐ +│ kurt_decimal │ +├────────────────────────┤ +│ -1.200000000000001 │ +└────────────────────────┘ +``` + +```sql +SELECT ARRAY_KURTOSIS([NULL, 2, 3, 4]) AS kurt_null; + +┌────────────────┐ +│ kurt_null │ +├────────────────┤ +│ 0 │ +└────────────────┘ +``` diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-max.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-max.md new file mode 100644 index 0000000000..332447c7cd --- /dev/null +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-max.md @@ -0,0 +1,47 @@ +--- +title: ARRAY_MAX +--- + +Returns the largest numeric value in an array. `NULL` elements are skipped; non-numeric values cause an error. + +## Syntax + +```sql +ARRAY_MAX() +``` + +## Return Type + +Same numeric type as the array elements. + +## Examples + +```sql +SELECT ARRAY_MAX([5, 2, 9, -1]) AS max_int; + +┌─────────┐ +│ max_int │ +├─────────┤ +│ 9 │ +└─────────┘ +``` + +```sql +SELECT ARRAY_MAX([1.5, -2.25, 3.0]) AS max_decimal; + +┌─────────────┐ +│ max_decimal │ +├─────────────┤ +│ 3.00 │ +└─────────────┘ +``` + +```sql +SELECT ARRAY_MAX([NULL, 10, 4]) AS max_with_null; + +┌───────────────┐ +│ max_with_null │ +├───────────────┤ +│ 10 │ +└───────────────┘ +``` diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-median.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-median.md new file mode 100644 index 0000000000..fab2d9600f --- /dev/null +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-median.md @@ -0,0 +1,47 @@ +--- +title: ARRAY_MEDIAN +--- + +Returns the median of the numeric values in an array. `NULL` elements are ignored. + +## Syntax + +```sql +ARRAY_MEDIAN() +``` + +## Return Type + +Numeric. For even-length inputs the result is the average of the two middle values. + +## Examples + +```sql +SELECT ARRAY_MEDIAN([1, 3, 2, 4]) AS med_even; + +┌────────┐ +│ med_even │ +├────────┤ +│ 2.5 │ +└────────┘ +``` + +```sql +SELECT ARRAY_MEDIAN([1, 3, 5]) AS med_odd; + +┌────────┐ +│ med_odd│ +├────────┤ +│ 3.0 │ +└────────┘ +``` + +```sql +SELECT ARRAY_MEDIAN([NULL, 10, 20, 30]) AS med_null; + +┌────────┐ +│ med_null│ +├────────┤ +│ 20.0 │ +└────────┘ +``` diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-min.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-min.md new file mode 100644 index 0000000000..e1524dc49e --- /dev/null +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-min.md @@ -0,0 +1,47 @@ +--- +title: ARRAY_MIN +--- + +Returns the smallest numeric value in an array. `NULL` elements are skipped; non-numeric values cause an error. + +## Syntax + +```sql +ARRAY_MIN() +``` + +## Return Type + +Same numeric type as the array elements. + +## Examples + +```sql +SELECT ARRAY_MIN([5, 2, 9, -1]) AS min_int; + +┌─────────┐ +│ min_int │ +├─────────┤ +│ -1 │ +└─────────┘ +``` + +```sql +SELECT ARRAY_MIN([1.5, -2.25, 3.0]) AS min_decimal; + +┌──────────────┐ +│ min_decimal │ +├──────────────┤ +│ -2.25 │ +└──────────────┘ +``` + +```sql +SELECT ARRAY_MIN([NULL, 10, 4]) AS min_with_null; + +┌──────────────┐ +│ min_with_null│ +├──────────────┤ +│ 4 │ +└──────────────┘ +``` diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-overlap.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-overlap.md index 51f0cc5e2d..9c56d9999f 100644 --- a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-overlap.md +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-overlap.md @@ -1,5 +1,6 @@ --- title: ARRAY_OVERLAP +title_includes: JSON_ARRAY_OVERLAP --- import FunctionDescription from '@site/src/components/FunctionDescription'; diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-size.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-size.md new file mode 100644 index 0000000000..d0100cc3bf --- /dev/null +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-size.md @@ -0,0 +1,40 @@ +--- +title: ARRAY_SIZE +title_includes: ARRAY_LENGTH +--- + +Returns the length of an array, counting `NULL` elements. + +Alias: `ARRAY_LENGTH` + +## Syntax + +```sql +ARRAY_SIZE() +``` + +## Return Type + +`BIGINT` + +## Examples + +```sql +SELECT ARRAY_SIZE([1, 2, 3]) AS size_plain; + +┌──────────┐ +│ size_plain │ +├──────────┤ +│ 3 │ +└──────────┘ +``` + +```sql +SELECT ARRAY_SIZE([1, NULL, 3]) AS size_with_null; + +┌──────────────┐ +│ size_with_null│ +├──────────────┤ +│ 3 │ +└──────────────┘ +``` diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-skewness.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-skewness.md new file mode 100644 index 0000000000..e48e6ac615 --- /dev/null +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-skewness.md @@ -0,0 +1,47 @@ +--- +title: ARRAY_SKEWNESS +--- + +Returns the skewness of numeric values in an array. `NULL` items are ignored; non-numeric items raise an error. + +## Syntax + +```sql +ARRAY_SKEWNESS() +``` + +## Return Type + +Floating-point. + +## Examples + +```sql +SELECT ARRAY_SKEWNESS([1, 2, 3, 4]) AS skew; + +┌──────┐ +│ skew │ +├──────┤ +│ 0 │ +└──────┘ +``` + +```sql +SELECT ARRAY_SKEWNESS([1.5, 2.5, 3.5, 4.5]) AS skew_decimal; + +┌────────────┐ +│ skew_decimal│ +├────────────┤ +│ 0 │ +└────────────┘ +``` + +```sql +SELECT ARRAY_SKEWNESS([NULL, 2, 3, 10]) AS skew_null; + +┌────────────────────┐ +│ skew_null │ +├────────────────────┤ +│ 1.6300591617118865 │ +└────────────────────┘ +``` diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-sort.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-sort.md new file mode 100644 index 0000000000..8324aa4850 --- /dev/null +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-sort.md @@ -0,0 +1,70 @@ +--- +title: ARRAY_SORT +title_includes: ARRAY_SORT_ASC_NULL_FIRST, ARRAY_SORT_ASC_NULL_LAST, ARRAY_SORT_DESC_NULL_FIRST, ARRAY_SORT_DESC_NULL_LAST +--- + +Sorts the elements of an array. By default, `ARRAY_SORT` orders ascending and places `NULL` values last. Use the explicit variants to control order and `NULL` placement. + +## Syntax + +```sql +ARRAY_SORT() +ARRAY_SORT_ASC_NULL_FIRST() +ARRAY_SORT_ASC_NULL_LAST() +ARRAY_SORT_DESC_NULL_FIRST() +ARRAY_SORT_DESC_NULL_LAST() +``` + +## Return Type + +`ARRAY` + +## Examples + +```sql +SELECT ARRAY_SORT([3, 1, 2]) AS sort_default; + +┌──────────────┐ +│ sort_default │ +├──────────────┤ +│ [1,2,3] │ +└──────────────┘ +``` + +```sql +SELECT ARRAY_SORT([NULL, 2, 1]) AS sort_with_nulls; + +┌────────────────┐ +│ sort_with_nulls│ +├────────────────┤ +│ [1,2,NULL] │ +└────────────────┘ +``` + +```sql +SELECT ARRAY_SORT_ASC_NULL_FIRST([NULL, 2, 1]) AS asc_null_first; + +┌────────────────┐ +│ asc_null_first │ +├────────────────┤ +│ [NULL,1,2] │ +└────────────────┘ +``` + +```sql +SELECT ARRAY_SORT_DESC_NULL_LAST([NULL, 2, 1]) AS desc_null_last; + +┌────────────────┐ +│ desc_null_last │ +├────────────────┤ +│ [2,1,NULL] │ +└────────────────┘ + +SELECT ARRAY_SORT_DESC_NULL_FIRST([NULL, 2, 1]) AS desc_null_first; + +┌─────────────────┐ +│ desc_null_first │ +├─────────────────┤ +│ [NULL,2,1] │ +└─────────────────┘ +``` diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-stddev-pop.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-stddev-pop.md new file mode 100644 index 0000000000..f58fcf8f55 --- /dev/null +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-stddev-pop.md @@ -0,0 +1,38 @@ +--- +title: ARRAY_STDDEV_POP +title_includes: ARRAY_STD +--- + +Computes the population standard deviation of numeric array values. `NULL` entries are ignored; non-numeric entries raise an error. + +## Syntax + +```sql +ARRAY_STDDEV_POP() +``` + +## Return Type + +Floating-point. + +## Examples + +```sql +SELECT ARRAY_STDDEV_POP([2, 4, 4, 4, 5, 5, 7, 9]) AS stddev_pop; + +┌────────────┐ +│ stddev_pop │ +├────────────┤ +│ 2 │ +└────────────┘ +``` + +```sql +SELECT ARRAY_STDDEV_POP([1.5, 2.5, NULL, 3.5]) AS stddev_pop_null; + +┌─────────────────┐ +│ stddev_pop_null │ +├─────────────────┤ +│ 0.816496580927726 │ +└─────────────────┘ +``` diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-stddev-samp.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-stddev-samp.md new file mode 100644 index 0000000000..06daaa3df3 --- /dev/null +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-stddev-samp.md @@ -0,0 +1,38 @@ +--- +title: ARRAY_STDDEV_SAMP +title_includes: ARRAY_STDDEV +--- + +Computes the sample standard deviation of numeric array values. `NULL` items are ignored; non-numeric entries raise an error. + +## Syntax + +```sql +ARRAY_STDDEV_SAMP() +``` + +## Return Type + +Floating-point. + +## Examples + +```sql +SELECT ARRAY_STDDEV_SAMP([2, 4, 4, 4, 5, 5, 7, 9]) AS stddev_samp; + +┌─────────────┐ +│ stddev_samp │ +├─────────────┤ +│ 2.138089935299395 │ +└─────────────┘ +``` + +```sql +SELECT ARRAY_STDDEV_SAMP([1.5, 2.5, NULL, 3.5]) AS stddev_samp_null; + +┌─────────────────┐ +│ stddev_samp_null │ +├─────────────────┤ +│ 1 │ +└─────────────────┘ +``` diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-sum.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-sum.md new file mode 100644 index 0000000000..a2e7c4ee7b --- /dev/null +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-sum.md @@ -0,0 +1,51 @@ +--- +title: ARRAY_SUM +--- + +Sums the numeric elements in an array. `NULL` items are skipped, and non-numeric values raise an error. + +## Syntax + +```sql +ARRAY_SUM() +``` + +## Return Type + +Numeric (matches the widest numeric type in the array). + +## Examples + +```sql +SELECT ARRAY_SUM([1, 2, 3, 4]) AS total; + +┌───────┐ +│ total │ +├───────┤ +│ 10 │ +└───────┘ +``` + +```sql +SELECT ARRAY_SUM([1.5, 2.25, 3.0]) AS total; + +┌────────┐ +│ total │ +├────────┤ +│ 6.75 │ +└────────┘ +``` + +```sql +SELECT ARRAY_SUM([10, NULL, -3]) AS total; + +┌───────┐ +│ total │ +├───────┤ +│ 7 │ +└───────┘ +``` + +## Related + +- [ARRAY_AGGREGATE](array-aggregate) diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-to-string.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-to-string.md new file mode 100644 index 0000000000..6efc959c0f --- /dev/null +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array-to-string.md @@ -0,0 +1,37 @@ +--- +title: ARRAY_TO_STRING +--- + +Concatenates the string elements of an array into a single string, separated by a delimiter. `NULL` elements are skipped. + +## Syntax + +```sql +ARRAY_TO_STRING(, ) +``` + +## Return Type + +`STRING` + +## Examples + +```sql +SELECT ARRAY_TO_STRING(['a', 'b', 'c'], ',') AS joined; + +┌────────┐ +│ joined │ +├────────┤ +│ a,b,c │ +└────────┘ +``` + +```sql +SELECT ARRAY_TO_STRING([NULL, 'x', 'y'], '-') AS joined_no_nulls; + +┌──────────────────┐ +│ joined_no_nulls │ +├──────────────────┤ +│ x-y │ +└──────────────────┘ +``` diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array.md new file mode 100644 index 0000000000..feaee48f3c --- /dev/null +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/array.md @@ -0,0 +1,47 @@ +--- +title: ARRAY +--- + +Builds an array literal from the supplied expressions. Each argument is evaluated and stored in order. All elements must be castable to a common type. + +## Syntax + +```sql +ARRAY(, , ... ) +``` + +## Return Type + +`ARRAY` + +## Examples + +```sql +SELECT ARRAY(1, 2, 3) AS arr_int; + +┌─────────┐ +│ arr_int │ +├─────────┤ +│ [1,2,3] │ +└─────────┘ +``` + +```sql +SELECT ARRAY('alpha', UPPER('beta')) AS arr_text; + +┌───────────┐ +│ arr_text │ +├───────────┤ +│ ["alpha","BETA"] │ +└───────────┘ +``` + +```sql +SELECT ARRAY(1, NULL, 3) AS arr_with_null; + +┌────────────────┐ +│ arr_with_null │ +├────────────────┤ +│ [1,NULL,3] │ +└────────────────┘ +``` diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/index.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/index.md index 7c21c01c94..ea2222e22d 100644 --- a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/index.md +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/1-array/index.md @@ -8,8 +8,10 @@ This section provides reference information for array functions in Databend. Arr | Function | Description | Example | |----------|-------------|---------| +| [ARRAY](array) | Builds an array from expressions | `ARRAY(1, 2, 3)` → `[1,2,3]` | | [ARRAY_CONSTRUCT](array-construct) | Creates an array from individual values | `ARRAY_CONSTRUCT(1, 2, 3)` → `[1,2,3]` | | [RANGE](range) | Generates an array of sequential numbers | `RANGE(1, 5)` → `[1,2,3,4]` | +| [ARRAY_GENERATE_RANGE](array-generate-range) | Generates a sequence with optional step | `ARRAY_GENERATE_RANGE(0, 6, 2)` → `[0,2,4]` | ## Array Access & Information @@ -19,6 +21,9 @@ This section provides reference information for array functions in Databend. Arr | [ARRAY_GET](array-get) | Alias for GET function | `ARRAY_GET([1,2,3], 1)` → `1` | | [CONTAINS](contains) | Checks if an array contains a specific value | `CONTAINS([1,2,3], 2)` → `true` | | [ARRAY_CONTAINS](array-contains) | Checks if an array contains a specific value | `ARRAY_CONTAINS([1,2,3], 2)` → `true` | +| [ARRAY_SIZE](array-size) | Returns array length (alias: `ARRAY_LENGTH`) | `ARRAY_SIZE([1,2,3])` → `3` | +| [ARRAY_COUNT](array-count) | Counts non-`NULL` entries | `ARRAY_COUNT([1,NULL,2])` → `2` | +| [ARRAY_ANY](array-any) | Returns the first non-`NULL` value | `ARRAY_ANY([NULL,'a','b'])` → `'a'` | ## Array Modification @@ -39,6 +44,7 @@ This section provides reference information for array functions in Databend. Arr | [ARRAY_SLICE](array-slice) | Extracts a portion of an array | `ARRAY_SLICE([1,2,3,4], 1, 2)` → `[1,2]` | | [SLICE](slice) | Alias for ARRAY_SLICE function | `SLICE([1,2,3,4], 1, 2)` → `[1,2]` | | [ARRAYS_ZIP](arrays-zip) | Combines multiple arrays element-wise | `ARRAYS_ZIP([1,2], ['a','b'])` → `[(1,'a'),(2,'b')]` | +| [ARRAY_SORT](array-sort) | Sorts values; variants control order/nulls | `ARRAY_SORT([3,1,2])` → `[1,2,3]` | ## Array Set Operations @@ -59,6 +65,27 @@ This section provides reference information for array functions in Databend. Arr | [ARRAY_REDUCE](array-reduce) | Reduces array to a single value using aggregation | `ARRAY_REDUCE([1,2,3], 0, (acc,x) -> acc + x)` → `6` | | [ARRAY_AGGREGATE](array-aggregate) | Aggregates array elements using a function | `ARRAY_AGGREGATE([1,2,3], 'sum')` → `6` | +## Array Aggregations & Statistics + +| Function | Description | Example | +|----------|-------------|---------| +| [ARRAY_SUM](array-sum) | Sum of numeric values | `ARRAY_SUM([1,2,3])` → `6` | +| [ARRAY_AVG](array-avg) | Average of numeric values | `ARRAY_AVG([1,2,3])` → `2` | +| [ARRAY_MEDIAN](array-median) | Median of numeric values | `ARRAY_MEDIAN([1,3,2])` → `2` | +| [ARRAY_MIN](array-min) | Minimum value | `ARRAY_MIN([3,1,2])` → `1` | +| [ARRAY_MAX](array-max) | Maximum value | `ARRAY_MAX([3,1,2])` → `3` | +| [ARRAY_STDDEV_POP](array-stddev-pop) | Population standard deviation (alias: `ARRAY_STD`) | `ARRAY_STDDEV_POP([1,2,3])` | +| [ARRAY_STDDEV_SAMP](array-stddev-samp) | Sample standard deviation (alias: `ARRAY_STDDEV`) | `ARRAY_STDDEV_SAMP([1,2,3])` | +| [ARRAY_KURTOSIS](array-kurtosis) | Excess kurtosis of values | `ARRAY_KURTOSIS([1,2,3,4])` | +| [ARRAY_SKEWNESS](array-skewness) | Skewness of values | `ARRAY_SKEWNESS([1,2,3,4])` | +| [ARRAY_APPROX_COUNT_DISTINCT](array-approx-count-distinct) | Approximate distinct count | `ARRAY_APPROX_COUNT_DISTINCT([1,1,2])` → `2` | + +## Array Formatting + +| Function | Description | Example | +|----------|-------------|---------| +| [ARRAY_TO_STRING](array-to-string) | Joins array elements into a string | `ARRAY_TO_STRING(['a','b'], ',')` → `'a,b'` | + ## Array Utility Functions | Function | Description | Example | diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-construct-keep-null.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-construct-keep-null.md index 407d0386f4..212dba919e 100644 --- a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-construct-keep-null.md +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-construct-keep-null.md @@ -1,6 +1,6 @@ --- title: OBJECT_CONSTRUCT_KEEP_NULL -title_includes: TRY_OBJECT_CONSTRUCT_KEEP_NULL +title_includes: TRY_OBJECT_CONSTRUCT_KEEP_NULL, JSON_OBJECT_KEEP_NULL, TRY_JSON_OBJECT_KEEP_NULL --- import FunctionDescription from '@site/src/components/FunctionDescription'; @@ -69,4 +69,3 @@ SELECT TRY_OBJECT_CONSTRUCT_KEEP_NULL('key'); │ NULL │ └─────────────────────────────────────┘ ``` - diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-construct.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-construct.md index de1053f9ee..465927b8a4 100644 --- a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-construct.md +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-construct.md @@ -1,6 +1,6 @@ --- title: OBJECT_CONSTRUCT -title_includes: TRY_OBJECT_CONSTRUCT +title_includes: TRY_OBJECT_CONSTRUCT, JSON_OBJECT, TRY_JSON_OBJECT --- import FunctionDescription from '@site/src/components/FunctionDescription'; @@ -69,4 +69,3 @@ SELECT TRY_OBJECT_CONSTRUCT('key'); │ NULL │ └───────────────────────────┘ ``` - diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-delete.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-delete.md index 3414be9015..fac9c3a0f0 100644 --- a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-delete.md +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-delete.md @@ -1,5 +1,6 @@ --- title: OBJECT_DELETE +title_includes: JSON_OBJECT_DELETE --- import FunctionDescription from '@site/src/components/FunctionDescription'; diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-insert.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-insert.md index 5d07f189dd..a57c55f268 100644 --- a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-insert.md +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-insert.md @@ -1,5 +1,6 @@ --- title: OBJECT_INSERT +title_includes: JSON_OBJECT_INSERT --- import FunctionDescription from '@site/src/components/FunctionDescription'; @@ -60,4 +61,4 @@ This example demonstrates an error that occurs when trying to insert a value for SELECT OBJECT_INSERT('{"a":1,"b":2,"d":4}'::variant, 'a', 10); error: APIError: ResponseError with 1006: ObjectDuplicateKey while evaluating function `object_insert('{"a":1,"b":2,"d":4}', 'a', 10)` in expr `object_insert('{"a":1,"b":2,"d":4}', 'a', 10)` -``` \ No newline at end of file +``` diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-keys.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-keys.md index 92f81b0ca7..8c81ea8b5f 100644 --- a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-keys.md +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-keys.md @@ -1,5 +1,6 @@ --- title: OBJECT_KEYS +title_includes: JSON_OBJECT_KEYS --- import FunctionDescription from '@site/src/components/FunctionDescription'; @@ -41,4 +42,4 @@ SELECT id, object_keys(var), json_object_keys(var) FROM t; │ 1 │ ["a","b"] │ ["a","b"] │ │ 2 │ ["x","y"] │ ["x","y"] │ └───────────┴──────────────────┴───────────────────────┘ -``` \ No newline at end of file +``` diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-pick.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-pick.md index bdac9effe2..cfb147326e 100644 --- a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-pick.md +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/2-object/object-pick.md @@ -1,5 +1,6 @@ --- title: OBJECT_PICK +title_includes: JSON_OBJECT_PICK --- import FunctionDescription from '@site/src/components/FunctionDescription'; diff --git a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/index.md b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/index.md index ff56b683be..711443fdde 100644 --- a/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/index.md +++ b/docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/index.md @@ -48,12 +48,17 @@ Structured and semi-structured functions in Databend enable efficient processing | Function | Description | Example | |----------|-------------|--------| +| [ARRAY](array/array) | Builds an array from expressions | `ARRAY(1, 2, 3)` | | [ARRAY_CONSTRUCT](array/array-construct) | Creates an array from individual values | `ARRAY_CONSTRUCT(1, 2, 3)` | | [RANGE](array/range) | Generates an array of sequential numbers | `RANGE(1, 5)` | -| [GET](array/get) | Gets an element from an array by index | `GET(PARSE_JSON('[1,2,3]'), 0)` | +| [ARRAY_GENERATE_RANGE](array/array-generate-range) | Generates a sequence with optional step | `ARRAY_GENERATE_RANGE(0, 6, 2)` | +| [GET](array/get) | Gets an element from an array by index | `GET([1,2,3], 0)` | | [ARRAY_GET](array/array-get) | Alias for GET function | `ARRAY_GET([1,2,3], 1)` | | [CONTAINS](array/contains) | Checks if an array contains a specific value | `CONTAINS([1,2,3], 2)` | | [ARRAY_CONTAINS](array/array-contains) | Checks if an array contains a specific value | `ARRAY_CONTAINS([1,2,3], 2)` | +| [ARRAY_SIZE](array/array-size) | Returns array length (alias: `ARRAY_LENGTH`) | `ARRAY_SIZE([1,2,3])` | +| [ARRAY_COUNT](array/array-count) | Counts the non-`NULL` elements | `ARRAY_COUNT([1,NULL,2])` | +| [ARRAY_ANY](array/array-any) | Returns the first non-`NULL` entry | `ARRAY_ANY([NULL,'a','b'])` | | [ARRAY_APPEND](array/array-append) | Appends an element to the end of an array | `ARRAY_APPEND([1,2], 3)` | | [ARRAY_PREPEND](array/array-prepend) | Prepends an element to the beginning of an array | `ARRAY_PREPEND([2,3], 1)` | | [ARRAY_INSERT](array/array-insert) | Inserts an element at a specific position | `ARRAY_INSERT([1,3], 1, 2)` | @@ -73,6 +78,18 @@ Structured and semi-structured functions in Databend enable efficient processing | [ARRAY_FILTER](array/array-filter) | Filters array elements based on a condition | `ARRAY_FILTER([1,2,3,4], x -> x > 2)` | | [ARRAY_REDUCE](array/array-reduce) | Reduces array to a single value using aggregation | `ARRAY_REDUCE([1,2,3], 0, (acc, x) -> acc + x)` | | [ARRAY_AGGREGATE](array/array-aggregate) | Aggregates array elements using a function | `ARRAY_AGGREGATE([1,2,3], 'sum')` | +| [ARRAY_SUM](array/array-sum) | Sum of numeric values | `ARRAY_SUM([1,2,3])` | +| [ARRAY_AVG](array/array-avg) | Average of numeric values | `ARRAY_AVG([1,2,3])` | +| [ARRAY_MEDIAN](array/array-median) | Median of numeric values | `ARRAY_MEDIAN([1,3,2])` | +| [ARRAY_MIN](array/array-min) | Minimum value | `ARRAY_MIN([1,2,3])` | +| [ARRAY_MAX](array/array-max) | Maximum value | `ARRAY_MAX([1,2,3])` | +| [ARRAY_STDDEV_POP](array/array-stddev-pop) | Population standard deviation | `ARRAY_STDDEV_POP([1,2,3])` | +| [ARRAY_STDDEV_SAMP](array/array-stddev-samp) | Sample standard deviation | `ARRAY_STDDEV_SAMP([1,2,3])` | +| [ARRAY_KURTOSIS](array/array-kurtosis) | Excess kurtosis | `ARRAY_KURTOSIS([1,2,3,4])` | +| [ARRAY_SKEWNESS](array/array-skewness) | Skewness | `ARRAY_SKEWNESS([1,2,3,10])` | +| [ARRAY_APPROX_COUNT_DISTINCT](array/array-approx-count-distinct) | Approximate distinct count | `ARRAY_APPROX_COUNT_DISTINCT([1,1,2])` | +| [ARRAY_SORT](array/array-sort) | Sorts values; variants control order/nulls | `ARRAY_SORT([3,1,2])` | +| [ARRAY_TO_STRING](array/array-to-string) | Joins array elements | `ARRAY_TO_STRING(['a','b'], ',')` | | [ARRAY_COMPACT](array/array-compact) | Removes null values from an array | `ARRAY_COMPACT([1, NULL, 2, NULL, 3])` | | [ARRAY_FLATTEN](array/array-flatten) | Flattens nested arrays into a single array | `ARRAY_FLATTEN([[1,2], [3,4]])` | | [ARRAY_REVERSE](array/array-reverse) | Reverses the order of array elements | `ARRAY_REVERSE([1,2,3])` |