chDB como driver ADBC

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

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.

Instalação

Instale o driver do ADBC Driver Foundry usando o dbc:

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:

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.

Conexão pelo Python

Instale o gerenciador de drivers ADBC do Python:

pip install adbc-driver-manager pyarrow

Em seguida, carregue pelo nome o driver chDB instalado com 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())

`uri`	Banco de dados
`chdb://`	Em memória
`chdb:///absolute/path`	No disco, persistido no diretório especificado

Ciclo de vida da conexão

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.

Como usar o ADBC com o pacote Python chDB

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.

Funcionalidades implementadas

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.

Banco de dados

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

Conexão

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

Instrução

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.

ClickHouse SQL e comportamento dos tipos

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.

Exemplos

Ingestão em massa do Arrow

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

Parâmetros

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

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

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

Como o driver é verificado

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.

Primeiros passos

Integrações por linguagem

DataStore

Configuração

Depuração

Guias para desenvolvedores

Referência técnica

Instalação

Conexão pelo Python

Ciclo de vida da conexão

Como usar o ADBC com o pacote Python chDB

Funcionalidades implementadas

Banco de dados

Conexão

Instrução

ClickHouse SQL e comportamento dos tipos

Exemplos

Ingestão em massa do Arrow

Parâmetros

C

Como o driver é verificado

​Instalação

​Conexão pelo Python

​Ciclo de vida da conexão

​Como usar o ADBC com o pacote Python chDB

​Funcionalidades implementadas

​Banco de dados

​Conexão

​Instrução

​ClickHouse SQL e comportamento dos tipos

​Exemplos

​Ingestão em massa do Arrow

​Parâmetros

​C

​Como o driver é verificado

Instalação

Conexão pelo Python

Ciclo de vida da conexão

Como usar o ADBC com o pacote Python chDB

Funcionalidades implementadas

Banco de dados

Conexão

Instrução

ClickHouse SQL e comportamento dos tipos

Exemplos

Ingestão em massa do Arrow

Parâmetros

C

Como o driver é verificado