Для AI-агентов: markdown этой страницы — /docs-content/infra/database/query.md индекс документации — /llms.txt

Выполнить SQL-запрос на чтение

POST /v1/infra/servers/:id/db/query

Выполняет один SQL-запрос на чтение к SQLite-базе приложения и возвращает колонки и строки результата. Подходит для выборок с условиями, соединениями и агрегатами, которых нет у чтения строк одной таблицы.

Условия доступа к базе и лимиты запросов — Когда база доступна и Лимиты. Изменить данные — Выполнить SQL на запись.

Параметры

Параметр	Тип	Обяз.	Описание
Параметр`id` (path)	Типstring (UUID)	Обяз.да	ОписаниеID приложения с `kind` равным `GALAXY_APP`. Список: `GET /v1/infra/servers`

Поля запроса (body)

Поле	Тип	Обяз.	Описание
Поле`sql`	Типstring	Обяз.да	ОписаниеОдна SQL-инструкция на чтение, до 16 384 байт в UTF-8. Значения подставляются через позиционные маркеры `?`
Поле`parameters`	Типarray	Обяз.нет	ОписаниеЗначения для маркеров `?` по порядку, до 256 штук. Каждое — строка до 16 384 символов, конечное число или `null`. Логические значения не принимаются, вместо них передавайте `1` и `0`. По умолчанию `[]`
Поле`file`	Типstring	Обяз.нет	ОписаниеПуть к файлу базы относительно `/data`, до 1024 байт в UTF-8. Список файлов — `data.files[].file` в `GET /db`. По умолчанию — `data.defaultFile` оттуда же

Другие поля тела дают 400 VALIDATION_ERROR. Тело — до 64 КиБ.

Пагинация. Курсора и номера страницы у эндпоинта нет: при data.truncated: true строки сверх лимита отбрасываются. Остаток забирается следующим запросом: добавьте в sql устойчивую сортировку ORDER BY и LIMIT с OFFSET либо условие по ключу последней полученной строки, например WHERE id > ?.

Примеры

curl — личный ключ

Terminal

curl -X POST "https://vibecode.bitrix24.tech/v1/infra/servers/APP_ID/db/query" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT id, name, email FROM customers WHERE id > ? ORDER BY id",
    "parameters": [1]
  }'

curl — OAuth-приложение

Terminal

curl -X POST "https://vibecode.bitrix24.tech/v1/infra/servers/APP_ID/db/query" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT id, name, email FROM customers WHERE id > ? ORDER BY id",
    "parameters": [1]
  }'

JavaScript — личный ключ

javascript

const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${appId}/db/query`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      sql: 'SELECT id, name, email FROM customers WHERE id > ? ORDER BY id',
      parameters: [1],
    }),
  }
)
const { success, data, error } = await res.json()
if (!success) throw new Error(`${error.code}: ${error.details?.reason ?? error.message}`)
// Строки — позиционные массивы в порядке data.columns
const rows = data.rows.map(r => Object.fromEntries(data.columns.map((c, i) => [c, r[i]])))
console.log(rows, data.truncated ? 'результат обрезан' : '')

JavaScript — OAuth-приложение

javascript

const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${appId}/db/query`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      sql: 'SELECT id, name, email FROM customers WHERE id > ? ORDER BY id',
      parameters: [1],
    }),
  }
)
const { success, data, error } = await res.json()
if (!success) throw new Error(error.code)
console.log(data.columns, data.rows)

Поля ответа

Поле	Тип	Описание
Поле`success`	Типboolean	Описание`true` при успешном ответе
Поле`data.file`	Типstring	ОписаниеПуть прочитанного файла относительно `/data`
Поле`data.columns`	Типarray	ОписаниеИмена колонок результата по порядку. Одинаковые имена, например после соединения таблиц, остаются отдельными элементами
Поле`data.rows`	Типarray	ОписаниеСтроки результата, до 500. Каждая строка — массив значений в порядке `data.columns`
Поле`data.rows[][]`	Типstring \| number \| null \| object	ОписаниеЗначение ячейки. Текст — строкой, числа — числом, SQL `NULL` — `null`. Значения, которые нельзя передать числом или строкой JSON, приходят объектом с полем `type` — см. три строки ниже
Поле`data.rows[][]` с `type: "blob"`	Типobject	ОписаниеДвоичные данные, поле `base64` — содержимое в кодировке Base64
Поле`data.rows[][]` с `type: "integer"`	Типobject	ОписаниеЦелое число больше 9 007 199 254 740 991 по модулю, поле `value` — число строкой
Поле`data.rows[][]` с `type: "float"`	Типobject	ОписаниеБесконечность или не-число, поле `value` — `Infinity`, `-Infinity` или `NaN`
Поле`data.rowCount`	Типinteger	ОписаниеЧисло строк в `data.rows`
Поле`data.truncated`	Типboolean	Описание`true`, если результат обрезан: строк больше 500 или ответ приблизился к 1 МиБ. Строки сверх лимита не возвращаются
Поле`data.durationMs`	Типnumber	ОписаниеВремя чтения на хосте в миллисекундах

Пример ответа

JSON

{
  "success": true,
  "data": {
    "file": "app.db",
    "columns": ["id", "name", "email"],
    "rows": [
      [2, "Customer B", "b@example.com"],
      [3, "Customer C", null]
    ],
    "rowCount": 2,
    "truncated": false,
    "durationMs": 0.75
  }
}

Пример ответа при ошибке

422 — запрос пытается изменить данные: