# 数组函数
数组操作函数对输入的数组数据进行一些基本操作，如添加元素、查找元素，转换数组并返回操作后的数组数据。
DWS支持的数组函数参考[表1]。
 表1数组函数 
| 函数名称                                                                                            | 功能                                | 使用示例                          |
|:---|:---|:---|
| [array_append(anyarray, anyelement)]    | 向数组末尾添加元素。                          | ``` SELECT array_append(ARRAY[1,2], 3) AS RESULT; ```                         |
| [array_prepend(anyelement, anyarray)]      | 向数组开头添加元素                          | ``` SELECT array_append(ARRAY[1,2], 3) AS RESULT; ```                         |
| [array_cat(anyarray, anyarray)]             | 连接两个数组。                          | ``` SELECT array_cat(ARRAY[1,2,3], ARRAY[4,5]) AS RESULT; ```                 |
| [array_ndims(anyarray)]                   | 返回数组的维数。                         | ``` SELECT array_dims(ARRAY[[1,2,3], [4,5,6]]) AS RESULT; ```                 |
| [array_dims(anyarray)]                   | 返回数组维数的文本表示。                     | ``` SELECT array_dims(ARRAY[[1,2,3], [4,5,6]]) AS RESULT; ```                 |
| [array_length(anyarray, int)]            | 返回数组维度的长度。                       | ``` SELECT array_length(array[1,2,3], 1) AS RESULT; ```                       |
| [array_lower(anyarray, int)]                  | 返回数组维数的下界。                          | ``` SELECT array_lower('[0:2]={1,2,3}'::int[], 1) AS RESULT; ```              |
| [array_upper(anyarray, int)]                | 返回数组维数的上界。                         | ``` SELECT array_upper(ARRAY[1,8,3,7], 1) AS RESULT; ```                      |
| [array_to_string(anyarray, text \[, text\])] | 将数组转换为字符串。                         | ``` SELECT array_to_string(ARRAY[1, 2, 3, NULL, 5], ',', '*') AS RESULT; ```  |
| [string_to_array(text, text \[, text\])]  | 将字符串转换为数组。                         | ``` SELECT string_to_array('xx~^~yy~^~zz', '~^~', 'yy') AS RESULT; ```        |
| [array_flatten(anyarray)]              | 将多维数组转换为一维数组。                      | ``` SELECT array_flatten(ARRAY[1, 2], [3,4]]) AS RESULT; ```                  |
| [array_distinct(anyarray)]                   | 返回去重之后的数组，不统计NULL值。                | ``` SELECT array_distinct(ARRAY[1, 2, 3, 1, NULL, 5]) AS RESULT; ```          |
| [array_uniq(anyarray)]                   | 返回去重之后的数组元素个数。                   | ``` SELECT array_uniq(ARRAY[1, 2, 3, 1, NULL, 5]) AS RESULT; ```              |
| [array_sort(anyarray)]                        | 返回按升序排列后的数组。                      | ``` SELECT array_sort(ARRAY[1, 2, 3, 1, NULL, 5]) AS RESULT; ```              |
| [array_reversesort(anyarray)]             | 返回按降序排列后的数组。                       | ``` SELECT array_reversesort(ARRAY[1, 2, 3, 1, NULL, 5]) AS ```               |
| [unnest(anyarray)]                        | 扩展一个数组为一组行。                       | ``` SELECT unnest(ARRAY[1,2]) AS RESULT; ```                                  |
| [interval(N, N1, N2, N3 ... )]           | 从输入的整数数组中，查找返回最后一个小于等于目标参数n的数组索引。 | ``` SELECT INTERVAL(10, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 10, 11) AS RESULT; ``` |
| [split(text, text)]                      | 将字符串按分隔符进行分隔，并返回数组。                | ``` SELECT SPLIT('a-b-c-d-e', '-') AS RESULT; ```                             |
   
 #### array_append(anyarray, anyelement)
描述：向数组末尾添加元素，只支持一维数组。
返回类型：anyarray
示例：向数组\[1,2\]末尾添加元素3。
```
SELECT array_append(ARRAY[1,2], 3) AS RESULT;
 result  
---------
 {1,2,3}
(1 row)
```
 #### array_prepend(anyelement, anyarray)
描述：向数组开头添加元素，只支持一维数组。
返回类型：anyarray
示例：向数组\[2,3\]开头添加元素1。
```
SELECT array_prepend(1, ARRAY[2,3]) AS RESULT;
 result  
---------
 {1,2,3}
(1 row)
```
 #### array_cat(anyarray, anyarray)
