Вопросы к данным обычным языком: как устроен text-to-SQL и почему без проверки он опасен

Что такое text-to-SQL и когда он действительно нужен

Классическая аналитика устроена так: бизнес задаёт вопрос, аналитик пишет запрос, проверяет его и отдаёт ответ или строит дашборд. Text-to-SQL убирает посредника для части вопросов. Менеджер филиала пишет «сколько заявок мы получили на прошлой неделе по каналам», а система сама находит нужные данные, считает и показывает результат.

Важно понимать, чем это отличается от дашборда. Дашборд отвечает на заранее известные вопросы, и каждая цифра на нём однажды была проверена. Text-to-SQL отвечает на вопросы, которые никто заранее не предусмотрел, а значит, каждый ответ — это новый, ещё не проверенный запрос. Отсюда и главный риск, и главная ценность подхода.

Когда text-to-SQL оправдан

• Много повторяющихся несложных вопросов, на которые аналитики тратят время: «сколько», «за какой период», «в разрезе чего».
• Ключевые метрики уже определены и согласованы, хотя бы для основной части бизнеса.
• Данные лежат в хранилище с понятной структурой, а не в десятке разрозненных выгрузок.
• Пользователи готовы видеть, как получен ответ, и задавать уточняющие вопросы.

Когда лучше не начинать

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

Правило выбора простое: если вы не можете дать аналитику-новичку документ, по которому он за день начнёт правильно отвечать на типовые вопросы, модель тоже не сможет. Сначала нужна эта документация, потом text-to-SQL.

Как устроен конвейер: шаг за шагом

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

1. Разбор вопроса

Система определяет, что спрашивают: какую метрику, за какой период, в каких разрезах и с какими фильтрами. На этом шаге всплывает неоднозначность. «Прошлый месяц» — это календарный месяц или последние тридцать дней? «Клиенты» — все зарегистрированные или только платившие? Хорошая система не угадывает, а уточняет или явно сообщает, какую трактовку выбрала.

2. Подбор контекста

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

3. Генерация запроса

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

4. Проверка до выполнения

Запрос проверяется программно: синтаксис, обращения только к разрешённым таблицам, только чтение, наличие обязательных фильтров, ограничение на объём результата. Это дешёвая защита, которая отсекает целый класс проблем ещё до обращения к данным.

5. Выполнение с правами пользователя

Запрос выполняется не от имени всесильного технического аккаунта, а с правами того, кто спросил. Если менеджеру филиала видны только его филиал и только агрегаты, база сама вернёт только это.

6. Представление ответа

Результат показывается вместе с объяснением: какая метрика, по какому определению, за какой период, с какими фильтрами. При желании — сам запрос. Без этого шага пользователь не может отличить правильный ответ от правдоподобного.

Почему модель ошибается на реальной базе

Демонстрации text-to-SQL обычно проводят на аккуратных учебных базах: несколько таблиц, понятные названия, очевидные связи. Рабочее хранилище выглядит иначе. В нём есть таблицы orders, orders_new и orders_backup, поле stat с кодами без расшифровки, суммы в разных валютах и даты в разных часовых поясах. Модель не может знать, какая из таблиц актуальна, если это нигде не записано.

Вторая причина — бизнес-термины. «Выручка», «активный клиент», «отток», «конверсия» в каждой компании определены по-своему, а иногда и в разных отделах одной компании. Модель подставит общепринятое значение слова, и цифра разойдётся с официальной отчётностью. Пользователь при этом не получит никакого предупреждения.

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

Семантический слой и словарь метрик

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

Что входит в семантический слой

• Сущности бизнеса: клиент, заказ, платёж, филиал, продукт — и таблицы, где они хранятся.
• Связи между сущностями с указанием типа: один к одному или один ко многим.
• Описание полей на человеческом языке, включая расшифровку кодов и статусов.
• Фильтры по умолчанию, которые применяются к любому запросу.
• Метрики с формулами, разрезами и владельцами.
• Примеры правильных вопросов и запросов к ним.

Как описать метрику: пример

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

