# Amazon Redshift Export Integration

[AWS LinuxへのTD Agentのインストール](https://docs.treasuredata.com/smart/project-product-documentation/installing-td-agent-on-aws-linux)について詳しく学んでください。

既存のAmazon Redshift clusterにjobの結果を書き込むことができます。Exportに関するAmazon Redshiftのサンプルworkflowについては、[Treasure Boxes](https://github.com/treasure-data/treasure-boxes/tree/master/td/redshift)を参照してください。

# 前提条件

- TD Toolbeltを含むTreasure Dataの基本的な知識
- 実行中の**Amazon Redshift cluster**のセットアップ - シングルノードまたはマルチノードcluster
- queryを実行するTreasure Data tableに対する少なくとも'Query only'権限


# 制限事項

- Redshiftに結果をエクスポートする際、Redshiftは宛先tableがすでに存在する場合、カラムタイプの変換を試みます。変換中にカラムがNULLになり、Redshift上のカラムがNOT NULLフィールドの場合、すべてのレコードが拒否されます。これは、Redshiftへの結果エクスポートのjobが成功した場合でも発生する可能性がありますが、Redshiftにはデータが取り込まれません。
- このconnectorは、timestamp/dateタイプのデータをサポートしていません。このタイプのデータをstringカラムまたはUnix timestampに変換する必要があります。


# サポートされているRegion

Result Output to Redshiftは、いくつかのregionにデータをエクスポートできます。以下はサポートされているregionです:

- us-east-1 (US Standard)
- us-west-2 (Oregon)
- eu-west-1 (Ireland)
- ap-northeast-1 (Tokyo)
- us-west-1 (N. California)
- ap-southeast-1 (Singapore)
- ap-southeast-2 (Sydney)
- sa-east-1 (São Paulo)


以下のregionはサポートされていません:

- us-east-2 (Ohio)
- ap-south-1 (Mumbai)
- ap-northeast-2 (Seoul)
- ca-central-1 (Central)
- eu-central-1 (Frankfurt)
- eu-west-2 (London)


サポートしたい他のregionがある場合は、[Treasure Data supportに連絡](https://docs.treasuredata.com/smart/project-product-documentation/contacting-treasure-data-support)してください。

# Architecture

フロントエンドアプリケーションは、[Treasure Agent](https://docs.treasuredata.com/smart/project-product-documentation/about-treasure-data-s-server-side-agent) (td-agent)を介してTreasure Dataに収集されるデータをストリーミングします。Treasure Dataは定期的にデータ上でjobを実行し、jobの結果をRedshift clusterに書き込みます。

![](/assets/image2021-3-1_12-11-53.286db825500f33438282d58ee89b9f7a3847264bba23b703f45aa708641c95cf.0edad2c5.png)

この画像は、Redshiftの使用に精通しているデータアナリストが、データのアップロード方法ではなく、queryと視覚化に集中できるようにする、かなり一般的なアーキテクチャを示しています。

## Treasure Data Integration の静的 IP アドレス

セキュリティポリシーで IP ホワイトリストが必要な場合は、接続を成功させるために Treasure Data の IP アドレスを許可リストに追加する必要があります。

リージョンごとに整理された静的 IP アドレスの完全なリストは、次のリンクにあります:
[https://api-docs.treasuredata.com/en/overview/ip-addresses-integrations-result-workers/](https://api-docs.treasuredata.com/en/overview/ip-addresses-integrations-result-workers/)

# Amazon Redshift Configuration

Amazon Redshiftは、シングルノードモードまたはマルチノード/clusterモードで設定できます。マルチノード構成は、利用可能なノード上でのquery実行の並列化により、より多くのquery計算能力を提供します。

# TD Consoleを使用してConnectionを作成

## 新しいAuthenticaitonの作成

Treasure Dataでは、queryを実行する前にデータconnectionを作成して設定する必要があります。データconnectionの一部として、integrationにアクセスするためのauthenticationを提供します。

1. **TD Console**を開きます。
2. **Integrations Hub** > **Catalog**に移動します。
3. Catalog画面の右端にある検索アイコンをクリックし、**Amazon Redshift**と入力します。
4. Amazon Redshift connectorにカーソルを合わせ、**Create Authentication**を選択します。


![](/assets/amazonredshift.72b30214eceebe7b0fea54137a0622f0286279c4112f82ec8cef094f631cb6ae.0edad2c5.png)

認証するcredentialsを入力します。

![](/assets/image2021-3-1_14-40-15.e7a57af257de8db9efedfdd4cef6ca2b742481ac5db98f0cbe2c5254c0aeb12c.0edad2c5.png)

| Parameter | Value |
|  --- | --- |
| Host | source databaseのhost情報(IPアドレスなど)。Redshift設定ページから取得できます。通常、形式は次のとおりです:name.<instance_id>.region.redshift.amazonaws.com。nameはclusterに提供されたもの、instance idはcluster作成時にAmazon Redshiftによって自動生成されます、regionは選択したAmazon availability zoneです。hostnameの代わりにIPアドレスを使用している場合は、`region`オプションを明示的に設定する必要があります。 |
| Port | sourceインスタンス上の接続port。PostgreSQLのデフォルトは5432です。Redshift serverにアクセスするためのport番号。":"はオプションで、デフォルトでは5439と想定されます。マルチノードcluster設定では異なる場合があります。実際の値は、Redshift clusterの詳細ページから取得できます。 |
| User | source databaseに接続するためのUsername。Amazon RedshiftインスタンスのCredentials。これらのcredentialsは、Redshift clusterを最初に作成するときに指定され、S3 public/private access keysとは異なります。 |
| Password | source databaseに接続するためのpassword。 |
| Use SSL | SSLを使用して接続する場合は、このボックスにチェックを入れます |
| JDBC Connection options | source databaseに必要な特別なJDBC接続(オプション)。 |
| Region | Redshiftインスタンスがホストされているaws region。Redshiftインスタンスが配置されているregionを指定します。hostnameにregion名が含まれていない場合、このオプションが必要です。redshift://user:password@host/database/table?region=us-east-1 |
| Socket connection timeout | socket接続のタイムアウト(秒単位)(デフォルトは300)。 |
| Network timeout | network socketオペレーションのタイムアウト(秒単位)。0はタイムアウトなしを意味します。 |
| Rows per batch | 一度に取得する行数。 |
| Options | JDBC driverに与えたいOptions。[Installing Redshift JDBC Driver](https://github.com/aws/amazon-redshift-jdbc-driver?tab=readme-ov-file#installation-and-configuration-of-driver)を参照してください。`例えば、これらのパラメータと値のフィールドを使用して、LogLevelやLogPathなどのさまざまなURLオプションを定義できます。jdbc:redshift://company.us-west1.redshift.amazonaws.com:9000/Default;LogLevel=3;LogPath =C:	emp `Redshiftへのresult outputは、オプションのURLパラメータとして指定できるさまざまなオプションをサポートしています。これらのオプションは互いに互換性があり、組み合わせることができます。該当する場合、デフォルトの動作が示されます。SSL Option **ssl**オプションは、Redshiftに接続する際にSSLを使用するかどうかを決定します。`ssl=true` Treasure DataからRedshift接続にSSLを使用します。`redshift://user:password@host/database/table?ssl=true` `ssl=false`(デフォルト)Treasure DataからRedshiftにSSLを使用しません。`redshift://user:password@host/database/table?ssl=false` |


1. 必要な接続の詳細を入力した後、**Continue**を選択します。
2. 後でconnectionの詳細を変更する必要がある場合に見つけられるように、connectionに名前を付けます。
3. オプションで、組織内の他のユーザーとこのconnectionを共有したい場合は、**Share with others**を選択します。
4. **Done**を選択します。


## Queryの定義

1. [Creating a Destination Integration](https://docs.treasuredata.com/smart/project-product-documentation/creating-a-destination-integration)の指示を完了します。
2. **Data Workbench > Queries**に移動します。
3. データをエクスポートするqueryを選択します。
4. queryを実行して、結果セットを検証します。
5. **Export Results**を選択します。
6. 既存のintegration authenticationを選択します。
![](/assets/image2020-12-18_13-44-6.09e8af43184e33e337bef7c546600eaaa5be9f010b690af1d591c7c2b4bb2df3.c27c97ee.png)
7. 追加のExport Resultsの詳細を定義します。export integrationコンテンツで、integrationパラメータを確認します。
例えば、Export Results画面は異なる場合があり、入力する追加の詳細がない場合もあります:
![](/assets/image2023-5-17_14-42-52.d2483b20e117c4abf1aaa32c5071595644e4c6b9d987ef4ea4ce4a2038171b85.c27c97ee.png)
8. **Done**を選択します。
9. queryを実行します。
10. データが指定した宛先に移動したことを検証します。


## RedshiftのIntegration Parameters

![](/assets/image2021-3-2_16-49-44.a46c316ca063ddebba7e30d47d889873237d2845170b127f8300ef13eceba64e.0edad2c5.png)

| Parameter | Values | Description |
|  --- | --- | --- |
| Database |  | データをエクスポートするdatabaseの名前。Redshift clusterの作成時に指定されたdatabaseの名前。Redshift clusterの詳細ページから取得できます。 |
| Table |  | データをエクスポートするdatabase内のtableの名前。database内のtableの名前。query出力が実行されるときに存在しない場合があります。tableが存在しない場合、指定された名前のtableが作成されます。 |
| Mode | appendreplacetruncateupdate | databaseデータを変更するさまざまな方法を制御します。- **Append Mode**: これがデフォルトモードです。queryの結果がcollectionに追加されます。collectionがまだ存在しない場合、新しいcollectionが作成されます。このメソッドは[**atomic**](https://docs.treasuredata.com/smart/project-product-documentation/glossary/a/atomicity)ではありません
- **Replace Mode**: **replace**モードは、既存のtableのすべてのコンテンツをqueryの結果出力で置き換えることで構成されます。tableが存在しない場合、新しいtableが作成されます。最速の結果を得るには、RDS database tableに対して一度に1つの**write**接続のみを開くことをお勧めします。replaceモードは、**単一のトランザクション**で以下の手順を実行することにより、[**atomicity**](https://docs.treasuredata.com/smart/project-product-documentation/glossary/a/atomicity)(tableのconsumerが常に一貫したデータを持つように)を達成します:1. temporary tableを作成する;2. temporary tableに書き込む;3. ALTER TABLE RENAMEを使用して既存のtableをtemporary tableで置き換える。最速の結果を得るには、RDS database tableに対して一度に1つの**write**接続のみを開くことをお勧めします。
- **Truncate Mode**: Truncateモードは、tableのindexを保持します。**truncate**モードでは、システムはまず既存のtableをtruncateしてすべてのレコードを削除し、次にtableのschemaを変更せずに既存のtableにqueryの結果を挿入します。結果出力tableに、宛先tableのschemaと名前またはタイプ(またはその両方)が一致しないカラムが含まれている場合、そのカラムは削除され、宛先tableに書き込まれません。宛先tableが存在しない場合、これは問題ではありません:結果出力tableのschemaと一致するschemaで新しいtableが作成されます。truncateモードはtemporary tableを使用するため、書き込みの**atomicity**を達成します。replaceとは異なり、truncateモードはtableのindexを保持します。
- **Update Mode**: **update**モードでは、"unique"パラメータで指定されたカラムに重複した値を引き起こす場合を除いて、行が挿入されます。そのような場合、代わりに更新が実行されます。updateモードを使用する場合、uniqueパラメータが必要です。tableが存在しない場合、作成されます。このモードは、実際の宛先tableにデータを挿入する前に、受信データを保存するためにtemporary tableを使用するため、**atomic**です。

 |
| In-place append | select  clear | コピーするのではなく、既存のデータを変更するために選択します。これにより、大幅なパフォーマンス向上が得られます。`mode=append`の場合、`inplace`マイナーオプションでアクションのatomicityを制御できます。`true`の場合、temporary tableは使用されず、operationはatomicであることが保証されません。オプションが`false`の場合、temporary tableが使用されます。デフォルト値はtrueです。 |
| Schema |  | ターゲットtableが配置されているschemaを制御します。指定されていない場合、デフォルトのschemaが使用されます。デフォルトのschemaは、ユーザーの"search_path"設定に依存しますが、通常は"public"です。 |
| Method | copy  bulk copy | `copy`(デフォルト)このオプションを使用すると、COPY Redshift SQLコマンドを使用して、異なるフローでデータをエクスポートできます。**`bulk_copy`**このオプションは`copy`コマンドを使用しますが、異なるフローを使用します。Treasure DataからSSLを使用してRedshift接続をインスタンス化できます。例:`redshift://user:password@host/database/table?method=bulk_copy`。 |
| Serial Copy | select  clear | **serial_copy**オプションは、並列にファイルをアップロードするときに発生する可能性のあるデッドロックを回避するために、すべてのファイルを1つずつ順番にアップロードするかどうかを決定します。`serial_copy=true` `serial_copy=false`(デフォルト) |


## Example Query


```SQL
select * from an_redshift_data limit 800000000
```

## 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 Examples

TD Toolbeltを使用して、Amazon Redshiftにエクスポートしたいデータを返すqueryを実行する場合:

## CLIを使用した1回限りのExport


```bash
td query -w -d testdb \
--result 'redshift://username:password@host.redshift.amazonaws.com/database/table?mode=replace' \
"SELECT code, COUNT(1) FROM www_access GROUP BY code"
```

## CLIを使用したScheduled Export


```bash
td sched:create hourly_count_example "0 * * * *" -d testdb \
--result 'redshift://username:password@host.redshift.amazonaws.com/database/table?mode=replace' \
"SELECT COUNT(*) FROM www_access"
```

## Troubleshooting

### Result Output to Redshiftのjobが成功した場合でも、Redshiftがデータを取得しない場合

Result Output to Redshiftは、宛先tableがすでに存在する場合、カラムタイプの変換を試みます。変換が失敗すると、カラムがNULLになり、Redshift上のカラムがNOT NULLフィールドの場合、すべてのレコードが拒否されます。