PostgreSQL Export Integration

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Cursorに接続

  CursorにMCPサーバーをインストール
• VS Codeに接続

  VS CodeにMCPサーバーをインストール

Treasure Dataからジョブ結果を既存のPostgreSQLインスタンスにエクスポートできます。PostgreSQLデータのインポートについては、PostgreSQL Import Integrationを参照してください。

このトピックには以下が含まれます:

前提条件

• TD Toolbeltを含む、Treasure Dataの基本的な知識。
• PostgreSQLインスタンス。

Treasure Data Integration の静的 IP アドレス

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

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

TD Consoleを使用した接続の作成

新しい接続の作成

1. 新しい接続を作成するために、以下のフィールド値を設定します。

• Host: ソースデータベースのホスト情報（IPアドレスなど）。
• User: ソースデータベースに接続するためのユーザー名。
• Password: ソースデータベースに接続するためのパスワード。
• Use SSL: SSLを使用して接続する場合はこのボックスにチェックを入れます
  • Require a valid SSL certificate?: 接続時に有効なSSL証明書の提示を要求します。

PostgreSQLインスタンスへの結果エクスポートの設定

Treasure Dataからのエクスポートはクエリを使用します。クエリは新規作成することも、既存のものを再利用することもできます。クエリ内でデータ接続を設定します。

1. Creating a Destination Integrationの手順を完了します。
2. Data Workbench > Queriesに移動します。
3. データをエクスポートしたいクエリを選択します。
4. クエリを実行して結果セットを検証します。
5. Export Resultsを選択します。
6. 既存の統合認証を選択します。
7. 追加のExport Resultsの詳細を定義します。エクスポート統合の内容で、統合パラメータを確認してください。 例えば、Export Results画面が異なる場合や、入力する追加の詳細がない場合があります:
8. Doneを選択します。
9. クエリを実行します。
10. 指定した宛先にデータが移動したことを検証します。

Export Resultパラメータの設定

• Database name: データを転送するデータベースの名前。(例: your_database_name)
• Table: データをエクスポートしたいテーブル。
• Output mode: データをアップロードするための異なる方法。
  • Append (デフォルト): appendモードは、URLにモードオプションが指定されていない場合に使用されるデフォルトモードです。このモードでは、クエリ結果がテーブルに追加されます。テーブルが存在しない場合は作成されます。このモードはアトミックです。
  • Replace: replaceモードは、既存のテーブルの全コンテンツをクエリの結果出力で置き換えます。テーブルがまだ存在しない場合は、新しいテーブルが作成されます。replaceモードは、以下の3つのステップを単一のトランザクションで実行することでアトミック性（テーブルの消費者が常に一貫したデータを持つこと）を実現します:
    1. 一時テーブルを作成する
    2. 一時テーブルに書き込む
    3. ALTER TABLE RENAMEを使用して既存のテーブルを一時テーブルで置き換える
    • Truncate: システムはまず既存のテーブルをtruncateし、その後クエリ結果を挿入します。テーブルがまだ存在しない場合は、新しいテーブルが作成されます。このモードはアトミックです。
    • Update: "unique"パラメータで指定された列に重複値が発生しない限り、行が挿入されます。重複する場合は、代わりに更新が実行されます。updateモードを使用する場合、"unique"パラメータが必要です。このモードはアトミックです。
    • Insert Method: このオプションは、データがPostgresテーブルにどのように書き込まれるかを制御します。デフォルトの方法はcopyで、ほとんどの状況で推奨されます。
    • Copy(デフォルト): データはまずサーバー上の一時ファイルに保存され、その後COPYトランザクションを使用してPostgresに書き込まれます。この方法はINSERTよりも高速なので、大量のデータを処理する際に便利です。
    • Insert: データは'INSERT'ステートメントを使用してPostgresに書き込まれます。これは最も信頼性が高く互換性のある方法で、ほとんどの状況で推奨されます。
    • Schema: ターゲットテーブルが配置されているスキーマを定義します。指定されていない場合は、デフォルトのスキーマが使用されます。デフォルトのスキーマはユーザーの"search_path"設定によりますが、通常は"public"です。
    • Foreign Data Wrapper: このオプションは、データの保存にデータラッパーを使用するかどうかを制御します。デフォルトはnoneで、ほとんどのインスタンスで機能するはずです。
    • None (デフォルト) - foreign-data wrapperなし。
    • Cstore - 宛先テーブルでカラムナストレージが必要/有効になっている場合に使用されます。

(オプション) 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 を選択します。

4. ドロップダウンで、次のスケジュールオプションのいずれかを選択します:

   ドロップダウン値	説明
   Custom cron...	Custom cron... の詳細を参照してください。
   @daily (midnight)	指定されたタイムゾーンで 1 日 1 回午前 0 時 (00:00 am) に実行します。
   @hourly (:00)	毎時 00 分に実行します。
   None	スケジュールなし。

Custom cron... の詳細

 *    *    *    *    *
 -    -    -    -    -
 |    |    |    |    |
 |    |    |    |    +----- 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.

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

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 出力をカスタマイズします。

• 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 番号。

6. Schedule を設定します。

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

7. Create を選択します。

(オプション) CLIを使用したエクスポート統合

TD Consoleが利用できない場合、またはニーズを満たさない場合は、CLIを使用してクエリを発行し、結果を出力できます。以下の手順では、CLIを使用してクエリ出力結果をフォーマットする方法を示します。

td query コマンドの使用方法

単一クエリの結果を Postgres サーバーに出力するには、td query コマンドに --result オプションを追加します。ジョブが完了すると、結果がデータベースに書き込まれます:

