# クエリ実行（Trino）

データに関する質問を平易な日本語で入力すると、Studioが最適化されたTrino SQLに変換し、アカウントに対して実行して結果を表示します。これらすべてがチャットストリーム内で完結します。SQLの完全な可視性により、結果に基づいて行動する前にすべてのクエリを確認できます。

注意
AIはサンドボックス実行環境内で`tdx query`コマンドを使用してTrinoクエリを実行します。生成されたすべてのSQL文はツールコールの展開表示で確認できるため、独立してレビュー、コピー、再実行が可能です。

## 目的

自然言語によるリクエストを通じてTreasure AIアカウントに対してTrinoクエリを実行し、会話内にインラインで構造化された読みやすい結果を受け取ります。

## 前提条件

- Treasure AI Studioにサインイン済みであること（[はじめに](/ja/products/ai-studio/getting-started)）
- Treasure AIアカウントでアクセス可能なデータベースが少なくとも1つあること


## AIを通じたクエリ実行

データをクエリする最も簡単な方法は、求めていることを平易な言葉で説明することです。

- 「過去30日間で売上上位10名の顧客を表示してください」
- 「`pageviews`テーブルには何行ありますか？」
- 「`mydb.users`にはどのようなカラムがありますか？」


AIはリクエストをTrino SQLクエリに変換し、`tdx query`を使用して実行し、結果をフォーマットされたテーブルとして表示します。これらすべてがチャットストリーム内で完結します。

### 内部での処理の流れ

1. **クエリを自然言語で説明します**
2. **AIがSQLを作成し**、Bashツール経由で実行します：`tdx query "SELECT ..."`
3. **ツールコールがチャットに表示され**、実行中のコマンドを確認できます
4. **クエリ結果が自動的に**構造化されたテーブルとして表示されます（[クエリ結果テーブル](/ja/products/ai-studio/query/query-results)を参照）
5. **AIが結果を解釈し**、会話を続けます


各ステップがリアルタイムで進行するのを確認できます。ツールコールインジケーターには実行中のコマンドが表示され、結果が届くと結果テーブルが自動的に展開されます。

## 特定のコマンドのリクエスト

クエリの構文と実行を正確に制御するには、実行したいコマンドをAIに直接指示します。


```
You: Run tdx query "SELECT count(*) AS total_users FROM mydb.users"
```

または、スキーマの簡易確認のために`tdx describe`や`tdx show`の使用を指示することもできます。


```
You: Describe the mydb.users table
You: Show me a preview of mydb.users
```

| コマンド | 目的 | 出力 |
|  --- | --- | --- |
| `tdx query "<sql>"` | 任意のTrino SQLを実行する | クエリ結果テーブル |
| `tdx describe <db.table>` | テーブルスキーマを表示する（カラム名と型） | スキーマテーブル |
| `tdx show <db.table>` | テーブルデータをプレビューする（デフォルト件数制限付きのSELECT *） | データテーブル |


完全なコマンドリファレンスについては、[TDXコマンド](/ja/products/ai-studio/query/tdx-commands)を参照してください。

## チャット内のクエリライフサイクル

クエリが実行されると、チャットストリームに**ツールコールインジケーター**が表示されます。

### 実行中

- **スピニングローダー**アイコンがクエリの進行中を示します
- **コマンドの説明**がモノスペースフォントで完全なコマンドプレビューとともに表示されます
- 実行中のSQLを正確に確認できます


### 完了時

- **緑色のチェックマーク**がスピナーと置き換わります
- ツールコールの行が**展開可能**になります — クリックすると完全なコマンドと生の出力を確認できます
- **クエリ結果テーブル**がツールコールの下に自動的に表示され、カラムヘッダー、型、フォーマットされたデータを含む構造化された結果が表示されます
- **実行統計**がテーブルの下に表示されます（詳細は[クエリ結果テーブル](/ja/products/ai-studio/query/query-results)を参照）
- **実行時間バッジ**が1秒以上の場合に実行時間を表示します（例：「3.2s」）


### エラー時

- **赤いXアイコン**がクエリの失敗を示します
- 「クエリが失敗しました」エラーカードが以下の情報とともに表示されます：
  - 実行されたSQL（モノスペースフォント）
  - クエリエンジンからのエラーメッセージ
  - トラブルシューティング用の**ジョブID**
- ツールがゼロ以外のステータスで終了した場合、**終了コードバッジ**（例：「Exit 1」）が表示されます


## クエリの停止

AIの応答の一部としてクエリが実行中の場合、チャット入力エリアの**停止**ボタン（四角いアイコン）をクリックしてAIの実行ストリームを中断できます。

注意
応答を停止すると、AIの実行ストリームが終了します。クエリ自体はTrinoエンジン上で引き続き実行される場合があります。長時間実行されているクエリをキャンセルする必要がある場合は、Treasure AIコンソールを使用してください。

