chDB como driver ADBC

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.

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.

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

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.

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.

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.

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.

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:

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.

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

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

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

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.