td query -w -d testdb \
--result 'postgresql://user:password@host/database/table' \
"SELECT code, COUNT(1) FROM www_access GROUP BY code"

出力が体系的に Postgres に書き込まれるスケジュールクエリを作成するには、td sched:create コマンドでスケジュールを作成する際に --result オプションを追加します:

td sched:create hourly_count_example "0 * * * *" \
-d testdb \
--result 'postgresql://user:password@host/database/table' \
"SELECT COUNT(*) FROM www_access"

結果出力 URL フォーマット

結果出力先は、次のフォーマットの URL で表されます:

postgresql:``//username:password@hostname:port/database/table

各項目の説明:

• postgresql は Postgres への結果出力を識別します
• username と password は Postgres サーバーへの認証情報です
• hostname は Postgres サーバーのホスト名です
• port は Postgres サーバーにアクセスするためのポート番号です。「:」はオプションであり、デフォルトでは 5432 と見なされます
• database は宛先データベースの名前です
• table は上記のデータベース内のテーブル名です。クエリ出力が実行される時点で存在しない場合は、指定された名前のテーブルがユーザーのために作成されます

オプション

Postgres への結果出力は、オプションの URL パラメータとして指定できる様々なオプションをサポートしています。これらのオプションは互いに互換性があり、組み合わせることができます。該当する場合、デフォルトの動作が示されています。

SSL オプション

ssl オプションは、Postgres サーバーへの接続に SSL を使用するかどうかを決定します。

Treasure Data から Postgres サーバーへの接続に SSL を使用します。Postgres サーバーは SSL 接続を受け入れるように設定されている 必要があります。

postgresql://user:password@host/database/table?ssl=true

Treasure Data から Postgres サーバーへの接続に SSL を使用しません。

postgresql://user:password@host/database/table?ssl=false

Schema オプション

対象テーブルが配置されているスキーマを制御します。指定されていない場合は、デフォルトのスキーマが使用されます。デフォルトのスキーマはユーザーの「search_path」設定に依存しますが、通常は「public」です。

postgresql://user:password@host/database/table?schema=target_schema

Update Mode オプション

データベースデータを変更する様々な方法を制御します。サポートされている 4 つのモードはすべてアトミックです。これは、宛先テーブルの変更を試みる前に、一時テーブルを使用して受信データを保存するためです:

• Append
• Replace
• Truncate
• Update

mode=append (デフォルト)

append モードはデフォルトで、URL にモードオプションが指定されていない場合に使用されます。このモードでは、クエリ結果がテーブルに追加されます。テーブルが存在しない場合は、テーブルが作成されます。

mode=append がデフォルトの動作であるため、次の 2 つの URL は同等です:

• postgresql://user:password@host/database/table
• postgresql://user:password@host/database/table?mode=append

mode=replace

replace モードは、既存のテーブルの内容全体をクエリの出力結果で置き換えます。テーブルがまだ存在しない場合は、新しいテーブルが作成されます。replace モードは、単一トランザクション内で以下の3つのステップを実行することにより、原子性を実現します(テーブルの利用者が常に一貫したデータを持つことを保証します)。

1. 一時テーブルを作成します。
2. 一時テーブルに書き込みます。
3. ALTER TABLE RENAME を使用して、既存のテーブルを一時テーブルで置き換えます。

例:

• postgresql://user:password@host/database/table?mode=replace

mode=truncate

truncate モードでは、システムはまず既存のテーブルをトランケートし、その後クエリ結果を挿入します。テーブルがまだ存在しない場合は、新しいテーブルが作成されます。

例:

postgresql://user:password@host/database/table?mode=truncate

replace とは異なり、truncate モードではテーブルのインデックスが保持されます。

mode=update

update モードでは、挿入される行が "unique" パラメータで指定された列に重複する値を引き起こす場合を除き、行が挿入されます。そのような場合は、挿入の代わりに行の更新が実行されます。update モードを使用する場合は、"unique" パラメータが必要です。

例:

1. postgresql://...?mode=update&unique=col1 # 単一のユニーク列
2. postgresql://...?mode=update&unique=[col1,col2] # 複数のユニーク列

Write method オプション

method オプションは、データが Postgres テーブルに書き込まれる方法を制御します。以下を使用できます:

• method=insert
• method=copy

デフォルトのメソッドは insert で、ほとんどの状況で推奨される方法です。

method=insert (デフォルト)

insert メソッドでは、データは 'INSERT' ステートメントを使用して Postgres に書き込まれ、最も信頼性が高く互換性のある方法です。

method=insert はデフォルトの動作であるため、以下の2つの URL は同等です:

1. postgresql://user:password@host/database/table
2. postgresql://user:password@host/database/table?method=insert

method=copy

copy メソッドを使用すると、データはまずサーバー上の一時ファイルに保存され、その後 COPY トランザクションを使用して Postgres に書き込まれます。このメソッドは INSERT よりも高速であるため、大量のデータを処理する場合に便利です。

例:

postgresql://user:password@host/database/table?method=copy

(オプション) ワークフローでのエクスポート結果の設定

Treasure Workflow 内で、このデータコネクタを使用してデータを出力することを指定できます。

timezone: UTC

_export:
  td:
    database: sample_datasets

+td-result-output-postgresql:
  td>: queries/sample.sql
  result_connection: your_connections_name
  result_settings:
   database: database_name
   table: table_name
   mode: append
   set_role: new_role

ワークフロー内でデータコネクタを使用してデータをエクスポートする方法についてお読みください。ワークフローの例をご覧ください。