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

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

Community Maintained

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

Установка dlt с зависимостями ClickHouse​

Для установки библиотеки dlt с зависимостями ClickHouse:​

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

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

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

примечание

Эта команда инициализирует ваш конвейер с chess в качестве источника и 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. Это автоматически обрабатывается с помощью табличной функции 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 (gcp_access_key_id и gcp_secret_access_key), теперь вам нужно предоставить client_email, project_id и private_key для вашей учетной записи сервиса в разделе [destination.filesystem.credentials]. Это связано с тем, что поддержка промежуточного хранения GCS сейчас реализована как временное решение и все еще не оптимизирована.

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

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

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

Поддержка dbt​

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

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

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