# add_time フィルター関数

Integrations 用の add_time フィルタープラグインを使用すると、スキーマ内の既存の列から値をコピーするか、値を指定することで、新しい時間ベースの列をスキーマに追加できます。

このプラグインは、以下の表で説明する2つのオプションを提供します。

| **オプション** | **説明** |
|  --- | --- |
| to_column | 新しい列名と型を定義します。 |
| from_column | データ内の既存の列を to_column で定義された新しい列にマッピングします。（**または** from_value） |
| from_value | 固定値または増分値を新しい列にマッピングします。（**または** from_column） |


`add_time` フィルターは、すべての Treasure Data Integrations で動作します。

このプラグインは、guess 操作がソースデータ内の time 列を検出できない場合に Source に追加できます。guess 操作は、以下の条件で time 列を見つけられない場合があります：

1. データソースに time 列が存在しない。
2. データソースに time 列が含まれているが、その型が Timestamp または Long ではない。


このトピックの内容：

* [設定](#configuration)
* [ユースケース](#use-cases)
* [ユースケース 1: time ベースの列に 0 を追加する](#use-case-1-add-0s-for-time-based-column)
* [ユースケース 2: from_value 設定を使用して増分値で新しい time 列を追加する](#use-case-2-add-a-new-time-column-with-incremental-value-using-the-from_value-configuration)
* [incremental_time モードでの from_value の例](#from_value-example-with-incremental_time-mode)
* [upload_time モードでの from_value の例](#from_value-example-with-upload_time-mode)
* [ユースケース 3: from_column 設定を使用してデータ内の既存の unixtime(ms) 列を新しい列にマッピングする](#use-case-3-map-an-existing-unixtimems-column-in-data-to-a-new-column-using-the-from_column-configuration)
* [from_column の例](#from_column-example)


## 設定

`load.yml` に type `add_time` の `filter` セクションを追加します。例：

```yaml
in:
...
filters:
- type: add_time
  to_column:
    name: time
    type: timestamp
  from_column: # または from_value を使用して固定または増分時間値を使用
    name: created_at
    timestamp_format: "%Y-%m-%d %H:%M:%S"
out:
...
```

利用可能な[設定オプションの詳細](https://github.com/treasure-data/embulk-filter-add_time/blob/master/README.md#configuration)について学んでください。
問題を避けるため、`add_time` フィルターは `rename` などの他のフィルタープラグインの後に使用することをお勧めします。

## ユースケース

以下は add_time を使用できるいくつかのユースケースです：

### ユースケース 1: time ベースの列に 0 を追加する

time ベースの列がないテーブルがある場合、0 で埋めたい場合があります。その場合は、.yml にこのセクションを追加してください。

```yaml
filters:
- type: add_time
  to_column: {name: time}
  from_value: {value: 0, unix_timestamp_unit: sec}
```

### ユースケース 2: from_value 設定を使用して増分値で新しい time 列を追加する

from_value オプションを使用して、固定値または増分値で新しい time 列を追加できます。from_value は以下のモードをサポートしています：

* fixed_time（デフォルトモード）：to_column セクションで定義された新しい列名が、value パラメータで指定された固定値で追加されます。
* incremental_time：to_column セクションで定義された新しい列名が、タイムスタンプから開始して各レコードごとに 1 秒ずつ増加する値で追加され、タイムスタンプに達した後はラップアラウンドして再びタイムスタンプから開始します。
* upload_time：to_column セクションで定義された新しい列名が、インポートジョブのアップロードが開始された時間に対応する固定値でセットに追加されます。このモードは追加のパラメータを必要としません。スケジュールされた実行に便利です。upload_time モードを使用した計画されたコネクタは、定義されたスケジュール時間を 'time' 列に挿入できます。


#### incremental_time モードでの from_value の例

```yaml
filters:
- type: add_time
  to_column:
    name: time
    type: timestamp
  from_value:
    mode: incremental_time
    from: "2016-01-01 00:00:00 UTC"
    to: "2016-01-01 01:00:00 UTC"
```

#### upload_time モードでの from_value の例

```yaml
filters:
- type: add_time
  to_column:
    name: time
    type: timestamp
  from_value:
    mode: upload_time # スケジュール時間を `time` 列に挿入
```

from_value 設定の詳細と[追加の例](https://github.com/treasure-data/embulk-filter-add_time/blob/master/README.md#from_value-configuration)をご覧ください。

### ユースケース 3: from_column 設定を使用してデータ内の既存の unixtime(ms) 列を新しい列にマッピングする

from_column 設定は、データ内の列の1つの名前と、値を解析して to_column 設定にマッピングするためのフォーマットを指定します。この設定は、ソース列自体の名前を変更するのではなく、name で指定された列から値のコピーを作成します。

#### from_column の例

```yaml
filters:
- type: add_time
  to_column:
    name: time
    type: long
    unix_timestamp_unit: sec
  from_column:
    name: created_at # created_at はデータ内の列
    unix_timestamp_unit: milli # ミリ秒単位の unixtime 型
```

from_column 設定の詳細と[追加の例](https://github.com/treasure-data/embulk-filter-add_time/blob/master/README.md#from_column-configuration)をご覧ください。