# Treasure Data Data Exchange Export Integration

Treasure Dataコネクタを使用して、ジョブ結果をTreasure Dataデータベースに書き込むことができます。通常、このコネクタは、あるTreasure DataアカウントからTreasure Dataアカウントにデータをエクスポートするために使用されます。

あるTDアカウントから別のTDアカウントへのジョブ結果の書き込みに関するサンプルワークフローについては、[Treasure Boxes](https://github.com/treasure-data/treasure-boxes/tree/master/td/another_td)を参照してください。

アカウント内のあるテーブルから同じアカウント内の別のテーブルにデータを書き込むためにこのコネクタを使用することは強くお勧めしません。代わりに、最高のパフォーマンスを得るために「INSERT INTO」クエリまたは「INSERT OVERWRITE/CREATE TABLE AS SELECT」クエリを使用してください。Presto：「CREATE TABLE AS SELECT」または「INSERT INTO」 Hive：「INSERT INTO/OVERWRITE」

## 前提条件

- TD [Toolbelt](https://toolbelt.treasuredata.com/)を含むTreasure Dataの基本的な知識。


## 基本的な使用方法

TD ConsoleまたはCLIから接続を設定できます。

## TD Consoleで接続を作成する

TD Console内から接続を設定できます。アカウント間転送を完了するには、ターゲットのTreasure Dataアカウントから開始します。ターゲットアカウントプロファイルからAPI Key情報をコピーする必要があります。

### API Key情報を取得する

1. **TD Console** > **My Settings**に移動します。管理者権限が必要です。
![](/assets/image-20200513-172241.5c1fd8360e6e917db074642a3c64e44eebb8437b573de805f2af6aab6c90ba6c.e4e4f55a.png)
2. **API Keys**を選択します。
![](/assets/image-20200513-173834.f0a0fc83c7c560d2b61b90a7aaf744608ec66e1f1fbfbaece53dbcd901f601b8.e4e4f55a.png)
3. 必要に応じてアクセスを検証します。
![](/assets/image-20200513-174119.f2995567ec7192e1ab7645862385a7a8fe781aa209d90f43e7e627c6e199047b.e4e4f55a.png)
4. 検証が完了してプロファイルに戻ると、マスターキーと書き込み専用キーの両方が表示されます。Write-only API keyをハイライトします。それを選択すると、自動的にクリップボードにコピーされます。
![](/assets/image-20200513-175122.921f399aea98b7b9799edd4a696979114197fa1a4f0d412398cba5c67e70d4f6.e4e4f55a.png)![](/assets/image-20200513-174543.be19e382e9fe1cb13dd26b549030fecc822723c49fdf29b22685cdb03e4c41d4.e4e4f55a.png)


データ転送がmode=replaceなどで既存のデータを更新する場合は、書き込み専用キーの代わりにマスターキーを使用する必要があります。

### 新しい認証を作成する

データ接続を設定する際、統合にアクセスするための認証を提供します。Treasure Dataでは、認証を設定してからソース情報を指定します。

1. **TD Console**を開きます。
2. **Integrations Hub** > **Catalog**に移動します。
3. Treasure Dataタイルを検索して選択します。
![](/assets/image-20200513-180817.290d16ad023e623f4ac349d5101008c4111197c95ea0d544bd9c79869ca49733.e4e4f55a.png)
4. **Create**を選択します。ターゲットアカウントから書き込み専用**API Key**を入力します。**API Hostname**には、エクスポートに使用するサーバーを入力します。フィールドを空白のままにして、リージョンのデフォルトサーバーを使用できます。または、次のいずれかの値を入力できます：
  - US: [*api.treasuredata.com*](http://api.treasuredata.com)
  - JP: [*api.treasuredata.co.jp*](http://api.treasuredata.co.jp)
  - EU01: [*api.eu01.treasuredata.com*](http://api.eu01.treasuredata.com)
  - AP02 (Korea): [*api.api02.treasuredata.com*](http://api.api02.treasuredata.com)


![](/assets/image-20200513-181011.db17ca82046db3cfa4bac40094e86d1336f22cde90ac6f6a70fb7e9e9f628944.e4e4f55a.png)

1. **Continue**を選択します。接続に名前を付けて**Create Connectionを選択します。**


あるリージョンから別のリージョンにデータを書き込む場合、例えばAWS USからAWS JPの場合、API Hostnameフィールドは必須です。

### Treasure Data Connectorで出力を指定する

転送を作成するには、データ接続を設定するクエリを作成または再利用します。

1. **TD Console**を開きます。
2. Data Workbench > Queriesに移動します。データをエクスポートするために使用する予定のクエリをハイライトします。
3. クエリエディタの右上にある**Export Results**を選択します。
![](/assets/image-20200513-203249.de106fdc17b785c33dca5a00b00d63e66453cd0b3fb074638715ead7768f4400.e4e4f55a.png)

```sql
SELECT code, COUNT(1) FROM www_access GROUP BY code
```
4. **Choose Integration**ダイアログが開きます。
![](/assets/image-20200513-202807.858b6fbbfd044c51a986cc90474cf386233b53729ac171ff1189171d158b4cf1.e4e4f55a.png)
5. **Use Existing Integration**を選択し、保存された認証の名前を検索します。


### パラメータの指定

1. 認証を選択した後、**Next**を選択します。**Export Results**ダイアログが開きます。
![](/assets/treasuredatadde.b223eeb60dde65c060f8a57a544233ba864ea1e02fb197c3e34507cbe90bfe03.e4e4f55a.png)
2. パラメータを指定し、**Done**を選択します。


| Parameters | Description |
|  --- | --- |
| Database name (required) | 既存のデータベースの名前。 |
| Table name (required) | テーブル名。テーブルが存在しない場合は新しいテーブルが作成されます。 |
| Mode (required) | データをインポートするためのAppendまたはReplaceメソッドを選択します。- **Append**（デフォルト）-データインポート結果がテーブルに追加されます。テーブルが存在しない場合は作成されます。
- **Replace**-既存のテーブルの全体の内容をクエリの結果出力で置き換えます。テーブルが存在しない場合は、新しいテーブルが作成されます。

 |
| Time (optional) | ユーザー定義の時間値。クエリ結果に時間カラムがない場合に適用されます。 |
| File split size (KB) | ファイルサイズがこの値以上の場合にファイルを分割するために使用します（16MB-512MB） |


### (オプション) Query Export ジョブをスケジュールする

Scheduled Jobs と Result Export を使用して、指定したターゲット宛先に出力結果を定期的に書き込むことができます。

Treasure Data のスケジューラー機能は、高可用性を実現するために定期的なクエリ実行をサポートしています。

2 つの仕様が競合するスケジュール仕様を提供する場合、より頻繁に実行するよう要求する仕様が優先され、もう一方のスケジュール仕様は無視されます。

例えば、cron スケジュールが `'0 0 1 * 1'` の場合、「月の日」の仕様と「週の曜日」が矛盾します。前者の仕様は毎月 1 日の午前 0 時 (00:00) に実行することを要求し、後者の仕様は毎週月曜日の午前 0 時 (00:00) に実行することを要求するためです。後者の仕様が優先されます。

#### TD Console を使用してジョブをスケジュールする

1. **Data Workbench > Queries** に移動します
2. 新しいクエリを作成するか、既存のクエリを選択します。
3. **Schedule** の横にある None を選択します。
![](/assets/image2021-1-15_17-28-51.f1b242f6ecc7666a0097fdf37edd1682786ec11ef80eff68c66f091bc405c371.0f87d8d4.png)
4. ドロップダウンで、次のスケジュールオプションのいずれかを選択します:
![](/assets/image2021-1-15_17-29-47.45289a1c99256f125f4d887e501e204ed61f02223fde0927af5f425a89ace0c0.0f87d8d4.png)
| ドロップダウン値 | 説明 |
|  --- | --- |
| Custom cron... | [Custom cron... の詳細](#custom-cron-details)を参照してください。 |
| @daily (midnight) | 指定されたタイムゾーンで 1 日 1 回午前 0 時 (00:00 am) に実行します。 |
| @hourly (:00) | 毎時 00 分に実行します。 |
| None | スケジュールなし。 |


#### Custom cron... の詳細

![](/assets/image2021-1-15_17-30-23.0f94a8aa5f75ea03e3fec0c25b0640cd59ee48d1804a83701e5f2372deae466c.0f87d8d4.png)

| **Cron 値** | **説明** |
|  --- | --- |
| `0 * * * *` | 1 時間に 1 回実行します。 |
| `0 0 * * *` | 1 日 1 回午前 0 時に実行します。 |
| `0 0 1 * *` | 毎月 1 日の午前 0 時に 1 回実行します。 |
| "" | スケジュールされた実行時刻のないジョブを作成します。 |



```
 *    *    *    *    *
 -    -    -    -    -
 |    |    |    |    |
 |    |    |    |    +----- day of week (0 - 6) (Sunday=0)
 |    |    |    +---------- month (1 - 12)
 |    |    +--------------- day of month (1 - 31)
 |    +-------------------- hour (0 - 23)
 +------------------------- min (0 - 59)
```

次の名前付きエントリを使用できます:

- Day of Week: sun, mon, tue, wed, thu, fri, sat.
- Month: jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec.


各フィールド間には単一のスペースが必要です。各フィールドの値は、次のもので構成できます:

| フィールド値  | 例  | 例の説明  |
|  --- | --- | --- |
| 各フィールドに対して上記で表示された制限内の単一の値。 |  |  |
| フィールドに基づく制限がないことを示すワイルドカード
`'*'`。 | `'0 0 1 * *'` | 毎月 1 日の午前 0 時 (00:00) に実行するようにスケジュールを設定します。 |
| 範囲 `'2-5'`
フィールドの許可される値の範囲を示します。 | `'0 0 1-10 * *'` | 毎月 1 日から 10 日までの午前 0 時 (00:00) に実行するようにスケジュールを設定します。 |
| カンマ区切りの値のリスト `'2,3,4,5'`
フィールドの許可される値のリストを示します。 | `0 0 1,11,21 * *'` | 毎月 1 日、11 日、21 日の午前 0 時 (00:00) に実行するようにスケジュールを設定します。 |
| 周期性インジケータ `'*/5'`
フィールドの有効な値の範囲に基づいて、
スケジュールが実行を許可される頻度を表現します。 | `'30 */2 1 * *'` | 毎月 1 日、00:30 から 2 時間ごとに実行するようにスケジュールを設定します。
`'0 0 */5 * *'` は、毎月 5 日から 5 日ごとに午前 0 時 (00:00) に実行するようにスケジュールを設定します。 |
| `'*'`
ワイルドカードを除く上記の
いずれかのカンマ区切りリストもサポートされています
`'2,*/5,8-10'` | `'0 0 5,*/10,25 * *'` | 毎月 5 日、10 日、20 日、25 日の午前 0 時 (00:00) に実行するようにスケジュールを設定します。 |


1. (オプション) Delay execution を有効にすることで、クエリの開始時刻を遅延させることができます。


### クエリを実行する

クエリに名前を付けて保存して実行するか、単にクエリを実行します。クエリが正常に完了すると、クエリ結果は指定された宛先に自動的にエクスポートされます。

設定エラーにより継続的に失敗するスケジュールジョブは、複数回通知された後、システム側で無効化される場合があります。

(オプション) Delay execution を有効にすることで、クエリの開始時刻を遅延させることができます。

## Audience Studio で Segment をアクティベートする

Audience Studio で activation を作成することで、segment データをターゲットプラットフォームに送信することもできます。

1. **Audience Studio** に移動します。
2. parent segment を選択します。
3. ターゲット segment を開き、右クリックして、**Create Activation** を選択します。
4. **Details** パネルで、Activation 名を入力し、前述の Configuration Parameters のセクションに従って activation を設定します。
5. **Output Mapping** パネルで activation 出力をカスタマイズします。


![](/assets/ouput.b2c7f1d909c4f98ed10f5300df858a4b19f71a3b0834df952f5fb24018a5ea78.8ebdf569.png)

- Attribute Columns
  - **Export All Columns** を選択すると、変更を加えずにすべての列をエクスポートできます。
  - **+ Add Columns** を選択して、エクスポート用の特定の列を追加します。Output Column Name には、Source 列名と同じ名前があらかじめ入力されます。Output Column Name を更新できます。**+ Add Columns** を選択し続けて、activation 出力用の新しい列を追加します。
- String Builder
  - **+ Add string** を選択して、エクスポート用の文字列を作成します。次の値から選択します:
    - String: 任意の値を選択します。テキストを使用してカスタム値を作成します。
    - Timestamp: エクスポートの日時。
    - Segment Id: segment ID 番号。
    - Segment Name: segment 名。
    - Audience Id: parent segment 番号。


1. **Schedule** を設定します。


![](/assets/snippet-output-connector-on-audience-studio-2024-08-28.a99525173709da1eb537f839019fa7876ffae95045154c8f2941b030022f792c.8ebdf569.png)

- スケジュールを定義する値を選択し、オプションでメール通知を含めます。


1. **Create** を選択します。


batch journey の activation を作成する必要がある場合は、[Creating a Batch Journey Activation](/products/customer-data-platform/journey-orchestration/batch/creating-a-batch-journey-activation) を参照してください。

## CLIからのオンデマンドジョブの場合

オンデマンドジョブの場合は、`td query`コマンドに`--result`オプションを追加するだけです。ジョブが完了すると、結果は`testdb`データベース内の`output_table`に書き込まれます。


```bash
$ td query --result 'td://@/testdb/output_table' \
  -w -d testdb \
  "SELECT code, COUNT(1) FROM www_access GROUP BY code"
```

### スケジュールされたジョブの場合

スケジュールされたジョブの場合は、ジョブをスケジュールするときに`--result`オプションを追加するだけです。ジョブが実行されるたびに、結果は`output_table`に書き込まれます。


```bash
$ td result:create mydb td://@/testdb
$ td sched:create hourly_count_example "0 * * * *" \
  -d testdb "select count(*) from www_access" \
  --result mydb:output_table
```

### データを変更する2つの方法

2つの方法でデータを追加または削除できます：

- append
- replace



```
td://@/testdb/output_table              # append
td://@/testdb/output_table?mode=append  # append
td://@/testdb/output_table?mode=replace # replace
```

#### Append

これはデフォルトモードです。クエリ結果はテーブルに追加されます。テーブルがまだ存在しない場合は、新しいテーブルが作成されます。この操作は冪等ではありません。同じ呼び出しを繰り返し行っても同じ結果を生成することはできません。このモードは[atomic](https://docs.treasuredata.com/smart/project-product-documentation/glossary)ではありません。

#### Replace

テーブルがすでに存在する場合、既存のテーブルの行はクエリ結果で置き換えられます。テーブルがまだ存在しない場合は、新しいテーブルが作成されます。

次の3つのステップを**単一のトランザクション**で実行することにより、[**atomicity**](https://docs.treasuredata.com/smart/project-product-documentation/glossary)（テーブルの消費者が常に一貫したデータを持つように）を実現します。

1. 一時テーブルを作成します。
2. 一時テーブルに書き込みます。
3. 既存のテーブルを一時テーブルでアトミックに置き換えます。