Leggibile dall'uomo
Sintassi di scrittura intuitiva simile a SQL per gli sviluppatori, combinata con un albero di query YAML/JSON (TugQT) per gli strumenti — chiunque può ispezionarla e modificarla.
Specifica aperta · precedentemente DTQL
Query facili da leggere, confrontare e affidabili.
TugQL è un linguaggio di query portabile e leggibile dall'uomo. Combina una sintassi di testo pulita in stile SQL con una rappresentazione dell'albero di query strutturato 1:1 e senza perdite (TugQT) serializzata come semplice YAML/JSON. Salva una query, modificala a mano, confrontala nei sistemi di controllo versione ed eseguila su diversi backend senza alcuna perdita.
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 20Una query è un dato. Trattala come tale.
TugQL trasforma una query in un documento comprensibile e confrontabile che puoi salvare, revisionare e versionare — portabile su qualsiasi backend.
Round-trip senza perdite
La semplificazione canonica ricostruisce query strutturalmente identiche all'originale. Nessun elemento viene eliminato o approssimato silenziosamente.
Validato da schema
Pubblicato con validazione completa JSON Schema (draft 2020-12). Qualsiasi strumento, in qualunque linguaggio, può validare la struttura di una query prima dell'esecuzione.
Ideale per i diff
Formattazione canonica e serializzazione deterministica dell'albero. Le query salvate generano diff puliti in Git e si revisionano come codice ordinario.
Portabile per progettazione
TugQL espone funzionalità universali tra i backend: la stessa query funziona invariata su Git, SQLite, PostgreSQL o Firestore.
Non tutto SQL
Un sottoinsieme portabile deliberatamente mirato e ben definito. I costrutti non portabili vengono respinti esplicitamente anziché tradotti in modo rischioso.
02 — Esempio
Una query in formato TugQL & TugQT
Scrivi con la sintassi di testo TugQL; conserva o scambia sotto forma di albero strutturato TugQT.
Gli sviluppatori compongono le query nella sintassi di testo TugQL — leggibile, compatta e simile a SQL. Sotto il cofano, il parser genera TugQT (Tug Query Tree), una rappresentazione canonica leggibile dalla macchina.
Ogni nodo si mappa in modo deterministico tra sintassi e albero. Errori di sintassi o violazioni di schema restituiscono diagnostiche dettagliate con l'indicazione precisa del testo sorgente.
Nota sul nome: TugQL era precedentemente noto come DTQL. I documenti e i file di query DTQL esistenti restano supportati per retrocompatibilità.
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 — nodo → TugQT
Mappatura
Ogni nodo di query supportato ha una rappresentazione strutturata definita.
| Nodo di query | Rappresentazione TugQT |
|---|---|
| From su una collezione radice | from: { name, alias? } |
| Colonna | elemento sotto columns: — espressione con as: opzionale |
| Confronto | { op, left, right } |
| Condizione di gruppo (And) | { and: [ … ] } |
| Condizione di gruppo (Or) | { or: [ … ] } |
| Espressione di ordinamento | elemento sotto orderBy: — espressione con desc: true opzionale |
| Riferimento al campo | { field: <nome> } |
| Costante | { value: <scalare> } |
| Array | { values: [ <scalare>, … ] } |
| Operatore | ==, In, >, >=, <, <= |
| Limite / Offset | limit: <int> / offset: <int> |
Un'espressione imposta esattamente uno tra field, value o values, discriminando un riferimento di campo, una costante o un array.
04 — sottoinsieme supportato
Cosa rappresenta TugQL
Collezioni singole o join, colonne selezionate, filtri, ordinamento e paginazione. Tutto ciò che è fuori ambito viene rifiutato — mai ignorato in silenzio.
Supportato
Sorgenti di collezioni · colonne selezionate · alberi di confronto e gruppi And/Or · ordinamento · limit / offset · join · parametri. Espressioni: campo, costante, array. Operatori: ==, !=, In, >, >=, <, <=, And, Or.
Fuori ambito (rifiutato)
Join cartesiani illimitati · sintassi dialettale specifica di un singolo database · operatori di mutazione non tipizzati fuori dallo schema. La serializzazione fallisce anziché perdere il significato della query.
Lossless & canonico
resolve(parse(text)) produce alberi deterministici; la serializzazione è canonica, garantendo diff ordinati tra le varie versioni salvate.
05 — dove viene eseguito
Una query, molteplici backend
TugQL è la superficie di query portabile. Si collega a un livello di astrazione dati (DALgo) che la adatta a qualunque archivio sottostante.
Poiché TugQL esprime il sottoinsieme portabile, una query scritta una sola volta si comporta allo stesso modo sia su un repository Git (inGitDB), sia su SQLite, PostgreSQL o Firestore.
TugQLlinguaggio di query portabile
DALgolivello di astrazione dati
inGitDB
SQLite
PostgreSQL
Firestore
06 — per iniziare
Specifica & implementazioni
Il linguaggio è una specifica aperta con schema pubblicato e implementazioni in Go e TypeScript.
-
specifica · schema
tugql/tugql
La specifica TugQL, il JSON Schema canonico (draft 2020-12) e documenti di esempio validati. Precedentemente DTQL.
-
implementazione di riferimento · Go
dal-go/dalgo/dtql
La libreria Go: parsing, validazione, risoluzione, formattazione ed esecuzione di query TugQL con garanzie lossless.
Utilizzato nello sviluppo del prodotto
Esplora e interroga i dati con DataTug.
DataTug aiuta gli sviluppatori a esplorare schemi di database, comporre ed eseguire query e comprendere i risultati. L'integrazione con TugQL e TugQT è in continuo sviluppo. Scopri gli strumenti dietro DataTug.
Salvala. Confrontala. Eseguila ovunque.
TugQL trasforma la query in un artefatto di prim'ordine e verificabile — comprensibile alle persone, validato dagli strumenti e portabile su tutti i backend.