Text-to-SQL: вопросы к базе, ограничения и проверка SQL

Бизнес-аналитик спрашивает: «Какова выручка за сентябрь?» Руководителю операций недостаточно получить одно число — ему нужны определение метрики, сохранённый SQL и перечень исключённых записей. Тогда ответ можно повторить и проверить.

Text-to-SQL, или text2sql, переводит вопрос на обычном языке в запрос к данным. Но модель не должна сама решать, что считать выручкой, выбирать похожие колонки или получать право на запись. Надёжный процесс начинается со словаря метрик и разрешённой схемы, а заканчивается проверкой SQL человеком.

Какую задачу решает этот процесс

Процесс подходит для вопросов к реляционной базе: аналитик формулирует вопрос, помощник составляет SELECT к ограниченной витрине, а проверяющий видит запрос и может воспроизвести результат. Например, в условном расчёте руководитель операций получает не просто «2500 условных денежных единиц», а пояснение: какие строки вошли в сумму, какой период использован и почему отменённые заказы исключены.

Граница процесса узкая: помощник читает только разрешённые объекты БД с ограниченными правами. Он не анализирует файл Excel, не изменяет рабочие данные и не записывает ответ в CRM. Передачу структурированных данных в рабочую систему стоит проектировать отдельно — этот смежный сценарий разобран в руководстве по передаче данных в CRM.

Какие данные и правила подготовить

До подключения модели составьте паспорт данных. В нём для каждого поля укажите источник, смысл, ответственного и статус. Ниже — заполненный синтетический образец без клиентских данных.

К паспорту добавьте:

• схему разрешённых таблиц, колонок и связей;
• словарь бизнес-метрик с примерами вопросов;
• отдельную учётную запись с минимальными правами чтения;
• шаблоны SQL и параметры периода вместо свободной подстановки текста;
• allowlist объектов, лимит подробной выдачи, timeout и порог допустимой стоимости плана;
• проверочные вопросы: какой статус входит, по какой дате отбираются строки, что делать с NULL, возвратами и валютами.

Обязательные сведения блокируют запуск, если они не заполнены. Условные нужны только при соответствующем устройстве данных. Неизвестное нельзя заменять догадкой модели: решение принимает ответственный специалист.

Как перевести бизнес-вопрос в запрос к данным

Сначала разберите вопрос на определения. Для «выручки за сентябрь 2026 года» нужно согласовать три вещи:

1. Метрика. В синтетическом примере выручка — SUM(amount) только для status = 'paid'.
2. Период. Используем полуинтервал: paid_at >= DATE '2026-09-01' и paid_at < DATE '2026-10-01'. Такая граница однозначно исключает 1 октября.
3. Статус. canceled не входит в сумму.

Схема примера состоит из одной разрешённой таблицы reporting.orders, поэтому join не нужен. Имя схемы reporting условное; в рабочем запросе нужно использовать точное имя разрешённой схемы. Если для реального вопроса понадобится join, заранее укажите разрешённые таблицы, ключи и кардинальность связи. Без описанной связи помощник возвращает вопрос человеку: неверный join способен умножить строки и исказить сумму.

Нельзя угадывать колонку по похожему названию. Если словарь метрик не связывает слово «выручка» с orders.amount, orders.status и orders.paid_at, система должна спросить, какое поле, дату и набор статусов использовать.

Как ограничить выполнение SQL

Ограничение строится из нескольких независимых мер:

• отдельная роль получает CONNECT к нужной базе, USAGE для разрешённой схемы и только необходимые права SELECT на объекты, но не становится владельцем и не получает прав записи; администратор отдельно проверяет права роли и при необходимости отзывает CREATE для схем, TEMPORARY для базы и ненужные права EXECUTE на функции, в том числе выданные PUBLIC;
• запрос выполняется в транзакции READ ONLY;
• валидатор допускает только разрешённые схемы, таблицы, колонки, безопасные для чтения функции и связи;
• даты и другие значения передаются параметрами;
• statement_timeout останавливает слишком долгую команду;
• подробная выборка получает лимит строк;
• до выполнения система рассматривает план через EXPLAIN и сравнивает его оценку с правилами владельца БД.

Это учебная последовательность по документации PostgreSQL 18, а не отчёт о живом запуске. В PostgreSQL 18 транзакция READ ONLY запрещает перечисленные в документации команды записи для невременных таблиц и ряд DDL-команд, но остаётся высокоуровневым ограничением и не заменяет минимальные права роли. statement_timeout прерывает команду, превысившую заданное время. Значение порога зависит от базы и нагрузки.

