Открытая спецификация · ранее DTQL

Запросы, которые можно читать, сравнивать и доверять.

TugQL — переносимый, человекочитаемый язык запросов. Он сочетает чистый SQL-подобный синтаксис с эквивалентным представлением 1:1 без потерь в виде дерева запросов (TugQT), сериализуемого в обычный YAML/JSON. Сохраняйте запрос, редактируйте вручную, просматривайте diff в Git и выполняйте на различных хранилищах без потерь данных.

Читать спецификацию Смотреть пример


          $ 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). Любой инструмент на любом языке может проверить структуру запроса перед выполнением.

Удобен для diff в Git

Каноническое форматирование и детерминированная сериализация дерева. Сохраненные запросы наглядно диффаются в 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