NativeDumper

NativeDumper(
connector,
compression_method=CompressionMethod.ZSTD,
logger=None,
timeout=DBMS_DEFAULT_TIMEOUT_SEC,
)

Класс для чтения и записи данных в Native формате ClickHouse.

Параметры:

  • connector (CHConnector) – Коннектор для подключения к ClickHouse

  • compression_method (CompressionMethod) – Метод сжатия данных

  • logger (Logger | None) – Логгер для записи событий

  • timeout (int) – Таймаут операций в секундах

Исключение:

  • ValueError – Если используется порт 9000

  • ClickhouseServerError – При ошибках сервера ClickHouse

  • NativeDumperError – При других ошибках инициализации

Описание:

Внешний модуль native-dumper входит в состав dbhose-airflow, но может быть установлен отдельно.

Установка модуля native-dumper без установки dbhose-airflow

pip install native-dumper

Линки на проект:

Часть кода написана на языке Rust, что обеспечивает более быструю работу по сравнению с языком Python.

Назначение класса NativeDumper - обмен данными с сервером Clickhouse по http/https протоколу.

Импорт модуля

from native_dumper import (
    NativeDumper,
    CHConnector,
)

connector = CHConnector(
    host="localhost",
    dbname="",
    user="my_user",
    password="my_password",  # noqa: S106
    port=8123,

)
dumper = NativeDumper(connector)

NativeDumper предоставляет функциональность для работы с Native форматом ClickHouse - бинарным протоколом, оптимизированным для эффективной передачи данных между клиентом и сервером.

Класс автоматически устанавливает соединение с сервером ClickHouse, проверяет совместимость и инициализирует необходимые компоненты для работы с Native форматом.

Параметры инициализации:

Параметры конструктора NativeDumper

Параметр

Тип

Описание

connector

CHConnector

Обязательный. Коннектор, содержащий параметры подключения к ClickHouse (хост, порт, пользователь, пароль)

compression_method

CompressionMethod

Метод сжатия данных. По умолчанию: CompressionMethod.ZSTD. Поддерживаемые методы: ZSTD, LZ4, NONE

logger

Logger | None

Логгер для записи событий и ошибок. Если не указан, создается DumperLogger по умолчанию

timeout

int

Таймаут операций в секундах. По умолчанию: DBMS_DEFAULT_TIMEOUT_SEC

Атрибуты экземпляра:

connector: CHConnector

Коннектор для подключения к ClickHouse.

compression_method: CompressionMethod

Метод сжатия данных.

logger: Logger

Логгер для записи событий.

cursor: HTTPCursor

Курсор для выполнения запросов через HTTP протокол.

version: str

Версия сервера ClickHouse.

dbname: str

Имя СУБД (всегда «clickhouse»).

Ограничения и исключения:

  • Порт 9000 не поддерживается - NativeDumper использует HTTP/HTTPS протокол (порт 8123 по умолчанию), а не Native протокол (порт 9000)

  • Требуется корректный коннектор - должен содержать все необходимые параметры подключения

  • Автоматическое переподключение - при потере соединения могут возникать исключения

Примеры использования:

# Создание NativeDumper с параметрами по умолчанию
from native-dumper import NativeDumper, CHConnector, CompressionMethod

connector = CHConnector(
    host="localhost",
    port=8123,
    user="default",
    password=""
)

dumper = NativeDumper(
    connector=connector,
    compression_method=CompressionMethod.ZSTD,
    timeout=30
)

# Создание с кастомным логгером
import logging

custom_logger = logging.getLogger("native_dumper")
custom_logger.setLevel(logging.DEBUG)

dumper_with_logger = NativeDumper(
    connector=connector,
    logger=custom_logger
)

Обработка ошибок:

try:
    connector = CHConnector(host="localhost", port=9000)  # Неправильный порт!
    dumper = NativeDumper(connector=connector)
except ValueError as e:
    print(f"Неправильная конфигурация: {e}")

try:
    connector = CHConnector(host="nonexistent", port=8123)
    dumper = NativeDumper(connector=connector)
except NativeDumperError as e:
    print(f"Ошибка подключения: {e}")

Примечания:

  • Native формат - самый эффективный способ передачи данных в/из ClickHouse

  • Используется HTTP/HTTPS протокол (порт 8123 или 443), а не Native TCP протокол (порт 9000)

  • Сжатие данных уменьшает объем передаваемых данных и ускоряет передачу по сети

  • Класс автоматически отправляет HELLO-пакет при инициализации для проверки соединения

  • Для больших объемов данных рекомендуется использовать ZSTD сжатие

Доступные методы класса и декоратор multiquery

Дополнительные компоненты

См. также: