Renta / Документация / Источники / ClickHouse Reverse ETL

ClickHouse как источник Reverse ETL

Renta читает таблицы, представления или результаты SQL-запросов из ClickHouse и передаёт данные в бизнес-инструменты через пайплайны Reverse ETL. Модель данных задаёт строки для синхронизации и ключ для их сопоставления между запусками.

Перед началом работы

Подготовьте параметры подключения и пользователя ClickHouse с правами, перечисленными ниже.

ТребованиеЧто подготовить
Сетевой доступРазрешите подключения с IP-адресов Renta к HTTP- или HTTPS-интерфейсу кластера. Обычно используются порты 8123 для HTTP и 8443 для HTTPS. Укажите порт, настроенный на вашем сервере.
Пользователь ClickHouseСоздайте отдельного пользователя базы данных. Renta нужны права на чтение данных модели и запись рабочих таблиц в отдельную базу на том же кластере.
Подключение Reverse ETLДобавьте подключение источника Reverse ETL, даже если кластер уже используется как ETL destination. В Renta это разные подключения.

Для Yandex Managed Service for ClickHouse по HTTPS корневой сертификат Яндекса уже включён в Renta.

Выдайте нужные привилегии

Renta хранит рабочие таблицы в служебной базе, которая в настройках называется Planner database. По умолчанию её имя renta_planner. Выдайте пользователю ClickHouse следующие привилегии:

ПривилегияОбластьНазначение
CREATE DATABASE*.*Создание служебной базы.
CREATE TABLE, DROP TABLE, INSERT, SELECT, ALTER, OPTIMIZEСлужебная базаСоздание, чтение и обновление рабочих таблиц, удаление старых таблиц.
SELECTБазы, из которых читают моделиПредпросмотр, проверка ключа и чтение модели при синхронизации.

Выполните эти запросы от имени пользователя с правами на управление доступом. Замените пароль и analytics своими значениями. Если служебная база будет называться иначе, замените и renta_planner.

CREATE USER renta IDENTIFIED WITH sha256_password BY 'your-strong-password';

GRANT CREATE DATABASE ON *.* TO renta;
GRANT CREATE TABLE, DROP TABLE, INSERT, SELECT, ALTER, OPTIMIZE ON renta_planner.* TO renta;
GRANT SELECT ON analytics.* TO renta;

Выдайте SELECT для каждой базы, из которой читают модели. Renta выполняет CREATE DATABASE IF NOT EXISTS при сохранении подключения и начале запуска. Пользователю нужно право на этот запрос, даже если база уже существует.

Подключите ClickHouse для Reverse ETL

Понадобятся адрес HTTP-интерфейса, порт, имя базы и учётные данные пользователя.

Откройте каталог источниковStep 1

В меню выберите Connections > Sources > Add source. В фильтре Source type выберите Reverse ETL, затем ClickHouse.

Каталог источников с фильтром Reverse ETL и выделенной плиткой ClickHouse
Введите параметры подключенияStep 2

Заполните параметры подключения.

  1. Source name.
    Название подключения в Renta.
  2. Server hostname.
    Адрес с протоколом, например https://ch.example.com. Без протокола Renta использует HTTP.
  3. Database name.
    База по умолчанию для запросов. Из неё мастер модели получает список таблиц и представлений.
  4. Port.
    Порт HTTP- или HTTPS-интерфейса.
  5. User и Password.
    Учётные данные пользователя ClickHouse.
  6. Planner database.
    Служебная база. Оставьте поле пустым для renta_planner или задайте имя из латинских букв, цифр и подчёркиваний. Оно не должно начинаться с цифры.
Форма подключения ClickHouse с заполненными полями Server hostname и Database name
Сохраните подключениеStep 3

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

Нижняя часть формы подключения с пустым полем Planner database и кнопкой Save
Проверьте подключениеStep 4

Убедитесь, что подключение появилось в Connections > Sources со статусом Active.

Список источников с новым подключением ClickHouse в статусе Active

Создайте модель данных

Откройте Tools > Context layers и нажмите New model. Одну модель могут использовать несколько пайплайнов.

