nativelib

Библиотека для работы с Native форматом ClickHouse, написанная на Cython.

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

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

pip install nativelib

Назначение:

Преобразование данных между ClickHouse Native Format и Python структурами (pandas.DataFrame, polars.DataFrame, Python типы). Оптимизирована для скорости и эффективности обработки столбцовых данных.

Особенности:

  • Написана на Cython для максимальной производительности

  • Работает с бинарным «columnar» форматом ClickHouse

  • Поддерживает двунаправленную конвертацию (чтение/запись)

  • Интеграция с pandas и polars DataFrame

Поддерживаемые типы данных ClickHouse:

  • Целочисленные (UInt8-256, Int8-256)

  • Вещественные (Float32/64), Decimal

  • Строковые (String, FixedString)

  • Временные (Date, DateTime, Time)

  • Специальные (Enum, Bool, UUID, IPv4/6)

  • Составные (Array, LowCardinality, Nullable)

Неподдерживаемые типы (на данный момент):

  • Tuple

  • Map

  • Variant

  • AggregateFunction

  • Geometry типы

  • Nested

  • Dynamic

  • JSON

  • другие сложные структуры

Типы данных ClickHouse ↔ Python в виде таблицы:

Поддерживаемые типы данных

Тип ClickHouse

Чтение

Запись

Тип Python (Чтение/Запись)

Целочисленные

UInt8

int

UInt16

int

UInt32

int

UInt64

int

UInt128

int

UInt256

int

Int8

int

Int16

int

Int32

int

Int64

int

Int128

int

Int256

int

Вещественные

Float32

float

Float64

float

BFloat16

float

Decimal(P, S)

decimal.Decimal

Строковые

String

str

FixedString(N)

str

Временные

Date

datetime.date

Date32

datetime.date

DateTime

datetime.datetime

DateTime64

datetime.datetime

Time

datetime.timedelta

Time64

datetime.timedelta

Специальные

Enum

str / Union[int, enum.Enum, str]

Bool

bool

UUID

uuid.UUID

IPv4

ipaddress.IPv4Address

IPv6

ipaddress.IPv6Address

Составные

Array(T)

list[T*]

LowCardinality(T)

Union[str, date, datetime, int, float]

Nullable(T)

Optional[T*]

Nothing

None

*T - любой простой тип данных из таблицы

Зависимости:

  • pandas>=2.1.0 - для работы с DataFrame

  • polars>=0.20.31 - альтернативная обработка данных

  • backports.zoneinfo==0.2.1 - для Python < 3.9 (поддержка временных зон)

Производительность:

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

Классы

Внутренние компоненты