chDB como driver ADBC

ADBC es una API independiente del proveedor para transferir datos de Arrow entre una aplicación y una base de datos. El driver ADBC de chDB se distribuye a través de ADBC Driver Foundry y puede cargarlo cualquier administrador de drivers ADBC.

Los resultados se transfieren como lotes de registros de Arrow, sin conversión fila por fila. Las aplicaciones pueden usar el mismo driver desde Python o cualquier otro lenguaje con un administrador de drivers ADBC.

Instale el controlador desde ADBC Driver Foundry mediante dbc:

dbc install chdb

El primer paquete dbc publicado para chDB corresponde a la versión 26.7.0. Para consultar las versiones disponibles, ejecute:

dbc search -v chdb

El driver instalado se puede cargar con el nombre chdb desde un administrador de drivers ADBC.

Linux y macOS son compatibles con las arquitecturas x86-64 y arm64.

Instale el gestor de controladores ADBC para Python:

pip install adbc-driver-manager pyarrow

A continuación, cargue por nombre el driver chDB instalado mediante 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())

chDB ejecuta un engine embedded en cada proceso mientras haya conexiones abiertas. Tenga en cuenta las siguientes reglas:

• Todas las conexiones ADBC abiertas simultáneamente en un proceso deben usar la misma ruta de almacenamiento.
• Se admiten varias conexiones a esa ruta, incluidas las utilizadas de forma concurrente desde distintos threads. Para queries concurrentes, asigne a cada worker su propia conexión en lugar de ejecutar operaciones simultáneas en una única conexión.
• Al cerrar la última conexión, se apaga el engine embedded. Una conexión posterior puede volver a iniciarlo, incluso con una ruta de almacenamiento diferente, pero los apagados y arranques repetidos consumen tiempo y memoria. Mantenga al menos una conexión abierta para tareas repetitivas.
• Solo un proceso del sistema operativo puede abrir un directorio en disco determinado a la vez. Asigne a cada proceso su propio directorio o utilice una database en memoria.

El paquete dbc instala un driver ADBC nativo independiente. Es distinto de la biblioteca nativa que carga el paquete chdb para Python.

En un proceso de Python, no espere que una conexión ADBC cargada por dbc y una conexión chdb normal compartan tablas en memoria ni el estado del engine. Para una ruta de base de datos determinada, use el driver ADBC o la API de chdb para Python, pero no ambos a la vez; no mantenga ambos abiertos en la misma ruta en disco. Para mover datos entre las dos API, cierre todas las conexiones de una antes de abrir las de la otra, o transfiera los datos explícitamente mediante Arrow o archivos.

Not yet indica una capacidad del controlador ADBC que se podrá añadir más adelante. Not applicable indica una funcionalidad que no se ajusta al modelo de ejecución actual de chDB o ClickHouse.

La ingestión masiva admite los modos create, append, create_append y replace en la base de datos predeterminada o en una base de datos con nombre.

chDB utiliza ClickHouse SQL y su sistema de tipos. La siguiente semántica de ClickHouse también se aplica al acceder a chDB mediante ADBC:

• Las columnas no admiten valores NULL, salvo que se declaren como Nullable(...). Un NULL tipado vinculado a una columna String sin Nullable se almacena como una cadena vacía, no como NULL.
• Use las comillas para identificadores de ClickHouse; los ejemplos usan comillas invertidas.
• Las bases de datos de ClickHouse se asignan a db_schema de ADBC. No existe una capa de catálogo por encima de ellas, por lo que las operaciones con ámbito de catálogo no son aplicables.
• Decimal no acepta escalas negativas y Date32 abarca desde 1900-01-01 hasta 2299-12-31.
• Un DateTime64 sin zona horaria se interpreta en la zona horaria del motor.
• La salida Arrow actual de ClickHouse no representa el tipo Time, por lo que no se puede volver a leer mediante ADBC.

Algunos tipos de Arrow conservan sus valores, pero se vuelven a leer como un tipo de Arrow distinto:

Los datos binarios se almacenan como String y se vuelven a leer como UTF-8. Por tanto, las cargas útiles que no son UTF-8 válidas no son compatibles como valores binary de ida y vuelta.

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

Después de ejecutar dbc install chdb, el administrador de controladores de C puede resolver el controlador por nombre:

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

Las compilaciones de lanzamiento de chDB ADBC ejecutan dos suites externas con el driver nativo en Linux x86-64 y arm64, y macOS x86-64 y arm64:

• la suite de conformidad de Apache Arrow ADBC, que verifica el contrato de C
• la suite de validación de ADBC Driver Foundry, que verifica el comportamiento a nivel de SQL, los recorridos de ida y vuelta de tipos, los metadatos y la ingestión masiva

Las tablas de compatibilidad de esta página se basan en los resultados de esas ejecuciones. Las suites se encuentran en el repositorio chdb-core.