# SQL 函数
<a name="s3-select-sql-reference-sql-functions"></a>

**重要**  
不再向新客户提供 Amazon S3 Select。Amazon S3 Select 的现有客户可以像往常一样继续使用该功能。[了解详情](https://aws.amazon.com/blogs/storage/how-to-optimize-querying-your-data-in-amazon-s3/) 

Amazon S3 Select 支持以下 SQL 函数。

**Topics**
+ [聚合函数](s3-select-sql-reference-aggregate.md)
+ [条件函数](s3-select-sql-reference-conditional.md)
+ [转换函数](s3-select-sql-reference-conversion.md)
+ [日期函数](s3-select-sql-reference-date.md)
+ [字符串函数](s3-select-sql-reference-string.md)

# 聚合函数
<a name="s3-select-sql-reference-aggregate"></a>

**重要**  
不再向新客户提供 Amazon S3 Select。Amazon S3 Select 的现有客户可以像往常一样继续使用该功能。[了解详情](https://aws.amazon.com/blogs/storage/how-to-optimize-querying-your-data-in-amazon-s3/) 

Amazon S3 Select 支持以下聚合函数。


| 函数 | 参数类型 | 返回类型 | 
| --- | --- | --- | 
| `AVG(expression)` | `INT`, `FLOAT`, `DECIMAL` | `DECIMAL` 适用于 `INT` 参数，`FLOAT` 适用于浮点型参数；否则与参数数据类型相同。 | 
| `COUNT` |  `-`  | `INT` | 
| `MAX(expression)` | `INT`, `DECIMAL` | 和参数类型相同。 | 
| `MIN(expression)` | `INT`, `DECIMAL` | 和参数类型相同。 | 
| `SUM(expression)` | `INT`, `FLOAT`, `DOUBLE`, `DECIMAL` | `INT` 适用于 `INT` 参数，`FLOAT` 适用于浮点型参数；否则与参数数据类型相同。 | 

## SUM 示例
<a name="s3-select-sql-reference-aggregate-case-examples"></a>

要聚合 [S3 清单报告](https://docs.aws.amazon.com/AmazonS3/latest/userguide/storage-inventory.html)中某个文件夹的对象总大小，请使用 `SUM` 表达式。

以下 S3 清单报告是使用 GZIP 压缩的 CSV 文件。共有三列。
+ 第一列是 S3 清单报告所用于的 S3 桶（*`DOC-EXAMPLE-BUCKET`*）的名称。
+ 第二列是唯一标识桶中对象的对象键名称。

  第一行中的 `example-folder/` 值表示文件夹 `example-folder`。在 Amazon S3 中，当您在桶中创建文件夹时，S3 使用设置为您提供的文件夹名称的键创建一个 0 字节对象。

  第二行中的 `example-folder/object1` 值表示文件夹 `example-folder` 中的对象 `object1`。

  第三行中的 `example-folder/object2` 值表示文件夹 `example-folder` 中的对象 `object2`。

  有关 S3 文件夹的更多信息，请参阅[使用文件夹在 Amazon S3 控制台中整理对象](using-folders.md)。
+ 第三列是对象大小（以字节为单位）。

```
"DOC-EXAMPLE-BUCKET","example-folder/","0"
"DOC-EXAMPLE-BUCKET","example-folder/object1","2011267"
"DOC-EXAMPLE-BUCKET","example-folder/object2","1570024"
```

要使用 `SUM` 表达式计算文件夹 `example-folder` 的总大小，请使用 Amazon S3 Select 运行 SQL 查询。

```
SELECT SUM(CAST(_3 as INT)) FROM s3object s WHERE _2 LIKE 'example-folder/%' AND _2 != 'example-folder/';
```

查询结果：

```
3581291
```

# 条件函数
<a name="s3-select-sql-reference-conditional"></a>

**重要**  
不再向新客户提供 Amazon S3 Select。Amazon S3 Select 的现有客户可以像往常一样继续使用该功能。[了解详情](https://aws.amazon.com/blogs/storage/how-to-optimize-querying-your-data-in-amazon-s3/) 

Amazon S3 Select 支持以下条件函数。

**Topics**
+ [CASE](#s3-select-sql-reference-case)
+ [COALESCE](#s3-select-sql-reference-coalesce)
+ [NULLIF](#s3-select-sql-reference-nullif)

## CASE
<a name="s3-select-sql-reference-case"></a>

`CASE` 表达式是一种条件表达式，类似于其他语言中的 `if/then/else` 语句。`CASE` 用于指定存在多个条件时的结果。有两种类型的 `CASE` 表达式：简单和搜索。

在简单 `CASE` 表达式中，将一个表达式与一个值比较。在找到匹配项时，将应用 `THEN` 子句中的指定操作。如果未找到匹配项，则应用 `ELSE` 子句中的操作。

在搜索 `CASE` 表达式中，基于布尔表达式计算每个 `CASE`，而且 `CASE` 语句会返回第一个匹配的 `CASE`。如果在 `WHEN` 子句中未找到匹配的 `CASE`，则返回 `ELSE` 子句中的操作。

### 语法
<a name="s3-select-sql-reference-case-syntax"></a>

**注意**  
目前，Amazon S3 Select 不支持 `ORDER BY` 或包含新行的查询。请确保使用不带换行符的查询。

以下是用于匹配条件的简单 `CASE` 语句：

```
CASE expression WHEN value THEN result [WHEN...] [ELSE result] END					
```

以下是用于计算每个条件的搜索 `CASE` 语句：

```
CASE WHEN boolean condition THEN result [WHEN ...] [ELSE result] END					
```

### 示例
<a name="s3-select-sql-reference-case-examples"></a>

**注意**  
如果您使用 Amazon S3 控制台运行以下示例，并且 CSV 文件包含标题行，请选择**排除第一行 CSV 数据**。

**示例 1：**使用简单 `CASE` 表达式以在查询中将 `New York City` 替换为 `Big Apple`。将所有其他城市名称替换为 `other`。

```
SELECT venuecity, CASE venuecity WHEN 'New York City' THEN 'Big Apple' ELSE 'other' END FROM S3Object;
```

查询结果：

```
venuecity        |   case
-----------------+-----------
Los Angeles      | other
New York City    | Big Apple
San Francisco    | other
Baltimore        | other
...
```

**示例 2：**使用搜索 `CASE` 表达式来基于单个门票销售的 `pricepaid` 值分配组编号：

```
SELECT pricepaid, CASE WHEN CAST(pricepaid as FLOAT) < 10000 THEN 'group 1' WHEN CAST(pricepaid as FLOAT) > 10000 THEN 'group 2' ELSE 'group 3' END FROM S3Object;					
```

查询结果：

```
pricepaid |  case
-----------+---------
12624.00 | group 2
10000.00 | group 3
10000.00 | group 3
9996.00 | group 1
9988.00 | group 1
...
```

## COALESCE
<a name="s3-select-sql-reference-coalesce"></a>

`COALESCE` 按顺序评估参数并返回第一个非未知值，即第一个非空或非缺失值。此函数无法传播空值和缺失值。

### 语法
<a name="s3-select-sql-reference-coalesce-syntax"></a>

```
COALESCE ( expression, expression, ... )
```

### 参数
<a name="s3-select-sql-reference-coalesce-parameters"></a>

 *`expression`*   
对其执行函数的目标表达式。

### 示例
<a name="s3-select-sql-reference-coalesce-examples"></a>

```
COALESCE(1)                -- 1
COALESCE(null)             -- null
COALESCE(null, null)       -- null
COALESCE(missing)          -- null
COALESCE(missing, missing) -- null
COALESCE(1, null)          -- 1
COALESCE(null, null, 1)    -- 1
COALESCE(null, 'string')   -- 'string'
COALESCE(missing, 1)       -- 1
```

## NULLIF
<a name="s3-select-sql-reference-nullif"></a>

给定两个表达式，如果两个表达式的计算结果为相同值，则 `NULLIF` 返回 `NULL`；否则 `NULLIF` 返回第一个表达式的计算结果。

### 语法
<a name="s3-select-sql-reference-nullif-syntax"></a>

```
NULLIF ( expression1, expression2 )
```

### 参数
<a name="s3-select-sql-reference-nullif-parameters"></a>

 `expression1, expression2`   
对其执行函数的目标表达式。

### 示例
<a name="s3-select-sql-reference-nullif-examples"></a>

```
NULLIF(1, 1)             -- null
NULLIF(1, 2)             -- 1
NULLIF(1.0, 1)           -- null
NULLIF(1, '1')           -- 1
NULLIF([1], [1])         -- null
NULLIF(1, NULL)          -- 1
NULLIF(NULL, 1)          -- null
NULLIF(null, null)       -- null
NULLIF(missing, null)    -- null
NULLIF(missing, missing) -- null
```

# 转换函数
<a name="s3-select-sql-reference-conversion"></a>

**重要**  
不再向新客户提供 Amazon S3 Select。Amazon S3 Select 的现有客户可以像往常一样继续使用该功能。[了解详情](https://aws.amazon.com/blogs/storage/how-to-optimize-querying-your-data-in-amazon-s3/) 

Amazon S3 Select 支持以下转换函数。

**Topics**
+ [CAST](#s3-select-sql-reference-cast)

## CAST
<a name="s3-select-sql-reference-cast"></a>

`CAST` 函数将一种类型的实体 (如计算结果为单个值的表达式) 转换为另一种类型。

### 语法
<a name="s3-select-sql-reference-cast-syntax"></a>

```
CAST ( expression AS data_type )
```

### 参数
<a name="s3-select-sql-reference-cast-parameters"></a>

 *`expression`*   
一个或多个值、运算符和计算结果为值的 SQL 函数的组合。

 *`data_type`*   
要将表达式转换到的目标数据类型，如 `INT`。有关支持的数据类型的列表，请参阅 [数据类型](s3-select-sql-reference-data-types.md)。

### 示例
<a name="s3-select-sql-reference-cast-examples"></a>

```
CAST('2007-04-05T14:30Z' AS TIMESTAMP)
CAST(0.456 AS FLOAT)
```

# 日期函数
<a name="s3-select-sql-reference-date"></a>

**重要**  
不再向新客户提供 Amazon S3 Select。Amazon S3 Select 的现有客户可以像往常一样继续使用该功能。[了解详情](https://aws.amazon.com/blogs/storage/how-to-optimize-querying-your-data-in-amazon-s3/) 

Amazon S3 Select 支持以下日期函数。

**Topics**
+ [DATE\$1ADD](#s3-select-sql-reference-date-add)
+ [DATE\$1DIFF](#s3-select-sql-reference-date-diff)
+ [EXTRACT](#s3-select-sql-reference-extract)
+ [TO\$1STRING](#s3-select-sql-reference-to-string)
+ [TO\$1TIMESTAMP](#s3-select-sql-reference-to-timestamp)
+ [UTCNOW](#s3-select-sql-reference-utcnow)

## DATE\$1ADD
<a name="s3-select-sql-reference-date-add"></a>

给定日期部分、数量和时间戳，`DATE_ADD` 返回通过修改由数量的日期部分而更新的时间戳。

### 语法
<a name="s3-select-sql-reference-date-add-syntax"></a>

```
DATE_ADD( date_part, quantity, timestamp )
```

### 参数
<a name="s3-select-sql-reference-date-add-parameters"></a>

*`date_part`*   
指定要修改的日期部分。这可能是以下值之一：  
+ 年
+ 个月
+ day
+ 小时
+ minute
+ 秒

 *`quantity`*   
应用到已更新的时间戳的值。`quantity` 的正值添加到时间戳的 date\$1part，并减去负值。

 *`timestamp`*   
对其执行函数的目标时间戳。

### 示例
<a name="s3-select-sql-reference-date-add-examples"></a>

```
DATE_ADD(year, 5, `2010-01-01T`)                -- 2015-01-01 (equivalent to 2015-01-01T)
DATE_ADD(month, 1, `2010T`)                     -- 2010-02T (result will add precision as necessary)
DATE_ADD(month, 13, `2010T`)                    -- 2011-02T
DATE_ADD(day, -1, `2017-01-10T`)                -- 2017-01-09 (equivalent to 2017-01-09T)
DATE_ADD(hour, 1, `2017T`)                      -- 2017-01-01T01:00-00:00
DATE_ADD(hour, 1, `2017-01-02T03:04Z`)          -- 2017-01-02T04:04Z
DATE_ADD(minute, 1, `2017-01-02T03:04:05.006Z`) -- 2017-01-02T03:05:05.006Z
DATE_ADD(second, 1, `2017-01-02T03:04:05.006Z`) -- 2017-01-02T03:04:06.006Z
```

## DATE\$1DIFF
<a name="s3-select-sql-reference-date-diff"></a>

给定日期部分和两个有效的时间戳，`DATE_DIFF` 返回日期部分的不同之处。当 `date_part` 的 `timestamp1` 值大于 `date_part` 的 `timestamp2` 值时，返回值为负整数。当 `date_part` 的 `timestamp1` 值小于 `date_part` 的 `timestamp2` 值时，返回值为正整数。

### 语法
<a name="s3-select-sql-reference-date-diff-syntax"></a>

```
DATE_DIFF( date_part, timestamp1, timestamp2 )
```

### 参数
<a name="s3-select-sql-reference-date-diff-parameters"></a>

 **`date_part`**   
指定要比较的时间戳部分。有关 `date_part` 的定义，请参阅[DATE\$1ADD](#s3-select-sql-reference-date-add)。

 **`timestamp1`**   
要比较的第一个时间戳。

 **`timestamp2`**   
要比较的第二个时间戳。

### 示例
<a name="s3-select-sql-reference-date-diff-examples"></a>

```
DATE_DIFF(year, `2010-01-01T`, `2011-01-01T`)            -- 1
DATE_DIFF(year, `2010T`, `2010-05T`)                     -- 4 (2010T is equivalent to 2010-01-01T00:00:00.000Z)
DATE_DIFF(month, `2010T`, `2011T`)                       -- 12
DATE_DIFF(month, `2011T`, `2010T`)                       -- -12
DATE_DIFF(day, `2010-01-01T23:00`, `2010-01-02T01:00`) -- 0 (need to be at least 24h apart to be 1 day apart)
```

## EXTRACT
<a name="s3-select-sql-reference-extract"></a>

给定日期部分和时间戳，`EXTRACT` 返回时间戳的日期部分的值。

### 语法
<a name="s3-select-sql-reference-extract-syntax"></a>

```
EXTRACT( date_part FROM timestamp )
```

### 参数
<a name="s3-select-sql-reference-extract-parameters"></a>

 **`date_part`**   
指定时间戳中要提取的部分。这可能是以下值之一：  
+ `YEAR`
+ `MONTH`
+ `DAY`
+ `HOUR`
+ `MINUTE`
+ `SECOND`
+ `TIMEZONE_HOUR`
+ `TIMEZONE_MINUTE`

 **`timestamp`**   
对其执行函数的目标时间戳。

### 示例
<a name="s3-select-sql-reference-extract-examples"></a>

```
EXTRACT(YEAR FROM `2010-01-01T`)                           -- 2010
EXTRACT(MONTH FROM `2010T`)                                -- 1 (equivalent to 2010-01-01T00:00:00.000Z)
EXTRACT(MONTH FROM `2010-10T`)                             -- 10
EXTRACT(HOUR FROM `2017-01-02T03:04:05+07:08`)             -- 3
EXTRACT(MINUTE FROM `2017-01-02T03:04:05+07:08`)           -- 4
EXTRACT(TIMEZONE_HOUR FROM `2017-01-02T03:04:05+07:08`)    -- 7
EXTRACT(TIMEZONE_MINUTE FROM `2017-01-02T03:04:05+07:08`)  -- 8
```

## TO\$1STRING
<a name="s3-select-sql-reference-to-string"></a>

给定时间戳和格式模式，`TO_STRING` 以指定格式返回时间戳的字符串表示形式。

### 语法
<a name="s3-select-sql-reference-size-syntax"></a>

```
TO_STRING ( timestamp time_format_pattern )
```

### 参数
<a name="s3-select-sql-reference-size-parameters"></a>

 *`timestamp`*   
对其执行函数的目标时间戳。

 *`time_format_pattern`*   
具有以下特殊字符解释的字符串：      
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/AmazonS3/latest/userguide/s3-select-sql-reference-date.html)

### 示例
<a name="s3-select-sql-reference-size-examples"></a>

```
TO_STRING(`1969-07-20T20:18Z`,  'MMMM d, y')                    -- "July 20, 1969"
TO_STRING(`1969-07-20T20:18Z`, 'MMM d, yyyy')                   -- "Jul 20, 1969"
TO_STRING(`1969-07-20T20:18Z`, 'M-d-yy')                        -- "7-20-69"
TO_STRING(`1969-07-20T20:18Z`, 'MM-d-y')                        -- "07-20-1969"
TO_STRING(`1969-07-20T20:18Z`, 'MMMM d, y h:m a')               -- "July 20, 1969 8:18 PM"
TO_STRING(`1969-07-20T20:18Z`, 'y-MM-dd''T''H:m:ssX')           -- "1969-07-20T20:18:00Z"
TO_STRING(`1969-07-20T20:18+08:00Z`, 'y-MM-dd''T''H:m:ssX')     -- "1969-07-20T20:18:00Z"
TO_STRING(`1969-07-20T20:18+08:00`, 'y-MM-dd''T''H:m:ssXXXX')   -- "1969-07-20T20:18:00+0800"
TO_STRING(`1969-07-20T20:18+08:00`, 'y-MM-dd''T''H:m:ssXXXXX')  -- "1969-07-20T20:18:00+08:00"
```

## TO\$1TIMESTAMP
<a name="s3-select-sql-reference-to-timestamp"></a>

给定字符串，`TO_TIMESTAMP` 将其转换为时间戳。`TO_TIMESTAMP` 是 `TO_STRING` 的逆运算。

### 语法
<a name="s3-select-sql-reference-to-timestamp-syntax"></a>

```
TO_TIMESTAMP ( string )
```

### 参数
<a name="s3-select-sql-reference-to-timestamp-parameters"></a>

 *`string`*   
对其执行函数的目标字符串。

### 示例
<a name="s3-select-sql-reference-to-timestamp-examples"></a>

```
TO_TIMESTAMP('2007T')                         -- `2007T`
TO_TIMESTAMP('2007-02-23T12:14:33.079-08:00') -- `2007-02-23T12:14:33.079-08:00`
```

## UTCNOW
<a name="s3-select-sql-reference-utcnow"></a>

`UTCNOW` 以时间戳的形式返回当前时间（UTC）。

### 语法
<a name="s3-select-sql-reference-utcnow-syntax"></a>

```
UTCNOW()
```

### 参数
<a name="s3-select-sql-reference-utcnow-parameters"></a>

`UTCNOW` 不带任何参数。

### 示例
<a name="s3-select-sql-reference-utcnow-examples"></a>

```
UTCNOW() -- 2017-10-13T16:02:11.123Z
```

# 字符串函数
<a name="s3-select-sql-reference-string"></a>

**重要**  
不再向新客户提供 Amazon S3 Select。Amazon S3 Select 的现有客户可以像往常一样继续使用该功能。[了解详情](https://aws.amazon.com/blogs/storage/how-to-optimize-querying-your-data-in-amazon-s3/) 

Amazon S3 Select 支持以下字符串函数。

**Topics**
+ [CHAR\$1LENGTH, CHARACTER\$1LENGTH](#s3-select-sql-reference-char-length)
+ [LOWER](#s3-select-sql-reference-lower)
+ [SUBSTRING](#s3-select-sql-reference-substring)
+ [TRIM](#s3-select-sql-reference-trim)
+ [UPPER](#s3-select-sql-reference-upper)

## CHAR\$1LENGTH, CHARACTER\$1LENGTH
<a name="s3-select-sql-reference-char-length"></a>

`CHAR_LENGTH`（或 `CHARACTER_LENGTH`）计算指定字符串中的字符数。

**注意**  
`CHAR_LENGTH` 和 `CHARACTER_LENGTH` 是同义词。

### 语法
<a name="s3-select-sql-reference-char-length-syntax"></a>

```
CHAR_LENGTH ( string )
```

### 参数
<a name="s3-select-sql-reference-char-length-parameters"></a>

 *`string`*   
对其执行函数的目标字符串。

### 示例
<a name="s3-select-sql-reference-char-length-examples"></a>

```
CHAR_LENGTH('')          -- 0
CHAR_LENGTH('abcdefg')   -- 7
```

## LOWER
<a name="s3-select-sql-reference-lower"></a>

给定字符串，`LOWER` 将所有大写字符转换为小写字符。所有非大写字符保持不变。

### 语法
<a name="s3-select-sql-reference-lower-syntax"></a>

```
LOWER ( string )
```

### 参数
<a name="s3-select-sql-reference-lower-parameters"></a>

 **`string`**   
对其执行函数的目标字符串。

### 示例
<a name="s3-select-sql-reference-lower-examples"></a>

```
LOWER('AbCdEfG!@#$') -- 'abcdefg!@#$'
```

## SUBSTRING
<a name="s3-select-sql-reference-substring"></a>

指定字符串、起始索引和长度（可选)，`SUBSTRING` 返回从起始索引直至字符串结尾处的子字符串，或最大长度为输入的字符串长度的子字符串。

**注意**  
输入字符串的首字符的索引位置为 1。  
 如果 `start` < 1，且未指定长度，则索引位置设置为 1。
 如果 `start` < 1，且指定了长度，则索引位置设置为 `start + length -1`。
 如果 `start + length -1` < 0，则返回一个空字符串。
 如果 `start + length -1` > = 0，则返回从索引位置 1 开始的长度为 `start + length - 1` 的子字符串。

### 语法
<a name="s3-select-sql-reference-substring-syntax"></a>

```
SUBSTRING( string FROM start [ FOR length ] )
```

### 参数
<a name="s3-select-sql-reference-substring-parameters"></a>

 **`string`**   
对其执行函数的目标字符串。

 **`start`**   
字符串的开始位置。

 **`length`**   
要返回的子字符串的长度。如果不存在，则执行到字符串的结尾。

### 示例
<a name="s3-select-sql-reference-substring-examples"></a>

```
SUBSTRING("123456789", 0)      -- "123456789"
SUBSTRING("123456789", 1)      -- "123456789"
SUBSTRING("123456789", 2)      -- "23456789"
SUBSTRING("123456789", -4)     -- "123456789"
SUBSTRING("123456789", 0, 999) -- "123456789" 
SUBSTRING("123456789", 1, 5)   -- "12345"
```

## TRIM
<a name="s3-select-sql-reference-trim"></a>

从字符串中剪裁前导或尾随字符。要删除的原定设置字符为空格（`' '`）。

### 语法
<a name="s3-select-sql-reference-trim-syntax"></a>

```
TRIM ( [[LEADING | TRAILING | BOTH remove_chars] FROM] string )
```

### 参数
<a name="s3-select-sql-reference-trim-parameters"></a>

 **`string`**   
对其执行函数的目标字符串。

 `LEADING` \$1 `TRAILING` \$1 `BOTH`   
此参数指示是否剪裁前导和/或尾随字符。

 **`remove_chars`**   
要删除的一组字符。`remove_chars` 可能是长度 > 1 的字符串。此函数返回包含在已删除字符串开头或结尾发现的 `remove_chars` 中任何字符的字符串。

### 示例
<a name="s3-select-sql-reference-trim-examples"></a>

```
TRIM('       foobar         ')               -- 'foobar'
TRIM('      \tfoobar\t         ')            -- '\tfoobar\t'
TRIM(LEADING FROM '       foobar         ')  -- 'foobar         '
TRIM(TRAILING FROM '       foobar         ') -- '       foobar'
TRIM(BOTH FROM '       foobar         ')     -- 'foobar'
TRIM(BOTH '12' FROM '1112211foobar22211122') -- 'foobar'
```

## UPPER
<a name="s3-select-sql-reference-upper"></a>

给定字符串，`UPPER` 将所有小写字符转换为大写字符。所有非小写字符保持不变。

### 语法
<a name="s3-select-sql-reference-upper-syntax"></a>

```
UPPER ( string )
```

### 参数
<a name="s3-select-sql-reference-upper-parameters"></a>

 **`string`**   
对其执行函数的目标字符串。

### 示例
<a name="s3-select-sql-reference-upper-examples"></a>

```
UPPER('AbCdEfG!@#$') -- 'ABCDEFG!@#$'
```