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

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

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 позволяет добавлять колонки в заполнилиенную таблицу, которые не являются нулевыми.
  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. Это обрабатывается автоматически ключевыми функциями ClickHouse GCS таблиц, которые dlt использует под капотом.

Функция таблицы GCS ClickHouse поддерживает только аутентификацию с использованием ключей Hash-based Message Authentication Code (HMAC). Для этого 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-ключам gcp_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.