ADBCドライバーとしてのchDB

ADBC は、アプリケーションとデータベース間で Arrow データを移動するためのベンダー中立な API です。chDB ADBC ドライバーは ADBC Driver Foundry を通じて配布され、任意の ADBC ドライバーマネージャーで読み込むことができます。

結果は行ごとの変換なしに Arrow の record batch として受け渡されます。アプリケーションでは、Python または ADBC ドライバーマネージャーを利用できる他の任意の言語から、同じドライバーを使用できます。

dbc を使用して、ADBC Driver Foundry からドライバーをインストールします。

dbc install chdb

chDB 向けに最初にパブリッシュされた dbc パッケージは、バージョン 26.7.0 です。利用可能なバージョンを確認するには、次を実行します。

dbc search -v chdb

インストールしたドライバーは、ADBC ドライバーマネージャー から chdb という名前で読み込めます。

x86-64 および arm64 アーキテクチャの Linux と macOS をサポートしています。

Python ADBC ドライバーマネージャーをインストールします。

pip install adbc-driver-manager pyarrow

次に、dbc でインストールした chDB ドライバーを名前でロードします。

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 は、接続が開かれている間、各プロセスで 1 つの埋め込みエンジンを実行します。以下のルールに注意してください。

• プロセス内で同時に開かれているすべての ADBC 接続は、同じストレージパスを参照する必要があります。
• このパスへの複数の接続がサポートされており、異なるスレッドから同時に使用する接続も含まれます。クエリを同時実行する場合は、1 つの接続で複数の操作を同時に実行するのではなく、各ワーカーに専用の接続を割り当ててください。
• 最後の接続を閉じると、埋め込みエンジンは停止します。その後の接続で再起動でき、異なるストレージパスを使用することもできますが、停止と起動を繰り返すと時間とメモリを消費します。繰り返し処理を行う場合は、少なくとも 1 つの接続を開いたままにしてください。
• 特定のディスク上のディレクトリを同時に開ける OS プロセスは 1 つだけです。各プロセスに専用のディレクトリを割り当てるか、インメモリデータベースを使用してください。

dbc パッケージは、スタンドアロンのネイティブ ADBC ドライバーをインストールします。これは、Python の chdb パッケージが読み込むネイティブライブラリとは別のものです。

1 つの Python プロセス内で、dbc によって読み込まれた ADBC 接続と通常の chdb 接続が、インメモリテーブルやエンジンの状態を共有することは想定しないでください。特定のデータベースパスでは、ADBC ドライバーまたは Python の chdb API のいずれか一方のみを使用し、同じオンディスクパスで両方を開いたままにしないでください。2 つの API 間でデータを移動するには、一方のすべての接続を閉じてからもう一方を開くか、Arrow またはファイルを介して明示的にデータを渡してください。

未対応 は、今後追加可能な ADBC ドライバーの機能を示します。該当なし は、現在の chDB または ClickHouse の実行モデルに該当しない機能を示します。

一括インジェストでは、デフォルトデータベースまたは名前付きデータベースに対して、create、append、create_append、replace モードをサポートしています。

chDB は ClickHouse SQL とその型システムを使用します。ADBC 経由で chDB にアクセスする場合にも、以下の ClickHouse のセマンティクスが適用されます。

• カラムは、Nullable(...) として宣言しない限り Nullable にはなりません。通常の String カラムにバインドされた型付き NULL は、NULL ではなく空文字列として格納されます。
• ClickHouse の識別子のクォーティングを使用してください。例ではバッククォートを使用しています。
• ClickHouse データベースは ADBC の db_schema に対応します。上位のカタログレイヤーは存在しないため、カタログスコープの操作は利用できません。
• Decimal は負のスケールを受け付けず、Date32 の範囲は 1900-01-01 から 2299-12-31 です。
• タイムゾーンを指定しない DateTime64 は、エンジンのタイムゾーンで解釈されます。
• 現在の ClickHouse Arrow 出力では Time 型を表現できないため、ADBC 経由で読み戻すことはできません。

一部の Arrow 型は値を保持しますが、読み戻すと別の Arrow 型になります。

バイナリデータは String として格納され、UTF-8 として読み戻されます。したがって、有効な UTF-8 ではないペイロードは、binary 値として往復変換することはサポートされていません。

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

dbc install chdb の実行後、C ドライバーマネージャーは名前でドライバーを解決できます。

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

chDB ADBC リリースビルドでは、Linux x86-64 および arm64、macOS x86-64 および arm64 上でネイティブドライバーに対し、2 つの外部テストスイートを実行します。

• C のコントラクトを確認する Apache Arrow ADBC 適合性スイート
• SQL レベルの動作、型のラウンドトリップ、メタデータ、一括インジェストを確認する ADBC Driver Foundry 検証スイート

このページのサポート表は、これらの実行結果に基づいています。これらのスイートは chdb-core リポジトリにあります。