chDB в качестве драйвера ADBC

ADBC — независимый от поставщика API для передачи данных Arrow между приложением и базой данных. Драйвер chDB ADBC распространяется через ADBC Driver Foundry и может быть загружен любым менеджером драйверов ADBC.

Результаты передаются в виде батчей записей Arrow без построчного преобразования. Приложения могут использовать один и тот же драйвер из Python или любого другого языка с менеджером драйверов ADBC.

Установите драйвер из ADBC Driver Foundry с помощью dbc:

dbc install chdb

Первый опубликованный пакет dbc для chDB имеет версию 26.7.0. Чтобы проверить доступные версии, выполните:

dbc search -v chdb

Установленный драйвер можно загрузить по имени chdb с помощью менеджера драйверов ADBC.

Поддерживаются Linux и macOS на архитектурах x86-64 и arm64.

Установите менеджер драйверов Python ADBC:

pip install adbc-driver-manager pyarrow

Затем загрузите драйвер chDB, установленный через dbc, по имени:

from adbc_driver_manager import dbapi

with dbapi.connect(
    driver="chdb",
    db_kwargs={"uri": "chdb://"},
    autocommit=True,
) as conn:
    with conn.cursor() as cur:
        cur.execute("SELECT number FROM numbers(3)")
        print(cur.fetch_arrow_table())

chDB запускает один встроенный движок в каждом процессе, пока в нём есть открытые подключения. Учитывайте следующие правила:

• Все одновременно открытые ADBC-подключения в одном процессе должны указывать на один и тот же путь к хранилищу.
• Поддерживается несколько подключений к этому пути, в том числе одновременно используемых из разных потоков. Для параллельных запросов используйте отдельное подключение для каждого воркера, а не выполняйте одновременные операции через одно подключение.
• При закрытии последнего подключения встроенный движок завершает работу. Последующее подключение может снова запустить его, в том числе с другим путём к хранилищу, однако повторные остановка и запуск требуют времени и памяти. Для повторяющихся операций держите открытым хотя бы одно подключение.
• Один каталог на диске может быть одновременно открыт только одним процессом операционной системы. Используйте отдельный каталог для каждого процесса или базу данных в памяти.

Пакет dbc устанавливает автономный нативный драйвер ADBC. Он отличается от нативной библиотеки, которую загружает пакет Python chdb.

В рамках одного процесса Python не следует ожидать, что ADBC-подключение, загруженное через dbc, и обычное подключение chdb будут совместно использовать таблицы в памяти или состояние движка. Для одного пути к базе данных одновременно используйте либо драйвер ADBC, либо API Python chdb; не держите оба подключения открытыми для одного пути на диске. Чтобы перенести данные между двумя API, перед открытием подключений с другой стороны закройте все подключения с первой либо явно передайте данные через Arrow или файлы.

Not yet обозначает возможность драйвера ADBC, которая может быть добавлена позднее. Not applicable обозначает возможность, неприменимую к текущей модели выполнения chDB или ClickHouse.

Массовая ингестия поддерживает режимы create, append, create_append и replace в базу данных по умолчанию или указанную базу данных.

chDB использует ClickHouse SQL и его систему типов. При доступе к chDB через ADBC также действуют следующие правила ClickHouse:

• Столбцы не допускают NULL, если не объявлены как Nullable(...). Типизированное значение NULL, привязанное к обычному столбцу String, сохраняется как пустая строка, а не как NULL.
• Используйте правила экранирования идентификаторов ClickHouse; в примерах используются обратные кавычки.
• Базы данных ClickHouse сопоставляются с db_schema в ADBC. Над ними нет уровня каталога, поэтому операции на уровне каталога неприменимы.
• Decimal не поддерживает отрицательные масштабы, а Date32 охватывает диапазон от 1900-01-01 до 2299-12-31.
• DateTime64 без часового пояса интерпретируется в часовом поясе движка.
• Текущий вывод ClickHouse Arrow не поддерживает тип Time, поэтому его нельзя считать обратно через ADBC.

Некоторые типы Arrow сохраняют свои значения, но при чтении возвращаются как другой тип Arrow:

Бинарные данные хранятся как String и считываются обратно как UTF-8. Поэтому полезные нагрузки, не являющиеся допустимым UTF-8, не поддерживаются как значения binary с сохранением при записи и последующем чтении.

import pyarrow as pa

from adbc_driver_manager import dbapi

table = pa.table({"id": [1, 2, 3], "name": ["a", "b", "c"]})

with dbapi.connect(
    driver="chdb",
    db_kwargs={"uri": "chdb://"},
    autocommit=True,
) as conn:
    with conn.cursor() as cur:
        cur.adbc_ingest("events", table, mode="create")
        cur.execute("SELECT count() FROM events")
        print(cur.fetchone())

from adbc_driver_manager import dbapi

with dbapi.connect(
    driver="chdb",
    db_kwargs={"uri": "chdb://"},
    autocommit=True,
) as conn:
    with conn.cursor() as cur:
        cur.execute("SELECT number FROM numbers(10) WHERE number > ?", (7,))
        print(cur.fetch_arrow_table())

После выполнения dbc install chdb менеджер драйверов C сможет найти драйвер по имени:

#include <arrow-adbc/adbc.h>
#include <arrow-adbc/adbc_driver_manager.h>

struct AdbcDatabase database = {0};
struct AdbcError error = {0};

AdbcDatabaseNew(&database, &error);
AdbcDatabaseSetOption(&database, "driver", "chdb", &error);
AdbcDatabaseSetOption(&database, "uri", "chdb://", &error);
AdbcDatabaseInit(&database, &error);

В сборках релиза chDB ADBC для нативного драйвера на Linux x86-64 и arm64, а также macOS x86-64 и arm64 запускаются два внешних набора тестов:

• набор тестов на соответствие Apache Arrow ADBC, проверяющий контракт C
• набор проверок ADBC Driver Foundry, проверяющий поведение на уровне SQL, преобразование типов в обоих направлениях, метаданные и массовую ингестию

Таблицы поддержки на этой странице основаны на результатах этих запусков. Наборы тестов находятся в репозитории chdb-core.