# Treasure Data CDPへのクエリ

質問を平易な言葉で伝えると、StudioはそれをSQLに変換してTreasure Data CDPに対して実行し、会話の中で回答します。SQLが隠されることはありません。エージェントはサンドボックス内で `tdx query` を使って実行し、チャットのツールコールには、あなたが読んでいる数値を生んだ文そのものが表示されます。この可視性こそが要点です。クエリの下書きはエージェントが書き、それを信頼するかどうかを決めるのはあなたです。

**このページはTreasure Data CDPについて書いています。** Studioは接続済みのSnowflakeやDatabricksにもクエリできますが、経路が異なります。[接続済みウェアハウスへのクエリ](#%E6%8E%A5%E7%B6%9A%E6%B8%88%E3%81%BF%E3%82%A6%E3%82%A7%E3%82%A2%E3%83%8F%E3%82%A6%E3%82%B9%E3%81%B8%E3%81%AE%E3%82%AF%E3%82%A8%E3%83%AA)を参照してください。

まずSQLスキルを有効にしてください
既定のプラグイン構成にSQLスキルは含まれていないため、新規アカウントはTreasure AI固有の知識なしにSQLを書いている状態です。これを有効にすることが、クエリ品質に対して効果の大きい変更です。[SQLスキルを有効にする](#sql%E3%82%B9%E3%82%AD%E3%83%AB%E3%82%92%E6%9C%89%E5%8A%B9%E3%81%AB%E3%81%99%E3%82%8B)を参照してください。

## 前提条件

- Treasure AI Studioにサインイン済みであること（[はじめに](/ja/products/ai-studio/getting-started)）
- Treasure AIアカウントでアクセス可能なデータベースが少なくとも1つあること
- ポリシーに **Download** 権限が含まれていること。これがないと、クエリは実行できても結果がチャットに届きません（[クエリ結果の取得にはCDPのDownload権限が必要](#%E3%82%AF%E3%82%A8%E3%83%AA%E7%B5%90%E6%9E%9C%E3%81%AE%E5%8F%96%E5%BE%97%E3%81%AB%E3%81%AFcdp%E3%81%AEdownload%E6%A8%A9%E9%99%90%E3%81%8C%E5%BF%85%E8%A6%81)）


## クエリ結果の取得にはCDPのDownload権限が必要

Treasure AI Studioからクエリを実行するには、Treasure Data CDPの権限が1つではなく2つ必要です。データベースに対する **クエリ** 権限と、結果をCDPの外に出すことを許可する **Download** 権限です。クエリ権限だけの場合、文は実行されたうえで結果の取得が失敗し、ツールコールには行ではなくエラーが返ります。部分的な結果が返ることもありません。

Treasure AI StudioはTreasure Data CDPから独立したサービスとして設計されており、クエリ自体はCDP内のジョブとして実行される一方、その結果はCDPの外にあるエージェントの実行環境へ引き渡されます。したがって、チャットでクエリ結果を参照することはCDP内での参照ではなく、CDPからのデータの持ち出しにあたります。CDPの権限モデルはこれをダウンロードとして扱い、Treasure AIコンソールから結果をダウンロードする場合と同じ制御を適用します。権限がない場合にコンソールが表示する 50 件のプレビューはコンソールの機能であり、Studioに相当するものはありません。

付与するのはStudioではなくCDP側です。**Control Panel** → **Policies** → **Permissions** → **Database Workbench** で、**Full Access** にはDownloadが含まれており、**Limited Access** には **Download Database** のトグルがあります。[Treasure ConsoleでのPolicy Basedデータベース権限の設定](/ja/products/control-panel/security/policies/setting-policy-based-database-permissions-in-td-console)と[ポリシーベースのデータベース権限マトリックス](/ja/products/control-panel/security/policies/policy-based-database-permissions-matrix)を参照してください。

自分の権限を確認するには、エージェントに `tdx policy` を実行させ、**Effective Permissions** の `Databases` の行を読んでください。`download`、またはそれを含む `manage` が記載されている必要があります。[`tdx policy`](/treasure-code/commands/policy)を参照してください。

この要件は、クエリ結果がチャットに入るすべての経路に適用されます。`tdx query --output` でファイルに書き出す場合も、[Hiveのジョブ経路](#trino%E3%81%AF%E3%83%81%E3%83%A3%E3%83%83%E3%83%88%E3%81%A7hive%E3%81%AF%E3%82%B8%E3%83%A7%E3%83%96%E3%81%A7)における `tdx job result` も対象です。

## SQLスキルを有効にする

スキルは、Treasure AI の SQL が実際にどう動くかをエージェントに教えるものです。時間絞り込みの `td_interval`、パーティションプルーニング、Trino では処理しきれないクエリを Hive に移す判断などがそれにあたります。スキルがなければ、エージェントはスキーマから推測できる範囲で汎用的な SQL を書くことになります。**書かれた SQL がおかしいと感じたら、まずここを疑ってください。**よくある原因であり、確認も簡単です。

**sql-skills** プラグインは、プリインストールされた **td-skills** マーケットプレイスに含まれていますが、**既定では有効になっていません**。有効にするには、**設定 → マーケットプレイス**を開き、**td-skills** を展開して **sql-skills** を **On** にします（Default / On / Off の制御については[プラグインマーケットプレイス](/ja/products/ai-studio/skills/marketplace)を参照）。

| スキル | エージェントに教える内容 |
|  --- | --- |
| `trino` | Treasure AI の Trino 方言と TD 固有の関数（`td_interval`、`td_time_range`、`td_time_string`） |
| `time-filtering` | `td_interval` のパターンとパーティションプルーニング。期間を絞ったクエリがテーブルのごく一部だけをスキャンするようになります |
| `trino-optimizer` | 性能改善（CTAS、UDPバケッティング、マジックコメント、近似集計） |
| `hive` | Hive SQL と Hive 固有の機能。Trino で処理しきれないワークロード向け。実行は `tdx query` ではなく後述のジョブ経由になります |
| `trino-to-hive-migration` | メモリ不足で失敗する Trino クエリを Hive 用に書き直す |


有効にすれば、リクエストがその領域に該当したときスキルは自動的に適用されます。質問ごとに呼び出す操作は不要です。[スキルとマーケットプレイス](/ja/products/ai-studio/skills/skills)を参照してください。

## データを尋ねる

SQLではなく、欲しい結果を説明してください。

- 「過去30日間の売上上位10顧客を見せて」
- 「`pageviews` テーブルの行数は？」
- 「`mydb.users` にはどんなカラムがある？」


エージェントは必要に応じてスキーマを調べ（`tdx databases`、`tdx tables`、`tdx describe`）、SQLを書き、`tdx query` で実行し、その出力を読んでから回答します。これらはすべて展開可能なツールコールとして表示されます。

具体的に指定するほど、回答は再現しやすくなります。テーブル・期間・粒度まで固定したリクエスト（「`marketing.signups` から過去30日間の日次サインアップ数を、テスト用アカウントを除いて」）は、「サインアップの状況は？」に比べてエージェントが推測する余地がはるかに小さくなります。

同じ前提が毎回当てはまるなら、繰り返すのをやめてください。用語の定義、プロジェクトで使うテーブル、常に効かせたいフィルターは作業フォルダの指示か組織のカスタム指示へ、書くのが難しいクエリはスキルへ。[業務知識をどこに書くか](/ja/products/ai-studio/concepts/reliable-answers#%E6%A5%AD%E5%8B%99%E7%9F%A5%E8%AD%98%E3%82%92%E3%81%A9%E3%81%93%E3%81%AB%E6%9B%B8%E3%81%8F%E3%81%8B)を参照してください。

## クエリの実行を見る

クエリはツールコールとしてチャットに表示され、行の状態で進行が分かります。

- **実行中** — スピナーと、等幅で表示されるコマンドのプレビュー
- **完了** — チェックマーク。1秒以上かかった場合は所要時間バッジも表示
- **失敗** — 警告アイコンと、コマンドの終了コードを示す **Exit** バッジ


行を展開すると、完全なコマンドと生の出力を確認できます。12行を超える出力は切り詰められ、**Show N more lines** で残りを表示できます。行の**コピー**ボタンでコマンドをコピーすれば、自分で再実行できます。

注意
クエリの結果はそのツールコールの中のテキストです。Studioはソート可能なテーブルとして描画しません。通常目にする整った表は、エージェントが回答の中で数値を書き直したものです。[クエリ結果の読み方](/ja/products/ai-studio/query/query-results)を参照してください。

## 信頼する前にSQLを確認する

ツールコールを展開して、文そのものを読んでください。毎回目を通す価値があるのは次の3点です。

- **選ばれたテーブル。** エージェントは自分が見つけた中から選びます。名前の似たテーブルの取り違えは、文章では見落としても `FROM` 句なら一目で分かります。
- **期間の指定。** 期間の欠落や誤りは、数値が桁違いにずれるよくある原因です。
- **前提していたフィルター。** テストアカウント、キャンセル済み注文、論理削除された行は、誰かが明示しない限り除外されません。


誤りがあれば、最初から質問し直すのではなく、どこが誤りかを伝えてください。「`status = 'test'` の行を除外して再実行して」と言えば、クエリの残りはそのまま活かせます。

## 結果を扱えるサイズに保つ

`tdx query` が出力を40行に制限するのは、対話的なターミナルに接続されているときだけです。サンドボックスはそうではないため、**`SELECT *` は全行を返します**。ツール出力が溢れるうえ、その分だけ以降の会話に使える余地が減るため、セッションは通常より早く要約に入り、前半のやり取りを取りこぼしやすくなります。

避け方は2つです。

- 明示的に上限を指定するか、行そのものではなく集計を求める（「行を見せて」ではなく「日別に集計して」）
- 本当に全件が必要なら、ファイルに書き出させる（`tdx query --output results.csv "..."`）。[スプレッドシートビューアー](/ja/products/ai-studio/files/file-viewers#%E3%82%B9%E3%83%97%E3%83%AC%E3%83%83%E3%83%89%E3%82%B7%E3%83%BC%E3%83%88%E3%83%93%E3%83%A5%E3%83%BC%E3%82%A2%E3%83%BC)で開けますが表示は読み取り専用です。ソートやフィルタが必要ならダウンロードして Excel で開いてください。作業フォルダ内のファイルはチャットより長く残ります


## 接続済みウェアハウスへのクエリ

接続済みのSnowflakeやDatabricksには tdx 経由では到達しません。Studioはコネクタを専用のツール群としてエージェントに提供し、エージェントはそちらを使います。そのため、このページの内容の多くはそのままでは当てはまりません。

| 相違点  | Treasure Data CDP  | 接続済みウェアハウス  |
|  --- | --- | --- |
| **SQLの実行方法** | サンドボックス内の `tdx query` | コネクタ専用のツール |
| **SQL方言** | Trino（重い処理はHive） | そのウェアハウス自身の方言 |
| **SQLスキル** | 有効。Treasure AIの方言と関数を教えます | 適用されません。`td_interval` などのTD関数は存在しません |
| **権限** | あなた自身のTreasure AIアカウントの権限 | コネクションを認可したときのロール。Snowflakeでは固定の `PUBLIC` ロール |
| **出力オプション** | `--json`、`--output` などtdxのフラグ | コネクタが返す形式 |


一方で、**回答の読み方はどちらでも同じ**です。SQLはツールコールに表示されて確認でき、返信はモデルによる出力の言い直しであり、[回答の品質](/ja/products/ai-studio/query/answer-quality)の層の考え方もそのまま使えます。設定手順は[コネクション](/ja/products/ai-studio/connections)、エージェントが到達できる範囲は各コネクタのページを参照してください。

## Trinoはチャットで、Hiveはジョブで

`tdx query` は Trino 専用です。エンジンを選ぶオプションが存在しないため、チャットで「クエリを実行する」ときは常に Trino が動き、結果はそのままツールコールにストリーミングされます。

Hive は経路が異なり、クエリをジョブとして投入し、結果を後から取得します。

```bash
tdx job submit --job-type hive -f query.sql --database mydb
tdx job result <job-id>
```

`tdx query` がエンジンを切り替えてくれることを期待せず、この2ステップをエージェントに依頼してください。投入と結果取得が別の呼び出しになるため、**Hive の実行はストリーミングされません**。エージェントは投入してから、改めて出力を取りに行きます。単発であれば Treasure AI コンソールで実行するほうが簡単なこともあります。

`hive` と `trino-to-hive-migration` のスキルが「正しい Hive SQL を**書く**」ためのものなのは、このためです。実行経路は依頼する側が指定します。

## クエリを停止する

**停止**をクリックするとエージェントのターンが終了します。すでにクエリエンジンで実行中の文まで必ずキャンセルされるわけではなく、そのジョブはサーバー側で完了まで走ることがあります。ジョブ自体を止めるには、Treasure AI コンソールでキャンセルするか、エージェントに `tdx jobs` で最近のジョブを一覧させて対象を特定してください。

## tdx を自分で実行する

結果を説明する代わりに、実行するコマンドを名指しすることもできます（「`tdx describe mydb.users` を実行して」）。エージェントはそのまま実行します。自分のマシンで tdx を使う場合との違いは3点です。

- **サンドボックス内のマネージドな tdx インストール**に対して実行されます。お使いのコンピューターへのインストールも副作用もありません
- **入口はチャットだけ**です。キーボードのコマンドパレットはありません
- **独自の MCP サーバーは追加できません。** 別のデータソースをエージェントに渡すには[コネクション](/ja/products/ai-studio/connections)を使用してください


コマンドの構文はローカルで tdx を実行する場合と同一です。すべてのコマンド・オプション・出力フォーマットを含む完全な CLI リファレンスは [Treasure Code コマンド](/treasure-code/commands/)、クエリ固有のオプションは [`tdx query`](/treasure-code/commands/query) を参照してください。

## トラブルシューティング

| 問題 | 解決策 |
|  --- | --- |
| SQLがTreasure AI固有の関数を使わない、テーブル全体をスキャンする | SQLスキルが無効になっている可能性が高いです。**設定 → マーケットプレイス**で **sql-skills** を有効にして再度尋ねてください（[SQLスキルを有効にする](#sql%E3%82%B9%E3%82%AD%E3%83%AB%E3%82%92%E6%9C%89%E5%8A%B9%E3%81%AB%E3%81%99%E3%82%8B)） |
| クエリが「access denied」で失敗する | そのデータベースへのアクセス権がない可能性があります。エージェントに `tdx databases` を実行させて到達できる範囲を確認し、管理者に問い合わせてください |
| クエリは実行されるが、結果の読み取りが拒否される | ポリシーに **Download** 権限（結果をCDPの外へ持ち出すことを許可する権限）が不足している可能性が高いです。エージェントに `tdx policy` を実行させて `Databases` の行を確認してください（[クエリ結果の取得にはCDPのDownload権限が必要](#%E3%82%AF%E3%82%A8%E3%83%AA%E7%B5%90%E6%9E%9C%E3%81%AE%E5%8F%96%E5%BE%97%E3%81%AB%E3%81%AFcdp%E3%81%AEdownload%E6%A8%A9%E9%99%90%E3%81%8C%E5%BF%85%E8%A6%81)） |
| クエリが遅い、またはメモリ不足で失敗する | まず期間を狭めてください。それだけで解決することもよくあります。次に `trino-optimizer` スキルでの最適化を依頼し、それでも Trino で実行できない場合は Hive 用に書き直させてジョブとして投入します（[Trinoはチャットで、Hiveはジョブで](#trino%E3%81%AF%E3%83%81%E3%83%A3%E3%83%83%E3%83%88%E3%81%A7hive%E3%81%AF%E3%82%B8%E3%83%A7%E3%83%96%E3%81%A7)） |
| 回答が間違っているように見える | [クエリの回答がおかしいとき](/ja/products/ai-studio/query/answer-quality)の切り分けを順に確認してください。プロンプトの問題、クエリの問題、解釈の問題を分けて特定できます |


## 次のステップ

- [クエリ結果の読み方](/ja/products/ai-studio/query/query-results) — 実際の表示のされ方と、結果の取り出し方
- [クエリの回答がおかしいとき](/ja/products/ai-studio/query/answer-quality) — 数値や示唆がおかしいときに確認すること
- [スキルとマーケットプレイス](/ja/products/ai-studio/skills/skills) — エージェントの動作を左右するプラグインの有効化
- [結果をチャートにする](/ja/products/ai-studio/query/query-results#%E7%B5%90%E6%9E%9C%E3%82%92%E3%83%81%E3%83%A3%E3%83%BC%E3%83%88%E3%81%AB%E3%81%99%E3%82%8B) — クエリ結果をチャートにする