# 使用 Supabase 進行 Text to SQL
## Supabase 是什麼？
Supabase 是一個開源的 平台服務，旨在簡化現代應用程式的開發流程。其核心特性包括：
* **資料庫：** 可以存放各種資料。
* **即時更新：** 資料一有變動，你的應用程式馬上就會知道。
* **帳號管理：** 幫你管理使用者的帳號和密碼。
* **內建身份驗證機制：**內建身份驗證機制，簡化使用者身份管理流程，並提供多種身份驗證方式。
* **自動產生 API(即獲取資料的途徑)：** 讓你用簡單的方式，就能從資料庫拿資料。
### 整合 Supabase 有什麼好處？
* **多張報表交叉查詢：**Supabase 支援多張表格相互關聯，可由 A 報表值查詢其與 B 報表中的關係
* **建立索引，提升查詢效率：**您可以針對經常查詢的內容建立索引，讓 AI 助理更精確的查找到您需要的內容
## 建立您的 Supabase
### 1. 建立 Supabase 帳號
* 首先，前往 [Supabase 官網](https://supabase.com/) 點按「Sign in / Start your project(註冊)」。
> 若您尚未註冊，請先註冊帳號，以便進行後續步驟
.png?alt=media)
* 登入後，您可以建立一個新的組織或使用舊有組織作業組織作業，在組織中再建立一個 project，每個 project 會有自己獨立的資料庫。
### 2. 進入 Database (資料庫)頁面
進入專案後，在左側的導航列表點選 Database > Tables 頁面新增資料
#### 建立新表格
點選「New Table」，新建表格並為您的表格命名：
Supabase 提供了多種方式來建立新表格：
* **手動新增欄位：** 適合從頭開始設計表格結構。您可以逐一新增欄位，並設定每個欄位的資料類型、預設值等。
* **匯入 .csv/.tsv 或純文字：** 適合快速建立表格，特別是當您已經有現成的資料時。
* **注意事項：**
* 純文字檔案的第一列必須為欄位名稱，欄位之間以逗號 (CSV) 或 Tab (TSV，就是按下鍵盤上的 Tab 鍵空格大小) 分隔。
此處選擇匯入資料：點按「Import data from CSV」，並貼上以 Tab 分隔的文字檔案，向下捲動可以看到製作成表格的結果。匯入完成後按下「Save」
#### 主鍵 (Primary Key)
匯入完成後，會導回到設定頁面，這時必須指定一個主鍵，主鍵就像是身分證字號一樣，作為識別每一筆資料的唯一值。在這裡，我們選擇客戶編號作為主鍵。
.png?alt=media)
#### 外鍵 (Foreign Key)
往下滾動，可以看見 Foreign key 的指定，Foreign Key (外鍵) 就像是地址，可以透過這個地址對應這筆資料的來源所在，或其他更詳細的資料。
.png?alt=media)
假設我們有兩個表格：「客戶資料表 (Customers)」和「訂單資料表 (Orders)」。
* **客戶資料表 (Customers)：**
* 客戶編號 (CustomerID) - 主鍵
* 客戶姓名 (CustomerName)
* 電話 (Phone)
* 地址 (Address)
* **訂單資料表 (Orders)：**
* 訂單編號 (OrderID) - 主鍵
* 客戶編號 (CustomerID) - 外鍵 (參考客戶資料表的 CustomerID)
* 訂單日期 (OrderDate)
* 總金額 (TotalAmount)
在這個例子中，「訂單資料表 (Orders)」中的「客戶編號 (CustomerID)」就是一個外鍵，它參考了「客戶資料表 (Customers)」的主鍵「客戶編號 (CustomerID)」。透過這個外鍵，我們可以知道每一筆訂單是由哪一個客戶所下的。
{% hint style="info" %}
這個例子中，外鍵應放在 Order Table 中：
**關係方向:**
* 一個客戶 → 可以有多筆訂單 (一對多關係)
* 一筆訂單 → 只屬於一個客戶
**外鍵原則:**
> 外鍵應該放在「多」的那一方
因此:
* ✅ Order Table 中設置 `customer_id` (外鍵)，因為他是一對多關係中對應到「多」個的那方
* ❌ Customer Table 不需要存訂單資訊
{% endhint %}
因此，我們在 Order Table 中設置連結 Customer Table 中的 Customer ID 對應為 Order Table 中的 Customer ID。
關聯完成後，按下「Save」 後即可建立資料庫間的關聯。
### 3. 建立完成
待表格建立完成後，您就擁有一個完整的資料庫，可以透過 SQL 語法查找資料庫內的資料了！
## 如何建立 Supabase 工具
想要在 MaiAgent 上使用 Supabase 工具，您需要將其建立為 MCP 工具，才能讓 AI 助理使用 Supabase 功能：
{% hint style="info" %}
工具介紹，請參考：[工具功能概覽](https://docs.maiagent.ai/tools/tool_description)
{% endhint %}
{% stepper %}
{% step %}
**至 MCP 服務平台建立 Server 與 Supabase 服務串聯**
如何串接 MCP 工具，請參考：[Remote MCP 服務概述](https://docs.maiagent.ai/tech/remote-mcp/remote-mcp) 目前僅有 [Composio 平台](https://docs.maiagent.ai/tech/remote-mcp/composio) 支援 Supabase 平台串接
{% endstep %}
{% step %}
**Composio 開啟可用功能**
在串接 Composio 時請開啟基本資料庫操作內容，如新增、刪除、查詢等。
{% hint style="warning" %}
Composio 內建已勾選基本內容於 Important 中，您不須額外設置，僅需確保 Important 選項是已勾選的
{% endhint %}
{% endstep %}
{% step %}
**將建置好的 Supabase 工具加入可用工具列表**
如何建立 MCP 工具，請參考：[建立 MCP 工具](https://docs.maiagent.ai/tools/mcp-setup)
**Supabase 工具連線網址**
當您在 MCP 服務平台上建立好 server 服務後，請將網址做以下處理：
1. 原網址(從 MCP Server 上得到)：\
[https://backend.composio.dev/v3/mcp/12345678/mcp?include\_composio\_helper\_actions=true](https://backend.composio.dev/v3/mcp/5987158a-806a-4c32-9ff6-4236e8891ac2/mcp?include_composio_helper_actions=true)
2. 將 「[?include\_composio\_helper\_actions=true](https://backend.composio.dev/v3/mcp/5987158a-806a-4c32-9ff6-4236e8891ac2/mcp?include_composio_helper_actions=true) 直接刪除
3. 新網址(將貼上於 MaiAgent 工具頁面)：\
[https://backend.composio.dev/v3/mcp/12345678/mcp](https://backend.composio.dev/v3/mcp/5987158a-806a-4c32-9ff6-4236e8891ac2/mcp?include_composio_helper_actions=true)
{% hint style="danger" %}
請務必刪除以上內容，否則 AI 助理將無法正確使用 supabase 工具
{% endhint %}
{% endstep %}
{% endstepper %}
工具建立完成後，請至 AI 助理設定中將 Supabase 工具加入至助理可用工具列表：
{% hint style="danger" %}
請在使用工具頁面按下儲存，否則 AI 助理仍然無法使用 Supabase 工具
{% endhint %}
## 使用 Supabase 工具的效果
透過 MaiAgent AI 助理配合 Supabase 工具，只需用日常用語描述您想要查詢的資料，Supabase 就能自動為您生成對應的 SQL 語法，並從關聯式資料庫中提取所需的資訊。
### 範例資料庫
#### 🏢 **1. Customers 表格（顧客資訊）**
| 欄位名稱 | 主鍵 | 必填 | 說明 |
|---|
客戶編號 (CustomerID) | ✅ | ✅ | 客戶唯一識別碼 |
客戶名稱 (CustomerName) | ❌ | ❌ | 客戶公司或個人名稱 |
客戶類型 (CustomerType) | ❌ | ❌ | 客戶分類（如：零售商、餐廳、經銷商） |
聯絡人姓名 (ContactName) | ❌ | ❌ | 主要聯絡人姓名 |
電話 (Phone) | ❌ | ❌ | 聯絡電話 |
Email | ❌ | ❌ | 電子郵件地址 |
地址 (Address) | ❌ | ❌ | 客戶地址 |
區域 (Region) | ❌ | ❌ | 地理區域（如：北部、南部） |
客戶等級 (CustomerLevel) | ❌ | ❌ | 客戶重要性等級（A、B、C級） |
**🔑 主鍵**: `客戶編號 (CustomerID)`\
**🔗 外鍵關聯**: 無
***
#### 📦 **2. Orders 表格（訂單資訊）**
| 欄位名稱 | 主鍵 | 必填 | 說明 |
|---|
訂單編號 (OrderID) | ✅ | ✅ | 訂單唯一識別碼 |
客戶編號 (CustomerID) | ❌ | ❌ | 關聯到 Customers 表格 |
訂單日期 (OrderDate) | ❌ | ❌ | 訂單建立日期 |
交貨日期 (DeliveryDate) | ❌ | ❌ | 預計或實際交貨日期 |
付款方式 (PaymentMethod) | ❌ | ❌ | 付款方式（現金、信用卡、匯款） |
訂單狀態 (OrderStatus) | ❌ | ❌ | 訂單處理狀態 |
總金額 (TotalAmount) | ❌ | ❌ | 訂單總金額（數值型態） |
運費 (ShippingFee) | ❌ | ❌ | 運送費用 |
**🔑 主鍵**: `訂單編號 (OrderID)`\
**🔗 外鍵關聯**:
* `客戶編號 (CustomerID)` → `Customers.客戶編號 (CustomerID)` ( Orders 的 CustomerID 對應 Customer 表格中的 CustomerID)
***
#### 🛍️ **3. Products 表格（商品資訊）**
| 欄位名稱 | 主鍵 | 必填 | 說明 |
|---|
產品編號 (ProductID) | ✅ | ✅ | 產品唯一識別碼 |
產品名稱 (ProductName) | ❌ | ❌ | 產品名稱 |
產品描述 (Description) | ❌ | ❌ | 產品詳細描述 |
產品類別 (Category) | ❌ | ❌ | 產品分類 |
品牌 (Brand) | ❌ | ❌ | 產品品牌 |
規格 (Size) | ❌ | ❌ | 產品規格或尺寸 |
成本 (Cost) | ❌ | ❌ | 產品成本（數值型態） |
價格 (Price) | ❌ | ❌ | 產品售價（數值型態） |
庫存量 (StockQuantity) | ❌ | ❌ | 目前庫存數量（數值型態） |
**🔑 主鍵**: `產品編號 (ProductID)`\
**🔗 外鍵關聯**: 無
### 情境一：追蹤還沒完成的訂單
* **資料庫狀態：** `Orders` 表格中有兩筆尚未完成的訂單，分別是 `OR003` 和 `OR004`。
* **自然語言輸入：** 在 AI 助理的問答中，您只需輸入：「請告訴我還沒完成的訂單有哪些」。AI 助理自動調用工具並產出 SQL 結構化查詢語句。
* **Supabase 自動查詢：** AI 助理會自動調用 Supabase 工具，將您的自然語言轉換為 SQL 查詢語句，例如：
.png?alt=media)
綜合查詢結果的回應與 AI 助理的分析，AI 助理將回應以下訂單內容，並依照優先程度排序：
透過 Supabase 工具與 AI 助理的協同合作，您可以輕鬆地追蹤未完成的訂單，並獲得 AI 助理提供的分析與排序建議，以便更有效地處理訂單，提升客戶滿意度。
### 情境二：查詢未完成訂單的顧客聯絡資訊
* 在 OR003 為還在處理中的訂單，顧客為 CU003，聯絡人為**黃採購**
* **自然語言輸入：** 在 AI 助理的問答中，輸入：「還在處理中的訂單，我應該要聯絡誰」。AI 助理自動調用工具並產出 SQL 結構化查詢語句。
* **Supabase 自動對應查詢：**可以看見雖然與 AI 助理對話的內容都屬於訂單表格，但透過設置的外鍵對應關係，supabase 能夠知道此處 `Customer ID` 對應到的是 `Customers` 表格中的 `ID` 查詢，因此回傳的內容為 `Customers` 表格內容。
* **AI 助理回應：**接著AI助理綜合分析後回應正確的聯絡人資訊及其他聯絡方式
透過 Supabase 工具，您可以充分利用資料庫中的表格對應關係，輕鬆地從多個相關表格中提取資訊，並獲得 AI 助理提供的顧客姓名列表。表格間的對應關係和清楚的定義確保了資料的關聯性和一致性，使得查詢結果更加可靠。
## **額外補充：**
* 您可以根據實際需求，調整自然語言輸入，例如：「請告訴我今天還沒完成的訂單」、「請告訴我 VIP 客戶還沒完成的訂單」等，Supabase 工具都能夠準確地解析並執行查詢。
* AI 助理可以進一步整合其他資訊，例如：庫存狀況、物流資訊等，提供更全面的訂單分析。
{% hint style="warning" %}
工具僅能調用您存放於資料庫的內容，若有分析需求，請務必將資料上傳至資料庫再開始分析。
{% endhint %}
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)
.png?alt=media)