> 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/tech/ja/advanced-genai-tech/text-to-sql.md).
# Text to SQL
Text to SQL の技術仕様：対応するデータベースと接続文字列の形式、読み取り専用の保護、ネットワークとアカウントの要件、大規模な schema の処理方法、クエリ結果の上限。
Text to SQL は、Agent がユーザーの自然言語による質問を SQL に変換し、接続先のデータベースを検索して、結果に基づいて回答する機能です。このページは、データベース管理者と技術担当者向けの仕様説明です。データベース接続の作成と Agent への関連付けの手順は、ユーザーマニュアルの [Text to SQL 機能](https://docs.maiagent.ai/build/database/text2sql)と[データベースの作成と設定](https://docs.maiagent.ai/build/database/create-database)をご覧ください。
## 動作方式
Text to SQL は、Agent が **Agent モード**を使用している場合のみ有効です。Agent は必要に応じて、次のツールを順に呼び出します。
1. クエリ可能なデータベースを一覧表示します（1 つの Agent に複数のデータベースを関連付けられます）。
2. データベース内のクエリ可能なテーブルとビュー、および入力されたテーブルの説明を一覧表示します。
3. 特定のテーブルのカラム構成とカラムの説明を読み取ります。
4. SQL クエリを実行し、結果を取得して回答します。
各クエリで返す行数は、プラットフォームの設定値が上限です（デフォルトは 1,000 行）。上限を超える場合は先頭の行だけを返し、結果が切り詰められたことをモデルに通知します。接続の切断などの一時的なエラーは自動で再試行します。SQL の構文エラーや権限エラーは、エラーメッセージをそのままモデルに渡し、モデルがクエリを修正します。
## 対応データベース
| 種類 | 接続文字列の形式 | 説明 |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| MaiAgent データベース | 不要です | スプレッドシートなどのファイルをアップロードしてテーブルを作成し、プラットフォームが管理します。ユーザーマニュアルの [MaiAgent データベースでの Text to SQL](https://docs.maiagent.ai/build/database/text-to-sql-maiagent)をご覧ください |
| PostgreSQL | `postgresql://ユーザー名:パスワード@ホスト:ポート/データベース` | `postgres://` で始まる形式にも対応します |
| MySQL | `mysql+pymysql://ユーザー名:パスワード@ホスト:ポート/データベース` | |
| Microsoft SQL Server | `mssql+pyodbc://ユーザー名:パスワード@ホスト:ポート/データベース?driver=ODBC+Driver+18+for+SQL+Server&TrustServerCertificate=yes&Encrypt=no` | プラットフォームに ODBC Driver 18 for SQL Server を組み込んでいます |
| Oracle | `oracle+oracledb://ユーザー名:パスワード@ホスト:ポート/?service_name=サービス名` | Oracle Database 12.1 以降に対応します。11g はプラットフォームで Oracle Client を追加で有効にする必要があります。MaiAgent の担当者にお問い合わせください |
| SynxDB | `postgresql://ユーザー名:パスワード@ホスト:ポート/データベース` | PostgreSQL 互換の MPP データウェアハウスです |
接続文字列の先頭は、選択した種類と一致する必要があります。一致しない場合は保存できません。作成時に 接続テストをクリックすると、プラットフォームからデータベースに接続できるか確認できます。
## 接続のセキュリティ
### 読み取り専用の保護
プラットフォームは、2 つの層でクエリを読み取り専用に制限します。
* **構文チェック**：`SELECT` のみ許可します（`WITH`、`UNION` などの読み取り構文を含みます）。`INSERT`、`UPDATE`、`DELETE`、`MERGE`、`CREATE`、`ALTER`、`DROP`、`TRUNCATE`、`SELECT … INTO`、およびセミコロンで連結した複数のステートメントはブロックします。
* **読み取り専用トランザクション**：PostgreSQL、MySQL、Oracle のクエリは読み取り専用トランザクションで実行し、データベース自体が書き込みを拒否します。SQL Server には同等の読み取り専用セッション設定がないため、プラットフォームは「クエリ後に必ずロールバックし、コミットしない」方式で処理します。この方式の保護は比較的弱くなります。
{% hint style="warning" %}
**必ず読み取り専用アカウントで接続してください。** プラットフォームの保護は第二の防御策です。データベースアカウントに必要なテーブルやビューの読み取り権限のみを付与することが、最も直接的な制御となります。SQL Server では特に重要です。
{% endhint %}
### アカウントと接続文字列
* MaiAgent 専用のアカウントを作成し、クエリが必要なテーブルやビューの `SELECT` 権限のみを付与することをおすすめします。
* 接続文字列にはユーザー名とパスワードが含まれます。保存後に読み取ると、マスクされた内容のみ表示します。変更する場合は、接続文字列全体を再入力してください。
* データベースを Agent に関連付けられるユーザーや、使用できるロールは、データベースのロール権限設定に従います。[データベースの作成と設定](https://docs.maiagent.ai/build/database/create-database)をご覧ください。
### ネットワーク要件
* データベースは MaiAgent プラットフォームから接続できる必要があります。プラットフォームからデータベースのホストとポート（接続文字列に記載したアドレス）に接続します。接続テストをクリックしたときと、各クエリの実行時に接続を確立します。
* ポートは接続文字列に従います。各データベースのデフォルト値は、PostgreSQL 5432、MySQL 3306、SQL Server 1433、Oracle 1521、SynxDB 5432 です（デプロイ設定によります）。
* **SaaS**：データベースは MaiAgent プラットフォームの送信元アドレスからの接続を許可する必要があります。ファイアウォールの許可リストを設定する場合は、MaiAgent の担当者に送信元 IP をお問い合わせください。
* **オンプレミスとプライベートクラウド**：プラットフォームとデータベースを同じネットワークセグメントに配置するか、VPN などで相互に接続できるようにする必要があります。
## 大規模な schema の処理
プラットフォームは schema 全体を一度にモデルに送信しません。モデルは最初にテーブル一覧と説明を取得し、必要に応じて個々のテーブルのカラム構成を読み取ります。テーブルが多い場合は、次の方法をおすすめします。
* **テーブルの指定****で範囲を絞ります**：質問への回答に必要なテーブルのみ公開します。空欄の場合、デフォルト schema 内のすべてのテーブルとビューをクエリできます。
* **別の schema のテーブルには schema 名を記載します**：例えば `sales.orders` です。プラットフォームは、デフォルト schema と指定テーブルに含まれる schema のみをスキャンします。
* **テーブル構造の説明****を入力します**：テーブルの用途とカラムの意味を説明すると、モデルが適切なテーブルとカラムを選びやすくなります。
* **あらかじめビューを作成します**：よく使う結合（JOIN）と業務ロジックをビューにまとめ、ビューだけを公開すると、クエリの誤りと権限リスクの両方を減らせます。
## よくある質問 接続テストが失敗する場合は？
接続文字列の先頭が選択した種類と一致するか、ホストとポートが正しいか、データベースが MaiAgent プラットフォームのアドレスからの接続を許可しているか（SaaS の場合は担当者に送信元 IP をお問い合わせください）、ユーザー名とパスワードが正しいかを順に確認してください。Oracle 11g はプラットフォームの追加設定が必要です。MaiAgent の担当者にお問い合わせください。
API で特定のテーブルの行数を取得するには？
データベース API（`/api/v1/sql-databases/…`）は、接続、テーブル、カラムの設定管理のみを提供します。テーブル一覧レスポンスの `count` はページネーション用のテーブル数であり、データ行数ではありません。行数を返すエンドポイントや SQL を実行するエンドポイントもありません。行数を知りたい場合は、会話で Agent に質問してください（例：「orders テーブルには何行ありますか？」）。モデルが `SELECT COUNT(*)` クエリを生成して回答します。または、データベースに直接接続してクエリしてください。
Agent は Text to SQL でデータを変更できますか？
できません。プラットフォームは読み取りクエリのみを許可し、書き込みや構造変更の構文をブロックします。API ドキュメントにあるデータベース、テーブル、カラムの `POST`／`PUT`／`PATCH` エンドポイントは、接続設定、テーブルとカラムの説明、およびスプレッドシートのテーブルへのアップロードを管理します。既存テーブルのデータ行への書き込みや変更は行わず、会話中の Agent もこれらのエンドポイントを呼び出せません。
Query Metadata は Text to SQL を制限しますか？
制限しません。Query Metadata はナレッジベース検索にのみ適用され、Agent が SQL を生成・実行する際には参照しません。リクエストごとにテーブルやデータ行を制限するフィールドもありません。データベースの範囲を絞れるのは、データベースの有効・無効、この Agent への関連付け、テーブルの指定、データベースアカウント自体の権限（ビューを含む）だけです。ユーザーの立場に応じて異なるデータを参照させる場合は、異なる Agent にそれぞれ別の接続または読み取り専用アカウントを組み合わせてください。
Agent の設定ページにデータベース設定が表示されない場合は？
データベース設定は Agent モードでのみ利用できます。先に Agent の回答モード設定で 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/tech/ja/advanced-genai-tech/text-to-sql.md?ask=&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.
.png?alt=media)