## クエリの検出

StudioはBashツールコールからクエリ結果を自動的に検出します。UIは以下を含むコマンドを認識します。

- `tdx query`、`tdx describe`、`tdx show`
- `trino`、`presto`
- `psql`、`mysql`、`sqlite3`


検出された場合、生の出力はプレーンテキストとして表示されるのではなく、構造化されたテーブルとして解析されます。2つの出力フォーマットが認識されます。

| フォーマット | 説明 |
|  --- | --- |
| **JSON配列** | `[{"col1": val1, ...}, ...]` — `--json`フラグによって生成される |
| **罫線テーブル** | `┌─│├┤┘`文字を使用したUnicodeテーブル形式 — `tdx query`のデフォルト出力 |


技術的な注意
クエリの検出は`detectQueryResult()`関数を介してクライアント側で行われます。この関数はBashコマンド文字列と出力フォーマットを検査します。Bashツールコールがクエリコマンドパターンにマッチし、その出力に有効なJSON配列または罫線テーブル文字が含まれている場合、出力はプレーンテキストの代わりに`QueryResultTable`コンポーネントとして表示されます。ストリーミング中に結果が検出されると、テーブルは自動的に展開されます。

## クエリ最適化のためのスキルの活用

複雑なクエリの場合、プロジェクト設定で組み込みのSQLスキルを有効化することで、レイテンシを削減し効率を向上させることができます。

| スキル | 機能 |
|  --- | --- |
| `sql-skills:trino` | Treasure AIのベストプラクティスに基づいたTrino SQLを作成する |
| `sql-skills:hive` | 重い処理向けのHive SQLを作成する |
| `sql-skills:time-filtering` | 時間ベースのクエリに`td_interval`とパーティションプルーニングを適用する |
| `sql-skills:trino-optimizer` | 低速なTrinoクエリを分析・最適化する |
| `sql-skills:trino-to-hive-migration` | メモリ消費の多いTrinoクエリをHiveに変換する |


例：`sql-skills:trino-optimizer`スキルが有効な状態で、クエリのレイテンシのボトルネックを分析するようAIに依頼します。パーティションプルーニング、述語プッシュダウン、その他の最適化が提案されます。

完全なスキルカタログについては、[スキルとマーケットプレイス](/ja/products/ai-studio/skills/skills)を参照してください。

## ベストプラクティス

1. **まず自然言語から始めましょう。** AIにクエリの初稿を作成させてください。結果を解釈する前に、ツールコール内のSQLを確認してください。
2. **クエリの前に`tdx describe`を使用しましょう。** スキーマ（カラム名、型）を理解することで、あなたとAIの両方が正確なクエリを作成しやすくなります。
3. **データベースコンテキストを設定しましょう。** セッションの開始時にAIに`tdx use database mydb`を実行させることで、すべてのクエリで完全修飾テーブル名を入力する手間を省けます。
4. **生成されたSQLを確認しましょう。** AIはあなたの説明と検出したスキーマに基づいてSQLを作成します。結果に基づいて行動する前に、必ずツールコールの展開表示でクエリを確認してください。
5. **大きな結果セットには出力フォーマットフラグを使用しましょう。** 大きな結果セットを処理する必要がある場合、AIに`--json`（構造化出力）または`--output results.csv`（ファイルへの保存）の使用を指示してください。


## 確認

- [ ] 「[your_database].[your_table]には何行ありますか？」と質問し、`tdx query`を実行するツールコールが表示されることを確認する
- [ ] 結果がカラムヘッダーと型を含む構造化されたテーブルとして表示されることを確認する
- [ ] ツールコールを展開して完全なSQLと生の出力を確認する


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

| 問題 | 解決策 |
|  --- | --- |
| クエリに時間がかかりすぎる | `sql-skills:trino-optimizer`スキルを使用してレイテンシの問題を分析してください。一般的な原因：フルテーブルスキャン（パーティションプルーニングを追加）、過剰なJOIN、時間カラムのWHERE句の欠如 |
| 「アクセスが拒否されました」でクエリが失敗する | Treasure AIアカウントがデータベースとテーブルへのアクセス権を持っていることを確認してください。AIに`tdx databases`を実行させて利用可能なデータベースを確認してください |
| AIが誤ったSQLを作成する | クエリリクエストの前に`sql-skills:trino`スキルを有効化してください。これによりAIにTreasure AI固有のSQLパターンと関数が提供されます |


## 次のステップ

- [クエリ結果テーブル](/ja/products/ai-studio/query/query-results) — フォーマット、カラム型、統計情報
- [TDXコマンド](/ja/products/ai-studio/query/tdx-commands) — 完全なCLIコマンドリファレンス
- [スキルとマーケットプレイス](/ja/products/ai-studio/skills/skills) — 最適化とベストプラクティスのためのSQLスキル