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

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

Renta читает модель данных из вашей базы ClickHouse и синхронизирует её строки в бизнес-инструмент через reverse-ETL пайплайн. Модель это SELECT-запрос в диалекте ClickHouse или таблица. Рабочие таблицы каждого запуска живут в planner database на том же кластере.

На этой странице описано, как подключить ClickHouse как источник Reverse ETL, создать на нём модель данных и запустить пайплайн. Настройки на стороне назначения описаны на его странице.

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

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

  1. Сетевой доступ.
    HTTP-интерфейс ClickHouse принимает подключения с IP-адресов Renta. Порты по умолчанию: 8443 для HTTPS и 8123 для HTTP.
  2. Отдельный пользователь ClickHouse.
    Renta входит под пользователем базы, который может создать planner database и читать базы, к которым обращаются модели. Привилегии перечислены в следующем разделе.
  3. Отдельное подключение.
    ClickHouse destination в воркспейсе не работает как источник Reverse ETL. Источник Reverse ETL это отдельное подключение со своим пользователем.

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

Рабочие таблицы каждого запуска Renta хранит в отдельной базе. Эта база называется planner database и носит имя renta_planner, если вы не переименуете её в настройках подключения.

ПривилегияОбластьДля чего нужна Renta
CREATE DATABASE.Создать planner database при сохранении подключения и в начале каждого запуска.
CREATE TABLE, DROP TABLE, INSERT, SELECT, ALTER, OPTIMIZEPlanner databaseЗаписать таблицы плана и отклонённых строк запуска и удалить таблицы старых запусков.
SELECTКаждая база, из которой читают моделиВыполнить превью, проверить уникальный ключ и прочитать модель при каждом запуске.

Чтобы создать пользователя и выдать привилегии, выполните запросы ниже от аккаунта с правами на управление доступом. Замените analytics на базу, из которой читают ваши модели, и повторите последний запрос для каждой другой базы, которую они используют.

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;

Привилегию CREATE DATABASE Renta проверяет при сохранении подключения, а не на первом запуске. Без неё Renta не сохраняет подключение и показывает привилегии, которые ожидает.

Подключите 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 или http://10.0.0.5. Хост без протокола Renta считает обычным HTTP.
  3. Database name.
    База по умолчанию для имён таблиц без префикса в ваших запросах. Пикер таблиц в мастере моделей показывает таблицы этой базы.
  4. Port.
    Порт HTTP-интерфейса.
  5. User и Password.
    Учётные данные созданного пользователя.
  6. Planner database.
    База для рабочих таблиц каждого запуска. Оставьте поле пустым, чтобы использовать renta_planner. Своё имя состоит из букв, цифр и подчёркиваний и не начинается с цифры.
Форма подключения ClickHouse с заполненными полями Server hostname и Database name
Сохраните подключениеStep 3

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

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

Подключение появляется в Connections > Sources со статусом Active. Теперь его можно использовать в моделях данных и reverse-ETL пайплайнах.

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

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

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

Модели живут в Tools > Data models. В списке видно, из какого хранилища читает каждая модель, её scope и число строк.

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

Чтобы создать модель, нажмите New model. Мастер проводит через четыре шага: источник данных, scope, схема и метаданные. Пятый шаг, меры, появляется только когда scope включает AI-агентов.

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

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

Шаг Data source с выбранным подключением ClickHouse, вариантом SQL query и запросом в редакторе
  1. Source.
    Подключение ClickHouse, из которого читает модель. После создания модели его нельзя поменять.
  2. Query type.
    Выберите SQL query, чтобы написать запрос самостоятельно, или Table or view, чтобы синхронизировать существующий объект как есть.

Если вы выбрали Table or view, панель справа показывает таблицы и представления базы подключения. Выберите одну, и Renta синхронизирует её колонка в колонку.

Если вы выбрали SQL query, напишите один SELECT-запрос в диалекте ClickHouse. Нажмите Format, чтобы отформатировать его. Renta проверяет запрос до отправки на сервер.

