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

Получить строки таблицы

GET /v1/infra/servers/:id/db/tables/:table/rows

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

Когда эндпоинт отвечает — см. Когда база доступна.

Параметры

Параметр Тип Обяз. По умолч. Описание
Параметрid (path) Типstring Обяз.да По умолч.— ОписаниеID приложения с kind равным GALAXY_APP. Список: GET /v1/infra/servers
Параметрtable (path) Типstring Обяз.да По умолч.— ОписаниеТочное имя таблицы или представления, до 256 байт в UTF-8. Список: поле data.tables[].name в GET /db/schema
Параметрfile (query) Типstring Обяз.нет По умолч.файл из VIBE_DB_PATH, иначе app.db ОписаниеПуть к файлу базы относительно /data, до 1024 байт в UTF-8. Список файлов: поле data.files[].file в GET /db. Абсолютный путь, выход за пределы /data и символическая ссылка дают 400 APP_DB_INVALID_FILE
Параметрlimit (query) Типnumber Обяз.нет По умолч.100 ОписаниеЧисло строк на странице, от 1 до 500
Параметрoffset (query) Типnumber Обяз.нет По умолч.0 ОписаниеСколько строк пропустить, от 0 до 1000000
Параметрsort (query) Типstring Обяз.нет По умолч.— ОписаниеКолонка для сортировки. Имя — из data.tables[].columns[].name в GET /db/schema
Параметрorder (query) Типstring Обяз.нет По умолч.asc ОписаниеНаправление сортировки: asc или desc
ПараметрfilterColumn (query) Типstring Обяз.нет По умолч.— ОписаниеКолонка, по которой фильтруются строки. Имя — из той же схемы, что и для sort
ПараметрfilterOp (query) Типstring Обяз.нет По умолч.— ОписаниеУсловие фильтра: eq — значение колонки равно filterValue, contains — значение колонки, приведённое к тексту, содержит filterValue как подстроку с учётом регистра. Символы % и _ в contains ищутся как обычные символы, а не как шаблон
ПараметрfilterValue (query) Типstring Обяз.нет По умолч.— ОписаниеЗначение для сравнения, до 16 384 символов. Длину ограничивает и вся строка запроса: значение из 8 000 латинских символов проходит, из 12 000 — сервер отвечает 414 без JSON-тела. Пустая строка — отдельное значение, а не отсутствие значения
ПараметрfilterValueIsNull (query) Типstring Обяз.нет По умолч.— Описаниеtrue — отобрать строки, где в filterColumn записано SQL-значение NULL. Передаётся вместо filterValue и только с filterOp=eq

Фильтр передаётся целиком или не передаётся вовсе: filterColumn, filterOp и одно из двух — filterValue или filterValueIsNull=true. Неполный фильтр, оба значения сразу, filterValueIsNull=true с contains, значение вне диапазона и любой параметр не из таблицы дают 400 VALIDATION_ERROR. Имя колонки в sort или filterColumn, которого нет в таблице, даёт 404 APP_DB_TABLE_NOT_FOUND.

Пагинация. За один вызов приходит не больше limit строк и не больше 1 МиБ JSON. Значение data.truncated равно true, когда за пределами страницы есть ещё строки или страница обрезана по размеру — тогда data.rowCount может оказаться меньше limit. Следующая страница запрашивается с offset, равным data.offset + data.rowCount.

Порядок строк в таблице и в представлении. В таблице строки сортируются по sort, затем по колонкам первичного ключа по возрастанию, затем по скрытому rowid, если он есть. Без sort порядок задаёт первичный ключ или rowid, поэтому страницы через offset не пересекаются и не теряют строки, пока данные не меняются. У представления такого добавочного порядка нет: страницы представления через offset могут повторять или пропускать строки.

Примеры

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/infra/servers/7c2b1f08-3a4d-4e91-9b6c-2f5e8a1d0c33/db/tables/customers/rows?limit=2" \
  -H "X-Api-Key: YOUR_API_KEY"

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/infra/servers/7c2b1f08-3a4d-4e91-9b6c-2f5e8a1d0c33/db/tables/customers/rows?limit=2" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

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

