Відкрита специфікація · раніше DTQL

Запити, які можна читати, порівнювати і довіряти.

TugQL — портативна, людиночитана мова запитів. Вона поєднує чистий SQL-подібний синтаксис із еквівалентним представленням 1:1 без втрат у вигляді структурованого дерева запитів (TugQT), серіалізованого у звичайний YAML/JSON. Зберігайте запит, редагуйте вручну, переглядайте diff у системі контролю версій та виконуйте на різних бекендах без втрат.

Читати специфікацію Переглянути приклад


          $ 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 перетворює запит на зрозумілий документ із підтримкою diff, який можна зберігати, рецензувати та версіонувати — портативний на будь-якому бекенді.

Зрозумілий людині

Інтуїтивний SQL-подібний синтаксис для людей плюс просте дерево запиту YAML/JSON (TugQT) для інструментів — кожен може перевірити та відредагувати.

Перетворення без втрат

Канонічна нормалізація відтворює запити, структурно ідентичні вихідним. Жодна деталь не втрачається і не спотворюється непомітно.

Валідований за схемою

Опубліковано з повною валідацією через JSON Schema (draft 2020-12). Будь-який інструмент будь-якою мовою може перевірити структуру запиту.

Зручний для diff у Git

Канонічне форматування та детермінована серіалізація. Збережені запити дають чистий diff у Git і перевіряються як звичайний код.

Портативний за задумом

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: <скаляр> }`
Масив	`{ values: [ <скаляр>, … ] }`
Оператор	`==`, `In`, `>`, `>=`, `<`, `<=`
Limit / Offset	`limit: <int>` / `offset: <int>`

Вираз встановлює рівно одне з полів: field, value або values, що розрізняє посилання на поле, константу або масив.

04 — підтримувана підмножина

Що охоплює TugQL

Колекції та об’єднання, вибір колонок, фільтрація, сортування та пагінація. Усе за межами відхиляється — і ніколи не ігнорується мовчки.

Підтримується

Джерела колекцій · вибрані колонки · порівняння та дерева And/Or · сортування · limit / offset · joins · параметри. Вирази: поле, константа, масив. Оператори: ==, !=, In, >, >=, <, <=, And, Or.

Поза межами (помилка)

Необмежені декартові добутки · діалектний синтаксис окремих СКБД · нетипізовані оператори модифікації поза схемою. Серіалізація завершується помилкою, щоб не втратити семантику запиту.

Без втрат і канонічно

resolve(parse(text)) генерує детерміновані дерева; серіалізація канонічна, тому збережені запити дають чистий diff при порівнянні версій.

05 — де виконується

Один запит, багато бекендів

TugQL — це портативний інтерфейс запитів. Він спирається на шар абстракції даних (DALgo), що адаптує його до будь-якого сховища.

Оскільки TugQL визначає портативну підмножину, одного разу написаний запит поводиться однаково як над Git-репозиторієм (inGitDB), так і в SQLite, PostgreSQL або Firestore.

TugQLпортативна мова запитів

DALgoшар абстракції даних

inGitDB SQLite PostgreSQL Firestore

06 — початок роботи

Специфікація та реалізації

Мова є відкритою специфікацією з опублікованою схемою та реалізаціями мовами Go і TypeScript.

Використовується у розробці продуктів

Досліджуйте та запитуйте дані разом із DataTug.

DataTug допомагає розробникам досліджувати схеми баз даних, створювати та виконувати запити й розуміти результати. Робота над контрактами запитів TugQL та TugQT активно триває. Дізнайтеся більше про інструменти DataTug.

Зберігайте. Порівнюйте. Виконуйте будь-де.

TugQL робить запит повноцінним артефактом — зрозумілим для людей, валідованим інструментами та портативним для будь-яких баз даних.

Читати специфікацію Отримати бібліотеку для Go