使用 Supabase 進行 Text to SQL

本文章將介紹如何在 MaiAgent 中使用 supabase 進行 Text to SQL 功能

Supabase 是什麼？

Supabase 是一個開源的 平台服務，旨在簡化現代應用程式的開發流程。其核心特性包括：

• 資料庫： 可以存放各種資料。

• 即時更新： 資料一有變動，你的應用程式馬上就會知道。

• 帳號管理： 幫你管理使用者的帳號和密碼。

• 內建身份驗證機制：內建身份驗證機制，簡化使用者身份管理流程，並提供多種身份驗證方式。

• 自動產生 API(即獲取資料的途徑)： 讓你用簡單的方式，就能從資料庫拿資料。

整合 Supabase 有什麼好處？

• 多張報表交叉查詢：Supabase 支援多張表格相互關聯，可由 A 報表值查詢其與 B 報表中的關係

• 建立索引，提升查詢效率：您可以針對經常查詢的內容建立索引，讓 AI 助理更精確的查找到您需要的內容

建立您的 Supabase

1. 建立 Supabase 帳號

• 首先，前往 Supabase 官網 點按「Sign in / Start your project(註冊)」。

若您尚未註冊，請先註冊帳號，以便進行後續步驟

• 登入後，您可以建立一個新的組織或使用舊有組織作業組織作業，在組織中再建立一個 project，每個 project 會有自己獨立的資料庫。

2. 進入 Database (資料庫)頁面

進入專案後，在左側的導航列表點選 Database > Tables 頁面新增資料

建立新表格

點選「New Table」，新建表格並為您的表格命名：

Supabase 提供了多種方式來建立新表格：

• 手動新增欄位： 適合從頭開始設計表格結構。您可以逐一新增欄位，並設定每個欄位的資料類型、預設值等。

• 匯入 .csv/.tsv 或純文字： 適合快速建立表格，特別是當您已經有現成的資料時。

  • 注意事項：

    • 純文字檔案的第一列必須為欄位名稱，欄位之間以逗號 (CSV) 或 Tab (TSV，就是按下鍵盤上的 Tab 鍵空格大小) 分隔。

此處選擇匯入資料：點按「Import data from CSV」，並貼上以 Tab 分隔的文字檔案，向下捲動可以看到製作成表格的結果。匯入完成後按下「Save」

選擇匯入方式

匯入純文字

預覽結果

主鍵 (Primary Key)

匯入完成後，會導回到設定頁面，這時必須指定一個主鍵，主鍵就像是身分證字號一樣，作為識別每一筆資料的唯一值。在這裡，我們選擇客戶編號作為主鍵。

外鍵 (Foreign Key)

往下滾動，可以看見 Foreign key 的指定，Foreign Key (外鍵) 就像是地址，可以透過這個地址對應這筆資料的來源所在，或其他更詳細的資料。

假設我們有兩個表格：「客戶資料表 (Customers)」和「訂單資料表 (Orders)」。

• 客戶資料表 (Customers)：

  • 客戶編號 (CustomerID) - 主鍵

  • 客戶姓名 (CustomerName)

  • 電話 (Phone)

  • 地址 (Address)

• 訂單資料表 (Orders)：

  • 訂單編號 (OrderID) - 主鍵

  • 客戶編號 (CustomerID) - 外鍵 (參考客戶資料表的 CustomerID)

  • 訂單日期 (OrderDate)

  • 總金額 (TotalAmount)

在這個例子中，「訂單資料表 (Orders)」中的「客戶編號 (CustomerID)」就是一個外鍵，它參考了「客戶資料表 (Customers)」的主鍵「客戶編號 (CustomerID)」。透過這個外鍵，我們可以知道每一筆訂單是由哪一個客戶所下的。

這個例子中，外鍵應放在 Order Table 中：

關係方向:

• 一個客戶 → 可以有多筆訂單 (一對多關係)

• 一筆訂單 → 只屬於一個客戶

外鍵原則:

外鍵應該放在「多」的那一方

因此:

• ✅ Order Table 中設置 customer_id (外鍵)，因為他是一對多關係中對應到「多」個的那方

• ❌ Customer Table 不需要存訂單資訊

因此，我們在 Order Table 中設置連結 Customer Table 中的 Customer ID 對應為 Order Table 中的 Customer ID。

關聯完成後，按下「Save」 後即可建立資料庫間的關聯。

3. 建立完成

待表格建立完成後，您就擁有一個完整的資料庫，可以透過 SQL 語法查找資料庫內的資料了！

如何建立 Supabase 工具

想要在 MaiAgent 上使用 Supabase 工具，您需要將其建立為 MCP 工具，才能讓 AI 助理使用 Supabase 功能：

工具介紹，請參考：工具功能概覽

1

至 MCP 服務平台建立 Server 與 Supabase 服務串聯

如何串接 MCP 工具，請參考：Remote MCP 服務概述 目前僅有 Composio 平台 支援 Supabase 平台串接

2

Composio 開啟可用功能

在串接 Composio 時請開啟基本資料庫操作內容，如新增、刪除、查詢等。

Composio 內建已勾選基本內容於 Important 中，您不須額外設置，僅需確保 Important 選項是已勾選的

3

將建置好的 Supabase 工具加入可用工具列表

如何建立 MCP 工具，請參考：建立 MCP 工具

Supabase 工具連線網址

當您在 MCP 服務平台上建立好 server 服務後，請將網址做以下處理：

1. 原網址(從 MCP Server 上得到)： https://backend.composio.dev/v3/mcp/12345678/mcp?include_composio_helper_actions=true

2. 將 「?include_composio_helper_actions=true 直接刪除

3. 新網址(將貼上於 MaiAgent 工具頁面)： https://backend.composio.dev/v3/mcp/12345678/mcp

請務必刪除以上內容，否則 AI 助理將無法正確使用 supabase 工具

工具建立完成後，請至 AI 助理設定中將 Supabase 工具加入至助理可用工具列表：

請在使用工具頁面按下儲存，否則 AI 助理仍然無法使用 Supabase 工具

使用 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 查詢語句，例如：

綜合查詢結果的回應與 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 助理可以進一步整合其他資訊，例如：庫存狀況、物流資訊等，提供更全面的訂單分析。

工具僅能調用您存放於資料庫的內容，若有分析需求，請務必將資料上傳至資料庫再開始分析。