Парсинг SQL в JSON/AST и построение Lineage-графов

ERflow API

Интегрируйте разбор SQL и построение моделей данных в свои процессы: ревью запросов, автодокументация, CI/CD и внутренние инструменты аналитики. API не требует доступа к базе данных — вы передаёте только текст SQL и получаете структурированный результат.

Base URL

https://erflow.ru

Формат

application/json

Лимит Free

100000 символов SQL

Business

без лимита + X-API-Key

Быстрый старт

Все методы принимают JSON вида {"sql": "..."}. Для трассировки поля в Tree Model добавьте {"field": "alias"}.

cURL (Windows)

curl -X POST https://erflow.ru/api/parse ^
  -H "Content-Type: application/json" ^
  -d "{\"sql\": \"WITH t AS (SELECT 1 AS x) SELECT x FROM t\"}"

Business-режим: добавьте заголовок -H "X-API-Key: <KEY>"

Python

import requests

url = "https://erflow.ru/api/er"
payload = {"sql": "SELECT u.id FROM users u LEFT JOIN posts p ON u.id=p.author_id"}
r = requests.post(url, json=payload, timeout=30)
r.raise_for_status()
data = r.json()
print(len(data["er"]["nodes"]), len(data["er"]["edges"]))

Авторизация

Заголовок X-API-Key (опционально)

Передайте ключ доступа для Business-режима:

X-API-Key: <YOUR_KEY>

Если ключ отсутствует, действуют лимиты Free (до 100000 символов SQL).

Лимиты и коды ответов

Коды ответов

Код	Когда	Формат
`200`	Успешный ответ (включая `status=partial`)	JSON
`400`	Неверный JSON или типы полей (например, `sql` не строка)	JSON с `error`
`413`	SQL превышает лимит Free	JSON с `error`, `limit`
`500`	Внутренняя ошибка сервиса	JSON с `error`

Пример ошибки (413 SQL too large)

{
  "error": "SQL too large",
  "limit": 100000,
  "hint": "Use X-API-Key with a PRO key to remove the limit."
}

Что означает status в parse/er/tree

ok — запрос разобран без предупреждений.
partial — разбор выполнен best-effort: есть предупреждения в errors, но структура пригодна для графов/дерева.
error — парсер не смог корректно построить AST; возвращается безопасный fallback.

Эндпоинты

Ниже — схемы запросов/ответов и описание атрибутов. Для краткости приведены ключевые поля; большие вложенные структуры (например, AST) описаны на уровне верхних узлов.

POST /api/parse AST / JSON

Разбирает SQL и возвращает устойчивую JSON-структуру (AST) для последующего построения ER/lineage и Tree Model.

Тело запроса

{
  "sql": "SELECT ..."
}

Параметры запроса

Поле	Тип	Обяз.	Описание
`sql`	string	да	SQL-текст. Парсер best-effort, поддерживает CTE/RECURSIVE, JOIN/USING, подзапросы, функции и окна.

Ответ (пример)

{
  "version": "1.0",
  "status": "ok",
  "errors": [],
  "ast": { "type": "statement", "with": null, "query": { "type": "query_block" } }
}

Поля ответа верхнего уровня

Путь	Тип	Описание
`version`	string	Версия формата ответа парсера.
`status`	string	`ok` / `partial` / `error`.
`errors[]`	array	Список предупреждений/ошибок. Каждый элемент: `{message, pos?}`.
`ast`	object\|null	AST запроса. Ключевые узлы: `statement.with`, `statement.query`, `query_block.select/from`.

Ключевые узлы AST (ориентиры)

Путь	Тип	Описание
`ast.type`	string	Обычно `statement`.
`ast.with.recursive`	boolean	Флаг `WITH RECURSIVE`.
`ast.with.ctes[]`	array	CTE-определения: `{name, columns?, recursive, query}`.
`ast.query.type`	string	`query_block` или `query_expr` (UNION/INTERSECT/EXCEPT).
`query_block.entities[]`	array	Источники из FROM/JOIN: `table`, `subquery`, `table_function`.
`query_block.edges[]`	array	JOIN-цепочка на уровне алиасов: `{from,to,join_type,on,using,conditions[]}`.
`query_block.select.items[]`	array	Поля SELECT: `{raw, expr, alias, column_refs[], functions[], window, subqueries[]}`.

POST /api/er ER / Lineage Graph

Строит ER/lineage-граф: узлы (tables/CTE/subquery/table_function), связи JOIN и эвристические роли полей (PK/FK/JOIN_KEY).

Тело запроса

{
  "sql": "SELECT ..."
}

Параметры запроса

Поле	Тип	Обяз.	Описание
`sql`	string	да	SQL-текст. Ответ включает `parse` + `er`.

Ответ (структура)

{
  "parse": { ... },
  "er": {
    "version": "1.1",
    "source": { "status": "ok|partial|error", "errors": [] },
    "nodes": [ ... ],
    "edges": [ ... ],
    "lineage": { "outputs": [ ... ] },
    "lineage_graph": { "nodes": [ ... ], "edges": [ ... ] }
  }
}

Главные поля er

Путь	Тип	Описание
`er.nodes[]`	array	Узлы ER (без RESULT).
`er.edges[]`	array	JOIN-связи между узлами.
`er.lineage.outputs[]`	array	Лёгкая колонка-lineage (output → inputs).
`er.lineage_graph`	object	Граф зависимостей (включает RESULT).

POST /api/tree Dependency Tree + Trace

Строит дерево зависимостей источников (RESULT → CTE → FROM/JOIN) и, опционально, трассировку происхождения выбранного поля результата.

Тело запроса

{
  "sql": "SELECT ...",
  "field": "user_id"  // опционально
}

Параметры запроса

Поле	Тип	Обяз.	Описание
`sql`	string	да	SQL-текст запроса.
`field`	string	нет	Alias/имя выходного поля в финальном SELECT для построения трассировки.

Ответ (структура)

{
  "parse": { ... },
  "tree": {
    "version": "1.0",
    "tree": { "id": "result", "children": [ ... ] },
    "fields": { "final": [ ... ] },
    "trace": { "field": "...", "paths": [ ... ] }
}

Типы данных

Идентификаторы узлов (Node ID)

cte:<name> — CTE-узел (например, cte:UserActivity).
table:<schema.table> — таблица без алиаса (например, table:public_users).
<scope>:<alias> — узел с алиасом (для самосоединений), например MAIN:u.
subquery:p<pos> — подзапрос (по позиции в SQL).