Treasure Data TD_TIME関数チートシート


# TD_TIME関数チートシート
Treasure DataのTD_TIME関数をまとめました。

## TD_TIME_RANGE 
### 戻り値：boolean

### 引数
| 引数 | 型 | 設定値 |
|:-:|:-|:-|
|1|int/long |time UNIXTIME
|2|int/long/string |start_time 文字列またはUNIXTIMEで指定可能
|3|int/long/string |end_time 文字列またはUNIXTIMEで指定可能
|4(option)|string default_timezone = 'UTC' | タイムゾーン

第1引数timeがstart_time以下で、end_timeより古い場合（start_time <= time && time <end_time）にtrueを返します。 
end_timeが省略されているかNULLの場合は、未来全て。 start_timeがNULLの場合、過去全てが対象となります。

```sql:例
SELECT文は省略
WHEREに指定する例
  TD_TIME_RANGE(time, '2021-01-01', '2021-01-02','JST')  --日付で期間指定
  TD_TIME_RANGE(time, '2021-01-01 JST')                  --日付以降指定
  TD_TIME_RANGE(time, NULL, '2021-01-01', 'JST')         --To指定 
  TD_TIME_RANGE(time, '2021-01-01', NULL, 'JST')         --From指定
  TD_TIME_RANGE(time, '2021-03-01 09:00:00','2021-03-22 18:00:00','JST')  --日時で期間指定
  TD_TIME_RANGE(time,1609426800,1617116400,'JST')  --期間指定 unix_timestampで指定
```

## TD_SCHEDULED_TIME

### 戻り値：long(UNIXTIME)

### 引数：なし

TDのSaved Queryのスケジュール機能によって、ジョブがスケジュールされた日時を返します。実際のクエリ開始時間が遅れる可能性があるため、戻り値はNOW（）とは異なる場合があります。
クエリがスケジュールされたクエリでない場合、ジョブが発行された時刻を返します。

```sql:例
SELECT TD_SCHEDULED_TIME() ---> スケジュールをcron(44 * * * *)で実行の場合、1616388240 (2021-03-22 13:44:00+0900)
SELECT TD_SCHEDULED_TIME() ---> スケジュールをhourlyで実行の場合、1616392800 (2021-03-22 15:00:00+0900)
```
Saved Queryにスケジュールが設定されていない場合、RUNをクリックするとダイアログボックスが表示され、TD_SCHEDULED_TIMEに設定する日時の登録を行うことになります。


## TD_INTERVAL 

### 戻り値：boolean

### 引数
| 引数 | 型 | 設定値 |
|:-:|:-|:-|
|1|int/long |time UNIXTIME
|2|string |interval
|3(option)|string default_timezone = 'UTC' | タイムゾーン

TD_INTERVALは、相対的な時間範囲を計算するために使用されます。 （絶対的な時間範囲の指定は、TD_TIME_RANGEを使用します。）

```sql:例
SELECT文は省略、タイムゾーンはJST
WHERE 
TD_INTERVAL(time, '-30s','JST')  --クエリ実行から30秒前
TD_INTERVAL(time, '-15m','JST')  --クエリ実行から15分前
TD_INTERVAL(time, '-1h','JST')   --クエリ実行から1時間前
TD_INTERVAL(time, '-1w','JST')   --クエリ実行から1週間前
TD_INTERVAL(time, '-1M','JST')   --クエリ実行から1ヶ月前
TD_INTERVAL(time,'-7d','JST')    --クエリ実行から7日前
TD_INTERVAL(time, '-1h/now','JST') --今から1時間前
TD_INTERVAL(time, '-1h/0d','JST') --今日の初め(2020-03-22 0:00:00)から1時間前
D_INTERVAL(time, '-7d/2021-03-31','JST') --2021-03-31から7日前
TD_INTERVAL(time, '-10d/-1M','JST') --クエリ実行の1分前から10日前
```

## TD_INTERVAL_RANGE

### 戻り値:ARRAY[(start time), (end time)]

### 引数
| 引数 | 型 | 設定値 |
|:-:|:-|:-|
|1|string |interval_string
|2(option)|string default_timezone = 'UTC'|timezone タイムゾーン

TD_INTERVALの日時範囲を確認するために使用することができます。

```sql:例（2021-03-22(JST)にクエリ実行)

SELECT TD_INTERVAL_RANGE('-30s','JST') ---> List [ "2021-03-22 15:53:52+0900", "2021-03-22 15:54:22+0900" ]
SELECT TD_INTERVAL_RANGE('-15m','JST') ---> List [ "2021-03-22 15:42:00+0900", "2021-03-22 15:57:00+0900" ]  --クエリ実行から15分前
SELECT TD_INTERVAL_RANGE('-1h','JST')  ---> List [ "2021-03-22 14:00:00+0900", "2021-03-22 15:00:00+0900" ]  --クエリ実行から1時間前
SELECT TD_INTERVAL_RANGE('-1w','JST')  ---> List [ "2021-03-15 00:00:00+0900", "2021-03-22 00:00:00+0900" ]  --クエリ実行から1週間前
SELECT TD_INTERVAL_RANGE('-1M','JST')  ---> List [ "2021-02-01 00:00:00+0900", "2021-03-01 00:00:00+0900" ]  --クエリ実行から1ヶ月前
SELECT TD_INTERVAL_RANGE('-7d','JST')  ---> List [ "2021-03-15 00:00:00+0900", "2021-03-22 00:00:00+0900" ]   --クエリ実行から7日前
SELECT TD_INTERVAL_RANGE('-1h/now','JST') ---> List [ "2021-03-22 15:00:00+0900", "2021-03-22 16:05:19+0900" ] --今から1時間前
SELECT TD_INTERVAL_RANGE('-1h/0d','JST') ---> List [ "2021-03-21 23:00:00+0900", "2021-03-22 00:00:00+0900" ]  --今日の初め(2020-03-22 0:00:00)から1時間前
SELECT TD_INTERVAL_RANGE('-7d/2021-03-31','JST') ---> List [ "2021-03-24 00:00:00+0900", "2021-03-31 00:00:00+0900" ] --2021-03-31から7日前
SELECT TD_INTERVAL_RANGE('-10d/-1M','JST') ---> List [ "2021-01-22 00:00:00+0900", "2021-02-01 00:00:00+0900" ] --クエリ実行の1ヶ月前から10日前
```

## TD_TIME_ADD

### 戻り値：long(UNIXTIME)

### 引数
| 引数 | 型 | 設定値 |
|:-:|:-|:-|
|1|int/long/string|time
|2|string |duration
|3(option)|string default_timezone = 'UTC' | タイムゾーン

timeに設定した日時からdurationに設定した時間オフセットの日時をUNIXTIMEで返します。
パフォーマンスを考慮し、「年(y)」と「月(m)」は、サポートされていません。

```sql:例
SELECT TD_TIME_ADD('2021-03-22 09:00:00', '1s') ---> 1616403601 (2021-03-22 09:00:01+0000)
SELECT TD_TIME_ADD('2021-03-22 09:00:00', '-1s','JST') ---> 1616371199 (2021-03-22 08:59:59+0900)
SELECT TD_TIME_ADD('2021-03-22 09:00:00', '-1m','JST') ---> 1616371140 (2021-03-22 08:59:00+0900)
SELECT TD_TIME_ADD('2021-03-22 09:00:00', '-1h','JST') ---> 1616367600 (2021-03-22 08:00:00+0900)
SELECT TD_TIME_ADD('2021-03-22 09:00:00', '-1d','JST') ---> 1616284800 (2021-03-21 09:00:00+0900)
SELECT TD_TIME_ADD('2021-03-22 09:00:00', '-1w','JST') ---> 1615766400 (2021-03-15 09:00:00+0900)
```


## TD_TIME_FORMAT

### 戻り値：string(日時の文字列)

### 引数
| 引数 | 型 | 設定値 |
|:-:|:-|:-|
|1|long|time
|2|string |format
|3(option)|string default_timezone = 'UTC' | タイムゾーン

