Renta / Документация / Назначения / ClickHouse

Назначение ClickHouse

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

Каждый пайплайн управляет одной целевой таблицей. Renta извлекает записи, сохраняет их в формате Parquet в собственной облачной инфраструктуре и инициирует прямое чтение этих файлов сервером ClickHouse по протоколу HTTPS.

Требования

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

  1. Доступность HTTP-интерфейса.
    Renta направляет запросы к HTTP-интерфейсу ClickHouse (порты по умолчанию: 8443 для HTTPS, 8123 для HTTP). Убедитесь, что разрешен входящий доступ с IP-адресов Renta.
  2. Доступность хранилища.
    ClickHouse загружает подготовленные Parquet-файлы с storage.googleapis.com по HTTPS. Если конфигурация вашего сервера использует секцию remote_url_allow_hosts, необходимо добавить в неё данный хост.
  3. Права выделенного пользователя.
    Для работы Renta требуются права на создание, заполнение, очистку (truncate) и удаление таблиц в пределах выделенной базы данных, а также на чтение внешних файлов с использованием табличной функции url.
Пользователь ClickHouse для Renta
Команды GRANT для отдельной учётной записи.

Подключение назначения

Конфигурация подключения определяет эндпоинт конкретной базы данных ClickHouse и соответствующие учётные данные для аутентификации Renta.

Подключение ClickHouse в качестве назначения

Выполните эти шаги, чтобы добавить вашу базу ClickHouse как назначение в Renta.

Перейдите в каталогStep 1
  1. В консоли Renta откройте Connections > Catalog в левом меню.
  2. Разверните категорию Data warehouse и нажмите карточку ClickHouse.
Карточка ClickHouse в категории Data warehouse каталога подключений Renta
Укажите адрес сервераStep 2

