# MaiAgent 資料庫進行 Text to SQL

想讓 AI 助理協助您分析 Excel、CSV 等試算表資料，只需要將檔案上傳至 MaiAgent 資料庫，AI 助理就能用自然語言查詢資料並產出統計分析結果。

{% hint style="info" %}
Text to SQL 的概念介紹請參考：[Text to SQL 功能](/database/text2sql.md)
{% endhint %}

## 步驟一：建立 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/HRs9S0Jju4lZX017CUGg" alt="建立 MaiAgent 資料庫"><figcaption><p>選擇 MaiAgent 資料庫並填寫名稱</p></figcaption></figure>

{% hint style="info" %}
詳細建立流程請參考：[建立與設定資料庫](/database/create-database.md)
{% endhint %}

## 步驟二：上傳試算表檔案 <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/vSgNU3S21nri9ADJFLqG" alt="表格管理"><figcaption><p>在表格管理頁籤上傳檔案</p></figcaption></figure>

您可以自行下載範例檔案（100 筆品項的食品銷售檔案.xlsx）進行測試，體驗 AI 助理的數據分析能力。

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

上傳完成後，等待處理狀態顯示「<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）必須只能是一個表格
* [x] 第一列必須為欄位名稱
* [x] 建議在欄位名稱後標註資料格式，如：`價格(int)`、`日期(datetime)`
* [x] 每個欄位的資料型態應保持一致
* [x] 如有特殊格式（例如貨幣、百分比等），需在上傳前統一格式化

{% hint style="info" %}
為提升 AI 查詢的準確度，建議為資料表和欄位加入描述。詳見：[建立與設定資料庫—編輯欄位描述](/database/create-database.md#bian-ji-lan-wei-miao-shu)
{% endhint %}

## 步驟三：關聯 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/mTuMMBsTb27pikGXkgdE" alt="關聯 AI 助理"><figcaption><p>將資料庫關聯至 AI 助理</p></figcaption></figure>

{% hint style="warning" %}
請確保 AI 助理的回答模式已切換至 **Agent 模式**，否則無法使用 Text to SQL 功能。

回答模式的詳細設定請參考：[建立 AI 助理](https://github.com/Playma-Co-Ltd/maiagent-user-guide-gitbook/blob/main/zh-tw/build/setup.md)
{% endhint %}

## 步驟四：與 AI 助理對話 <a href="#step-4-chat-with-ai-agent" id="step-4-chat-with-ai-agent"></a>

以上步驟完成後，您可以進入 AI 助理的對話頁面，直接用自然語言告訴 AI 助理您的需求。

{% hint style="info" %}
AI 助理對話介面請參考：[選擇串接平台](/conversations/choose-channel.md)，根據需求選擇最適合的對話平台。
{% endhint %}

### 數據分析 <a href="#data-analysis" id="data-analysis"></a>

Text to SQL 工具能協助您分析試算表中的數據，例如：「幫我找到去年銷售量最好的乳製品」

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

* 當您提出需求後，AI 助理會自動調用 Text-to-SQL 工具。
* 這個工具就像一位翻譯員，可以將您說的話翻譯成電腦看得懂的 SQL 語法，讓 AI 助理可以從資料庫中提取資料。

AI 助理會自動加上條件判斷、排序依據等查詢限制，將您的需求轉換為更完整的查詢指令。

* **AI 助理的思考 Query：** 找到去年銷售量最好的乳製品，按銷售數量降序排列。自動加入降序排列的條件，讓結果更符合您的需求。
* **AI 助理的回應(點按工具回應即可查看)：**

<div><figure><img src="/files/HmrJhi03IQFqySdr1y4x" alt=""><figcaption></figcaption></figure> <figure><img src="/files/DNAK8zKN3Dj6M67xiaI7" alt=""><figcaption></figcaption></figure></div>

**結果**

* AI 助理找到了所有「乳製品」的銷售資料及該項目的其他欄位資料。
* 每一行代表一筆資料，包含：產品 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/e1Qf4yT5IFNHDjotJFkz" alt=""><figcaption></figcaption></figure> <figure><img src="/files/PpsNxVrZmbPTDTHmTrW6" alt=""><figcaption></figcaption></figure></div>

2. 將 Agent 模式由一般模式改為<mark style="color:blue;">**畫布模式(Canvas)**</mark>

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

儲存設定後，即可與 AI 助理進行對話，例如：「請幫我產出統計過後的營收視覺化報表」

<figure><img src="/files/XCxnYxegTj9DhUBEZsCE" 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/pXIwg0tjhFFfwiHDbBY0" alt=""><figcaption></figcaption></figure>

報表呈現畫面如下，您可以：

1. 切換查看原始程式碼或畫面
2. 依照想查看的統計分類切換報表內容(此處依每個 AI 助理產出內容不同而不相同)

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

當切換至其他分類時，即可查看分類營收占比圓餅圖及分布分析長條圖：

<div><figure><img src="/files/02jr3wIdZ4D1HibZWOOq" alt=""><figcaption></figcaption></figure> <figure><img src="/files/h7fRkDEu00HiexX2d3kB" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
**額外提示**

* **資料品質很重要：** 確保您的試算表資料是乾淨且正確的，這將直接影響 AI 助理分析結果的準確性。
* **不想交給 AI 的資料需確實刪除**：在試算表中隱藏的資料仍然能正常解析並提供給 AI 助理，因此若有不希望暴露的資料不能僅以隱藏處理，而必須確實刪除。
* **多嘗試不同的問題：** 透過不同的提問方式，您可以從資料中挖掘出更多有價值的資訊。
* **善用 Canvas 模式：** Canvas 模式可以讓您輕鬆製作出各種視覺化報表，更直觀地呈現數據分析結果。
* **善用欄位描述：** 為資料表欄位加入描述，能顯著提升 AI 查詢的準確度。
  {% endhint %}


---

# Agent Instructions: 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:

```
GET https://docs.maiagent.ai/database/text-to-sql-maiagent.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.