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

Установка

Установите драйвер из ADBC Driver Foundry с помощью dbc:
Первый опубликованный пакет dbc для chDB имеет версию 26.7.0. Чтобы проверить доступные версии, выполните:
Установленный драйвер можно загрузить по имени chdb с помощью менеджера драйверов ADBC. Поддерживаются Linux и macOS на архитектурах x86-64 и arm64.

Подключение из Python

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

Жизненный цикл подключений

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

Использование ADBC с пакетом Python chDB

Пакет 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 в базу данных по умолчанию или указанную базу данных.

ClickHouse SQL и поведение типов

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 с сохранением при записи и последующем чтении.

Примеры

Массовая ингестия данных из Arrow

Параметры

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

Проверка драйвера

В сборках релиза chDB ADBC для нативного драйвера на Linux x86-64 и arm64, а также macOS x86-64 и arm64 запускаются два внешних набора тестов:
  • набор тестов на соответствие Apache Arrow ADBC, проверяющий контракт C
  • набор проверок ADBC Driver Foundry, проверяющий поведение на уровне SQL, преобразование типов в обоих направлениях, метаданные и массовую ингестию
Таблицы поддержки на этой странице основаны на результатах этих запусков. Наборы тестов находятся в репозитории chdb-core.
Последнее изменение 18 августа 2026 г.