Treasure Data - Support Engineering Team blog

トレジャーデータのサポートエンジニアリングチームのブログです。

td-toolbeltチュートリアル

こんにちは。Treasure Data サポートチームの大村です。今回はコマンドラインによるTDの操作方法についてチュートリアルをご紹介したいと思います。

TDには各種サービスを管理するためのWeb UI(TDコンソール)がありますが、このWeb UIと同等のコマンドラインツールもあります。 今回はこのtd-toolbeltのセットアップからquery実行までのチュートリアルをご紹介したいと思います。

インストール

ダウンロードおよびインストールは特に難しい部分はないと思います。 以下のページよりOSを指定してダウンロードし、ダブルクリックでインストールされます。 https://toolbelt.treasuredata.com/

セットアップ

プロキシサーバの設定

自社ネットワークからインターネットにアクセスするためにプロキシサーバを経由しないとインターネットにアクセスできないようにしている会社は多いです。 ブラウザではDHCP等で自動設定されていることが多いですが、td-toolbeltでは自分で設定する必要があります。 環境変数HTTP_PROXYおよびHTTPS_PROXYにプロキシサーバを設定してください。

Windowsの場合

> set HTTP_PROXY=http://proxy-host:proxy-port
> set HTTPS_PROXY=https://proxy-host:proxy-port

MaCOS/LinuxなどのBashの場合

> export HTTP_PROXY=http://proxy_host:proxy_port
> export HTTPS_PROXY=https://proxy_host:proxy_port

proxy_hostやproxy_portについては自分のネットワークを確認してください。

endpointの設定

Treasure Dataではいくつかのリージョンでサービスを提供しています。自分が使用しているTDの環境のリージョンを確認し、適切なエンドポイントを指定する必要があります。 https://tddocs.atlassian.net/wiki/spaces/PD/pages/1085143/Sites+and+Endpoints 上記ドキュメントのAPIというSiteのエンドポイントを指定するようにしてください。

自分が使用しているTDの環境のリージョン確認は上記ドキュメントのConsoleという部分で確認するとよいでしょう。 こちらはTDコンソールのURLを表しています。普段、ブラウザでアクセスしているURLになりますので確認して自分のTD環境がどのリージョンか確認してください。

アカウントセットアップ

これでTDにアクセスする準備ができました。まずは自分のアカウント情報をtd-toolbeltに保存する必要があります。 以下のコマンドを起動し、メッセージに従ってアカウントのセットアップを行ってください。

> td -e <endpoint> account

ちなみにUSリージョンの方はendpointの指定の必要はありません。デフォルトがusリージョンになっています. メールアドレスとパスワードを求められると思いますので、正しく入力してください。

Google SSOを使っている方はapi keyを使用してアクセスすることになります。 TDコンソールでAPIキーを確認して、以下のコマンドで設定してください。

> td apikey:set <api-key>

クエリ実行

ここまででtd-toolbeltを使って、TDを操作する準備ができました。 最後にクエリを実行してみましょう。クエリを実行するにはtdコマンドのqueryサブコマンドを使用します。

> td query -w -d sample_datasets "select symbol, high, low from nasdaq limit 3"
   :
   :
   :
WARNING: the job result is being downloaded...  90 B /  90 B : ======================================================== 100 ========================================================= 
+--------+---------+---------+                                                                      
| symbol | high    | low     |
+--------+---------+---------+
| CHCI   | 1.9499  | 1.82    |
| BIIB   | 292.859 | 283.0   |
| BIND   | 11.72   | 10.8237 |
+--------+---------+---------+
3 rows in set

上記のようにたくさんのログと最後に結果が返ってくれば成功です。ここではどのユーザにも存在するsample_datasetsデータベースを指定して、"select symbol, high, low from nasdaq limit 3"というクエリを実行しています。

td-toolbeltにはたくさんの機能がありますのでいろいろ使用してみてください。参考リンクのリファレンスやhelpコマンドで各サブコマンドの使い方を確認できるので、いろいろ試してみてください。

> td help
Additional commands, type "td help COMMAND" for more details:

  help:all                                   # Show usage of all commands
  help <command>                             # Show usage of a command
> td help query
Additional commands, type "td help COMMAND" for more details:

  help:all                                   # Show usage of all commands
  help <command>                             # Show usage of a command

TD-0562:Downloads yuu.ohmura$ td help query
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:
  -d, --database DB_NAME           use the database (required)
  -w, --wait[=SECONDS]             wait for finishing the job (for seconds)
  -G, --vertical                   use vertical table to show results
  -o, --output PATH                write result to the file
  -f, --format FORMAT              format of the result to write to the file (tsv, csv, json, msgpack, and msgpack.gz)
  -r, --result RESULT_URL          write result to the URL (see also result:create subcommand)
                                    It is suggested for this option to be used with the -x / --exclude option to suppress printing
                                    of the query result to stdout or -o / --output to dump the query result into a file.
  -u, --user NAME                  set user name for the result URL
  -p, --password                   ask password for the result URL
  -P, --priority PRIORITY          set priority
  -R, --retry COUNT                automatic retrying count
  -q, --query PATH                 use file instead of inline query
  -T, --type TYPE                  set query type (hive, presto)
      --sampling DENOMINATOR       OBSOLETE - enable random sampling to reduce records 1/DENOMINATOR
  -l, --limit ROWS                 limit the number of result rows shown when not outputting to file
  -c, --column-header              output of the columns' header when the schema is available for the table (only applies to json, tsv and csv formats)
  -x, --exclude                    do not automatically retrieve the job result
  -O, --pool-name NAME             specify resource pool by name
      --domain-key DOMAIN_KEY      optional user-provided unique ID. You can include this ID with your `create` request to ensure idempotence
      --engine-version ENGINE_VERSION
                                   EXPERIMENTAL: specify query engine version by name

次回はtd-toolbeltのコマンド構成について紹介したいと思います。

参考リンク