開放規範 · 原名 DTQL

可閱讀、 可比對、可信賴的查詢。

TugQL 是一種便攜、易於人類閱讀的查詢語言。它將簡潔的類 SQL 文字語法與以純 YAML/JSON 序列化的 1:1 無損結構化查詢樹（TugQT）相結合。您可以儲存查詢、手動編輯、在版本控制中比對差異，並在不同的後端無損執行。

閱讀規範 查看範例 $ go get github.com/dal-go/dalgo/dtql
query.tugql TugQL 
from users as u
select
  u.name,
  u.age as years
where
  u.age >= 18
  and (u.status in ('active', 'pending') or u.country == 'US')
order by
  u.name,
  u.age desc
limit 10
offset 20
01 — 為什麼選擇 TugQL

查詢即資料。請像對待資料一樣對待它。

TugQL 將查詢轉變為清晰易懂、可比對差異的文件，支援儲存、審查與版本控制——在任何支援的後端之間無縫遷移。

易於人類閱讀

面向開發者的直觀類 SQL 編寫語法，以及面向工具鏈的純 YAML/JSON 查詢樹（TugQT）——任何人都可以審查、理解和修改。

無損雙向轉換

規範的查詢降階能夠重建與原始輸入結構完全相等的查詢。不會有任何內容被靜默捨棄或近似替代。

經架構驗證

發布了完整的 JSON Schema 驗證（draft 2020-12）。任何語言的任何工具都可以在執行前驗證查詢結構的正確性。

版本控制友善

規範的格式化與確定性的語法樹序列化。儲存的查詢在 Git 中呈現乾淨清晰的 diff，能像程式碼一樣進行 code review。

天生具備跨平台便攜性

TugQL 提煉了跨後端通用的核心能力，因此同一個查詢無需修改即可直接運行於 Git、SQLite、PostgreSQL 或 Firestore。

並非全量 SQL

刻意聚焦於定義明確的便攜式子集。非通用語法會被明確拒絕，而不是進行具備不可預測風險的轉換。

02 — 範例

TugQL 文字語法與 TugQT 樹

使用 TugQL 文字語法編寫；以 TugQT 結構化查詢樹格式儲存或傳輸。

開發者使用 TugQL 文字語法編寫查詢——清晰、緊湊且類似 SQL。在底層，解析器產生 TugQT（Tug Query Tree），這是一種規範的機器可讀表示形式。

每個節點在文字語法和樹結構之間都有確定性的雙向對應。語法錯誤或架構違規將返回包含精確原始碼位置的診斷訊息。

關於命名的說明： TugQL 原名 DTQL。現有的 DTQL 文件和查詢檔案將繼續獲得回溯相容支援。
users.tugqt.yaml YAML 
from:
  name: users
columns:
  - field: name
  - field: age
    as: years
where:
  and:
    - op: '>='
      left:
        field: age
      right:
        value: 18
    - or:
        - op: In
          left:
            field: status
          right:
            values:
              - active
              - pending
        - op: ==
          left:
            field: country
          right:
            value: US
orderBy:
  - field: name
  - field: age
    desc: true
limit: 10
offset: 20
03 — 節點 → TugQT

對應規則

支援範圍內的每個查詢節點都有明確定義的結構化表示。

查詢節點TugQT 表示方式
根集合的 From 查詢from: { name, alias? }
資料欄定義columns: 下的項目——包含運算式及選用的 as:
比較運算{ op, left, right }
條件組合（And）{ and: [ … ] }
條件組合（Or）{ or: [ … ] }
排序運算式orderBy: 下的項目——包含運算式及選用的 desc: true
欄位參照{ field: <name> }
常數{ value: <scalar> }
陣列{ values: [ <scalar>, … ] }
運算子==, In, >, >=, <, <=
Limit / Offsetlimit: <int> / offset: <int>

運算式只設定 field、value 或 values 中的恰好一項，以此區分欄位參照、常數或陣列。

04 — 涵蓋子集

TugQL 支援的特性範圍

單個集合來源或連接樹、選定欄位、篩選運算式、排序和分頁。任何超出範圍的內容都會被明確拒絕——絕不會靜默忽略。

支援範圍內

集合來源 · 選定欄位 · 比較及 And/Or 樹 · 排序 · limit / offset · 連接 · 參數。運算式：欄位參照、常數、陣列。運算子：==, !=, In, >, >=, <, <=, And, Or。

超出範圍（報錯拒絕）

無限制的笛卡兒積 · 廠商專屬的特有 SQL 方言 · 缺乏架構約束的無型別修改運算。序列化時會直接報錯，確保絕不破壞查詢語意。

無損且規範

resolve(parse(text)) 產生確定性的查詢樹；序列化具有規範性，因此儲存的查詢能夠在不同版本之間清晰呈現 diff。

05 — 執行環境

一次編寫，多端運行

TugQL 是通用的便攜查詢層。它對應到底層資料抽象層（DALgo），後者將其適配到底層的各種儲存引擎中。

因為 TugQL 僅表達跨平台的通用子集，所以編寫一次的查詢在 Git 存放庫（inGitDB）、嵌入式 SQLite 檔案、PostgreSQL 資料庫或 Firestore 上的行為完全一致。

TugQL便攜查詢語言
DALgo資料抽象層
inGitDB SQLite PostgreSQL Firestore
06 — 快速上手

規範與實作

該語言是一項開放規範，擁有公開發布的 Schema，以及 Go 和 TypeScript 實作。

應用於真實產品開發

使用 DataTug 探索並查詢資料。

DataTug 幫助開發者瀏覽資料庫架構、建構並執行查詢並深入分析結果。其基於 TugQL 和 TugQT 的查詢協議研發正在持續推進。探索 DataTug 背後的工具。

儲存它。比對它。隨處運行它。

TugQL 讓查詢成為一等公民的審查產物——人類可讀、工具可驗證，並且能在多種後端之間無縫移植。

閱讀規範 取得 Go 語言程式庫