UNIXTIMEを指定した形式の日時の文字列に変換します。（使用可能な形式については、[Supported Time Formats in TD_TIME_FORMAT UDF](https://docs.treasuredata.com/display/public/PD/Supported+Time+Formats+in+TD_TIME_FORMAT+UDF)を参照ください。）

```sql:例
SELECT TD_TIME_FORMAT(1616371200, 'yyyy-MM-dd HH:mm:ss', 'JST') ---> 2021-03-22 09:00:00
SELECT TD_TIME_FORMAT(1616371200, 'yyyy-MM-dd HH:mm:ss z', 'JST') ---> 2021-03-22 09:00:00 GMT+09:00
SELECT TD_TIME_FORMAT(1616371200, 'yyyy-MM-dd HH:mm:ss.SSS', 'JST') ---> 2021-03-22 09:00:00.000
```
その他は[Supported Time Formats in TD_TIME_FORMAT UDF](https://docs.treasuredata.com/display/public/PD/Supported+Time+Formats+in+TD_TIME_FORMAT+UDF)をご参照ください。


## TD_TIME_PARSE

### 戻り値：long(UNIXTIME)

### 引数
| 引数 | 型 | 設定値 |
|:-:|:-|:-|
|1|string |time 日時の文字列
|2(option)|string default_timezone = 'UTC' | タイムゾーン

日時の文字列をUNIXタイムスタンプに変換します。

```sql:例
SELECT TD_TIME_PARSE('2021-03-22 09:00:00') ---> 1616403600
SELECT TD_TIME_PARSE('2021-03-22 09:00:00','JST') ---> 1616371200
SELECT TD_TIME_PARSE('2021-03-22') ---> 1616371200 (2021-03-22 00:00:00+0000)
SELECT TD_TIME_PARSE('2021-03-22','JST') ---> 1616338800 (2021-03-22 00:00:00+0900)

```


## TD_TIME_STRING

### 戻り値：string(日時の文字列)

### 引数
| 引数 | 型 | 設定値 |
|:-:|:-|:-|
|1|long |time UNIXTIME
|2|string |format string [ドキュメント](https://docs.treasuredata.com/display/public/PD/Supported+Presto+and+TD+Functions#SupportedPrestoandTDFunctions-TD_TIME_STRING)を参照
|3(option)|string default_timezone = 'UTC' | タイムゾーン

指定したUNIXTIMEを指定されたformat stringの文字列に変換します。

```sql:例
TD_TIME_STRING(1611657186,'s','JST') ---> 2021-01-26 19:33:06+0900
TD_TIME_STRING(1611657186,'s!','JST') --> 2021-01-26 19:33:06
TD_TIME_STRING(1611657186,'m','JST') ---> 22021-01-26 19:33:00+0900
TD_TIME_STRING(1611657186,'m!','JST') --> 2021-01-26 19:33
```


## TD_DATE_TRUNC

### 戻り値：long(UNIXTIME)

### 引数
| 引数 | 型 | 設定値 |
|:-:|:-|:-|
|1|string |unit
|2|long |time UNIXTIME
|3(option)|string default_timezone = 'UTC' | タイムゾーン

unitに指定した日時のレベルで、日時を切り捨てし、UNIXTIMEで返します。

```sql:例
SELECT TD_DATE_TRUNC('minute', 1616385696) #2021-03-22 04:01:36+0000 ---> 1616385660 (2021-03-22 04:01:00+0000) 分で切り捨て
SELECT TD_DATE_TRUNC('hour', 1616385696) #2021-03-22 04:01:36+0000 ---> 1616385600 (2021-03-22 04:00:00+0000) 時で切り捨て
SELECT TD_DATE_TRUNC('day', 1616385696) #2021-03-22 04:01:36+0000 ---> 1616371200 (2021-03-22 00:00:00+0000) 日で切り捨て
SELECT TD_DATE_TRUNC('week', 1616385696) #2021-03-22 04:01:36+0000 ---> 1616371200 (2021-03-22 00:00:00+0000) 週で切り捨て
SELECT TD_DATE_TRUNC('month', 1616385696) #2021-03-22 04:01:36+0000 ---> 1614556800 (2021-03-01 00:00:00+0000) 月で切り捨て
SELECT TD_DATE_TRUNC('quarter', 1616385696) #2021-03-22 04:01:36+0000 ---> 1609459200 (2021-01-01 00:00:00+0000) 四半期で切り捨て
SELECT TD_DATE_TRUNC('year', 1616385696) #2021-03-22 04:01:36+0000 ---> 1609459200 (2021-01-01 00:00:00+0000) 年で切り捨て
SELECT TD_DATE_TRUNC('minute', 1616385696,'JST') #2021-03-22 13:01:36+0900 ---> 1616385660 (2021-03-22 13:01:00+0900) 分で切り捨て、タイムゾーン指定

```



# 参考

https://docs.treasuredata.com/display/public/PD/Supported+Presto+and+TD+Functions