HTTP API¶

Все адреса ниже относятся к адресу вашего кабинета, например https://data.example.com. Пользовательский access token выдаёт локальный Keycloak. Запросы проходят через KrakenD и HTTP/gRPC gateway; права и SQL проверяет Go core.

Настройки пула PostgreSQL¶

Только роль system.admin может вызвать GET /v1/settings/database-pool и PUT /v1/settings/database-pool. Ответ включает настройки и текущие показатели open_connections, in_use_connections, idle_connections, wait_count, wait_duration_milliseconds. Изменение принимается полным JSON:

{"max_open_connections":20,"max_idle_connections":5,"connection_max_lifetime_seconds":1800,"connection_max_idle_seconds":300}

Лимиты применяются к Go core сразу, хранятся только в клиентском контуре и после перезапуска имеют приоритет над начальными переменными .env. Допустимы 1–100 открытых соединений, 1–100 свободных (не больше общего лимита), срок жизни 60–86400 секунд и простой 10–86400 секунд.

Настройки Go ELT worker¶

Роль system.admin может вызвать GET /v1/settings/worker и PUT /v1/settings/worker с полным JSON:

{"enabled":true,"concurrency":2,"interval_seconds":5}

Ответ также включает active_workers, completed_batches, last_heartbeat и last_error. Допустимы 1–32 горутины и интервал 1–300 секунд. Остановка через enabled:false отменяет текущие обработчики по Go context; клиентский обработчик обязан корректно завершать свою транзакцию при отмене. Настройки сохраняются только в локальном контуре. Worker читает их и сообщает состояние через внутренний gRPC с отдельным сервисным токеном; публичного маршрута для этого нет.

Каталог¶

Метод	Путь	Назначение
`GET`	`/v1/catalog`	Все разрешённые наборы и колонки
`GET`	`/v1/schemas`	Список доступных схем
`GET`	`/v1/schemas/{schema}/datasets`	Таблицы и представления схемы
`GET`	`/v1/datasets/{schema}/{name}/_mapping`	Поля, SQL-типы и nullable
`GET`	`/v1/datasets/{schema}/{name}/rows?limit=25`	Просмотр первых строк
`PUT`	`/v1/datasets/{schema}/{name}/columns/{column}/label`	Изменить подпись колонки; только `system.admin`

Обычный пользователь видит набор только при наличии catalog.list и dataset.read.<schema>.<name>. Системный администратор видит все клиентские наборы.

Каталог и _mapping возвращают label у набора и колонок и schemaLabel у схемы. Это подписи из PostgreSQL COMMENT. Они могут быть пустыми, если разработчик клиентской структуры их не задал. Для путей, фильтров, сортировки и ключей ответа используйте технические поля schema, name и columns[].name, а не подписи.

Системный администратор меняет подпись существующей колонки запросом PUT с телом {"label":"Дата продажи"}. Пустая строка удаляет комментарий и возвращает запасную подпись из технического имени. Максимум — 120 символов без управляющих знаков. Техническое имя, SQL-тип и права доступа не меняются. Изменение сохраняется в PostgreSQL этого клиента; чтобы оно сохранилось при создании новой установки, внесите ту же подпись в миграцию клиентского пакета.

Поиск и подсчёт¶

POST /v1/datasets/{schema}/{name}/_search принимает ограниченный JSON DSL:

{
  "query": {"bool": {"filter": [
    {"term": {"product": "Coffee"}},
    {"range": {"amount_cents": {"gte": 500}}}
  ]}},
  "sort": [{"id": "asc"}],
  "fields": ["id", "product", "amount_cents"],
  "from": 0,
  "size": 25
}

Пример вызова с вашим токеном:

curl -X POST 'https://data.example.com/v1/datasets/public/demo_sales/_search' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"query":{"match_all":{}},"size":10}'

Имя demo_sales здесь только пример: используйте набор из собственного каталога. Ответ содержит total и hits[]._source. Необязательный fields выбирает колонки _source; без него возвращаются все. Направление сортировки — asc или desc, колонку сортировки можно не включать в fields. POST .../_count принимает query и возвращает count без строк.

Поддерживаются match_all, term, terms, range, exists, match, bool. Размер тела до 8 KiB, size от 1 до 100, from + size не больше 1000, SQL timeout пять секунд. API читает данные; произвольный SQL и запись строк не предусмотрены. Этот DSL похож на Elasticsearch по форме, но не является совместимым API.