# MaiAgent 資料庫進行 Text to SQL

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

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

## 步驟一：建立 MaiAgent 資料庫

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="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-47693964f61a21cbe4bc63dea48231572c79a5b5%2Fdatabase-create-step2-maiagent.png?alt=media" alt="建立 MaiAgent 資料庫"><figcaption><p>選擇 MaiAgent 資料庫並填寫名稱</p></figcaption></figure>

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

## 步驟二：上傳試算表檔案

建立完成後，進入資料庫設定頁面：

1. 切換至「<mark style="color:blue;">表格管理</mark>」頁籤
2. 點擊「<mark style="color:blue;">上傳表格檔案</mark>」
3. 拖曳或選取您的試算表檔案

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-09ccb5aa77313aa38ba34535a6d73e8e314f3aa8%2Fdatabase-config-tables.png?alt=media" alt="表格管理"><figcaption><p>在表格管理頁籤上傳檔案</p></figcaption></figure>

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

{% file src="<https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-8d604a6457417ff38131ee0a0d95f8c83c8b1735%2F%E9%A3%9F%E5%93%81%E5%85%AC%E5%8F%B8%E9%8A%B7%E5%94%AE%E8%A1%A8_2024%E5%B9%B4%E5%BA%A6.xlsx?alt=media&token=09f0cb7d-85ed-4009-974b-2cb8edf87f39>" %}

上傳完成後，等待處理狀態顯示「<mark style="color:blue;">成功</mark>」，即代表資料表已建立完成。

{% hint style="warning" %}
支援格式：`.csv`、`.xlsx`、`.xls`、`.json`、`.jsonl`。Excel 檔案中每個工作表會各自建立一張資料表。
{% endhint %}

#### 表格格式注意事項

* [x] 每一個工作表（Sheet）必須只能是一個表格
* [x] 第一列必須為欄位名稱
* [x] 建議在欄位名稱後標註資料格式，如：`價格(int)`、`日期(datetime)`
* [x] 每個欄位的資料型態應保持一致
* [x] 如有特殊格式（例如貨幣、百分比等），需在上傳前統一格式化

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

## 步驟三：關聯 AI 助理

將資料庫關聯至您的 AI 助理，AI 助理才能查詢資料：

1. 切換至「<mark style="color:blue;">關聯 AI 助理</mark>」頁籤
2. 從左側選取要關聯的 AI 助理，移至右側
3. 點擊「<mark style="color:blue;">儲存</mark>」

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-e08163775dfd39fb858a84ff2f07aa388fa88517%2Fdatabase-config-chatbots.png?alt=media" alt="關聯 AI 助理"><figcaption><p>將資料庫關聯至 AI 助理</p></figcaption></figure>

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

回答模式的詳細設定請參考：[建立 AI 助理](https://docs.maiagent.ai/build/setup)
{% endhint %}

## 步驟四：與 AI 助理對話

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

{% hint style="info" %}
AI 助理對話介面請參考：[選擇串接平台](https://docs.maiagent.ai/conversations/xuan-ze-chuan-jie-ping-tai)，根據需求選擇最適合的對話平台。
{% endhint %}

### 數據分析

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

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-b49ef5cf4363892753424aa6225e7042392e2c2f%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-10-02%20123605.png?alt=media" alt=""><figcaption></figcaption></figure>

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

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

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

<div><figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-c4f745270d44290bd00923e4089e242f522e9ccd%2Fplayma%20%E6%89%8B%E5%86%8A%E7%9B%B8%E7%89%87%E5%8A%A0%E5%B7%A5%20(2).png?alt=media" alt=""><figcaption></figcaption></figure> <figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-ff5cc7add60481f938382af29146017a59aa96fc%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-10-02%20123141.png?alt=media" alt=""><figcaption></figcaption></figure></div>

**結果**

* AI 助理找到了所有「乳製品」的銷售資料及該項目的其他欄位資料。
* 每一行代表一筆資料，包含：產品 ID、產品名稱、產品類別、銷售金額、銷售數量......。
* AI 助理根據這些資料，判斷出銷售最好的乳製品是「乳酪」，銷售數量為 110，銷售金額為 40,150 元。

### 報表製作(Canvas 模式)

Text to SQL 工具也能協助您製作精美的報表，此功能會需要開啟 Canvas 模式：

1. 至「AI 助理設定頁面 > 回答模式設定下」找到 <mark style="color:blue;">Agent 模式</mark>

<div><figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-41678399a2144df49036f13fbc9a87910ab8fd4a%2Fplayma%20%E6%89%8B%E5%86%8A%E7%9B%B8%E7%89%87%E5%8A%A0%E5%B7%A5%20(4).png?alt=media" alt=""><figcaption></figcaption></figure> <figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-dbe72984ddec2401d58bf02e457318c4b3b3e160%2Fplayma%20%E6%89%8B%E5%86%8A%E7%9B%B8%E7%89%87%E5%8A%A0%E5%B7%A5%20(5).png?alt=media" alt=""><figcaption></figcaption></figure></div>

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

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-c9be337e0574e5ddb418ac8c45a8fe0f338567fb%2Fplayma%20%E6%89%8B%E5%86%8A%E7%9B%B8%E7%89%87%E5%8A%A0%E5%B7%A5%20(6).png?alt=media" alt=""><figcaption></figcaption></figure>

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

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-727fef28fa05ee8af3a6d501bc0dc5a30ca32c94%2F%E8%9E%A2%E5%B9%95%E6%93%B7%E5%8F%96%E7%95%AB%E9%9D%A2%202025-10-02%20142354.png?alt=media" 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="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-4c8190e58d5e582b66ef541ddb971843b792a243%2Fplayma%20%E6%89%8B%E5%86%8A%E7%9B%B8%E7%89%87%E5%8A%A0%E5%B7%A5%20(7).png?alt=media" alt=""><figcaption></figcaption></figure>

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

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

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-15f5d597a9ca2985c25b2fc6957f5ac514df6d07%2Fplayma%20%E6%89%8B%E5%86%8A%E7%9B%B8%E7%89%87%E5%8A%A0%E5%B7%A5%20(8).png?alt=media" alt=""><figcaption></figcaption></figure>

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

<div><figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-fc5121a6f2b4c00165ddc86d69bf20f736d8a0af%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure> <figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-deeec5cd7e0b60180064919150b856db8e3945b6%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure></div>

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

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