Все параметры в этом примере условны — у вас окно, статусы и исключения будут свои. Важно другое: в описании нет ничего, что модели пришлось бы угадывать. Если два человека зададут вопрос «сколько у нас активных клиентов», они получат одну и ту же цифру и одно и то же объяснение.

Как строить слой: порядок работы

1. 01Соберите реальные вопросы, которые бизнес задаёт аналитикам, и сгруппируйте их по метрикам.
2. 02Выберите небольшой набор самых частых метрик для первой версии.
3. 03Для каждой метрики договоритесь с владельцем об определении и запишите его.
4. 04Определите таблицы — источники истины, остальные скройте от системы.
5. 05Опишите поля и коды, которые участвуют в этих метриках.
6. 06Добавьте к каждой метрике эталонные вопросы с проверенными ответами.
7. 07Расширяйте слой только по мере того, как появляются новые повторяющиеся вопросы.

Свободная генерация SQL или шаблоны

Есть два основных способа построить text-to-SQL. В первом модель пишет произвольный SQL по схеме и описаниям. Во втором модель только понимает вопрос и выбирает из семантического слоя метрику, разрезы, фильтры и период, а запрос собирается детерминированно из заранее проверенных блоков.

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

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

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

Права доступа и безопасность

Когда любой сотрудник может спросить что угодно, вопрос доступа становится центральным. Главное правило: модель не должна быть источником ограничений. Если запрос выполняется под техническим пользователем с полным доступом, никакая инструкция в промпте не гарантирует, что система не покажет зарплаты, персональные данные клиентов или данные чужого филиала.

Инструкцию можно обойти формулировкой вопроса, модель может её неправильно понять, а текст из данных может повлиять на её поведение. Права в базе данных обойти формулировкой нельзя.

1. 01Выполняйте запросы с правами конкретного пользователя, а не общего сервисного аккаунта.
2. 02Ограничивайте доступ по строкам: филиал видит только свои данные.
3. 03Ограничивайте доступ по столбцам: персональные и чувствительные поля скрыты для большинства ролей.
4. 04Разрешайте только чтение — никаких изменений, удалений и создания таблиц.
5. 05Ставьте лимиты на время выполнения и объём результата, чтобы один вопрос не нагрузил базу.
6. 06Подключайте систему к реплике или витрине, а не к рабочей базе приложений.
7. 07Логируйте вопрос, сгенерированный запрос, пользователя и результат.

Разбор примера: от вопроса до ответа

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

Шаг первый — «новый клиент». Без словаря модель, скорее всего, посчитает клиентов, зарегистрированных за месяц. Но в компании новым может считаться клиент, совершивший первую оплату в этом месяце. Разница существенная: зарегистрировавшиеся и не оплатившие в одну метрику попадают, в другую нет. Словарь снимает вопрос: используется записанное определение.

Шаг второй — «прошлый месяц». Система должна взять полный календарный месяц до текущего, в местном часовом поясе, если даты хранятся в UTC. Условие на период лучше задавать полуоткрытым интервалом: с первого числа прошлого месяца включительно до первого числа текущего не включительно.

Шаг третий — «по филиалам». У клиента может быть филиал регистрации, а у платежа — филиал, где он принят. Какой из них нужен, тоже должно быть записано в определении метрики. Если клиент платил в двух филиалах, неосторожный джойн посчитает его дважды.

Шаг четвёртый — фильтры по умолчанию: тестовые аккаунты, внутренние сотрудники, возвращённые платежи. Без них цифра будет немного завышена, и такую ошибку труднее всего заметить на глаз.

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

Типичные ошибки и как их поймать

Ниже — ошибки, которые чаще всего встречаются при внедрении, и способы обнаружить каждую до того, как она попадёт в решение.

