Treasure Data CDPを理解する- Export編 –

エクスポートとは

Treasure Data CDPにおけるエクスポートとは、その名の通りTreasure Data CDPに格納されているデータを外部に出力する機能になります。よく利用する方法としては下記が挙げられますので、各々細かく見ていきましょう。

• Result Export
• Bulk Export
• クエリの結果のダウンロード

Result Export(Result Output)

Treasure Data CDPからデータをエクスポートする際はこの機能を利用することが多いのではないかと思われるメジャーな機能です。エクスポートできるサービスはAWS S3やMySQL、SFTPサーバーなど多岐にわたります。機能名のResultとはクエリ(SQL)で抽出した結果のことを指しています。Treasure Data CDPではHive/Prestoという2種類のクエリエンジンを利用することができますが、その何れかを利用して抽出した結果を外部に書き出すことができます。 そのため本機能を利用するには当然ですがクエリを作成・実行する必要があります。

Result Exportの使い方

具体的には下記3通りの方法でResult Export機能を利用することができます。

• Treasure Data CDPコンソールからエクスポートする
• Workflowのtd>:オペレーターでエクスポートする
• CLI(Toolbelt)のtd queryコマンドでエクスポートする

最後のCLIの場合を除き、事前にエクスポート先の資格情報(接続するユーザー名、ホスト名、パスワード、秘密鍵など)をAuthenticationとして作成しておく必要があります。もちろん1つのAuthenticationを複数のResult Exportにて利用することができますが、例えば接続するユーザーを変えたいという場合は別途Authenticationを作成して対応することになります。

そして、エクスポート先情報(ファイルパスやテーブル名)やデータのフォーマット情報(区切り文字など)はResult Exportごとに設定します。Authenticationと役割が異なるということを意識いただくと設定箇所など混乱しづらいのではないかと思います。

Treasure Data CDPコンソールからResult Exportを利用する

Treasure Data CDPコンソール(Web UI)からResult Exportを利用する場合は、クエリ編集画面から設定することになります。画面右上のExport Resultsにチェックを入れるとAuthenticationの選択・作成を経てResult Exportの設定をすることが可能です。設定完了後Runをクリックしてクエリを実行すると、クエリによる抽出が完了した後にエクスポート処理が開始されます。

WorkflowからResult Exportを利用する

WorkflowからResult Export機能を利用するためにはtd>:オペレーターを使います。td>:オペレーターはクエリを実行することができるオペレーターですが、result_connection:にAuthentication名を、result_settings:にはエクスポート設定を記載することで実行したクエリの結果をエクスポートすることができます。

+td-result-into-s3:
  td>: queries/sample.sql # クエリ文
  result_connection: your_connections_name # Authentication名を記載
  result_settings:
    bucket: your_bucket # S3のバケット名
    path: /path/20201127_test.csv # オブジェクトパス(ファイルパス)
...

result_settings:に記載できるオプション名などは連携先サービスによって異なります。そのため、ドキュメントやtreasure-boxesを参照してください。

Treasure Data CDPコンソールのクエリからResult Export機能を利用する場合と比較すると、Workflowでの利用になるため他の処理と依存関係を設けることができるというメリットがあります。また、書き出し先などにWorkflowの変数${...}を利用して設定することができるため、例えば下記のように実行予定(sessionと言います)の情報をファイル名に含めるなどの柔軟なユースケースが実現できます。

+td-result-into-s3:
  td>: queries/sample.sql
  result_connection: your_connections_name
  result_settings:
    bucket: your_bucket
    path: /path/file_${moment(session_time).format("YYYYMMDD")}.csv.gz # ビルトイン変数 session_time を Moment.js で加工

また、少しAdvancedな使い方になりますが、td_result_export>:オペレーターを利用することでResult Export機能を利用することも可能です。td>:オペレーターの場合と異なり、過去に成功したHive/PrestoジョブのIDを指定することで、クエリによる抽出部分をスキップしてエクスポートできます。

あるクエリで抽出した結果を複数の場所にエクスポートしたいときに、何度もクエリを実行する必要がなくなるため有用かと思います。

+export_query_result:
  td_result_export>:
  job_id: 12345
  result_connection: my_s3_connection
  result_settings:
    bucket: your_bucket
    path: /logs/

CLI(Toolbelt)でResult Exportを利用する

CLI(Toolbelt)からResult Export機能を利用するためには、td queryコマンドの–resultオプションを指定する必要があります。td queryコマンドのヘルプを見てみましょう。

$ td query --help
usage:
  $ td query [sql]

example:
  $ td query -d example_db -w -r rset1 "select count(*) from table1"
  $ td query -d example_db -w -r rset1 -q query.txt

description:
  Issue a query

options:
...
  -r, --result RESULT_URL          write result to the URL (see also result:create subcommand)

