Перейти к основному содержимому
Перейти к основному содержимому

Подключение dlt к ClickHouse

Community Maintained

dlt — это библиотека с открытым исходным кодом, которую вы можете добавить в свои скрипты на Python для загрузки данных из различных, часто неструктурированных источников данных в хорошо структурированные, актуальные наборы данных.

Установка dlt с ClickHouse​

Чтобы установить библиотеку dlt с зависимостями для ClickHouse:​

Руководство по настройке​

1. Инициализируйте проект dlt​

Начните с инициализации нового проекта dlt следующим образом:

примечание

Эта команда инициализирует ваш конвейер с шахматами в качестве источника и ClickHouse в качестве назначения.

Указанная выше команда создает несколько файлов и директорий, включая .dlt/secrets.toml и файл зависимостей для ClickHouse. Вы можете установить необходимые зависимости, указанные в файле зависимостей, выполнив следующую команду:

или с помощью pip install dlt[clickhouse], что устанавливает библиотеку dlt и необходимые зависимости для работы с ClickHouse в качестве назначения.

2. Настройка базы данных ClickHouse​

Чтобы загрузить данные в ClickHouse, вам необходимо создать базу данных ClickHouse. Вот общий план того, что вам нужно сделать:

  1. Вы можете использовать существующую базу данных ClickHouse или создать новую.

  2. Чтобы создать новую базу данных, подключитесь к вашему серверу ClickHouse, используя командный инструмент clickhouse-client или SQL-клиент по вашему выбору.

  3. Выполните следующие SQL-команды, чтобы создать новую базу данных, пользователя и предоставить необходимые разрешения:

3. Добавление учетных данных​

Далее настройте учетные данные ClickHouse в файле .dlt/secrets.toml, как показано ниже:

примечание

HTTP_PORT Параметр http_port определяет номер порта, который будет использоваться при подключении к HTTP интерфейсу сервера ClickHouse. Это отличается от порта по умолчанию 9000, который используется для нативного протокола TCP.

Вы должны установить http_port, если не используете внешнее временное хранилище (т.е. вы не указываете параметр staging в вашем конвейере). Это связано с тем, что встроенное локальное хранилище ClickHouse использует библиотеку clickhouse content, которая взаимодействует с ClickHouse через HTTP.

Убедитесь, что ваш сервер ClickHouse настроен на прием HTTP соединений на порту, указанном в http_port. Например, если вы установили http_port = 8443, тогда ClickHouse должен прослушивать HTTP запросы на порту 8443. Если вы используете внешнее временное хранилище, вы можете опустить параметр http_port, так как clickhouse-connect использоваться не будет.

Вы можете передать строку подключения к базе данных, аналогичную той, что используется библиотекой clickhouse-driver. Учетные данные выше будут выглядеть следующим образом:

Режим записи​

Все режимы записи поддерживаются.

Режимы записи в библиотеке dlt определяют, как данные должны быть записаны в назначение. Существует три типа режимов записи:

Замена: Этот режим заменяет данные в назначении данными из ресурса. Он удаляет все классы и объекты и воссоздает схему перед загрузкой данных. Вы можете узнать больше об этом здесь.

Слияние: Этот режим записи сливает данные из ресурса с данными в назначении. Для режима merge необходимо указать primary_key для ресурса. Вы можете узнать больше об этом здесь.

Дополнение: Это режим по умолчанию. Он добавляет данные к существующим данным в назначении, игнорируя поле primary_key.

Загрузка данных​

Данные загружаются в ClickHouse самым эффективным способом, в зависимости от источника данных:

  • Для локальных файлов используется библиотека clickhouse-connect для прямой загрузки файлов в таблицы ClickHouse с помощью команды INSERT.
  • Для файлов в удаленном хранилище, таких как S3, Google Cloud Storage или Azure Blob Storage, используются функции таблиц ClickHouse, такие как s3, gcs и azureBlobStorage для чтения файлов и вставки данных в таблицы.

Наборы данных​

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

Поддерживаемые форматы файлов​

  • jsonl является предпочтительным форматом как для прямой загрузки, так и для временного хранилища.
  • parquet поддерживается как для прямой загрузки, так и для временного хранилища.