ПравилоЧто Renta отклоняет
Один запросВсё после первого запроса. Уберите дополнительные запросы, разделённые точкой с запятой.
Только чтениеINSERT, ALTER, DELETE, CREATE, DROP, TRUNCATE, RENAME и команды вроде KILL, SYSTEM или OPTIMIZE, в том числе внутри CTE.
SELECT в корнеЗапрос, корень которого не SELECT, UNION или подзапрос.
Без секций выводаЗавершающую секцию FORMAT и INTO OUTFILE. Renta оборачивает модель в подзапрос, где они запрещены.

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

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

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

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

Задайте scope

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

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

Пайплайн показывает только модели со scope Reverse ETL only или AI agents & Reverse ETL. Модель со scope AI agents only в списке Data model не появляется.

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

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

Шаг Schema с колонкой customer_id, выбранной как уникальный ключ
Тип ClickHouseТип в Renta
Int8 до Int32, UInt8 до UInt32int
Int64 и шире, UInt64 и ширеint64
Float32, Float64float
Decimal любой точностиdecimal
String, FixedString, UUID, Enum, IPv4, IPv6text
Date, Date32date
DateTime, DateTime64datetime
Boolbool
Array(T)Массив соответствующего типа
Map, Tuple, Nested, JSON, Variant, Dynamicjson

Обёртки Nullable и LowCardinality тип не меняют. Они влияют только на признак nullable.

В колонке Unique выберите колонку, по которой строка опознаётся между запусками. Ключ это одна колонка, а её имя может содержать только буквы, цифры и подчёркивания. Когда вы нажимаете Next step, Renta проверяет колонку на сервере.

ПроверкаСообщение
В колонке есть NULLЧисло NULL против общего числа строк. Уникальный ключ не может содержать NULL.
В колонке повторяются значенияЧисло дублей и число уникальных значений.

Renta сначала проверяет NULL. Колонка, в которой есть и NULL, и дубли, сообщает только про NULL. Дубли она покажет после того, как вы уберёте пустые значения. Проверка работает с тем же лимитом чтения и таймаутом, что и превью.

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

На шаге Metadata опишите модель для коллег и AI-агентов.

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

Auto-generate with AI отправляет строки выборки AI-провайдеру. Не используйте кнопку, если модель возвращает данные, которые нельзя передавать третьим лицам.

Справа видно определение инструмента, которое получит агент, и счётчик токенов: сколько контекста агента занимает модель.

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

Нажмите Create model. Модель появляется в списке с источником, scope и числом строк.

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

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

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

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

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

В левом меню нажмите New pipeline. Переключите вкладку с ETL на Reverse ETL, выберите ClickHouse и нажмите Next step.

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

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

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

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

Что запуск оставляет в кластере

Запуск reverse-ETL пайплайна читает модель и пишет рабочие таблицы в planner database на том же кластере.

Каждый запуск создаёт таблицу плана со строками на отправку и таблицу отклонённых строк, которые не принял получатель. Обе таблицы на движке MergeTree и названы по пайплайну и запуску. Renta хранит таблицы текущего и предыдущего запуска, а всё старше удаляет. После первой синхронизации в planner database две такие таблицы. Начиная со второй их четыре.

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

Запуск читает модель целиком при каждой синхронизации. Если у модели поменялись имена или типы колонок, следующий запуск синхронизирует всё заново, потому что предыдущий план уже не с чем сравнивать.

Ограничения

Для моделей и запусков ClickHouse действуют следующие ограничения.

  1. Ключ из одной колонки.
    Уникальный ключ это одна колонка. Если строку определяют несколько колонок, склейте их в запросе.
  2. Лимит на запрос.
    На каждый запрос внутри запуска Renta отводит до десяти минут. Если модель читается дольше, запуск завершается ошибкой. Сузьте запрос фильтром или читайте из материализованного представления.

Что дальше

Переходите к настройке назначения или проверьте сетевые требования.

Назначения Reverse ETL
Маппинг полей и параметры синхронизации для каждого назначения.
IP-адреса Renta
Адреса, которые нужно разрешить на HTTP-интерфейсе ClickHouse.
Google BigQuery Reverse ETL
Тот же процесс для модели данных в BigQuery.
Часто задаваемые вопросы

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.