Список моделей данных с кнопкой New model и счётчиками по scope

В мастере вы выбираете источник, область применения, схему и метаданные. Если модель доступна AI-агентам, появляются дополнительные шаги Measures и Access.

Определите запрос

На шаге Data source выберите подключение ClickHouse. После создания модели изменить источник нельзя.

Шаг Data source с выбранным подключением ClickHouse, вариантом SQL query и запросом в редакторе

Выберите Table or view, чтобы указать объект из базы подключения. Выберите SQL query, чтобы отобрать колонки, отфильтровать строки или соединить таблицы. Используйте синтаксис ClickHouse SQL. Кнопка Format форматирует запрос.

Модель принимает один запрос на чтение. Можно использовать подзапросы, CTE и UNION. Запросы на запись и административные команды отклоняются, в том числе внутри CTE. Уберите завершающие секции FORMAT и INTO OUTFILE: формат вывода задаёт Renta.

Проверьте запрос

Нажмите Run preview, чтобы проверить колонки и значения результата. Предпросмотр показывает до 100 строк, время выполнения и объём прочитанных данных.

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

Для запроса предпросмотра и отдельного запроса подсчёта строк действуют лимит чтения 10 ГиБ и серверный таймаут 60 секунд на каждый запрос. При превышении лимита чтения запрос прерывается с ошибкой. Добавьте фильтры, чтобы сократить объём чтения.

Если подсчитать все строки не удалось, отображается число строк предпросмотра, а не размер всей модели. Сам предпросмотр при этом может завершиться успешно.

Задайте область применения

На шаге Scope выберите, где будет доступна модель.

Шаг Scope с выбранным вариантом Reverse ETL only
ScopeГде доступна модельУникальный ключ
AI agents & Reverse ETLAI-агенты и пайплайны Reverse ETLОбязателен
AI agents onlyAI-агентыНеобязателен
Reverse ETL onlyПайплайны Reverse ETLОбязателен

В списке Data model пайплайна появляются только модели, доступные для Reverse ETL. Область применения определяет, как можно использовать модель. Доступ пользователей к запросам через AI настраивается отдельно на шаге Access.

Выберите уникальный ключ

На шаге Schema проверьте колонки результата, примеры значений и допустимость NULL. Наведите указатель на тип, чтобы увидеть исходный тип ClickHouse.

Шаг Schema с колонкой customer_id, выбранной как уникальный ключ

В столбце Unique выберите одну колонку, по которой Renta будет сопоставлять строки между запусками. Её значения должны быть уникальными и не содержать NULL. Имя колонки должно начинаться с латинской буквы или подчёркивания и содержать только латинские буквы, цифры и подчёркивания.

Нажмите Next step, чтобы проверить ключ. Как и для предпросмотра, действуют лимит чтения 10 ГиБ и серверный таймаут 60 секунд. Если найдены и NULL, и дубликаты, сначала появится сообщение о NULL. Исключите строки без ключа или выберите другую колонку, затем повторите проверку. Если ключ состоит из нескольких колонок, сформируйте в запросе одно значение, уникальное для каждого сочетания.

Основные типы ClickHouse отображаются в Renta следующим образом:

Тип ClickHouseТип в Renta
Int8, Int16, Int32, UInt8, UInt16, UInt32int
Int64, Int128, Int256, UInt64, UInt128, UInt256int64
Float32, Float64, BFloat16float
Decimaldecimal
String, FixedString, UUID, Enum, IPv4, IPv6text
Date, Date32date
DateTime, DateTime64datetime
Boolbool
Array(T)Массив соответствующего типа. Для Decimal используется array_float.

Обёртки Nullable и LowCardinality не меняют отображаемый базовый тип. Сам по себе LowCardinality не означает, что колонка допускает NULL.

Для Reverse ETL преобразуйте сложные типы, например Map, Tuple, Nested, JSON, Variant и Dynamic, в String в запросе или исключите их из сопоставления полей. Это относится и к массивам неподдерживаемых типов. Метка json в схеме не означает, что исходный тип поддерживается в Reverse ETL.

Добавьте метаданные

На шаге Metadata задайте имя модели и опишите её данные.