Укажите параметры подключения к базе данных:

  1. Server hostname.
    Полное доменное имя хоста (FQDN), включая протокол (например, https://clickhouse.example.com). Если протокол опущен, Renta по умолчанию использует http://.
  2. Database name.
    Целевая база данных для ваших таблиц. Renta требует, чтобы эта база данных была создана заранее, и ограничивает все операции записи только ей.
  3. Port.
    Порт HTTP-интерфейса. Значения по умолчанию: 8443 для HTTPS и 8123 для HTTP.
Форма нового подключения ClickHouse с полями имени хоста, базы данных и порта
Введите учётные данныеStep 3
  1. User.
    Имя пользователя ClickHouse, назначенное для операций Renta.
  2. Password.
    Пароль, связанный с указанным пользователем.

Аутентификация выполняется исключительно через HTTP-интерфейс. Доступ по нативному протоколу ClickHouse не требуется.

Поля User и Password в форме нового подключения ClickHouse
Назовите подключение и сохранитеStep 4

Укажите Destination name (внутренний идентификатор для консоли Renta) и нажмите Save.

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

Поле Destination name и кнопка Save в форме подключения ClickHouse
Проверьте подключениеStep 5

Подключение отобразится в списке Destinations со статусом Active, указывая на готовность к интеграции в пайплайны.

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

Создание пайплайна

Пайплайн устанавливает поток данных между конкретным источником и вашим подключением ClickHouse. Ниже приведена настройка на примере Stripe, однако данная методология универсальна для всех поддерживаемых источников.

Создание пайплайна в ClickHouse

Свяжите источник данных с вашей базой ClickHouse и настройте пайплайн.

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

В левом навигационном меню выберите New pipeline. Убедитесь, что активна вкладка ETL, выберите источник в разделе Already connected и нажмите Next step.

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

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

Шаг выбора подключения источ�ника с одной карточкой
Выберите ClickHouse как назначениеStep 3

На этапе Destination выберите ClickHouse из списка Already connected и нажмите Next step.

Шаг выбора назначения с карточкой ClickHouse в блоке Already connected
Выберите подключение назначенияStep 4

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

Шаг выбора подключения ClickHouse с именем базы данных и хостом на карточке

Настройка пайплайна

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

Настройки источника

Начальный раздел определяет область извлечения данных. Доступные параметры зависят от источника. Конфигурация Stripe, например, начинается с выбора типа отчёта.

Выпадающий список Report Types в настройках пайплайна со значением Balance Transactions

Выберите конкретные поля для извлечения. Каждое выбранное поле будет сопоставлено с колонкой в целевой таблице ClickHouse. Невыбранные поля исключаются из передачи данных.

Пикер Parameters со всеми отмеченными полями и ссылкой Unselect All

Под каждым полем Renta отображает результирующее имя колонки в целевой таблице. Используйте Select All для одновременного выбора всех доступных полей.

Имя интеграции и таблицы

В следующем разделе задается номенклатура пайплайна в системе Renta и соответствующей таблицы в ClickHouse.

Поля Integration name и Table name в настройках пайплайна
  1. Integration name.
    Назначенное отображаемое имя пайплайна в консоли Renta.
  2. Table name.
    Целевая таблица, создаваемая Renta в пределах указанной базы данных. Вы можете использовать автоматически сгенерированное имя или задать собственный идентификатор. Убедитесь, что каждому пайплайну присвоено уникальное имя таблицы, так как пайплайны перезаписывают свои таблицы во время выполнения.

Диапазон дат

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

Поля Date start и Date end блока Date Range
  1. Date start.
    Начальная дата окна извлечения данных.
  2. Date end.
    Конечная дата окна извлечения, которая может быть статической датой или динамической границей (например, Today).

Инициация ручного Full refresh из панели управления пайплайном приведёт к повторной загрузке данных за весь указанный период.

Период перезаписи

Период перезаписи (overwrite period) определяет ретроспективное окно для замены данных во время запланированных выполнений. Эта настройка применяется исключительно к типам отчётов временных рядов (time-series), которые генерируют партиционированные таблицы.

Выпадающий список Overwrite Period со значением Last 1 day

Renta удаляет существующие строки в указанном временном окне и повторно вставляет их с обновлёнными значениями. Выбор Without overwrite data сохраняет исторические записи нетронутыми и добавляет только новые данные, сгенерированные с момента предыдущего запуска.

Расписание

Расписание определяет частоту автоматической синхронизации данных. Все настроенные значения времени обрабатываются в UTC.

Выбор типа расписания с отмеченным �вариантом Daily
Тип расписанияОписание
ManualПайплайн запускается только вручную из консоли Renta или через API.
DailyПайплайн запускается раз в сутки в указанное время обновления.
IntervalПайплайн запускается через заданные интервалы времени.
Cron ExpressionПайплайн запускается по расписанию, заданному cron-выражением.

Для расписания Daily укажите Update time (точное время начала выполнения) и затем нажмите Create pipeline.

Выпадающий список Update time и кнопка Create pipeline

Renta дополнительно поддерживает программное выполнение через API-триггеры и интеграцию с внешними оркестраторами (например, Apache Airflow, Dagster, Prefect). Подробную информацию см. в документации по расписанию.

Сконфигурированный пайплайн будет отображаться в интерфейсе Pipelines на вкладке ETL, где будут показаны имя целевой таблицы, текущий статус выполнения и объём извлечённых записей.

Список Pipelines с новой интеграцией и именем её таблицы в ClickHouse

Таблица назначения

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

Движок и ключи

Используемый движок таблицы ClickHouse динамически определяется методологией синхронизации данных источника.

Режим синхронизацииДвижокКлючи
Полная перезагрузка и окно перезаписиMergeTreeСортировка по колонке date (если она присутствует в пайплайне). В противном случае ключ сортировки включает все невложенные колонки.
MergeReplacingMergeTreeИ первичный ключ, и ключ сортировки совпадают с ключом слияния источника (например, id записи).

Renta применяет партиционирование таблицы по колонке date, если она доступна и тип отчёта поддерживает это. Стратегия партиционирования оптимизирует операции перезаписи, позволяя Renta эффективно перезаписывать затронутые дни вместо полной перезаписи таблицы.

Имена колонок и типы данных

Номенклатура целевых колонок отражает имена полей, определённые в настройках пайплайна. Renta нормализует идентификаторы, заменяя символы . и : на подчёркивания (_). Поле fee.amount поэтому преобразуется в fee_amount.

Значение источникаТип в ClickHouse
Целые числаNullable(Int32), для широких диапазонов Nullable(Int64)
Дробные числаNullable(Float32)
Текст, JSON и идентификаторыNullable(String)
Логические флагиNullable(UInt8)
ДатыNullable(Date)
Отметки времениNullable(DateTime)
Списки значенийArray(Nullable(T))
Вложенные записиNested(...) с отдельной подколонкой на каждое поле

Все скалярные колонки создаются как nullable. Следовательно, отсутствующие значения из источника загружаются как NULL, а не как значения по умолчанию (например, ноль или пустая строка). Ключ слияния строго определяется как не-nullable колонка.

Изменение схемы

Изменение выбора полей пайплайна требует структурных изменений в определении таблицы, поскольку ClickHouse не поддерживает мутацию ключей сортировки (sorting keys) in-place.

Сохранение структурных изменений (добавление или удаление полей) инициирует пересоздание таблицы при следующем запуске. Renta удалит существующую таблицу, создаст новую схему и выполнит полную ретроспективную загрузку на основе настроенного Date Range. Данные за пределами этого окна будут безвозвратно удалены. При необходимости скорректируйте параметр Date start до сохранения, чтобы сохранить нужные исторические данные.

Стратегия синхронизации

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

СтратегияКогда применяетсяОписание
Полная перезагрузкаТипы отчётов без колонки с датой и любые пайплайны с непартиционированной таблицейRenta выполняет команду TRUNCATE TABLE и повторно загружает весь набор данных, гарантируя, что целевая таблица отражает точное состояние источника на момент выполнения.
Инкрементальное обновлениеТипы отчётов с колонкой даты и партиционированной таблицейRenta выполняет целевое удаление строк в пределах указанного окна перезаписи с использованием ключей партиционирования, после чего выполняет повторную вставку. Исторические партиции, предшествующие окну, остаются нетронутыми.
Инкрементальная (merge)Типы отчётов, которые поддерживают merge-синхронизацию. Для каждого источника они перечислены в его документацииRenta извлекает исключительно измененные записи с момента предыдущего выполнения и вставляет их в таблицу ReplacingMergeTree, используя идентификатор записи в качестве ключа. Устаревшие версии строк асинхронно удаляются во время фоновых слияний (background merges) ClickHouse.

Merge-режим доступен только для ClickHouse и Google BigQuery. Тот же источник с другим назначением переключается на полную перезагрузку.

Из-за механизма асинхронной дедупликации ReplacingMergeTree могут возникать временные дубликаты записей. Для гарантии строгой консистентности при операциях чтения из таблиц в merge-режиме, добавляйте в запросы модификатор FINAL или изолируйте самую последнюю строку по ключу с помощью оператора LIMIT 1 BY.

Диагностика ошибок

Renta стандартизирует ответы API ClickHouse в детерминированный набор диагностических сообщений. Приведенные ниже справочные таблицы классифицируют эти сообщения в зависимости от контекста: конфигурация подключения или логи выполнения пайплайна.

При сохранении подключения

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

СообщениеПричинаЧто делать
Specified incorrect access credentials for the Clickhouse server. Please verify the accuracy of the information.В поле Server hostname не указан протокол, и Renta не может собрать URL запроса. В тексте сказано про учётные данные, но с ними всё в порядке.Допишите https:// или http:// перед именем хоста и сохраните ещё раз.
Authentication failed: password is incorrect, or there is no user with such name.ClickHouse отклонил вход.Введите User и Password заново. Проверьте, что учётная запись существует и работает: отправьте любой запрос в HTTP-интерфейс мимо Renta.
Invalid ClickHouse credentials.ClickHouse отказал в запросе как неавторизованном.Проверьте учётную запись на readonly-профиль, IP-фильтр и квоту, которая её блокирует. Пользователю также должно быть разрешено подключаться с IP-адресов Renta.
ClickHouse server is unavailable.Renta не достучалась до HTTP-интерфейса: хост не разрезолвился, порт закрыт, соединение отклонено или истекло по таймауту, либо сервер ответил 404, 500 или 504.Проверьте Server hostname и Port, убедитесь, что HTTP-интерфейс поднят, и откройте IP-адреса Renta на файрволе.

Во время запуска пайплайна

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

СообщениеПричинаЧто делать
Unable to connect to Clickhouse. Please verify the accuracy of the provided credentials.Соединение истекло по таймауту.Проверьте файрвол и текущую нагрузку. Перегруженный кластер отваливается по таймауту так же, как недоступный.
ClickHouse server is unavailable.Тот же набор транспортных сбоев, что и на форме подключения: нет DNS-записи, закрыт порт, соединение отклонено или оборвано, либо ответ 404, 500 или 504.Повторите проверки подключения и посмотрите, пережил ли хост перезапуск, уменьшение кластера или смену адреса.
Access to Clickhouse is denied.HTTP-интерфейс ответил 403 Forbidden.Проверьте, что учётная запись не заблокирована и что в её списке разрешённых адресов есть IP-адреса Renta.
Not enough privileges for added ClickHouse user.Учётной записи не хватает одного из прав на таблицы в подключённой базе.Выдайте SELECT, INSERT, CREATE TABLE, DROP TABLE, TRUNCATE и ALTER TABLE, как описано на странице пользователя ClickHouse.
The ClickHouse user does not have the 'READ ON URL' privilege required to load data from a remote URL.Учётная запись не может пользоваться табличной функцией url, а через неё Renta загружает подготовленные Parquet-файлы.Выполните GRANT READ ON URL TO renta. До ClickHouse 25.7 команда выглядит как GRANT URL ON *.* TO renta.
Attempt to load data from an unauthorized remote URL into ClickHouse.В секции remote_url_allow_hosts конфигурации сервера нет хоста хранилища, и ClickHouse блокирует скачивание своей ошибкой 491.Добавьте в эту секцию storage.googleapis.com или уберите секцию, чтобы разрешить все хосты.
You need to increase the memory limit as the current limit has been reached.Сервер упёрся в лимит памяти при чтении Parquet-файла. Чтению нужен запас сверх размера самого файла.Поднимите max_memory_usage для учётной записи или уменьшите запуск: меньше полей, короче окно перезаписи, уже диапазон дат.
The ClickHouse server is returning a NOT_ENOUGH_SPACE error.На дисках ClickHouse закончилось свободное место.Освободите место или расширьте том и запустите пайплайн заново. Файлы, загруженные до падения, остаются в таблице, поэтому перезапускайте то же окно, а не считайте таблицу нетронутой.

Нераспознанные ответы ClickHouse не отображаются в логах выполнения в исходном виде. Они абстрагируются как An error has occurred. Please contact the technical support team. без специфики базы данных. При возникновении этой ошибки обратитесь в службу поддержки 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.