> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Использование chDB через Arrow Database Connectivity (ADBC)

[Экспериментальная возможность](https://clickhouse.com/docs/reference/settings/beta-and-experimental-features.md#experimental-features)

> [!WARNING]
>
> Драйвер ADBC экспериментальный. Его поведение и параметры могут меняться от релиза к релизу.

[ADBC](https://arrow.apache.org/adbc/) — независимый от поставщика API для передачи данных Arrow между приложением и базой данных. Драйвер chDB ADBC распространяется через ADBC Driver Foundry и может быть загружен любым менеджером драйверов ADBC.

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

## Установка

Установите драйвер из ADBC Driver Foundry с помощью [`dbc`](https://docs.columnar.tech/dbc/):

```bash theme={null}
dbc install chdb
```

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

```bash theme={null}
dbc search -v chdb
```

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

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

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

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

```bash theme={null}
pip install adbc-driver-manager pyarrow
```

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

```python theme={null}
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())
```

| `uri` | База данных |
| - | - |
| `chdb://` | В памяти |
| `chdb:///absolute/path` | На диске, с сохранением в указанном каталоге |

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

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.

### База данных

| Функция | Статус | Примечания |
| - | - | - |
| `AdbcDatabaseNew` / `Init` / `Release` | Поддерживается | |
| `AdbcDatabaseSetOption` | Поддерживается | Параметры движка `uri`, `path` и `chdb.*` |

### Подключение

| Функция | Статус | Примечания |
| - | - | - |
| `AdbcConnectionNew` / `Init` / `Release` | Поддерживается | |
| `AdbcConnectionGetInfo` | Поддерживается | |
| `AdbcConnectionGetObjects` | Поддерживается | Поддерживаются все уровни глубины |
| `AdbcConnectionGetTableSchema` | Поддерживается | |
| `AdbcConnectionGetTableTypes` | Поддерживается | |
| `AdbcConnectionGetOption` | Поддерживается | Включая текущую `db_schema` |
| `AdbcConnectionSetOption` | Частично | Автоматическая фиксация должна оставаться включенной; изменение `db_schema` недоступно |
| `AdbcConnectionCommit` / `Rollback` | Неприменимо | Операторы ClickHouse фиксируются автоматически; классической транзакции для фиксации или отката нет |
| `AdbcConnectionGetStatistics` | Пока нет | Статистика таблиц через драйвер недоступна |
| `AdbcConnectionReadPartition` | Неприменимо | Драйвер не создает распределенные партиции результатов |
| `AdbcConnectionCancel` | Пока нет | Отмена запросов chDB через ADBC пока недоступна |

### Оператор

| Функция | Статус | Примечания |
| - | - | - |
| `AdbcStatementNew` / `Release` | Поддерживается | |
| `AdbcStatementSetSqlQuery` | Поддерживается | ClickHouse SQL |
| `AdbcStatementPrepare` | Поддерживается | |
| `AdbcStatementBind` / `BindStream` | Поддерживается | Позиционные параметры `?` |
| `AdbcStatementGetParameterSchema` | Поддерживается | |
| `AdbcStatementExecuteQuery` | Поддерживается | Передаёт поток батчей записей Arrow |
| `AdbcStatementSetOption` | Поддерживается | Массовая ингестия, см. ниже |
| `AdbcStatementExecuteSchema` | Пока нет | Схема результата в настоящее время доступна после выполнения |
| `AdbcStatementExecutePartitions` | Не применимо | Результаты возвращаются в виде внутрипроцессного потока Arrow |
| `AdbcStatementSetSubstraitPlan` | Не применимо | chDB принимает ClickHouse SQL, а не планы Substrait |
| `AdbcStatementCancel` | Пока нет | Отмена запросов chDB пока недоступна через ADBC |

Массовая ингестия поддерживает режимы `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:

| Тип Arrow | Хранится как | Считывается как |
| - | - | - |
| `binary`, `large_binary`, `binary_view` | `String` | `string` |
| `fixed_size_binary` (массовый приём в новую таблицу) | `FixedString(n)` | `fixed_size_binary` |
| `large_string`, `string_view` | `String` | `string` |
| `float16` | `Float32` | `float` |
| `time32` / `time64` / `timestamp` | `DateTime64(n)` | `timestamp` |

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

## Примеры

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

```python theme={null}
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())
```

### Параметры

```python theme={null}
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())
```

### C

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

```c theme={null}
#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](https://github.com/chdb-io/chdb-core/tree/main/programs/local/adbc/validation).
