> 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/maiagent-user-guide-ja/database/text-to-sql-maiagent.md).

# MaiAgent データベースで Text to SQL を実行する

AI アシスタントに Excel や CSV などの表計算データの分析を手伝ってもらいたい場合は、ファイルを MaiAgent データベースにアップロードするだけで、AI アシスタントが自然言語でデータを照会し、統計分析の結果を出力できるようになります。

{% hint style="info" %}
Text to SQL の概念については、こちらをご参照ください：[Text to SQL 機能](/maiagent-user-guide/maiagent-user-guide-ja/database/text2sql.md)
{% endhint %}

## ステップ 1：MaiAgent データベースを作成する <a href="#step-1-create-maiagent-database" id="step-1-create-maiagent-database"></a>

1. 左側のナビゲーションバーから「<mark style="color:blue;">AI 機能</mark>」>「<mark style="color:blue;">データベース</mark>」に進みます
2. 「<mark style="color:blue;">データベースを追加</mark>」をクリックします
3. 「<mark style="color:blue;">MaiAgent データベース</mark>」を選択します
4. データベース名（例：「2024 年度売上データ」）を入力し、作成をクリックします

<figure><img src="/files/dJTrbWCADIAbx9pyqnmM" alt="MaiAgent データベースを作成する"><figcaption><p>MaiAgent データベースを選択して名前を入力する</p></figcaption></figure>

{% hint style="info" %}
詳しい作成手順については、こちらをご参照ください：[データベースの作成と設定](/maiagent-user-guide/maiagent-user-guide-ja/database/create-database.md)
{% endhint %}

## ステップ 2：表計算ファイルをアップロードする <a href="#step-2-upload-spreadsheet" id="step-2-upload-spreadsheet"></a>

作成が完了したら、データベースの設定ページに進みます：

1. 「<mark style="color:blue;">テーブル管理</mark>」タブに切り替えます
2. 「<mark style="color:blue;">テーブルファイルをアップロード</mark>」をクリックします
3. 表計算ファイルをドラッグするか選択します

<figure><img src="/files/f5TKrDAnMBchEqOnkDjE" alt="テーブル管理"><figcaption><p>テーブル管理タブでファイルをアップロードする</p></figcaption></figure>

サンプルファイル（100 品目の食品売上ファイル.xlsx）をダウンロードしてテストし、AI アシスタントのデータ分析能力をお試しいただけます。

{% file src="/files/H21gjtHo5FgC5eL6Uuxe" %}

アップロードが完了したら、処理ステータスが「<mark style="color:blue;">成功</mark>」と表示されるのをお待ちください。表示されれば、データテーブルの作成が完了したことを示します。

{% hint style="warning" %}
対応フォーマット：`.csv`、`.xlsx`、`.xls`、`.json`、`.jsonl`。Excel ファイル内の各ワークシートはそれぞれ個別のデータテーブルとして作成されます。
{% endhint %}

#### テーブルフォーマットに関する注意事項 <a href="#table-format-notes" id="table-format-notes"></a>

* [x] 各ワークシート（Sheet）には 1 つのテーブルのみを含める必要があります
* [x] 1 行目は必ず列名にしてください
* [x] 列名の後ろにデータ形式を記載することを推奨します。例：`価格(int)`、`日付(datetime)`
* [x] 各列のデータ型は一貫させてください
* [x] 特殊な形式（通貨、パーセンテージなど）がある場合は、アップロード前に形式を統一してください

{% hint style="info" %}
AI による照会の精度を高めるため、データテーブルや列に説明を追加することを推奨します。詳しくは：[データベースの作成と設定—列の説明を編集する](/maiagent-user-guide/maiagent-user-guide-ja/database/create-database.md#bian-ji-lan-wei-miao-shu)
{% endhint %}

## ステップ 3：AI アシスタントと関連付ける <a href="#step-3-link-ai-agent" id="step-3-link-ai-agent"></a>

データベースを AI アシスタントと関連付けることで、AI アシスタントがデータを照会できるようになります：

1. 「<mark style="color:blue;">AI アシスタントと関連付け</mark>」タブに切り替えます
2. 左側から関連付けたい AI アシスタントを選択し、右側に移動します
3. 「<mark style="color:blue;">保存</mark>」をクリックします

<figure><img src="/files/YfuWcPuKtzdEzYkaf4ph" alt="AI アシスタントと関連付ける"><figcaption><p>データベースを AI アシスタントと関連付ける</p></figcaption></figure>

{% hint style="warning" %}
AI アシスタントの回答モードが **Agent モード**に切り替わっていることを必ずご確認ください。そうでない場合、Text to SQL 機能は使用できません。

回答モードの詳しい設定については、こちらをご参照ください：[AI アシスタントを作成する](/maiagent-user-guide/maiagent-user-guide-ja/build/setup.md)
{% endhint %}

## ステップ 4：AI アシスタントと対話する <a href="#step-4-chat-with-ai-agent" id="step-4-chat-with-ai-agent"></a>

以上のステップが完了したら、AI アシスタントの対話ページに進み、自然言語で直接 AI アシスタントにご要望をお伝えいただけます。

{% hint style="info" %}
AI アシスタントの対話インターフェースについては、こちらをご参照ください：[連携プラットフォームを選択する](/maiagent-user-guide/maiagent-user-guide-ja/conversations/choose-channel.md)。ご要望に応じて最適な対話プラットフォームをお選びください。
{% endhint %}

### データ分析 <a href="#data-analysis" id="data-analysis"></a>

Text to SQL ツールは、表計算内のデータ分析をお手伝いします。例えば：「昨年最も売れた乳製品を見つけてください」

<figure><img src="/files/XsgiVBkpyCzZbvcRcJAA" alt=""><figcaption></figcaption></figure>

* ご要望を入力すると、AI アシスタントは自動的に Text-to-SQL ツールを呼び出します。
* このツールは翻訳者のような役割を果たし、お話しいただいた内容をコンピューターが理解できる SQL 構文に翻訳することで、AI アシスタントがデータベースからデータを抽出できるようにします。

AI アシスタントは、条件判断や並べ替えの基準といった照会の制約を自動的に追加し、ご要望をより完全な照会コマンドに変換します。

* **AI アシスタントの思考 Query：** 昨年最も売れた乳製品を見つけ、売上数量の降順で並べ替える。降順で並べ替える条件を自動的に追加し、結果がご要望により合致するようにします。
* **AI アシスタントの応答（ツールの応答をクリックすると確認できます）：**

<div><figure><img src="/files/Q4SqKB3dhp6bh1mn7V58" alt=""><figcaption></figcaption></figure> <figure><img src="/files/pqRuZoZrwlc6hx6fEHju" alt=""><figcaption></figcaption></figure></div>

**結果**

* AI アシスタントは、すべての「乳製品」の売上データと、その項目のその他の列データを見つけ出しました。
* 各行は 1 件のデータを表し、製品 ID、製品名、製品カテゴリ、売上金額、売上数量……などを含みます。
* AI アシスタントはこれらのデータをもとに、最も売れた乳製品が「チーズ」であり、売上数量が 110、売上金額が 40,150 円であると判断しました。

### レポート作成（Canvas モード） <a href="#report-creation-canvas-mode" id="report-creation-canvas-mode"></a>

Text to SQL ツールは、美しいレポートの作成もお手伝いします。この機能を使うには Canvas モードを有効にする必要があります：

1. 「AI アシスタント設定ページ > 回答モード設定の下」で <mark style="color:blue;">Agent モード</mark>を見つけます

<div><figure><img src="/files/HgiNLtkU82LlTc0CEr29" alt=""><figcaption></figcaption></figure> <figure><img src="/files/0KYRBmx3xkVuuLYwWTk7" alt=""><figcaption></figcaption></figure></div>

2. Agent モードを通常モードから<mark style="color:blue;">**キャンバスモード（Canvas）**</mark>に変更します

<figure><img src="/files/3zUVlh9BJcFKM3jU10nn" alt=""><figcaption></figcaption></figure>

設定を保存すると、AI アシスタントと対話できるようになります。例えば：「統計処理した売上の可視化レポートを作成してください」

<figure><img src="/files/Z1fsoWBMOACsreDnO2aa" alt=""><figcaption></figcaption></figure>

* **AI アシスタントの思考 Query：** 食品会社の各商品の売上統計を計算する。総売上、平均売上、売上標準偏差、売上分布区間、各カテゴリの売上構成比などの統計指標を含む。レポートに必要な計算結果を自動的に出力し、結果がご要望により合致するようにします。
* **AI アシスタントの応答（ツールの応答をクリックすると確認できます）：**

{% code overflow="wrap" %}

```
[('分類營收占比-主食', '10.72%'), ('分類營收占比-乳製品', '11.97%'), ('分類營收占比-冷凍', '9.06%'), ('分類營收占比-罐頭', '10.25%'), ('分類營收占比-肉類', '13.23%'), ('分類營收占比-蔬果', '13.34%'), ('分類營收占比-調料', '4.51%'), ('分類營收占比-零食', '14.53%'), ('分類營收占比-飲料', '12.40%'), ('商品總數', '100'), ('平均營收', '19546.06'), ('最低營收', '1400'), ('最高營收', '63364'), ('營收標準差', '15736.83'), ('總營收', '1954606')]
```

{% endcode %}

**結果**

* AI アシスタントは、ツールが自動的に統計したすべての必要な統計項目の結果を取得し、返します。
* AI アシスタントはこれらのデータを可視化の基礎として、Canvas を使ってインタラクティブなレポート画面を作成します。

> 「キャンバスを使用」のボックスをクリックすると、画面の内容を確認できます

<figure><img src="/files/oUf7AbFjUROCC7d1GM9V" alt=""><figcaption></figcaption></figure>

レポートの表示画面は以下のとおりです。ここでは次のことができます：

1. ソースコードと画面の表示を切り替える
2. 確認したい統計カテゴリに応じてレポート内容を切り替える（ここでは各 AI アシスタントが出力する内容によって異なります）

<figure><img src="/files/nPjGmb7vphBPeQCacSxZ" alt=""><figcaption></figcaption></figure>

別のカテゴリに切り替えると、カテゴリ別売上構成比の円グラフと分布分析の棒グラフを確認できます：

<div><figure><img src="/files/fShTnAFdcDnmbEBcbRuZ" alt=""><figcaption></figcaption></figure> <figure><img src="/files/waBu9eT1OxYDOItz008r" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
**追加のヒント**

* **データの品質は重要です：** 表計算データがクリーンで正確であることを確認してください。これは AI アシスタントの分析結果の精度に直接影響します。
* **AI に渡したくないデータは確実に削除してください**：表計算で非表示にしたデータも正常に解析され、AI アシスタントに提供されます。そのため、公開したくないデータがある場合は非表示にするだけでは不十分で、確実に削除する必要があります。
* **さまざまな質問を試してみてください：** 異なる聞き方をすることで、データからより多くの価値ある情報を引き出すことができます。
* **Canvas モードを活用してください：** Canvas モードを使えば、さまざまな可視化レポートを簡単に作成でき、データ分析の結果をより直感的に表現できます。
* **列の説明を活用してください：** データテーブルの列に説明を追加することで、AI による照会の精度を大幅に向上させることができます。
  {% endhint %}


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.maiagent.ai/maiagent-user-guide/maiagent-user-guide-ja/database/text-to-sql-maiagent.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.