LIMIT ограничивает число возвращённых строк, но не гарантирует дешёвое вычисление агрегата: для SUM серверу всё равно может понадобиться обработать множество строк. Оценка EXPLAIN также не равна измеренному времени — это оценка планировщика в его условных единицах.

Проверка одной подстроки SELECT не защищает систему. Запрос нужно разбирать по структуре и сопоставлять с allowlist. Полномочия роли и режим транзакции остаются обязательными даже после такой валидации.

Как проверить ответ и показать происхождение

Проверяющий должен видеть цепочку:

вопрос → определение метрики → таблицы и поля → SQL → исключённые строки → ручная сумма → решение.

Перед выполнением человек просматривает сгенерированный SQL. После выполнения он сравнивает результат с эталонным расчётом на контрольном наборе и читает пояснение исключений. Это позволяет отличить ошибку запроса от разногласия в определении метрики.

Неоднозначный вопрос не следует превращать в уверенный SQL. Например, фраза «покажи хорошие продажи за последнее время» не задаёт показатель, статусы, даты и валюту. Сигнал ошибки — отсутствуют обязательные определения. Действие человека — уточнить их и только затем разрешить новый запрос.

Учебный пример: путь от входных данных до результата

Все таблицы, имена, даты, суммы и лимиты ниже синтетические. Это не клиентский кейс Switch On AI и не результат живого теста.

Исходные данные:

Вопрос: «Какова выручка за сентябрь 2026 года?» Промежуточное решение: взять только paid, применить полуинтервал сентября и сложить amount. Строка 104 исключается по статусу, строка 105 — по верхней границе периода. Ручная сумма: 1200 + 800 + 500 = 2500 условных денежных единиц.

Учебный SQL для PostgreSQL 18 по официальной документации приведён с явными датами, чтобы расчёт можно было проверить вручную. В рабочей интеграции даты и другие входные значения нужно передавать параметрами, а не подставлять из текста вопроса:

Пять секунд — условный лимит примера, а не универсальная рекомендация. Владелец БД выбирает его по своей нагрузке. SUM пропускает значения amount, равные NULL. Если подходящих строк нет или во всех подходящих строках amount равен NULL, результатом будет NULL; COALESCE(..., 0) превратит его в ноль. Это правило нужно согласовать с владельцем метрики: отсутствие заказов и заказы с неизвестной суммой могут требовать разных решений.

Есть и отрицательный путь. На просьбу «удали отменённые заказы» помощник не должен генерировать или выполнять DELETE. Он сообщает, что операция записи запрещена, и передаёт запрос уполномоченному человеку. Это ожидаемое поведение проектируемой системы, а не заявление о проведённом тесте.

Как проверить результат перед запуском

Составьте приёмочные сценарии до подключения рабочей базы.

В тестовых материалах не должно быть реальных паролей, строк подключения и секретов. Отдельно проверьте роль чтения, read-only-транзакцию, allowlist, границы периода, статусы и NULL. SQL-инструкции в этом руководстве относятся к PostgreSQL 18; для другой версии или СУБД синтаксис и поведение нужно сверить с её документацией.

Что согласовать для внедрения

Готовый Text-to-SQL-инструмент может дать интерфейс и генерацию запросов, но сам по себе не знает определения ваших метрик, допустимые связи и правила доступа. Собственная интеграция связывает вопрос, словарь метрик, валидатор, учётную запись БД, журнал решений и передачу спорного случая человеку. Конкретную совместимость, тарифы, API и права выбранного продукта проверяют отдельно.

Switch On AI разрабатывает ИИ-помощника, бота или интеграцию для этой операции после проверки данных и API. Для данного сценария цель формулируется так: ответ на вопрос к базе можно воспроизвести по разрешённому SQL-запросу. Если модель выбирает разрешённый инструмент и запрашивает уточнения, уместен ИИ-помощник; если шаги всегда фиксированы, может хватить обычной интеграции. Диалоговый бот — лишь один из возможных интерфейсов.

Правила бухгалтерского, юридического, кадрового или отраслевого учёта задаёт и проверяет специалист заказчика. Этот материал не доказывает выполненное внедрение или совместимость с конкретным вендором.

Следующий шаг — выбрать ограниченную витрину и несколько типовых вопросов для пилота. На странице разработки ИИ-агентов можно сверить состав подходящей услуги. Затем можно разобрать одну операцию со Switch On AI и согласовать прототип: без обещания полного отраслевого внедрения, срока или гарантированного эффекта.