描述：连接两个数组，支持多维数组。
返回类型：anyarray
示例：连接数组\[1,2,3\]和数组\[4,5\]。
```
SELECT array_cat(ARRAY[1,2,3], ARRAY[4,5]) AS RESULT;
   result    
-------------
 {1,2,3,4,5}
(1 row)
```
连接二维数组\[\[1,2\],\[4,5\]\]和一维数组\[6,7\]。
```
SELECT array_cat(ARRAY[[1,2],[4,5]], ARRAY[6,7]) AS RESULT;
       result        
---------------------
 {{1,2},{4,5},{6,7}}
(1 row)
```
 #### array_ndims(anyarray)
描述：返回数组的维数。
返回类型：int
示例：查看数组\[\[1,2,3\], \[4,5,6\]\]的维数。
```
SELECT array_ndims(ARRAY[[1,2,3], [4,5,6]]) AS RESULT;
 result 
--------
      2
(1 row)
```
 #### array_dims(anyarray)
描述：返回数组维数的文本表示。
返回类型：text
示例：获取数组的维度，返回结果表示该数组是一个2行3列的二维数组。
```
SELECT array_dims(ARRAY[[1,2,3], [4,5,6]]) AS RESULT;
   result   
------------
 [1:2][1:3]
(1 row)
```
 #### array_length(anyarray, int)
描述：返回数组维度的长度。
返回类型：int
示例：计算数组\[1,2,3\]在第一维的长度。
```
SELECT array_length(array[1,2,3], 1) AS RESULT;
 result 
--------
      3
(1 row)
```
 #### array_lower(anyarray, int)
描述：返回数组维数的下界。
返回类型：int
示例：查询指定范围的数组\[0:2\]={1,2,3}，在第一维的下界。
```
SELECT array_lower('[0:2]={1,2,3}'::int[], 1) AS RESULT;
 result 
--------
      0
(1 row)
```
 #### array_upper(anyarray, int)
描述：返回数组维数的上界。
返回类型：int
示例：查询数组 \[1, 8, 3, 7\]在第一维的上界。
```
SELECT array_upper(ARRAY[1,8,3,7], 1) AS RESULT;
 result 
--------
      4
(1 row)
```
 #### array_to_string(anyarray, text \[, text\])