--result の部分にエクスポートに必要な情報をURLフォーマットで記載して利用します。エクスポート先によって記載する情報などが異なるため、ドキュメントを参照していただければと思います。

下記はS3にエクスポートする際のサンプルになりますが、URLフォーマットなどを事前に把握しておく必要があるため、Treasure Data CDPコンソールやWorkflowから利用するケースが多いかもしれません。また、エクスポート先の認証情報としてOAuthなどを利用する場合は利用できないため、先述した方法と比べると下火となっている方法かと思います。

$ td query --result 's3://accesskey:secretkey@/bucketname/path/to/file.csv.gz?compression=gz' -w -d testdb "SELECT code, COUNT(1) AS cnt FROM www_access GROUP BY code"

Result Exportのジョブについて

Result ExportとはHive/Prestoで抽出した結果をエクスポートする機能と説明しましたが、実はHive/PrestoのジョブとResult Exportのジョブは別々のジョブとなっています。そのためJob IDも別々の値が割り振られるのですが、Result ExportのジョブのログはHive/Prestoのジョブのログに出力されることもあり、Treasure Data CDPを利用する上で意識することは少ないのではないかと思います。

クエリ文がRESULT EXPORT FROM JOB となっているジョブがResult Exportのジョブです。はエクスポートするデータを抽出したHive/PrestoのジョブのIDとなっているため、どのジョブの結果をエクスポートしようとしているのかは簡単にわかりますね。

Bulk Export機能

Result Export機能とは異なり、AWS S3へのみエクスポートすることができる機能です。Treasure Data CDPのAWSリージョン(ご契約時に決定)とエクスポート先のS3のバケットのリージョンが同一の場合にのみ利用できる機能で、AWSの同一リージョン内での通信となるためネットワークレイテンシーの影響を受けづらく、高速にエクスポートが完了することが期待できるというメリットが挙げられます。

そのためエクスポート先がAWS S3かつリージョンが同一なのであればResult Exportと本機能のどちらを利用するか検討しても良いかと思います(後述の注意点を考慮して採用するかどうか検討してください)。具体的には下記いずれかの方法で利用することができます。

• CLI(Toolbelt)のtd table:exportコマンド
• Workflowのtd_table_export>:オペレーター

timeカラムの値でエクスポートするデータを絞り込みすることは可能ですが、Result Exportとは異なり柔軟にエクスポートするデータを絞り込み・整形することはできない点には注意してください。また、スキーマ設定(カラム名)をヘッダーとして追加するということができません。

エクスポート先ファイルのフォーマットにも注意が必要で、tsv.gzを利用することをお勧めします。jsonl.gzというフォーマットも選択可能ではありますが、パフォーマンスが良くないということと後方互換性のために残しているフォーマットになりますので、tsv.gzをお使いいただくのが良いかと思います。また、Bulk ExportはHiveのリソースを利用します。すでにHiveを多用いただいている場合は本機能とリソースを奪い合ってしまう可能性がありますので、クリティカルな処理と実行時間帯をずらすなどしていただくと良いでしょう。

詳細はドキュメントをご参照ください。

クエリ結果のダウンロード

エクスポートとすると違和感がありますが、手元にクエリにて抽出した結果をエクスポートできると解釈できなくはないかと思いますので紹介させてください。下記いずれかの方法で実行済みのジョブ(Hive/Presto)の結果をダウンロードすることができます。

• Treasure Data CDPコンソールのDownloadボタン
• CLI(Toolbelt)のtd job:show

Treasure Data CDPの文字コードは基本的にUTF-8(例えば Result Exports 機能は UTF-8 としてエクスポートします)なのですが、本機能はUTF-8以外にSJISとしてクエリ結果をダウンロードすることが可能です。前者利用時にModeをcliとすることで下記のような具体的なコマンドが表示されますので、コマンド実行などに不慣れな方はそのようにしていただくのも良いでしょう。

ブラウザ経由でのダウンロードは非常に大きなサイズのファイルをダウンロードしようとしても各種要因で失敗することが多いため、利用できるサイズ上限を設けています。圧縮時のサイズが上限を超えてしまう場合は後者のtd job:showコマンドのみ利用できます。

td job:show  -f csv -o xxxxxxx.csv --column-header

また、td job:showコマンドでもサイズが大きい場合は長時間化・失敗してしまうことがあります。その場合は迂回策として、S3やSFTPサーバーなどにResult Export機能でエクスポートし、それを経由してダウンロードするなどでご対応ください。

最後に

Treasure Data CDPからのエクスポート機能について簡単にまとめてみましたが、いかがでしたか？ インポートに比べて種類が少ないため自身で把握しやすい機能ではあるかと思いますが、理解の一助となりましたら幸いです。