Назначение clickhouse имеет несколько специфических отклонений от стандартных SQL назначений:

  1. Clickhouse имеет экспериментальный тип данных object, но мы обнаружили, что он немного непредсказуем, поэтому назначение dlt clickhouse будет загружать сложный тип данных в текстовый столбец. Если вам нужна эта функция, свяжитесь с нашим сообществом в Slack, и мы рассмотрим возможность ее добавления.
  2. Clickhouse не поддерживает тип данных time. Время будет загружено в текстовый столбец.
  3. Clickhouse не поддерживает тип данных binary. Вместо этого, двоичные данные будут загружены в текстовый столбец. При загрузке из jsonl двоичные данные будут строкой base64, а при загрузке из parquet объект binary будет преобразован в text.
  4. Clickhouse принимает добавление в таблицу с данными столбцов, которые не равны null.
  5. Clickhouse может вызывать ошибки округления в определенных условиях при использовании типов данных float или double. Если вы не можете допустить ошибки округления, обязательно используйте тип данных decimal. Например, загрузка значения 12.7001 в столбец типа double с установленным форматом загрузчика на jsonl предсказуемо приведет к ошибке округления.

Поддерживаемые подсказки столбцов​

ClickHouse поддерживает следующие подсказки столбцов:

  • primary_key - указывает, что столбец является частью первичного ключа. Несколько столбцов могут иметь эту подсказку для создания составного первичного ключа.

Двигатель таблицы​

По умолчанию, таблицы создаются с использованием движка таблиц ReplicatedMergeTree в ClickHouse. Вы можете указать альтернативный движок таблицы, используя table_engine_type с адаптером clickhouse:

Поддерживаемые значения:

  • merge_tree - создает таблицы с использованием движка MergeTree
  • replicated_merge_tree (по умолчанию) - создает таблицы с использованием движка ReplicatedMergeTree

Поддержка временного хранилища​

ClickHouse поддерживает Amazon S3, Google Cloud Storage и Azure Blob Storage в качестве назначения для временного хранилища файлов.

dlt будет загружать файлы Parquet или jsonl в указанное временное хранилище и использовать функции таблиц ClickHouse для загрузки данных непосредственно из временно сохраненных файлов.

Пожалуйста, обратитесь к документации файловой системы, чтобы узнать, как настроить учетные данные для назначений временного хранилища:

Чтобы запустить конвейер с включенным временным хранилищем:

Использование Google Cloud Storage в качестве временного хранилища​

dlt поддерживает использование Google Cloud Storage (GCS) в качестве временного хранилища при загрузке данных в ClickHouse. Это обрабатывается автоматически с помощью функции таблицы GCS ClickHouse, которую dlt использует под капотом.

Функция таблицы clickhouse GCS поддерживает аутентификацию только с использованием ключей HMAC (Hash-based Message Authentication Code). Чтобы включить это, GCS предоставляет режим совместимости с S3, который эмулирует API Amazon S3. ClickHouse использует это для доступа к ведрам GCS через свою интеграцию S3.

Чтобы настроить временное хранилище GCS с аутентификацией HMAC в dlt:

  1. Создайте ключи HMAC для вашей учетной записи службы GCS, следуя руководству Google Cloud.

  2. Настройте ключи HMAC, а также client_email, project_id и private_key для вашей учетной записи службы в настройках ClickHouse назначения вашего проекта dlt в config.toml:

Примечание: В дополнение к ключам HMAC bashgcp_access_key_id и gcp_secret_access_key, теперь вам нужно предоставить client_email, project_id и private_key для вашей учетной записи службы в разделе [destination.filesystem.credentials]. Это связано с тем, что поддержка временного хранилища GCS в настоящее время реализована как временное решение и все еще не оптимизирована.

dlt передаст эти учетные данные ClickHouse, который будет обрабатывать аутентификацию и доступ к GCS.

В настоящее время ведется активная работа по упрощению и улучшению настройки временного хранилища GCS для назначения dlt в ClickHouse в будущем. Подробная поддержка временного хранилища GCS отслеживается в следующих вопросах на GitHub:

  • Сделать назначение файловой системы работающим с gcs в режиме совместимости s3
  • Поддержка временного хранилища Google Cloud Storage

Поддержка dbt​

Интеграция с dbt в целом поддерживается через dbt-clickhouse.

Синхронизация состояния dlt​

Это назначение полностью поддерживает синхронизацию состояния dlt.