描述：将数组转换为字符串，并用指定的分隔符连接，同时支持定义如何处理数组中的NULL。
第一个text作为数组的新分隔符，第二个text替换数组值为NULL的值。
返回类型：text
示例：将数组\[1, 2, 3, NULL, 5\]转换为字符串，用"**,** "分隔元素，并用"**\***"替换NULL值。
```
SELECT array_to_string(ARRAY[1, 2, 3, NULL, 5], ',', '*') AS RESULT;
  result   
-----------
 1,2,3,*,5
(1 row)
```
![](https://support.huaweicloud.com/sqlreference-911-dws/public_sys-resources/note_3.0-zh-cn.png)
该函数的第二个参数text，控制如何处理数组中的NULL元素。如果省略此参数或显式指定为NULL，函数将忽略数组中所有NULL元素，且不会出现在最终输出的字符串中。
例如：
省略第二个参数text的场景。
```
SELECT array_to_string(ARRAY[1, NULL, 3, NULL, 5], ',') AS result;
 result
--------
 1,3,5
(1 row)
```
第二个参数text显式指定为NULL场景。
```
SELECT array_to_string(ARRAY[1, NULL, 3, NULL, 5], ',',NULL) AS RESULT;
 result
--------
 1,3,5
(1 row)
```
 #### string_to_array(text, text \[, text\])
描述：将字符串按指定的分隔符拆分成数组，同时支持替换特定值为NULL。
第二个text为指定的分隔符。第三个可选的text替换特定值为NULL，如果分隔后的子串与第三个可选的text完全匹配，则将其替换为NULL。
返回类型：text\[\]
示例：将字符串xx\~\^\~yy\~\^\~zz按照分隔符"\~\^\~"拆分成数组，并替换 'yy' 值为NULL。
```
SELECT string_to_array('xx~^~yy~^~zz', '~^~', 'yy') AS RESULT;
    result    
--------------
 {xx,NULL,zz}
(1 row)
```
字符串xx\~\^\~yy\~\^\~zz分隔后的子串yy与参数"y"未完全匹配，不会将其替换为NULL。
```
SELECT string_to_array('xx~^~yy~^~zz', '~^~', 'y') AS RESULT;
   result   
------------
 {xx,yy,zz}
(1 row)
```
![](https://support.huaweicloud.com/sqlreference-911-dws/public_sys-resources/note_3.0-zh-cn.png)
- 该函数的第三个参数text，控制替换特定值为NULL。如果省略此参数或显式指定为NULL，函数会将原字符串中连续两个分隔符之间的空子串替换为NULL。 例如：
  省略第三个参数text的场景。
  ```
  SELECT string_to_array('a,,b', ',') AS result;
    result
  ----------
   {a,"",b}
  (1 row)
  ```
  第三个参数text显式指定为NULL场景。
  ```
  SELECT string_to_array('a,,b', ',', NULL) AS result;
    result
  ----------
   {a,"",b}
  (1 row)
  ```
  
- 在string_to_array中，如果分隔符参数是NULL，输入字符串中的每个字符将在结果数组中变成一个独立的元素。如果分隔符是一个空字符串，则整个输入的字符串将变为一个元素的数组。否则输入字符串将在每个分隔字符串处分开。 例如：
  分隔符参数是NULL的场景。
  ```
  SELECT string_to_array('abc', NULL) AS result;
   result
  ---------
   {a,b,c}
  (1 row)
  ```
  分隔符是一个空字符串的场景。
  ```
  SELECT string_to_array('abcde', ' ')AS result;
   result
  ---------
   {abcde}
  (1 row)
  ```
  
 
 #### array_flatten(anyarray)
描述：将多维数组转换为一维数组。该函数仅9.1.1.100及以上集群版本支持。
返回类型：anyarray
示例：
```
SELECT array_flatten(ARRAY[1, 2], [3,4]]) AS RESULT;
  result   
-----------
 1,2,3,4
(1 row)
```
 #### array_distinct(anyarray)
描述：返回去重之后的数组，不统计NULL值。该函数仅9.1.1.100及以上集群版本支持。
返回类型：anyarray
示例：
```
SELECT array_distinct(ARRAY[1, 2, 3, 1, NULL, 5]) AS RESULT;
  result   
-----------
 1,2,3,5
(1 row)
```
![](https://support.huaweicloud.com/sqlreference-911-dws/public_sys-resources/caution_3.0-zh-cn.png)
array_distinct()、array_uniq()、array_sort()、array_reversesort()函数只支持一维数组。
 #### array_uniq(anyarray)
描述：返回去重之后的数组元素个数。如果数组元素包含NULL，也会统计。该函数仅9.1.1.100及以上集群版本支持。
返回类型：int
示例：
```
SELECT array_uniq(ARRAY[1, 2, 3, 1, NULL, 5]) AS RESULT;
  result   
---------
       5
(1 row)
```
 #### array_sort(anyarray)
描述：返回按升序排列后的数组。如果数组元素包含NULL，则输出的排序数组会将NULL排在最后。该函数仅9.1.1.100及以上集群版本支持。
返回类型：anyarray
示例：
```
SELECT array_sort(ARRAY[1, 2, 3, 1, NULL, 5]) AS RESULT;
  result   
---------
 1,1,2,3,5,NULL
(1 row)
```
 #### array_reversesort(anyarray)
描述：返回按降序排列后的数组。如果数组元素包含NULL，则输出的排序数组会将NULL排在最后。该函数仅9.1.1.100及以上集群版本支持。
返回类型：anyarray
示例：
```
SELECT array_reversesort(ARRAY[1, 2, 3, 1, NULL, 5]) AS RESULT;
  result   
---------
 5,3,2,1,1,NULL
(1 row)
```
 #### unnest(anyarray)
描述：扩展一个数组为一组行。
返回类型：setof anyelement
示例：
```
SELECT unnest(ARRAY[1,2]) AS RESULT;
 result 
--------
      1
      2
(2 rows)
```
unnest函数配合[string_to_array(text, text \[, text\])]数组使用。数组转列，先将字符串按逗号分割成数组，然后再把数组转成列：
```
SELECT unnest(string_to_array('a,b,c,d',',')) AS RESULT;
 result
--------
 a
 b
 c
 d
(4 rows)
```
 #### interval(N, N1, N2, N3 ... )
描述：从输入的整数数组中，查找返回最后一个小于等于目标参数n的数组索引。
若n为NULL，返回-1。interval函数不支持interval(N, N1)的场景。
返回类型：int
示例：查找数字10位于后面一串数字划分的哪个区间，并返回对应的区间索引。
```
SELECT INTERVAL(10, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 10, 11) AS RESULT;
 result    
--------
     11
(1 row)
```
 #### split(text, text)
描述：将字符串按分隔符进行分隔，并返回数组。
第一个参数text为字符串，第二个参数text为分隔符。
返回类型：text\[\]
示例：将字符串a-b-c-d-e按照分隔符"-"拆分成多个部分，并返回一个数组。
```
SELECT SPLIT('a-b-c-d-e', '-') AS RESULT;
   result    
-------------
 {a,b,c,d,e}
(1 row)
```
将字符串a-b-c-d-e按照分隔符"-"拆分并提取第四个元素。
```
SELECT SPLIT('a-b-c-d-e', '-')[4] AS RESULT;
 result   
--------
 d
(1 row)
```