Автоматическое описание таблиц и полей: как уйти от ручной документации баз данных

Какая самая частая проблема любой базы данных, хранилища данных или BI? Правильно — нет никакой документации. А какая самая главная боль любого разработчика или аналитика? Правильно — писать документацию. Самая большая проблема — документация всегда пишется вручную, а следовательно, с большими объемами мы можем справиться только большими трудозатратами. Очень часто на документацию «забивают», но не учитывают, что на поиск и понимание данных будут тратить кратно больше времени.

И как справиться? Да мы же живем в эпоху AI.

Итак, мы решили «запрячь» AI и поручить ему самую рутинную часть работы.

Но тут важно сразу остановиться и задать правильный вопрос: а что именно должен делать искусственный интеллект, чтобы описание получилось осмысленным, а не формальным набором слов?

Самый простой вариант — взять DDL таблицы, передать его модели и попросить: «Опиши, что здесь хранится». Такой подход напрашивается сам собой, но на практике он почти всегда дает слабый результат. Причина проста: названия таблиц и столбцов далеко не всегда отражают реальное бизнес-содержание данных. Особенно если речь идет про legacy-хранилища, которые развивались годами.

Представим столбец с названием CLIENT_NAME. Кажется очевидным, что там имя клиента. Но открываем данные и видим: «Иванов Иван Иванович». Это уже не просто имя, а ФИО. Или столбец cur_code, где лежат значения RUB, USD, EUR. Без анализа данных догадаться, что это код валюты, можно, но далеко не всегда такие примеры бывают настолько очевидны. А иногда встречаются поля вроде n24id, где без дополнительного контекста не разберется ни человек, ни AI.

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

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

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

В основе архитектуры лежит простой и понятный пайплайн.

Сначала система подключается к источникам данных и считывает метаданные: схемы, таблицы, столбцы, процедуры, связи. Поддерживаются разные СУБД: от классических PostgreSQL и MSSQL до аналитических хранилищ. Этот этап полностью автоматический и не требует участия пользователя.

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

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

Отдельно стоит отметить, что решение изначально проектировалось как on-premise. Это критично для enterprise: данные не покидают периметр компании, можно использовать собственные модели или локально развернутые LLM, а архитектура легко масштабируется под большие хранилища и BI-ландшафты.

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

Ключевым элементом всей системы является промпт. Именно от него зависит качество ответа. Какой вопрос – такой и ответ.

Отдельно стоит сказать про эксперименты с Chain of Thought. Мы пробовали заставлять модель рассуждать и объяснять, как она пришла к тому или иному выводу. Однако в задаче документации это не дало заметного прироста качества. Более того, такие рассуждения часто увеличивали объем текста и приводили к лишним деталям, которые в документации только мешают. В итоге мы оставили только итоговый, структурированный ответ.

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

Эти правки не пропадают бесследно. Принятые описания используются как дополнительный контекст для следующих запусков. Если в компании принято называть CUSTOMER не «клиентом», а «контрагентом», модель начинает использовать именно эту терминологию. По сути, таким образом постепенно формируется бизнес-глоссарий, на который опирается AI.

Мы многие модели тестировали и пришли к следующему списку самых лучших open-source моделей.

В системе используется не одна универсальная модель, а набор специализированных.

Описание BI-дашбордов — одна из самых сложных задач в автоматической документации. В отличие от таблиц, здесь важно понять не только структуру, но и смысл визуализаций, а также то, как бизнес должен интерпретировать данные.

Процесс начинается со сбора метаданных BI-отчета: списка дашбордов, вкладок, графиков, типов визуализаций и используемых показателей. Дополнительно формируются изображения вкладок и отдельных графиков, чтобы AI мог анализировать визуальный контекст, а не только названия элементов.

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

Для каждого графика формируется краткое описание и рекомендации по анализу — на что обращать внимание и какие выводы можно сделать. После этого на основе всех графиков формируется общее описание вкладки, а затем и всего дашборда в целом.

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

Структура хранилища постоянно меняется. Появляются новые таблицы и поля, дорабатываются процедуры, обновляются BI-дашборды и их логика. Если документация не актуализируется автоматически, она очень быстро теряет ценность и перестает отражать реальное состояние данных.

Процесс актуализации начинается с регулярного обновления метаданных. Система считывает текущую структуру источников и сравнивает ее с уже задокументированным состоянием. Так выявляются новые таблицы, столбцы, процедуры и BI-объекты, а также изменения в существующих элементах. Для всех новых или неописанных объектов автоматически запускается процесс формирования документации.

При этом переописание происходит осознанно. Если описание объекта уже было принято пользователем, оно не перезаписывается. Повторно обрабатываются только новые объекты или те, которые находятся в статусе «требуется принятие». Это позволяет сохранять ручные правки и накопленный бизнес-контекст.

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

Автоматическое описание метаданных не заменяет data catalog, а дополняет его. Data catalog остается точкой входа для работы с данными и процессов data governance, а AI-решение берет на себя формирование и актуализацию бизнес-описаний. Интеграция реализована через API и SDK: сгенерированные и подтвержденные описания автоматически передаются в data catalog, где становятся частью общей модели метаданных и доступны всем пользователям.

Автоматическое описание позволяет кратно сократить трудозатраты на документацию и анализ данных. Команды быстрее разбираются в legacy-хранилищах, ускоряется онбординг аналитиков, а data catalog наполняется актуальными бизнес-описаниями. На практике уже с первой итерации удается получить до 90–95% корректных описаний, что делает дальнейшую ручную работу минимальной.

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

Оставляйте заявку на нашем сайте и мы продемонстрируем работу нашего решения!