> ## 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)

export const ExperimentalBadge = () => {
  return <a href="https://clickhouse.com/docs/reference/settings/beta-and-experimental-features#experimental-features" className="experimentalBadge">
            <div className="experimentalIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.25" d="M5.5 2H10.5" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M9.50015 2V6.19625L13.4283 12.7425C13.4738 12.8183 13.4985 12.9049 13.4996 12.9934C13.5008 13.0818 13.4785 13.169 13.435 13.246C13.3914 13.323 13.3283 13.3871 13.2519 13.4317C13.1755 13.4764 13.0886 13.4999 13.0002 13.5H3.00015C2.91164 13.5 2.8247 13.4766 2.74822 13.432C2.67174 13.3874 2.60847 13.3233 2.56487 13.2463C2.52126 13.1693 2.49889 13.082 2.50004 12.9935C2.50119 12.905 2.52582 12.8184 2.5714 12.7425L6.50015 6.19625V2" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M4.47656 9.56754C5.30344 9.41254 6.47656 9.47942 7.99969 10.25C10.0153 11.2707 11.4216 11.0569 12.2184 10.7282" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            Экспериментальная возможность
        </a>;
};

<ExperimentalBadge />

<Warning>
  Драйвер ADBC экспериментальный. Его поведение и параметры могут меняться от релиза к релизу.
</Warning>

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

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

<div id="installation">
  ## Установка
</div>

Установите драйвер из 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.

<div id="connecting-from-python">
  ## Подключение из Python
</div>

Установите менеджер драйверов 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` | На диске, с сохранением в указанном каталоге |

<div id="connection-lifecycle">
  ## Жизненный цикл подключений
</div>

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

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

<div id="using-python-chdb-package">
  ### Использование ADBC с пакетом Python chDB
</div>

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

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

<div id="implemented-functionality">
  ## Реализованные возможности
</div>

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

<div id="database">
  ### База данных
</div>

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

<div id="connection">
  ### Подключение
</div>

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

<div id="statement">
  ### Оператор
</div>

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

<div id="clickhouse-sql-and-type-behavior">
  ## ClickHouse SQL и поведение типов
</div>

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

<div id="examples">
  ## Примеры
</div>

<div id="bulk-ingestion">
  ### Массовая ингестия данных из Arrow
</div>

```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())
```

<div id="parameters">
  ### Параметры
</div>

```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())
```

<div id="c-example">
  ### C
</div>

После выполнения `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);
```

<div id="verification">
  ## Проверка драйвера
</div>

В сборках релиза 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).