はじめに

ClickHouse Connect は、中核となるデータベースドライバーであり、幅広い Python アプリケーションとの相互運用性を提供します。

• 主なインターフェイスは、clickhouse_connect.driver にある同期 Client と、aiohttp ベースのネイティブな AsyncClient です。このドライバーパッケージは、クエリおよび insert のコンテキスト、streaming ヘルパー、DB-API サポート、さらに低レベルの HTTP メソッドも提供します。
• clickhouse_connect.datatypes パッケージは、ClickHouse Native バイナリ列指向フォーマットを使用して、ClickHouse の型を serialize および deserialize します。
• clickhouse_connect.driverc のオプションの Cython 拡張機能は、一般的なシリアライゼーション、変換、buffering の処理を高速化します。拡張機能をビルドできないプラットフォームでも、pure Python の経路は引き続き利用可能です。
• このパッケージには PEP 561 の型情報が含まれているため、下流の型チェッカーは、公開ドライバー、DB-API、SQLAlchemy の各インターフェイスに対する annotations を利用できます。
• clickhouse_connect.cc_sqlalchemy の SQLAlchemy dialect は、SQLAlchemy Core、スキーマ reflection、ClickHouse 固有のクエリ clauses と table engines、そして Alembic の移行をサポートします。基本的な ORM の reads と inserts は動作しますが、この dialect は完全な unit-of-work ORM の振る舞いではなく、分析ワークロード向けに設計されています。
• 中核ドライバーと ClickHouse Connect SQLAlchemy 実装は、ClickHouse を Apache Superset に接続するための推奨される方法です。ClickHouse Connect データベース接続、または clickhousedb SQLAlchemy dialect 接続文字列を使用してください。

このドキュメントは clickhouse-connect 1.6.0 時点の内容です。0.15.x 以前からアップグレードする場合は、1.0 migration guide を参照してください。

この package には、利用可能な環境向けのコンパイル済み wheel が含まれており、Cython 拡張機能をビルドできない場合は pure Python 実装にフォールバックします。PyArrow は Python 3.10 〜 3.14 をサポートしています。Python 3.14 では PyArrow 22 以降が必要です。

pip を使用して、PyPI から ClickHouse Connect をインストールします。

pip install clickhouse-connect

オプションのインテグレーションは、extras を使ってインストールします:

pip install "clickhouse-connect[async]"      # Native asyncio client
pip install "clickhouse-connect[pandas]"     # Pandas
pip install "clickhouse-connect[arrow]"      # PyArrow
pip install "clickhouse-connect[polars]"     # Polars
pip install "clickhouse-connect[sqlalchemy]" # SQLAlchemy dialect
pip install "clickhouse-connect[alembic]"    # SQLAlchemy and Alembic
pip install "clickhouse-connect[chdb]"       # Embedded chDB backend
pip install "clickhouse-connect[tzdata]"     # IANA time zones on minimal systems

ClickHouse Connect は、ソースコードからインストールすることもできます。

• GitHub リポジトリ を git clone します。
• プロジェクトのルートディレクトリに移動し、pip install . を実行します。ビルドシステムにより、オプションの C 拡張機能をコンパイルするための Cython が自動的にインストールされます。

インストールされたバージョンは、clickhouse_connect.__version__ で確認できます。

問題を報告する前に、ClickHouse Connect を最新リリースに更新してください。問題の報告は GitHub project に登録してください。ClickHouse Connect は、各ドライバーのリリース時点でアクティブにサポートされている ClickHouse リリースを対象としています。古いサーバーバージョンでも動作することはよくありますが、新しいデータ型やプロトコル機能では、より新しいサーバーが必要になる場合があります。

HTTP(S) で ClickHouse に接続するには、次の情報が必要です。

ClickHouse Cloud サービスの詳細は、ClickHouse Cloud コンソールで確認できます。 サービスを選択し、Connect をクリックします。

HTTPS を選択します。接続情報は curl コマンドの例として表示されます。

セルフマネージド ClickHouse を使用している場合、接続情報は ClickHouse 管理者によって設定されます。

ClickHouse に接続する方法として、次の 2 つの例を示します。

• localhost 上の ClickHouse サーバーに接続する。
• ClickHouse Cloud サービスに接続する。

import clickhouse_connect

client = clickhouse_connect.get_client(
    host="localhost",
    username="default",
    password="password",
)

import clickhouse_connect

client = clickhouse_connect.get_client(
    host="HOSTNAME.clickhouse.cloud",
    port=8443,
    username="default",
    password="your password",
)

ClickHouse SQL コマンドを実行するには、クライアントの command メソッドを使用します。

client.command(
    "CREATE TABLE new_table "
    "(key UInt32, value String, metric Float64) "
    "ENGINE MergeTree ORDER BY key"
)

バッチデータを挿入するには、クライアントの insert メソッドを使用し、行と値で構成された二次元配列を渡します。

row1 = [1000, "String Value 1000", 5.233]
row2 = [2000, "String Value 2000", -107.04]
data = [row1, row2]
client.insert("new_table", data, column_names=["key", "value", "metric"])

ClickHouse SQL を使用してデータを取得するには、client の query メソッドを使用します。

result = client.query("SELECT max(key), avg(metric) FROM new_table")
print(result.result_rows)
# Output: [(2000, -50.9035)]

client.close()

Experimental の chDB バックエンドでは、HTTP サーバーを介さずに Python プロセス内で ClickHouse クエリを実行します。まず chdb extra をインストールし、interface="chdb" または chdb:// DSN でバックエンドを選択します。

import clickhouse_connect

with clickhouse_connect.get_client(interface="chdb") as client:
    result = client.query("SELECT number FROM numbers(3)")
    print(result.result_rows)
    # Output: [(0,), (1,), (2,)]

デフォルトデータベースはメモリ上にあります。永続ストレージを使用するには、path="/data/my_chdb" を渡すか、dsn="chdb:///data/my_chdb" を使用します。chDB では、プロセスごとに指定できる engine path は 1 つだけです。async クライアントや外部データには対応していません。