> ## 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 como driver ADBC

> Como usar o chDB com o 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>
            Recurso experimental
        </a>;
};

<ExperimentalBadge />

<Warning>
  O driver ADBC é experimental. Seu comportamento e suas opções podem mudar entre lançamentos.
</Warning>

[ADBC](https://arrow.apache.org/adbc/) é uma API independente de fornecedor para transferir dados Arrow entre uma aplicação e um banco de dados. O driver ADBC do chDB é distribuído pelo ADBC Driver Foundry e pode ser carregado por qualquer gerenciador de drivers ADBC.

Os resultados são transferidos como lotes de registros Arrow, sem conversão linha por linha. As aplicações podem usar o mesmo driver em Python ou em qualquer outra linguagem com um gerenciador de drivers ADBC.

<div id="installation">
  ## Instalação
</div>

Instale o driver do ADBC Driver Foundry usando o [`dbc`](https://docs.columnar.tech/dbc/):

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

O primeiro pacote `dbc` publicado para o chDB é a versão 26.7.0. Para verificar as versões disponíveis, execute:

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

O driver instalado pode ser carregado pelo nome `chdb` por meio de um gerenciador de drivers ADBC.

Há suporte para Linux e macOS em x86-64 e arm64.

<div id="connecting-from-python">
  ## Conexão pelo Python
</div>

Instale o gerenciador de drivers ADBC do Python:

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

Em seguida, carregue pelo nome o driver chDB instalado com `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`                   | Banco de dados                                 |
| ----------------------- | ---------------------------------------------- |
| `chdb://`               | Em memória                                     |
| `chdb:///absolute/path` | No disco, persistido no diretório especificado |

<div id="connection-lifecycle">
  ## Ciclo de vida da conexão
</div>

O chDB executa um engine embutido em cada processo enquanto houver conexões abertas. Tenha estas regras em mente:

* Todas as conexões ADBC abertas simultaneamente em um processo devem apontar para o mesmo caminho de armazenamento.
* Há suporte para várias conexões nesse caminho, inclusive conexões usadas simultaneamente por diferentes threads. Para consultas concorrentes, dê a cada worker sua própria conexão, em vez de executar operações simultâneas em uma única conexão.
* Fechar a última conexão encerra o engine embutido. Uma conexão posterior pode iniciá-lo novamente, inclusive com um caminho de armazenamento diferente, mas desligamentos e inicializações repetidos consomem tempo e memória. Mantenha pelo menos uma conexão aberta para tarefas recorrentes.
* Apenas um processo do SO pode abrir determinado diretório em disco por vez. Dê a cada processo seu próprio diretório ou use um banco de dados em memória.

<div id="using-python-chdb-package">
  ### Como usar o ADBC com o pacote Python chDB
</div>

O pacote `dbc` instala um driver ADBC nativo independente. Ele é separado da biblioteca nativa carregada pelo pacote Python `chdb`.

Em um mesmo processo Python, não espere que uma conexão ADBC carregada por `dbc` e uma conexão `chdb` comum compartilhem tabelas em memória ou o estado do engine. Para um determinado caminho de banco de dados, use o driver ADBC ou a API Python `chdb` de cada vez; não mantenha ambos abertos no mesmo caminho em disco. Para mover dados entre as duas APIs, feche todas as conexões de um lado antes de abrir as do outro ou transfira os dados explicitamente por meio do Arrow ou de arquivos.

<div id="implemented-functionality">
  ## Funcionalidades implementadas
</div>

`Not yet` indica uma capacidade do driver ADBC que poderá ser adicionada futuramente. `Not applicable` indica um recurso que não é compatível com o modelo de execução atual do chDB ou do ClickHouse.

<div id="database">
  ### Banco de dados
</div>

| Função                                 | Status     | Observações                               |
| -------------------------------------- | ---------- | ----------------------------------------- |
| `AdbcDatabaseNew` / `Init` / `Release` | Compatível |                                           |
| `AdbcDatabaseSetOption`                | Compatível | Opções do engine `uri`, `path` e `chdb.*` |

<div id="connection">
  ### Conexão
</div>

| Função                                   | Status        | Observações                                                                                           |
| ---------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------- |
| `AdbcConnectionNew` / `Init` / `Release` | Compatível    |                                                                                                       |
| `AdbcConnectionGetInfo`                  | Compatível    |                                                                                                       |
| `AdbcConnectionGetObjects`               | Compatível    | Todas as profundidades                                                                                |
| `AdbcConnectionGetTableSchema`           | Compatível    |                                                                                                       |
| `AdbcConnectionGetTableTypes`            | Compatível    |                                                                                                       |
| `AdbcConnectionGetOption`                | Compatível    | Inclui o `db_schema` atual                                                                            |
| `AdbcConnectionSetOption`                | Parcial       | O autocommit deve permanecer habilitado; não é possível alterar `db_schema`                           |
| `AdbcConnectionCommit` / `Rollback`      | Não aplicável | As instruções do ClickHouse usam autocommit; não há uma transação clássica para confirmar ou reverter |
| `AdbcConnectionGetStatistics`            | Ainda não     | As estatísticas da tabela não são expostas pelo driver                                                |
| `AdbcConnectionReadPartition`            | Não aplicável | O driver não produz partições de resultados distribuídos                                              |
| `AdbcConnectionCancel`                   | Ainda não     | O cancelamento de consultas do chDB ainda não é exposto pelo ADBC                                     |

<div id="statement">
  ### Instrução
</div>

| Função                             | Status        | Observações                                                                    |
| ---------------------------------- | ------------- | ------------------------------------------------------------------------------ |
| `AdbcStatementNew` / `Release`     | Compatível    |                                                                                |
| `AdbcStatementSetSqlQuery`         | Compatível    | ClickHouse SQL                                                                 |
| `AdbcStatementPrepare`             | Compatível    |                                                                                |
| `AdbcStatementBind` / `BindStream` | Compatível    | Parâmetros posicionais `?`                                                     |
| `AdbcStatementGetParameterSchema`  | Compatível    |                                                                                |
| `AdbcStatementExecuteQuery`        | Compatível    | Transmite lotes de registros Arrow                                             |
| `AdbcStatementSetOption`           | Compatível    | Ingestão em massa; veja abaixo                                                 |
| `AdbcStatementExecuteSchema`       | Ainda não     | O schema de resultado fica disponível após a execução                          |
| `AdbcStatementExecutePartitions`   | Não aplicável | Os resultados são retornados como um stream Arrow no processo                  |
| `AdbcStatementSetSubstraitPlan`    | Não aplicável | O chDB aceita ClickHouse SQL, não planos Substrait                             |
| `AdbcStatementCancel`              | Ainda não     | O cancelamento de consultas do chDB ainda não está disponível por meio do ADBC |

A ingestão em massa é compatível com os modos `create`, `append`, `create_append` e `replace`, no banco de dados padrão ou em um banco de dados nomeado.

<div id="clickhouse-sql-and-type-behavior">
  ## ClickHouse SQL e comportamento dos tipos
</div>

O chDB usa o ClickHouse SQL e seu sistema de tipos. A semântica a seguir do ClickHouse também se aplica quando o chDB é acessado por ADBC:

* As colunas não aceitam valores nulos, a menos que sejam declaradas como `Nullable(...)`. Um NULL tipado vinculado a uma coluna simples `String` é armazenado como uma string vazia, e não como NULL.
* Use a delimitação de identificadores do ClickHouse; os exemplos usam backticks.
* Os bancos de dados do ClickHouse são mapeados para `db_schema` no ADBC. Não há uma camada de catálogo acima deles, portanto, operações no escopo do catálogo não se aplicam.
* `Decimal` não aceita escalas negativas, e `Date32` abrange o período de 1900-01-01 a 2299-12-31.
* Um `DateTime64` sem fuso horário é interpretado no fuso horário do engine.
* A saída Arrow atual do ClickHouse não representa o tipo `Time`; portanto, ele não pode ser lido por ADBC.

Alguns tipos Arrow preservam seus valores, mas são lidos como um tipo Arrow diferente:

| Tipo Arrow                                                 | Armazenado como  | Lido como           |
| ---------------------------------------------------------- | ---------------- | ------------------- |
| `binary`, `large_binary`, `binary_view`                    | `String`         | `string`            |
| `fixed_size_binary` (ingestão em massa em uma nova tabela) | `FixedString(n)` | `fixed_size_binary` |
| `large_string`, `string_view`                              | `String`         | `string`            |
| `float16`                                                  | `Float32`        | `float`             |
| `time32` / `time64` / `timestamp`                          | `DateTime64(n)`  | `timestamp`         |

Dados binários são armazenados como `String` e lidos como UTF-8. Portanto, payloads que não são UTF-8 válidos não são compatíveis com valores `binary` em operações de round-trip.

<div id="examples">
  ## Exemplos
</div>

<div id="bulk-ingestion">
  ### Ingestão em massa do 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">
  ### Parâmetros
</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>

Após executar `dbc install chdb`, o gerenciador de drivers C pode localizar o driver pelo nome:

```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">
  ## Como o driver é verificado
</div>

As compilações de lançamento do chDB ADBC executam duas suítes externas para o driver nativo em Linux x86-64 e arm64 e macOS x86-64 e arm64:

* a suíte de conformidade do Apache Arrow ADBC, que verifica o contrato em C
* a suíte de validação ADBC Driver Foundry, que verifica o comportamento no nível de SQL, conversões de tipos de ida e volta, metadados e ingestão em massa

As tabelas de suporte nesta página são derivadas dessas execuções. As suítes estão no [repositório chdb-core](https://github.com/chdb-io/chdb-core/tree/main/programs/local/adbc/validation).