diff --git a/docs/.vuepress/sidebar/en.js b/docs/.vuepress/sidebar/en.js index cb677e32d3bcb2..a05ad55e7c8f35 100644 --- a/docs/.vuepress/sidebar/en.js +++ b/docs/.vuepress/sidebar/en.js @@ -547,6 +547,16 @@ module.exports = [ "WINDOW-FUNCTION-ROW-NUMBER", ], }, + { + title: "Array Functions", + directoryPath: "array-functions/", + initialOpenGroupIndex: -1, + children: [ + "array_contains", + "array_position", + "element_at", + ], + }, "cast", "digital-masking", ], @@ -812,6 +822,7 @@ module.exports = [ "STRING", "TINYINT", "VARCHAR", + "ARRAY", ], }, { diff --git a/docs/.vuepress/sidebar/zh-CN.js b/docs/.vuepress/sidebar/zh-CN.js index e1fad836429d3f..65a972ca13ae4a 100644 --- a/docs/.vuepress/sidebar/zh-CN.js +++ b/docs/.vuepress/sidebar/zh-CN.js @@ -547,6 +547,16 @@ module.exports = [ "WINDOW-FUNCTION-ROW-NUMBER", ], }, + { + title: "Array函数", + directoryPath: "array-functions/", + initialOpenGroupIndex: -1, + children: [ + "array_contains", + "array_position", + "element_at", + ], + }, "cast", "digital-masking", ], @@ -812,6 +822,7 @@ module.exports = [ "STRING", "TINYINT", "VARCHAR", + "ARRAY", ], }, { diff --git a/docs/en/sql-manual/sql-functions/array-functions/array_contains.md b/docs/en/sql-manual/sql-functions/array-functions/array_contains.md new file mode 100644 index 00000000000000..57091a57edfbec --- /dev/null +++ b/docs/en/sql-manual/sql-functions/array-functions/array_contains.md @@ -0,0 +1,65 @@ +--- +{ + "title": "array_contains", + "language": "en" +} +--- + + + +## array_contains + +### description + +#### Syntax + +`BOOLEAN array_contains(ARRAY arr, T value)` + +Check if a value presents in an array column. Return below values: + +``` +1 - if value presents in an array; +0 - if value does not present in an array; +NULL - when array is NULL; +``` + +### notice + +`Only supported in vectorized engine` + +### example + +``` +mysql> set enable_vectorized_engine=true; + +mysql> SELECT id,c_array,array_contains(c_array, 5) FROM `array_test`; ++------+-----------------+------------------------------+ +| id | c_array | array_contains(`c_array`, 5) | ++------+-----------------+------------------------------+ +| 1 | [1, 2, 3, 4, 5] | 1 | +| 2 | [6, 7, 8] | 0 | +| 3 | [] | 0 | +| 4 | NULL | NULL | ++------+-----------------+------------------------------+ +``` + +### keywords + +ARRAY_CONTAINS diff --git a/docs/en/sql-manual/sql-functions/array-functions/array_position.md b/docs/en/sql-manual/sql-functions/array-functions/array_position.md new file mode 100644 index 00000000000000..dd47628c27a96a --- /dev/null +++ b/docs/en/sql-manual/sql-functions/array-functions/array_position.md @@ -0,0 +1,65 @@ +--- +{ + "title": "array_position", + "language": "en" +} +--- + + + +## array_position + +### description + +#### Syntax + +`BIGINT array_position(ARRAY arr, T value)` + +Returns a position/index of first occurrence of the `value` in the given array. + +``` +position - value position in array (starts with 1); +0 - if value does not present in the array; +NULL - when array is NULL or value is NULL. +``` + +### notice + +`Only supported in vectorized engine` + +### example + +``` +mysql> set enable_vectorized_engine=true; + +mysql> SELECT id,c_array,array_position(c_array, 5) FROM `array_test`; ++------+-----------------+------------------------------+ +| id | c_array | array_position(`c_array`, 5) | ++------+-----------------+------------------------------+ +| 1 | [1, 2, 3, 4, 5] | 5 | +| 2 | [6, 7, 8] | 0 | +| 3 | [] | 0 | +| 4 | NULL | NULL | ++------+-----------------+------------------------------+ +``` + +### keywords + +ARRAY_POSITION diff --git a/docs/en/sql-manual/sql-functions/array-functions/element_at.md b/docs/en/sql-manual/sql-functions/array-functions/element_at.md new file mode 100644 index 00000000000000..34e083d5d7aefd --- /dev/null +++ b/docs/en/sql-manual/sql-functions/array-functions/element_at.md @@ -0,0 +1,81 @@ +--- +{ + "title": "element_at", + "language": "en" +} +--- + + + +## element_at + +### description + +#### Syntax + +`T element_at(ARRAY arr, BIGINT position)` + +`T arr[position]` + +Returns an element of an array located at the input position. If there is no element at the position, return NULL. + +`position` is 1-based and support negtive number. + +### notice + +`Only supported in vectorized engine` + +### example + +positive `position` example: + +``` +mysql> set enable_vectorized_engine=true; + +mysql> SELECT id,c_array,element_at(c_array, 5) FROM `array_test`; ++------+-----------------+--------------------------+ +| id | c_array | element_at(`c_array`, 5) | ++------+-----------------+--------------------------+ +| 1 | [1, 2, 3, 4, 5] | 5 | +| 2 | [6, 7, 8] | NULL | +| 3 | [] | NULL | +| 4 | NULL | NULL | ++------+-----------------+--------------------------+ +``` + +negtive `position` example: + +``` +mysql> set enable_vectorized_engine=true; + +mysql> SELECT id,c_array,c_array[-2] FROM `array_test`; ++------+-----------------+----------------------------------+ +| id | c_array | %element_extract%(`c_array`, -2) | ++------+-----------------+----------------------------------+ +| 1 | [1, 2, 3, 4, 5] | 4 | +| 2 | [6, 7, 8] | 7 | +| 3 | [] | NULL | +| 4 | NULL | NULL | ++------+-----------------+----------------------------------+ +``` + +### keywords + +ELEMENT_AT, SUBSCRIPT diff --git a/docs/en/sql-manual/sql-reference/Data-Types/ARRAY.md b/docs/en/sql-manual/sql-reference/Data-Types/ARRAY.md new file mode 100644 index 00000000000000..a157503bc55c7b --- /dev/null +++ b/docs/en/sql-manual/sql-reference/Data-Types/ARRAY.md @@ -0,0 +1,84 @@ +--- +{ + "title": "ARRAY", + "language": "en" +} +--- + + + +## ARRAY + +### description + +ARRAY\ + +An array of T-type items, it cannot be used as a key column. Now ARRAY can only used in Duplicate Model Tables. + +T-type could be any of: + +``` +BOOLEAN, TINYINT, SMALLINT, INT, BIGINT, LARGEINT, FLOAT, DOUBLE, DECIMAL, DATE, +DATETIME, CHAR, VARCHAR, STRING +``` + +### example + +Create table example: + +``` +mysql> CREATE TABLE `array_test` ( + `id` int(11) NULL COMMENT "", + `c_array` ARRAY NULL COMMENT "" +) ENGINE=OLAP +DUPLICATE KEY(`id`) +COMMENT "OLAP" +DISTRIBUTED BY HASH(`id`) BUCKETS 1 +PROPERTIES ( +"replication_allocation" = "tag.location.default: 1", +"in_memory" = "false", +"storage_format" = "V2" +); +``` + +Insert data example: + +``` +mysql> INSERT INTO `array_test` VALUES (1, [1,2,3,4,5]); +mysql> INSERT INTO `array_test` VALUES (2, array(6,7,8)), (3, array()), (4, null); +``` + +Select data example: + +``` +mysql> SELECT * FROM `array_test`; ++------+-----------------+ +| id | c_array | ++------+-----------------+ +| 1 | [1, 2, 3, 4, 5] | +| 2 | [6, 7, 8] | +| 3 | [] | +| 4 | NULL | ++------+-----------------+ +``` + +### keywords + + ARRAY, array_contains, array_position, element_at diff --git a/docs/zh-CN/sql-manual/sql-functions/array-functions/array_contains.md b/docs/zh-CN/sql-manual/sql-functions/array-functions/array_contains.md new file mode 100644 index 00000000000000..8cf1fd52bd26f8 --- /dev/null +++ b/docs/zh-CN/sql-manual/sql-functions/array-functions/array_contains.md @@ -0,0 +1,65 @@ +--- +{ + "title": "array_contains", + "language": "zh-CN" +} +--- + + + +## array_contains + +### description + +#### Syntax + +`BOOLEAN array_contains(ARRAY arr, T value)` + +判断数组中是否包含value。返回结果如下: + +``` +1 - value在数组arr中存在; +0 - value不存在数组arr中; +NULL - arr为NULL时。 +``` + +### notice + +`仅支持向量化引擎中使用` + +### example + +``` +mysql> set enable_vectorized_engine=true; + +mysql> SELECT id,c_array,array_contains(c_array, 5) FROM `array_test`; ++------+-----------------+------------------------------+ +| id | c_array | array_contains(`c_array`, 5) | ++------+-----------------+------------------------------+ +| 1 | [1, 2, 3, 4, 5] | 1 | +| 2 | [6, 7, 8] | 0 | +| 3 | [] | 0 | +| 4 | NULL | NULL | ++------+-----------------+------------------------------+ +``` + +### keywords + +ARRAY_CONTAINS diff --git a/docs/zh-CN/sql-manual/sql-functions/array-functions/array_position.md b/docs/zh-CN/sql-manual/sql-functions/array-functions/array_position.md new file mode 100644 index 00000000000000..bce5f3a5c765e7 --- /dev/null +++ b/docs/zh-CN/sql-manual/sql-functions/array-functions/array_position.md @@ -0,0 +1,65 @@ +--- +{ + "title": "array_position", + "language": "zh-CN" +} +--- + + + +## array_position + +### description + +#### Syntax + +`BIGINT array_position(ARRAY arr, T value)` + +返回`value`在数组中第一次出现的位置/索引。 + +``` +position - value在array中的位置(从1开始计算); +0 - 如果value在array中不存在; +NULL - 如果数组为NULL,或者value为NULL。 +``` + +### notice + +`仅支持向量化引擎中使用` + +### example + +``` +mysql> set enable_vectorized_engine=true; + +mysql> SELECT id,c_array,array_position(c_array, 5) FROM `array_test`; ++------+-----------------+------------------------------+ +| id | c_array | array_position(`c_array`, 5) | ++------+-----------------+------------------------------+ +| 1 | [1, 2, 3, 4, 5] | 5 | +| 2 | [6, 7, 8] | 0 | +| 3 | [] | 0 | +| 4 | NULL | NULL | ++------+-----------------+------------------------------+ +``` + +### keywords + +ARRAY_POSITION diff --git a/docs/zh-CN/sql-manual/sql-functions/array-functions/element_at.md b/docs/zh-CN/sql-manual/sql-functions/array-functions/element_at.md new file mode 100644 index 00000000000000..873524a4e9e758 --- /dev/null +++ b/docs/zh-CN/sql-manual/sql-functions/array-functions/element_at.md @@ -0,0 +1,81 @@ +--- +{ + "title": "element_at", + "language": "zh-CN" +} +--- + + + +## element_at + +### description + +#### Syntax + +`T element_at(ARRAY arr, BIGINT position)` + +`T arr[position]` + +返回数组中位置为 `position` 的元素。如果该位置上元素不存在,返回NULL。 + +`position` 从1开始,并且支持负数。 + +### notice + +`仅支持向量化引擎中使用` + +### example + +`position` 为正数使用范例: + +``` +mysql> set enable_vectorized_engine=true; + +mysql> SELECT id,c_array,element_at(c_array, 5) FROM `array_test`; ++------+-----------------+--------------------------+ +| id | c_array | element_at(`c_array`, 5) | ++------+-----------------+--------------------------+ +| 1 | [1, 2, 3, 4, 5] | 5 | +| 2 | [6, 7, 8] | NULL | +| 3 | [] | NULL | +| 4 | NULL | NULL | ++------+-----------------+--------------------------+ +``` + +`position` 为负数使用范例: + +``` +mysql> set enable_vectorized_engine=true; + +mysql> SELECT id,c_array,c_array[-2] FROM `array_test`; ++------+-----------------+----------------------------------+ +| id | c_array | %element_extract%(`c_array`, -2) | ++------+-----------------+----------------------------------+ +| 1 | [1, 2, 3, 4, 5] | 4 | +| 2 | [6, 7, 8] | 7 | +| 3 | [] | NULL | +| 4 | NULL | NULL | ++------+-----------------+----------------------------------+ +``` + +### keywords + +ELEMENT_AT, SUBSCRIPT diff --git a/docs/zh-CN/sql-manual/sql-reference/Data-Types/ARRAY.md b/docs/zh-CN/sql-manual/sql-reference/Data-Types/ARRAY.md new file mode 100644 index 00000000000000..cffe63f3be4e40 --- /dev/null +++ b/docs/zh-CN/sql-manual/sql-reference/Data-Types/ARRAY.md @@ -0,0 +1,84 @@ +--- +{ + "title": "ARRAY", + "language": "zh-CN" +} +--- + + + +## ARRAY + +### description + +ARRAY\ + +由T类型元素组成的数组,不能作为key列使用。目前支持在Duplicate模型的表中使用。 + +T支持的类型有: + +``` +BOOLEAN, TINYINT, SMALLINT, INT, BIGINT, LARGEINT, FLOAT, DOUBLE, DECIMAL, DATE, +DATETIME, CHAR, VARCHAR, STRING +``` + +### example + +建表示例如下: + +``` +mysql> CREATE TABLE `array_test` ( + `id` int(11) NULL COMMENT "", + `c_array` ARRAY NULL COMMENT "" +) ENGINE=OLAP +DUPLICATE KEY(`id`) +COMMENT "OLAP" +DISTRIBUTED BY HASH(`id`) BUCKETS 1 +PROPERTIES ( +"replication_allocation" = "tag.location.default: 1", +"in_memory" = "false", +"storage_format" = "V2" +); +``` + +插入数据示例: + +``` +mysql> INSERT INTO `array_test` VALUES (1, [1,2,3,4,5]); +mysql> INSERT INTO `array_test` VALUES (2, array(6,7,8)), (3, array()), (4, null); +``` + +查询数据示例: + +``` +mysql> SELECT * FROM `array_test`; ++------+-----------------+ +| id | c_array | ++------+-----------------+ +| 1 | [1, 2, 3, 4, 5] | +| 2 | [6, 7, 8] | +| 3 | [] | +| 4 | NULL | ++------+-----------------+ +``` + +### keywords + + ARRAY, array_contains, array_position, element_at