Шаг Metadata с именем модели, описанием, кнопкой Auto-generate with AI и превью определения инструмента
  1. В Model name укажите имя, например customer_orders.
  2. В Description объясните, что представляет одна строка, когда использовать модель и какие правила учитывать при работе с данными. Поддерживается Markdown.
  3. В Column descriptions поясните поля, которым нужен дополнительный контекст: единицы измерения, значение дат или статусов.

Auto-generate with AI предлагает описания колонок на основе запроса и выборки не более чем из десяти строк. Эти строки отправляются AI-провайдеру. Используйте функцию, только если данные можно передавать этому провайдеру, и проверьте полученные описания.

Настройте доступ для AI

Для AI agents only и AI agents & Reverse ETL заполните дополнительные шаги:

  1. На Measures выберите агрегации, доступные AI-ассистентам.
  2. На Access предоставьте доступ пользователям или группам рабочего пространства. У владельцев доступ уже есть.

Примеры и синтаксис запросов описаны на странице Context Layer.

Создайте модель

Нажмите Create model, чтобы сохранить модель и вернуться к списку.

Список моделей, отфильтрованный до новой модели с источником ClickHouse и бейджем scope Reverse ETL

Чтобы изменить модель, откройте её и используйте вкладки Query, Schema & key или Metadata. У моделей для AI-агентов также есть вкладки Measures и Access.

Запустите пайплайн Reverse ETL

Понадобится сохранённая модель с областью применения Reverse ETL only или AI agents & Reverse ETL.

Выберите ClickHouse как источникStep 1

Нажмите New pipeline, откройте вкладку Reverse ETL, выберите ClickHouse и нажмите Next step.

Шаг выбора источника в мастере пайплайна с вкладкой Reverse ETL и выбранной карточкой ClickHouse
Выберите подключениеStep 2

Выберите подключение, на котором создана модель, и нажмите Next step. В настройках назначения выберите модель в списке Data model.

Шаг выбора подключения ClickHouse с карточкой подключения и кнопкой Next step

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

Хранение и синхронизация

Каждый новый запуск читает результат модели и использует рабочие таблицы в служебной базе для сравнения строк и учёта отправки. Эти таблицы занимают место в вашем кластере ClickHouse.

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

Изменение имён или типов колонок, используемых пайплайном, может вызвать полную повторную синхронизацию. Для чтения модели и построения сравнения серверный таймаут составляет 30 минут на запрос. Для остальных SQL-операций по умолчанию действует таймаут 10 минут. Это ограничения отдельных запросов, а не общей длительности запуска.

Решение проблем

По сообщению об ошибке определите, какую настройку нужно проверить.

ПроблемаЧто сделать
Не удалось подключитьсяПроверьте протокол, порт HTTP-интерфейса, учётные данные и доступ с IP-адресов Renta. Если ClickHouse Cloud выходит из режима ожидания, повторите попытку через минуту.
Нет прав на создание служебной базыВыдайте пользователю CREATE DATABASE. Уже существующая база не отменяет эту проверку.
Модели нет в Data modelНа вкладке Query задайте Reverse ETL only или AI agents & Reverse ETL и сохраните модель.
Ключ содержит NULL или дубликатыПроверьте значения ключа в результате запроса. Исключите строки без ключа, устраните дубликаты или выберите другую колонку.
Неподдерживаемый тип ClickHouseПреобразуйте поле в String, например через toString или toJSONString, либо исключите его из сопоставления полей.
Превышен лимит чтения или таймаутСократите период, добавьте фильтры или используйте заранее подготовленную таблицу либо представление.

Что дальше

Настройте назначение или узнайте, как запрашивать модель через AI-ассистента.

Назначения Reverse ETL
Сопоставление полей и настройки синхронизации.
Context Layer
Меры, доступ и запросы к модели из AI-ассистента.
IP-адреса Renta
Адреса для настройки сетевого доступа.

Ready to get started?

Build your data pipeline today or get a personalized demo. Start free!

Need help?

Get expert support to ensure your project succeeds. We're here to help!

Feature requests?

Help shape our product! Share your ideas for new features and integrations.