Text-to-SQL плагин (Productivity Tool)

CedrusData Engine поддерживает подключаемый плагин, преобразующий запрос пользователя на естественном языке в SQL («Text-to-SQL»). Плагин не входит в поставку по умолчанию — это точка расширения (SPI), которую реализует конкретный провайдер (например, обёртка над LLM-сервисом). CedrusData Engine отвечает только за загрузку и вызов плагина, а также за интеграцию с SQL-редактором Web UI.

Примечание

Интерфейс является экспериментальным и может измениться в будущих версиях без сохранения обратной совместимости.

Настройка

Чтобы включить Text-to-SQL, добавьте свойство с путем к файлу настроек плагина в etc/config.properties координатора:

cedrusdata.productivity-tool.config-file=etc/productivity-tool.properties

Создайте файл etc/productivity-tool.properties, указав имя зарегистрированной фабрики и её свойства:

productivity-tool.name=<имя_фабрики>

Пример со сторонним провайдером (имена свойств — условные, конкретный набор определяется реализацией плагина):

productivity-tool.name=my-llm-provider
my-llm-provider.endpoint=https://llm.corp.example.com/v1/complete
my-llm-provider.api-key=${ENV:MY_LLM_API_KEY}
my-llm-provider.model=my-model-name

Конфигурационные свойства

Свойство	Описание
cedrusdata.productivity-tool.config-file	Путь к properties-файлу с конфигурацией Text-to-SQL плагина (например, etc/productivity-tool.properties). Если не задано, плагин не загружается и функциональность Text-to-SQL недоступна. [Тип: string]
productivity-tool.name	Задаётся внутри файла, на который указывает cedrusdata.productivity-tool.config-file. Имя зарегистрированной ProductivityToolFactory, которую необходимо активировать. [Тип: string]

Возможности Text-to-SQL

Основной метод SPI — ProductivityTool.textToSql(...)

При вызове из Web UI CedrusData Engine передаёт в реализацию плагина:

• identity — идентичность вызывающего пользователя (для аудита, персонализации ответа или дополнительных проверок доступа на стороне плагина);

• tabId — непрозрачный идентификатор вкладки SQL-редактора (session + tab), позволяющий провайдеру вести историю диалога или контекст в рамках одной вкладки;

• catalog / schema — текущий контекст каталога/схемы, выбранный пользователем в SQL-редакторе (если выбран);

• userText — текст запроса на естественном языке, введённый пользователем после префикса -- AI/;

• schemaExplorer — интерфейс для доступа к метаданным каталогов, схем, таблиц, представлений и колонок с учётом прав текущего пользователя. Каждый вызов SchemaExplorer выполняется в изолированной read-only auto-commit транзакции, поэтому интерфейс безопасно использовать из любого потока, включая асинхронные callback’и.

Реализация возвращает CompletableFuture<String> со сгенерированным SQL-текстом, который затем показывается пользователю (и, при использовании SQL-редактора, автоматически подставляется на место исходного комментария). Логика самого преобразования (обращение к LLM, построение промпта на основе схемы, кэширование и т.д.) полностью лежит на стороне плагина — CedrusData Engine выступает только транспортом между Web UI и плагином.