• Не та таблица. Как поймать: в логах смотрите, к каким таблицам обращаются запросы; любое обращение к таблице вне списка источников истины — сигнал.
• Подмена определения метрики. Как поймать: эталонные вопросы по каждой метрике с ответами, сверенными с официальной отчётностью.
• Размножение строк в джойне. Как поймать: автоматическая проверка, что число уникальных ключей в результате соответствует ожидаемой гранулярности.
• Неверный период. Как поймать: в ответе всегда показывайте фактические даты начала и конца, а не только слова «прошлый месяц».
• Пропущенные фильтры. Как поймать: программная проверка запроса на наличие обязательных условий до выполнения.
• Изменение ответа после обновления модели или промпта. Как поймать: регрессионный прогон эталонного набора после каждого изменения.
• Уверенный ответ на вопрос вне описанных данных. Как поймать: эталонные вопросы, на которые система обязана отказать.

Неоднозначные вопросы и честный отказ

Люди задают вопросы неточно: «как дела в филиале», «почему упали продажи», «сколько у нас клиентов». Хорошая система уточняет период, определение и разрез, а если вопрос допускает несколько трактовок, показывает варианты. Вопросы «почему» требуют особой осторожности: text-to-SQL может показать, где и когда изменилась метрика, но не причину. Если система начинает сочинять объяснения, пользователь принимает гипотезу за факт.

Честный отказ — «такой метрики нет в описании, обратитесь к её владельцу» — кажется недостатком, но именно он сохраняет доверие. Пользователь, который один раз получил уверенную неправильную цифру, перестаёт доверять системе целиком.

Как проверять качество и запускать систему

Эталонный набор вопросов

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

Регрессионные прогоны

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

Мониторинг в работе

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

Порядок запуска

1. 01Пилот на узком наборе метрик и узкой группе пользователей, которые умеют проверять ответы, — аналитиках и опытных пользователях отчётов.
2. 02Разбор их обратной связи и доработка словаря метрик.
3. 03Расширение на бизнес-пользователей с обязательным показом пояснений к ответу.
4. 04Постепенное добавление метрик, каждая — с эталонными вопросами.

Термины

• Text-to-SQL — преобразование вопроса на естественном языке в SQL-запрос к базе данных.
• Семантический слой — описание данных на языке бизнеса поверх физических таблиц: сущности, связи, метрики, фильтры.
• Словарь метрик — часть семантического слоя с формулами, источниками, разрезами и владельцами метрик.
• Источник истины — таблица, которая официально считается правильной для данной сущности или метрики.
• Гранулярность — уровень детализации результата: одна строка на клиента, на заказ, на день.
• Эталонный набор — вопросы с заранее проверенными правильными ответами для оценки системы.
• Регрессия — ухудшение ответов после изменения, которое должно было что-то улучшить.
• Ограничение по строкам и столбцам — права в базе, определяющие, какие записи и поля видит пользователь.

Чек-лист внедрения

1. 01Собраны реальные вопросы бизнеса и выбраны метрики для первой версии.
2. 02Определения метрик согласованы с владельцами и записаны.
3. 03Таблицы — источники истины определены, устаревшие и дублирующие скрыты.
4. 04Поля, коды и статусы описаны на человеческом языке.
5. 05Фильтры по умолчанию зафиксированы и проверяются программно.
6. 06Выбран режим: шаблоны, свободная генерация или гибрид — под аудиторию и цену ошибки.
7. 07Запросы выполняются с правами пользователя, только на чтение, к реплике или витрине.
8. 08Есть ограничения по строкам и столбцам для чувствительных данных.
9. 09Есть лимиты на время выполнения и объём результата.
10. 10Ответ показывает метрику, определение, фактические даты периода и фильтры.
11. 11Собран эталонный набор, включая вопросы для уточнения и для отказа.
12. 12Регрессионный прогон обязателен после каждого изменения.
13. 13Все вопросы, запросы и ответы логируются и регулярно просматриваются.

Итог

Text-to-SQL делает данные доступнее, но его качество определяется не моделью, а подготовкой: семантическим слоем, словарём метрик, правами доступа и проверкой. Начинайте с узкого набора хорошо описанных метрик и пользователей, которые умеют проверять ответы. Расширяйте охват только тогда, когда система стабильно отвечает правильно и честно говорит «не знаю» там, где данных нет.