javascript 
const appId = '7c2b1f08-3a4d-4e91-9b6c-2f5e8a1d0c33'
const res = await fetch(`https://vibecode.bitrix24.tech/v1/infra/servers/${appId}/db/tables/customers/rows?limit=2`, {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log(data.columns, data.rows)

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

javascript 
const appId = '7c2b1f08-3a4d-4e91-9b6c-2f5e8a1d0c33'
const res = await fetch(`https://vibecode.bitrix24.tech/v1/infra/servers/${appId}/db/tables/customers/rows?limit=2`, {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean ОписаниеВсегда true при успехе
Полеdata.file Типstring ОписаниеФайл базы, из которого прочитаны строки, — путь относительно /data
Полеdata.table Типstring ОписаниеИмя таблицы или представления из запроса
Полеdata.columns Типarray ОписаниеИмена колонок в порядке их следования в таблице. Повторяющиеся имена остаются отдельными элементами
Полеdata.rows Типarray ОписаниеСтроки страницы. Каждая строка — массив значений в порядке data.columns
Полеdata.rows[][] Типstring, number, null, object ОписаниеЗначение ячейки. Объект приходит в трёх случаях: { "type": "blob", "base64": "..." } — двоичные данные в base64, { "type": "integer", "value": "..." } — целое число по модулю больше 9 007 199 254 740 991 в виде строки, { "type": "float", "value": "NaN" } — нечисловое значение NaN, Infinity или -Infinity
Полеdata.rowKeys Типarray ОписаниеКлючи строк, по одному на каждую строку data.rows в том же порядке
Полеdata.rowKeys[] Типstring, null ОписаниеНепрозрачный ключ строки до 1024 символов — значение для :key в PATCH /db/tables/:table/rows/:key и DELETE /db/tables/:table/rows/:key. Ключ привязан к приложению, файлу и таблице, из которых прочитан. Берите его из ответа как есть, а не собирайте из значений колонок. null — строку нельзя изменить по ключу: это строка представления или виртуальной таблицы, у таблицы нет первичного ключа и скрытого rowid, в колонке первичного ключа этой строки записан NULL или двоичное значение, либо ключ длиннее 1024 символов
Полеdata.rowCount Типnumber ОписаниеЧисло строк на этой странице
Полеdata.limit Типnumber ОписаниеЗначение limit, с которым выполнен запрос
Полеdata.offset Типnumber ОписаниеЗначение offset, с которым выполнен запрос
Полеdata.truncated Типboolean Описаниеtrue — за пределами страницы есть ещё строки или страница обрезана по размеру 1 МиБ
Полеdata.durationMs Типnumber ОписаниеВремя чтения в миллисекундах

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

Таблица customers с первичным ключом id и тремя строками, запрос с limit=2:

JSON 
{
  "success": true,
  "data": {
    "file": "app.db",
    "columns": [
      "id",
      "name",
      "email",
      "created_at"
    ],
    "rows": [
      [
        1,
        "Customer A",
        "a@example.com",
        "2026-10-20 08:12:46"
      ],
      [
        2,
        "Customer B",
        "b@example.com",
        "2026-10-20 08:12:46"
      ]
    ],
    "rowCount": 2,
    "truncated": true,
    "durationMs": 1.114,
    "rowKeys": [
      "eyJ2IjoxLCJhcHBJZCI6IjdjMmIxZjA4LTNhNGQtNGU5MS05YjZjLTJmNWU4YTFkMGMzMyIsImZpbGUiOiJhcHAuZGIiLCJ0YWJsZSI6ImN1c3RvbWVycyIsImtpbmQiOiJwayIsImNvbHVtbnMiOlsiaWQiXSwidmFsdWVzIjpbeyJ0eXBlIjoiaW50ZWdlciIsInZhbHVlIjoiMSJ9XX0",
      "eyJ2IjoxLCJhcHBJZCI6IjdjMmIxZjA4LTNhNGQtNGU5MS05YjZjLTJmNWU4YTFkMGMzMyIsImZpbGUiOiJhcHAuZGIiLCJ0YWJsZSI6ImN1c3RvbWVycyIsImtpbmQiOiJwayIsImNvbHVtbnMiOlsiaWQiXSwidmFsdWVzIjpbeyJ0eXBlIjoiaW50ZWdlciIsInZhbHVlIjoiMiJ9XX0"
    ],
    "table": "customers",
    "limit": 2,
    "offset": 0
  }
}

Представление active_customers, запрос без параметров — строки представления правке по ключу не подлежат, поэтому в rowKeys приходит null:

JSON 
{
  "success": true,
  "data": {
    "file": "app.db",
    "columns": [
      "id",
      "name"
    ],
    "rows": [
      [
        1,
        "Customer A"
      ],
      [
        2,
        "Customer B"
      ]
    ],
    "rowCount": 2,
    "truncated": false,
    "durationMs": 0.965,
    "rowKeys": [
      null,
      null
    ],
    "table": "active_customers",
    "limit": 100,
    "offset": 0
  }
}

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

404 — таблицы с таким именем нет в базе:

JSON 
{
  "success": false,
  "error": {
    "code": "APP_DB_TABLE_NOT_FOUND",
    "message": "Table or column not found"
  }
}

Ошибки

HTTP Код Описание
HTTP400 КодVALIDATION_ERROR ОписаниеПараметр вне допустимого диапазона, неизвестный параметр или неполный фильтр. Сообщение Invalid database read parameters
HTTP400 КодVALIDATION_ERROR ОписаниеИмя таблицы в :table длиннее 256 байт. Сообщение Invalid table name
HTTP400 КодAPP_DB_INVALID_FILE ОписаниеНекорректный путь в file: абсолютный, с выходом за пределы /data или через символическую ссылку
HTTP400 КодAPP_DB_UNSUPPORTED_PLACEMENT ОписаниеПриложение размещено не в Галактике
HTTP401 КодMISSING_API_KEY ОписаниеНе передан заголовок X-Api-Key
HTTP401 КодINVALID_API_KEY ОписаниеКлюч не найден или недействителен
HTTP402 КодBILLING_FROZEN ОписаниеХост галактики спит, и его нельзя разбудить: счёт аккаунта заморожен
HTTP403 КодINFRA_SCOPE_REQUIRED ОписаниеУ ключа нет скоупа vibe:infra
HTTP403 КодAPP_DB_DISABLED ОписаниеРабота с базой приложения не включена для портала
HTTP403 КодSERVER_WAKE_BLOCKED ОписаниеХост галактики спит, и пробуждение для него запрещено
HTTP404 КодNOT_FOUND ОписаниеПриложение не найдено, удалено или недоступно этому ключу
HTTP404 КодAPP_DB_NOT_FOUND ОписаниеУ приложения нет тома /data или файла базы — приложение ещё не создало базу
HTTP404 КодAPP_DB_TABLE_NOT_FOUND ОписаниеВ базе нет таблицы или представления :table, либо колонки из sort или filterColumn
HTTP409 КодAPP_DB_BUSY ОписаниеХост занят другой операцией, ещё не проснулся или база занята записью приложения. Повторите после срока из заголовка Retry-After
HTTP409 КодAPP_DB_WAL_CLOSED ОписаниеРаботающее приложение закрыло соединение с базой. Повтор без изменения приложения вернёт тот же отказ — см. Когда база доступна
HTTP414 Код— ОписаниеСтрока запроса длиннее предела сервера, ответ приходит HTML-страницей без JSON. Сократите filterValue
HTTP422 КодAPP_DB_QUERY_TIMEOUT ОписаниеЧтение не уложилось в отведённое время
HTTP422 КодAPP_DB_CORRUPT ОписаниеФайл базы повреждён. Восстановите базу из копии — Восстановить базу из копии
HTTP429 КодRATE_LIMITED ОписаниеПревышен лимит запросов на чтение для портала — Лимиты. Пауза — в заголовке Retry-After
HTTP503 КодAPP_DB_TOOL_UNAVAILABLE ОписаниеХост не подготовлен к чтению базы или временно недоступен. Повторите после срока из заголовка Retry-After. Готовность хоста — GET /app-db/prepare
HTTP503 Кодuser_self_deletion_pending ОписаниеВладелец ключа удаляет свой аккаунт на этом портале

Полный список общих ошибок API — Ошибки.

Смотрите также