3. Описание MCP-сервера › 3.3 Движок › База данных › engine_db_select

Читает данные пулом шагов: выборки и карту зависимостей таблиц. Писать не умеет.

Право

«Прямой доступ → База данных → Чтение данных» (AGENT_ENGINE_DB_SELECT).

Параметры

Параметр	Тип	Что это
[`pool`]	список объектов	шаги пула — см. «База данных»
[`pool_source`]	строка	файл JSON на этом компьютере со списком шагов — абсолютный путь или путь от папки магазина — вместо `pool`

Нужен pool или pool_source, но не оба.

Шаги

select

Поле	Что это
`sql`	запрос: `SELECT`, `SHOW`, `DESCRIBE` или `EXPLAIN`
`params`	значения для `:ИМЁН` запроса
`name`	имя шага; им называется файл тяжёлого шага
`big`	снять предел в 5000 строк
`output`	путь на этом компьютере: строки пишутся туда, а не в ответ

Проверяется весь текст запроса, после ведущих комментариев: он должен читать. EXPLAIN пишущей команды и SELECT … INTO OUTFILE отказывают — первый выполняет команду, чтобы показать план, второй пишет файл на сервере.

Шаг отвечает rows — сколько строк, и data — сами строки объектами.

dependent

Поле	Что это
`table`	главная таблица
`ids`	id строк главной таблицы — посчитать, сколько строк на них указывает

В базе магазина нет внешних ключей: какая таблица на какую указывает, записано в движке вручную, и шаг читает этот список.

Шаг отвечает depend — по строке на связь: main — главная таблица, table — зависимая, key — её поле, указывающее на строку главной, nullable — может ли оно стоять пустым. С ids добавляется count — сколько строк каждой зависимой таблицы указывают на эти id.

count — прогноз, а не отчёт: сколько строк повиснет, если удалить эти id. Строки, которые уже остались без владельца, он не видит. Таблицы, где на эти id не указывает ни одна строка, в count не попадают: пустой count значит, что не висит ничего.
Пустой depend значит, что связей не записано, а не что зависимых нет.
Одна таблица может быть привязана дважды — user_task к user через user_id и exec_id, — поэтому count идёт по таблицам, а не по связям.

Ответ

{"ok": true,
 "steps": [{"num": 1, "do": "select", "rows": 2,
            "data": [{"id": "1", "name": "Root"}, {"id": "2", "name": "Laptops"}]}],
 "changed": [], "unlocked": [], "ms": 10}

Поле	Что это
`ok`	дошёл ли пул до конца
`steps`	шаги по порядку: номер `num`, шаг `do`, `name`, если было, и ответ шага
`changed`, `unlocked`	у чтения всегда пусты
`ms`	сколько длился вызов на сервере

Тяжёлый шаг вместо data несёт file и head — см. «База данных».

Отказы

Шаг, который не прошёл, останавливает пул. Ответ приходит с признаком ошибки и тем же JSON; у этого шага поле error с причиной, шаги до него выполнены.

`error` шага	Когда
`This command runs select and dependent steps only`	шаг не `select` и не `dependent`
`This command reads only, and this step starts with …`	запрос не читает
`An EXPLAIN of a … may run it; this command reads only`	`EXPLAIN` пишущей команды
`INTO OUTFILE writes a file on the server; this command reads only`	запрос пишет файл на сервере
`Too many rows: …. Narrow the query, or repeat this step with "big": true`	больше 5000 строк без `big`
`Unknown table: …`	в `table` названа таблица, которой нет
`The id of this step takes a whole number, and […] is not one`	в `ids` не целое число
`No step named … before this one`	`@имя` ссылается на шаг, которого раньше нет
текст ошибки базы	ошибка в запросе

Отказы до запуска пула:

Ответ	Когда
`pool is required: …`	нет ни `pool`, ни `pool_source`
`pool or pool_source, not both…`	указаны оба
`No such file: …`	файла `pool_source` нет
`… is not utf-8 text - save it in utf-8.`	файл пула не в UTF-8 или в нём нулевой байт
`… is not whole json: it breaks at byte …`	файл пула обрезан или испорчен
`… holds no list of steps…`	в файле не список шагов

Общие отказы — «Ответы и отказы».