# クエリ結果の読み方

Studioでのクエリは2つの異なるものを生み、その区別が事故を防ぎます。1つは**生の出力**で、エージェントが実行したツールコールの中にあります。もう1つは**エージェントによる説明**で、回答本文の文章と整った表がこれにあたります。前者はクエリエンジンが返したものであり、後者はそれについて生成されたテキストです。このページでは両方の読み方と、結果セット全体が必要なときにチャットの外へ取り出す方法を扱います。

注意
Studioはクエリ出力をインタラクティブなテーブルとして描画しません。チャット内でのソート・フィルタ・エクスポートはなく、実行統計の行もありません。出力はテキストで、それ以上に構造化されたものが必要ならファイルに書き出します。

結果の読み方はデータソースを問わず同じです。ただしこのページの `tdx` 固有の話（行数の上限、出力フラグ）はTreasure Data CDPに対するものです。[接続済みウェアハウス](/ja/products/ai-studio/query/query-execution#%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)では、そのコネクタが返す形式になります。

## 前提条件

- Treasure AI Studioにサインイン済みであること（[はじめに](/ja/products/ai-studio/getting-started)）
- エージェントが実行したクエリがあること（[データのクエリ](/ja/products/ai-studio/query/query-execution)）


## 生の出力がある場所

チャットでクエリのツールコールを展開してください。中には実行されたコマンドと、その下に `tdx query` が出力したままの内容が等幅ブロックで表示されます（既定の罫線テーブル形式、または `--json` を使った場合はJSON）。

見え方を決めるのは次の2点です。

- **長い出力は12行で切られ**、**Show N more lines** で残りを表示します
- **1秒以上かかった場合は所要時間バッジ**が、失敗した場合は **Exit** バッジが行に付きます


ツールコールの**コピー**ボタンはコマンドをコピーします。Treasure Code やコンソールで自分で再実行したいときに最短です。

## 回答内の表は「言い直し」です

エージェントが回答するとき、多くの場合その数値をmarkdownの表や短い要約に整えます。**その表は結果セットの描画ではなく、読み取った出力からモデルが書き起こしたもの**です。たいていは忠実ですが、行が落ちたり、数値が丸められたり、列順が変わったりすることもあり、その違いを示す表示はどこにもありません。

したがって、重要な数値は文章ではなくツールコールと突き合わせてください。両者が食い違う場合、記録として正しいのはツールコールです。

警告
数値に続く分析にはこれがより強く当てはまります。「ロイヤルティキャンペーンが効いて売上が23%増加しました」という文には、クエリが出した数値と、モデルが推測した原因が混在しています。[解釈は生成されたテキストです](/ja/products/ai-studio/concepts/reliable-answers#%E8%A7%A3%E9%87%88%E3%81%AF%E7%94%9F%E6%88%90%E3%81%95%E3%82%8C%E3%81%9F%E3%83%86%E3%82%AD%E3%82%B9%E3%83%88%E3%81%A7%E3%81%99)を参照してください。

## 結果セット全体を取り出す

`tdx query` が40行に自己制限するのは対話的なターミナル上だけです。サンドボックスにはターミナルがないため、上限のないクエリはすべての行をツール出力に返します。その大半は切り詰めの向こうに隠れて読めないうえ、以降の会話にAIが使えるはずだった余地をまるごと占有します。

完全な結果が必要なときは、チャットの外へ出してください。

1. クエリをファイルに書き出させます: `tdx query --output results.csv "SELECT ..."`（`--json`、`--jsonl`、`--tsv` も使えます）
2. [スプレッドシートビューアー](/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)で開きます。読み取り専用の表示で、複数シートのワークブックにはシートタブが付きます
3. 手元に必要ならファイルカードまたはファイルパネルからダウンロードします


[作業フォルダ](/ja/products/ai-studio/concepts/work-folders)の中に書き出したファイルは、チャットが無くなった後も残ります。組織の[保持期間](/ja/products/ai-studio/security/data-retention)を越えて結果を保管する方法でもあります。

## 結果をチャートにする

Treasure AI Studioにチャートエンジンはありません。チャートを依頼すると、エージェントは他の成果物とまったく同じことをします。ファイルを書いて開くだけです。多くの場合それは自己完結したHTMLページで、[HTMLビューアー](/ja/products/ai-studio/files/file-viewers#html%E3%83%93%E3%83%A5%E3%83%BC%E3%82%A2%E3%83%BC)に表示されます。[Mermaidダイアグラム](/ja/products/ai-studio/files/file-viewers#mermaid%E3%83%93%E3%83%A5%E3%83%BC%E3%82%A2%E3%83%BC)や単なる画像になることもあります。チャート専用のパネルもチャート種別のメニューもなく、生成後に設定を変える場所もありません。

このことには実用上3つの帰結があります。

- **種類を選ぶのではなく、言葉で頼む。** 「直近30日の日次サインアップを折れ線グラフでプロットして」と言えば折れ線グラフが返ります。「ローンチ後にサインアップがどう動いたか見せて」のように問いだけを伝えると、種類の選択はエージェントに委ねられます。それで困らないことも多いですが、意図しないものが選ばれることもあります。チャートの種類を明示するコストはゼロです。
- **修正は再生成。** チャートはファイルなので、変更はそのファイルの新しい版になります。同じチャットで依頼すれば（「棒グラフにして」「地域別に分けて」「降順に並べ替えて」）、クエリ結果を文脈に持ったままエージェントが書き直します。
- **見た目は「何が書いたか」で決まる。** チャート生成はStudio自体の機能ではなく、ドキュメント生成を担うのと同じ[プラグイン](/ja/products/ai-studio/files/artifacts#%E5%AF%BE%E5%BF%9C%E3%81%99%E3%82%8B%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E5%BD%A2%E5%BC%8F)から来ています。「ダッシュボード」も同列のHTMLファイル1つ（1ページに複数のチャートを並べたもの）であり、独自のレイアウト規則や保存された状態を持つStudioの機能ではありません。


空のチャートは、たいてい読み込みがブロックされています
チャートのHTMLはチャートライブラリを公開CDNから取得することが多く、そのリクエストが成功しないとファイルは描画されません。制限の強いネットワーク下では成功しません。クエリが明らかに行を返しているのにチャートが空で開く場合は、CDNから読み込むのではなくチャートライブラリをファイルにインライン展開して再生成するようエージェントに依頼してください。

チャートには[回答内の表](#%E5%9B%9E%E7%AD%94%E5%86%85%E3%81%AE%E8%A1%A8%E3%81%AF%E8%A8%80%E3%81%84%E7%9B%B4%E3%81%97%E3%81%A7%E3%81%99)と同じ疑いを持つべきです。エージェントはチャートファイルにデータを自分で書き込むため、チャートが元のクエリと食い違うことがあります。チャートを他の人に見せるなら、まずいくつかの値をツールコールと照合してください。

## クエリが失敗したとき

失敗したクエリは、警告アイコンと **Exit** バッジの付いたツールコールとして表示されます。展開すると、原因となった文の下にエンジンのエラーテキストがあります。

| エラー | 原因 | 対処 |
|  --- | --- | --- |
| テーブルが見つからない | データベース名またはテーブル名の誤り | エージェントに `tdx databases`、次に `tdx tables <db>` を実行させ、正しい名前で再実行する |
| カラムが見つからない | スペルミス、または存在しないカラム | `tdx describe <db.table>` を実行させ、クエリを修正する |
| 権限がない | そのデータベースを読む権限がアカウントにない、またはクエリはできても結果をダウンロードする権限がない | 管理者に確認してください。エージェントはあなた自身の権限で実行しています。文が実行されたうえで結果の取得で失敗する場合は後者で、**Download** 権限が必要です（[クエリ結果の取得にはCDPのDownload権限が必要](/ja/products/ai-studio/query/query-execution#%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)） |
| 構文エラー | SQLが不正 | ツールコール内の文を読んでください。同種のエラーが繰り返されるなら、SQLスキルが無効の可能性が高いです（[SQLスキルを有効にする](/ja/products/ai-studio/query/query-execution#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)） |
| メモリまたはリソースのエラー | Trinoには重すぎるクエリ | 期間を狭めるようエージェントに依頼してください。本当に Hive が必要な場合は、`tdx query` では実行できずジョブとして投入する必要があります（[Trinoはチャットで、Hiveはジョブで](/ja/products/ai-studio/query/query-execution#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)） |


## コンソールでジョブを特定する

Studioは結果の横にジョブIDを表示しません。実行計画やリソース使用量、ログを見るためにTreasure AIコンソールでクエリを追跡したい場合は、エージェントに `tdx jobs` で最近のジョブを一覧させ、時刻と文で自分のジョブを特定してからコンソールで開いてください。[`tdx job`](/treasure-code/commands/job)を参照してください。

## 確認

- [ ] クエリのツールコールを展開し、コマンドの下にある生の出力を読む
- [ ] エージェントの回答にある数値を、その出力と突き合わせる
- [ ] 結果をCSVファイルとして書き出させ、スプレッドシートビューアーで開く


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

| 問題 | 解決策 |
|  --- | --- |
| 出力が途中で切れている | ツールコールを展開して **Show N more lines** を使ってください。本当に大きい結果なら、チャットで読まずファイルに書き出してください |
| エージェントの表と生の出力が食い違う | ツールコールを信頼してください。エージェントに出力を読み直させて訂正させ、すでに使ってしまった数値も確認し直してください |
| 結果をソートまたはフィルタしたい | チャット内ではどちらもできず、スプレッドシートビューアーにもソートとフィルタの機能はありません。`ORDER BY` / `WHERE` を付けて再実行するか、ファイルに書き出してダウンロードし Excel で開いてください |
| 大きなクエリの後でチャットが遅い・忘れっぽい | 大きな結果は、以降の会話に使える余地をほとんど残しません。次の質問は新しいチャットで始め、結果はファイルに保持してください（[セッション内メモリ](/ja/products/ai-studio/chat/in-session-memory)） |


## 次のステップ

- [クエリの回答がおかしいとき](/ja/products/ai-studio/query/answer-quality) — 結果や示唆がおかしいときに確認すること
- [データのクエリ](/ja/products/ai-studio/query/query-execution) — 質問がSQLになる流れと、その確認方法
- [ファイルビューア](/ja/products/ai-studio/files/file-viewers) — 書き出した結果を開くスプレッドシートビューアー