> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/ja/build/database/text2sql.md).

# Text to SQL 機能

本ページでは、MaiAgent システムで Text to SQL 機能を使用し、日常の会話でデータベース内の情報を手軽に照会する方法を紹介します

## **Text to SQL とは？** <a href="#what-is-text-to-sql" id="what-is-text-to-sql"></a>

**Text to SQL**（Text2SQL とも呼ばれます）は、**自然言語の質問**（人間の日常的な言葉）を **SQL データベースクエリ**に自動変換するインテリジェントなツールです。簡単に言えば、Agent が「<mark style="color:blue;">人の言葉を理解</mark>」し、データベースを直接操作できるようにするものです。

{% hint style="info" %}
Text2SQL の詳細については、こちらをご覧ください：[技術担当者向けマニュアル—Text to SQL](https://docs.maiagent.ai/tech/advanced-genai-tech/text-to-sql)
{% endhint %}

あなたがコンビニのオーナーだと想像してください。

**従来の方法：**

* あなた：「昨日コーラが何本売れたか調べて」
* 従業員：「オーナー、レジシステムでの調べ方を教えてください...」
* あなた：「ここをクリックして、あそこを選んで、条件を入力して...」

手取り足取り教える必要があり、時間がかかります。

**Text2SQL があれば：**

* あなた：「昨日コーラが何本売れたか調べて」
* AI 従業員：「承知しました！」💫 *（クエリ方法を自動生成してデータベースを呼び出します）* → 「昨日はコーラが 87 本売れました」✅

### **Text to SQL のコア機能** <a href="#text-to-sql-core-features" id="text-to-sql-core-features"></a>

```
自然言語の質問 → AI による理解・分析 → SQL クエリ → クエリの実行 → 結果の返却
```

Agent に「昨日一番売れた飲み物を探して」と尋ねると、Agent はまず質問を分析し、「飲み物」で、「昨日」「一番」売れたものを探していると理解します。次に SQL 構文を生成してデータベースに問い合わせ、最後に結果の「コーラ」をお知らせします。

## **Text to SQL で AI にできること** <a href="#what-text-to-sql-can-do" id="what-text-to-sql-can-do"></a>

### **具体的な活用シーン** <a href="#use-cases" id="use-cases"></a>

#### **🏥 医療クリニック** <a href="#medical-clinic" id="medical-clinic"></a>

```
医師の質問：「今日予約している糖尿病の患者を探して」
AI の回答：「今日の糖尿病患者の予約は 5 名です：
- 王さん 10:00 再診
- 李さん 14:30 経過観察検査
- 陳さん 16:00 血糖モニタリング」
```

#### **🏫 学校管理** <a href="#school-management" id="school-management"></a>

```
教師の質問：「今回の試験で不合格の生徒は何人？」
AI の回答：「今回の数学の試験：
- 総人数：45 名
- 不合格：8 名（17.8%）
- 再試験が必要な生徒の一覧を作成しました」
```

#### **🏪 小売チェーン店** <a href="#retail-chain" id="retail-chain"></a>

```
店長の質問：「3 店舗の月間売上を比較して」
AI の回答：「11 月の店舗別売上比較：
- 台北店：¥1,200,000 (↑15%)
- 台中店：¥950,000 (↑8%)  
- 高雄店：¥800,000 (↓3%)」
```

### **Text to SQL のメリット** <a href="#text-to-sql-advantages" id="text-to-sql-advantages"></a>

#### **⚡ 効率の向上** <a href="#efficiency-improvement" id="efficiency-improvement"></a>

* **従来の方法**：SQL の専門家がクエリを書く必要がある → 30 分
* **Text2SQL**：自然言語で質問する → 3 秒

#### **🎯 導入のハードルを下げる** <a href="#lower-barrier" id="lower-barrier"></a>

* 複雑な SQL 構文を学ぶ**必要はありません**
* データベース構造を覚える**必要はありません**
* **誰でも**データを照会できます

#### **📱 リアルタイムのやり取り** <a href="#real-time-interaction" id="real-time-interaction"></a>

* 質問すればすぐに答えが返ります
* 追加の質問にも対応します
* クエリ条件を動的に調整できます

## MaiAgent で Text to SQL 機能を使用する方法 <a href="#how-to-use-text-to-sql-in-maiagent" id="how-to-use-text-to-sql-in-maiagent"></a>

データベースは、左側メニューの「<mark style="color:blue;">AI 機能</mark>」→「<mark style="color:blue;">データベース</mark>」で一元的に作成します。1 つのデータベースを複数の Agent で使用でき、1 つの Agent を複数のデータベースに関連付けることもできます。設定は次の 3 ステップです。

### 1. データベースを作成して有効化する <a href="#enter-database-url" id="enter-database-url"></a>

「<mark style="color:blue;">データベース</mark>」ページで「<mark style="color:blue;">データベースを追加</mark>」をクリックし、データベースの種類を選択します。

* **MaiAgent データベース**：独自のデータベースがない場合に使用します。Excel、CSV、JSON ファイルをアップロードすると、システムが自動的にテーブルを作成します。接続文字列は不要です。[MaiAgent データベースで Text to SQL を使用する](/maiagent-user-guide/ja/build/database/text-to-sql-maiagent.md)をご参照ください。
* **外部データベース**：既存の PostgreSQL、MySQL、SQL Server、Oracle、SynxDB に接続します。接続文字列の入力が必要で、事前にデータベースが MaiAgent からの接続を許可していることを確認してください。

新しく作成したデータベースは、デフォルトでは無効になっています。「<mark style="color:blue;">データベースを有効化</mark>」をオンにすると、Agent がそのデータベースを照会できるようになります。詳しい手順、各データベースの接続文字列の形式、ネットワークのチェックリストについては、[データベースの作成と設定](/maiagent-user-guide/ja/build/database/create-database.md)をご参照ください。

### 2. Agent を Agent モードに切り替える <a href="#switch-to-agent-mode" id="switch-to-agent-mode"></a>

Agent の <mark style="color:blue;">設定</mark> で、左側ナビゲーションの「<mark style="color:blue;">回答モード設定</mark>」をクリックし、<mark style="color:blue;">Agent モード</mark>を選択します。

{% hint style="warning" %}
Text to SQL は Agent モードでのみ使用できます。他の回答モードの Agent では、左側ナビゲーションの「<mark style="color:blue;">データベース設定</mark>」がロックされ、データベースを選択できません。各回答モードの説明については、[Agent の作成](/maiagent-user-guide/ja/build/agent/setup.md#select-answer-mode-to-build-prompt)をご参照ください。
{% endhint %}

### 3. データベースと Agent を関連付ける <a href="#link-database-to-agent" id="link-database-to-agent"></a>

次の 2 つの方法のいずれかを選択します。

* Agent の <mark style="color:blue;">設定</mark> で、左側ナビゲーションの「<mark style="color:blue;">データベース設定</mark>」をクリックし、「<mark style="color:blue;">データベースを選択</mark>」を押して照会するデータベースにチェックを入れ、保存をクリックします。
* データベース設定ページの「<mark style="color:blue;">関連 AI アシスタント</mark>」タブで、Agent を右側に移動して保存します。[Agent とグループ権限の関連付け](/maiagent-user-guide/ja/build/database/link-chatbots-groups.md)をご参照ください。

設定が完了すると、Agent との会話で自然言語を使ってデータを照会できます。たとえば「先月最も売れた商品は？」のように質問できます。

## **トラブルシューティング** <a href="#troubleshooting" id="troubleshooting"></a>

* **接続に失敗する**：接続文字列の形式、アカウントとパスワード、ファイアウォールやホワイトリストが開放されているかを確認してください。[データベースの作成と設定：ネットワークの事前準備](/maiagent-user-guide/ja/build/database/create-database.md#network-prerequisites)をご参照ください。
* **Agent がデータベースを照会しない**：回答モードが Agent モードであること、データベースが有効化されていること、そのデータベースがこの Agent に関連付けられていることを確認してください。
* **Agent がデータベースしか照会せず、ナレッジベース検索ツールがないと回答する**：Agent モードでは、ナレッジベース検索も一連のツール（`retrieve_text_nodes` など）です。<mark style="color:blue;">ツール検索機能を有効化</mark>している場合、これらのツールは Text to SQL と同様に、先に検索で見つかってからでないと呼び出せません。モデルが検索を省略して「ツールがない」と回答することがあります。ロール指示に「回答する前に retrieve\_text\_nodes でナレッジベースを検索する」と明記するか、ツール検索をオフにしてすべてのツールを直接利用できるようにしてください。[Agent のツール設定](/maiagent-user-guide/ja/build/tools/configure_tools.md)をご参照ください。2 つのモードでの検索の違いについては、[技術担当者向けマニュアル - チャットモードと Agent モードでのナレッジベース検索の違い](https://docs.maiagent.ai/tech/quickstart/rag#chat-vs-agent-retrieval)をご参照ください。
* **特定のユーザーに一部のデータだけを照会させたい**：[メタデータクエリ](/maiagent-user-guide/ja/org/querymetadata.md#scope-and-limits)が制限するのはナレッジベース検索のみで、Text to SQL には適用されません。データベースの範囲は、有効化／関連付ける Agent、<mark style="color:blue;">テーブルの指定</mark>、ロール権限でのみ制御でき、リクエストごとに制限することはできません。ユーザーごとにアクセスを分けたい場合は、立場ごとに別々の Agent とデータベース接続（または読み取り専用アカウント）を作成してください。
* **クエリエラー**：テーブル名とカラム名が正しいことを確認し、テーブルとカラムに説明を追加してください。[カラムの説明を編集する](/maiagent-user-guide/ja/build/database/create-database.md#edit-column-description)をご参照ください。
* **権限不足**：データベースアカウントにこれらのテーブルの読み取り権限があるかを確認してください。
* **応答が遅い**：クエリの複雑さを確認し、インデックスの追加を検討するか、「<mark style="color:blue;">テーブルの指定</mark>」でクエリの範囲を絞り込んでください。

仕様面の説明（読み取り専用の保護、ネットワーク要件、大規模スキーマの扱い、クエリ結果の上限）については、[技術担当者向けマニュアル - Text to SQL](https://docs.maiagent.ai/tech/advanced-genai-tech/text-to-sql)をご参照ください。

***

Text2SQL により Agent がデータベースの専門家となり、誰でも自然言語で素早くビジネスインサイトを得られるため、データドリブンな意思決定の効率が大幅に向上します！


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/maiagent-user-guide/ja/build/database/text2sql.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.