跳至主要內容
翻譯頁面

本頁面由英文在 AI 協助下翻譯而成。若兩者有出入,請以英文版本為準。

StackQL 架構概觀

StackQL 是單一 Go 二進位檔,在雲端與 SaaS Provider 的 API 之上實作 SQL 引擎。在架構上它分為四層:接受 SQL 的進入點、規劃 SQL 的剖析器與查詢引擎、依宣告式 Provider 規格執行即時 API 呼叫的 Provider SDK,以及對具體化結果執行關聯式運算的 SQL 後端。

元件​

進入點。共有三種進入方式,最終都交由同一個剖析器處理:

  • CLI / shell(stackql shell、stackql exec),用於互動式與批次作業。
  • PostgreSQL 線路協定伺服器(stackql srv,以 psql-wire 建構),讓任何 Postgres 用戶端(psql、DBeaver、BI 工具、pandas)都能連線。
  • MCP 伺服器(stackql mcp),向 AI 代理程式公開探索、驗證與受管控執行的工具(詳見 StackQL MCP 架構)。

SQL 剖析器。以 Yacc 為基礎的文法(stackql-parser),產生 AST。此方言涵蓋標準動詞,以及 StackQL 中繼命令(SHOW、DESCRIBE、REGISTRY)和用於非 CRUD 生命週期作業的 EXEC 動詞。

查詢引擎。規劃 AST:決定哪些部分下推到 Provider API(路由參數、支援的述詞),哪些在本機處理;協調 API 的執行(包括查詢跨越多個區域或需要多次呼叫時的平行扇出),並彙總結果。

Provider SDK(omnisdk)。通用的 API 用戶端,在 StackQL v1.0 中取代了 any-sdk。它從登錄庫載入 Provider 規格、處理各 Provider 的驗證、將每個陳述式規劃為 Provider 交換的圖形、根據查詢參數建立 HTTP 要求、將支援的述詞與筆數限制推送到這些要求中、不論採用哪種分頁機制(資料指標、位移、權杖)都能逐頁走訪分頁回應,並在 JSON 回應抵達時將其關聯化為資料列。

SQL 後端。具體化的 API 結果預設會存入內嵌的 SQLite 資料庫(也可改為設定外部 PostgreSQL),並在其中以完整的 SQL 語意執行聯結(包括跨 Provider 聯結)、彙總、排序、子查詢與運算式。

決定性的設計決策:Provider 即資料​

StackQL 沒有經過編譯的 Provider 專屬外掛程式。Provider 是具版本控制的文件集,也就是開放的 StackQL Provider 登錄庫 中的擴充 OpenAPI 規格,將 API 作業對應到資源、SQL 動詞與參數。REGISTRY PULL aws 會下載規格;SDK 則在執行階段解譯它。

這帶來幾項結果:Provider 的涵蓋範圍取決於有文件記載的 API 介面,而不是外掛程式的開發投入;資料平面與生命週期作業可以用與控制平面 CRUD 相同的方式對應;整個介面都能在執行階段自我檢查(SHOW PROVIDERS、SHOW METHODS IN aws.ec2.instances、DESCRIBE github.repos.repos),正是這項特性讓 StackQL 對 AI 代理程式而言能夠自我描述。

查詢執行流程​

以 SELECT instance_id, instance_type FROM aws.ec2.instances WHERE region = 'us-east-1'; 為例:

  1. 剖析器產生 AST;引擎根據 Provider 規格解析 aws.ec2.instances,並選取 describe 存取方法,由 region 滿足其必要參數。
  2. SDK 進行驗證(根據環境變數)、發出 EC2 API 呼叫,並逐頁走訪分頁。
  3. 回應會攤平成資料列,並具體化到 SQL 後端。
  4. 後端套用投影與其餘的關聯式處理;結果會以要求的格式傳回給呼叫端。

在步驟 2,region IN (...) 述詞會變成依區域平行發出的呼叫;在步驟 4,聯結可跨越所有提供資料表的 Provider 運作。