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

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

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

**Topics**
+ [DATE\_ADD](#s3-select-sql-reference-date-add)
+ [DATE\_DIFF](#s3-select-sql-reference-date-diff)
+ [EXTRACT](#s3-select-sql-reference-extract)
+ [TO\_STRING](#s3-select-sql-reference-to-string)
+ [TO\_TIMESTAMP](#s3-select-sql-reference-to-timestamp)
+ [UTCNOW](#s3-select-sql-reference-utcnow)

## DATE\_ADD
<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\_part，并减去负值。

 *`{{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\_DIFF
<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\_ADD](#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\_STRING
<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.amazonaws.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\_TIMESTAMP
<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
```