clickhouse-1c-native

Высокопроизводительное решение для интеграции 1С:Предприятия 8.3 с СУБД ClickHouse. Проект состоит из внешней компоненты, написанной на Rust (Native API), и готового расширения конфигурации 1С.

Разработано для ультра-быстрой пакетной вставки данных (до сотен тысяч строк в секунду) и эффективного сбора структурированных логов/метрик без блокировки интерфейса 1С.

🚀 Ключевые возможности

• Асинхронное ядро на Rust: Компонента построена на базе tokio и официального драйвера clickhouse с автоматическим сжатием трафика по протоколу lz4.
• Двухфазный буфер в памяти (ВК): Метрики не отправляются мгновенно в сеть. Они накопливаются в эффективном буфере на стороне Rust и сбрасываются батчами. Хвост буфера автоматически дозаписывается при уничтожении (Drop) объекта в 1С.
• Высокопроизводительный импорт (TSV): Вставка табличных данных методом ПакетнаяВставка через самый быстрый для ClickHouse формат — Tab-Separated Values.
• Надежность сети: Интегрированная стратегия повторных запросов с джиттером через tokio-retry2.

📂 Структура репозитория

• /rust — Исходный код внешней компоненты на Rust.
• /1c — Папка с расширением 1С:
  • /1c/src — Исходный код расширения, распакованный в текстовые файлы (для удобного отслеживания истории в Git).
  • /1c/build — Готовый скомпилированный файл расширения (.cfe).

🛠 Системные требования и сборка

Требования

• ОС: Windows x64 (тестировалось и проверялось на Win). Код кроссплатформенный, для сборки под Linux достаточно активировать настройки целевой платформы в вашем окружении.
• Rust: Toolchain 2021 edition.
• Платформа 1С:Предприятие 8.3.20+ (x64).

Сборка компоненты

В проекте настроена автоматизация через утилиту cargo-make. Для сборки финального релизного бинарника перейдите в папку rust и выполните:

cargo make pack

Полученную динамическую библиотеку (.dll) необходимо загрузить в общий макет КХ_ВК расширения 1С или прописать к ней прямой путь на диске.

---

🗄 Структура таблицы метрик в ClickHouse

Для корректной работы функции логирования метрик, создайте в ClickHouse целевую таблицу со следующей схемой:

CREATE TABLE IF NOT EXISTS system_1c.metrics
(
    event_time DateTime64(3) DEFAULT now(),
    event_type LowCardinality(String),
    event_name String,
    duration_ms UInt32,
    status LowCardinality(String),
    user LowCardinality(String),
    comment String,
    payload Map(String, String)
) 
ENGINE = MergeTree() 
ORDER BY (event_type, event_name, event_time);

---

💻 Спецификация методов компоненты (API Rust)

Встроенные методы компоненты, доступные на стороне 1С:

Метод в 1С	Метод в Rust	Описание
Подключиться(Адрес, Логин, Пароль)	Connect	Инициализирует сессию с сервером ClickHouse. Возвращает Булево.
ВыполнитьКоманду(ТекстSQL)	Execute	Выполняет произвольный SQL-запрос (SELECT, ALTER и т.д.). Возвращает JSON-строку.
ПакетнаяВставка(Таблица, СтрокаTSV, Проверять)	BulkInsert	Высокоскоростной поток данных. Третий параметр отвечает за предварительную проверку существования таблицы.
ЛогМетрики(...)	LogMetric	Запись метрики в буфер. Принимает параметры: тип, имя, длительность (мс), статус, пользователь, контекст.
❌ Не использовать!	FlushCacheManually	Внимание: Вызывает критическое падение процесса 1С. Метод заблокирован к использованию.

⚠️ Важная особенность буфера: Сброс накопленного кэша метрик в базу ClickHouse происходит асинхронно. Чтобы гарантированно "вытолкнуть" оставшийся хвост метрик из памяти в БД (например, в конце работы регламентного задания), необходимо явно переинициализировать объект компоненты или завершить её сессию (что спровоцирует вызов деструктора Drop на стороне Rust).

---

📋 Пример использования в 1С

1. Фиксация метрик (сбор логов)

// Начинаем замер времени
Метрика = КХ_Метрики.НачатьЗамер("HTTP", "ОтправкаКонтрагентов");

Попытка
    // ... логика вашего обмена ...
    КХ_Метрики.ФиксироватьМетрику(Метрика, "Success");
Исключение
    КХ_Метрики.ФиксироватьМетрику(Метрика, "Error");
КонецПопытки;

2. Массовая вкачка Таблицы Значений (Bulk Insert)

// Быстро преобразует ТЗ в TSV в памяти и заливает пакет в ClickHouse одной операцией
КХ_ИнтеграцияСлужебный.ВкачатьТаблицуЗначений("system_1c.my_data_table", ТаблицаСДанными, Ложь);

---

🤝 Обратная связь и Contribution

Если вы хотите предложить улучшения, исправить баги или помочь решить проблему с падением 1С при вызове FlushCacheManually (буду рад экспертам по потокам/Runtime в Native API!), пишите автору:

• Telegram: @brighontik

⚖️ Лицензия

Проект распространяется под лицензией MIT. Подробнее см. файл LICENSE.