Otwarta specyfikacja · wcześniej DTQL

Zapytania, które możesz czytać, porównywać i którym możesz ufać.

TugQL to przenośny, czytelny dla człowieka język zapytań. Łączy przejrzystą, zbliżoną do SQL składnię z bezstratną reprezentacją 1:1 w postaci ustrukturyzowanego drzewa zapytań (TugQT) serializowanego jako czysty YAML/JSON. Zapisz zapytanie, edytuj je ręcznie, porównuj diff w systemie kontroli wersji i wykonuj na różnych backendach bez żadnych strat.

Przeczytaj specyfikację Zobacz przykład


          $ 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 — Dlaczego TugQL

Zapytanie to dane. Traktuj je jak dane.

TugQL zamienia zapytanie w zrozumiały dokument z obsługą diff, który możesz przechowywać, recenzować i wersjonować — przenośny na każdym backendzie.

Czytelny dla człowieka

Intuicyjna składnia zbliżona do SQL dla programistów oraz proste drzewo zapytań YAML/JSON (TugQT) dla narzędzi — każdy może je przejrzeć i edytować.

Bezstratna konwersja w obie strony

Kanoniczna normalizacja odtwarza zapytania strukturalnie identyczne ze źródłem. Nic nie jest po cichu pomijane ani zniekształcane.

Walidacja schematem

Publikowane z pełną walidacją JSON Schema (draft 2020-12). Dowolne narzędzie w dowolnym języku może sprawdzić strukturę zapytania przed wykonaniem.

Przyjazny dla diffów

Kanoniczne formatowanie i deterministyczna serializacja drzewa. Zapisane zapytania tworzą czyste diffy w Git i można je recenzować jak kod.

Przenośny z założenia

TugQL udostępnia funkcjonalność wspólną dla różnych silników — to samo zapytanie działa bez zmian w Git, SQLite, PostgreSQL czy Firestore.

Świadomie nie pełny SQL

Celowo zdefiniowany, przenośny podzbiór. Nieprzenośne konstrukcje są jawnie odrzucane, zamiast być ryzykownie tłumaczone.

02 — Przykład

Zapytanie w postaci TugQL i TugQT

Pisz w składni tekstowej TugQL; przechowuj lub przesyłaj jako ustrukturyzowane drzewo zapytań TugQT.

Autorzy piszą zapytania w składni tekstowej TugQL — czytelnej, zwięzłej i zbliżonej do SQL. Pod spodem parser generuje TugQT (Tug Query Tree) — kanoniczną, czytelną maszynowo reprezentację.

Każdy węzeł mapuje się deterministycznie między składnią a drzewem. Błędy składni lub naruszenia schematu zwracają precyzyjne komunikaty diagnostyczne ze wskazaniem miejsca w kodzie.

Uwaga dotycząca nazwy: TugQL był wcześniej znany jako DTQL. Istniejące dokumenty i pliki zapytań DTQL są nadal w pełni obsługiwane dla zachowania wstecznej kompatybilności.

          
          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 — węzeł → TugQT

Mapowanie

Każdy obsługiwany węzeł zapytania ma ściśle zdefiniowaną reprezentację strukturalną.

Węzeł zapytania	Reprezentacja w TugQT
From po kolekcji głównej	`from: { name, alias? }`
Kolumna	element w `columns:` — wyrażenie z opcjonalnym `as:`
Porównanie	`{ op, left, right }`
Warunek grupowy (And)	`{ and: [ … ] }`
Warunek grupowy (Or)	`{ or: [ … ] }`
Wyrażenie sortowania	element w `orderBy:` — wyrażenie z opcjonalnym `desc: true`
Odwołanie do pola	`{ field: <nazwa> }`
Stała	`{ value: <skalar> }`
Tablica	`{ values: [ <skalar>, … ] }`
Operator	`==`, `In`, `>`, `>=`, `<`, `<=`
Limit / Offset	`limit: <int>` / `offset: <int>`

Wyrażenie ustawia dokładnie jedno z pól: field, value lub values, co odróżnia odwołanie do pola, stałą lub tablicę.

04 — obsługiwany zakres

Co obejmuje TugQL

Pojedyncze kolekcje lub złączenia, wybrane kolumny, filtry, sortowanie i stronicowanie. Wszystko poza zakresem jest odrzucane — nigdy po cichu ignorowane.

W zakresie

Źródła kolekcji · wybrane kolumny · drzewa porównań i grupy And/Or · sortowanie · limit / offset · złączenia · parametry. Wyrażenia: pole, stała, tablica. Operatory: ==, !=, In, >, >=, <, <=, And, Or.

Poza zakresem (odrzucone)

Nieograniczone iloczyny kartezjańskie · specyficzna składnia poszczególnych dialektów bazodanowych · nietypowane operatory mutacji poza schematem. Serializacja kończy się błędem, aby nie utracić znaczenia zapytania.

Bezstratny i kanoniczny

resolve(parse(text)) generuje deterministyczne drzewa zapytań; kanoniczna serializacja sprawia, że zapisane zapytania tworzą czyste diffy między wersjami.

05 — środowiska uruchomieniowe

Jedno zapytanie, wiele backendów

TugQL to przenośna warstwa zapytań. Łączy się z warstwą abstrakcji danych (DALgo), która dostosowuje ją do dowolnego magazynu pod spodem.

Ponieważ TugQL definiuje wspólny, przenośny podzbiór, raz napisane zapytanie działa dokładnie tak samo zarówno w repozytorium Git (inGitDB), jak i w pliku SQLite, bazie PostgreSQL czy Firestore.

TugQLprzenośny język zapytań

DALgowarstwa abstrakcji danych

inGitDB SQLite PostgreSQL Firestore

06 — jak zacząć

Specyfikacja i implementacje

Język jest otwartą specyfikacją z opublikowanym schematem oraz implementacjami w Go i TypeScript.

Wykorzystywane w rozwoju produktów

Eksploruj i badaj dane z DataTug.

DataTug pomaga programistom badać schematy baz danych, tworzyć i uruchamiać zapytania oraz analizować wyniki. Prace nad integracją kontraktów zapytań z TugQL i TugQT trwają nieustannie. Poznaj narzędzia stojące za DataTug.

Zapisz. Porównaj. Uruchom wszędzie.

TugQL czyni zapytanie pierwszorzędnym, weryfikowalnym artefaktem — czytelnym dla ludzi, walidowanym przez narzędzia i przenośnym między silnikami bazodanowymi.

Przeczytaj specyfikację Pobierz bibliotekę Go