ClickHouse Connect は、幅広い Python アプリケーションとの相互運用性を提供する中核的なデータベースドライバーです。
- 主なインターフェイスは、
clickhouse_connect.driver パッケージ内の Client オブジェクトです。この中核パッケージには、ClickHouse サーバーとの通信に使用される各種ヘルパークラスやユーティリティ関数に加え、insert クエリや select クエリを高度に管理するための「コンテキスト」実装も含まれています。
clickhouse_connect.datatypes パッケージは、実験的ではないすべての ClickHouse データ型について、基本実装とそのサブクラスを提供します。主な機能は、ClickHouse データを ClickHouse の “Native” バイナリ列指向フォーマットへシリアライゼーションおよびデシリアライゼーションすることで、ClickHouse とクライアントアプリケーション間の転送を最も効率的に行えるようにすることです。clickhouse_connect.cdriver パッケージ内の Cython/C クラスは、pure Python と比べて大幅に高い性能が得られるよう、最も一般的なシリアライゼーションとデシリアライゼーションの一部を最適化しています。clickhouse_connect.cc_sqlalchemy パッケージには SQLAlchemy dialect があり、datatypes および dbi パッケージをベースに構築されています。この実装は、JOIN を含む SELECT クエリ (INNER、LEFT OUTER、FULL OUTER、CROSS) 、WHERE 句、ORDER BY、LIMIT/OFFSET、DISTINCT 操作、WHERE 条件付きの論理削除ステートメント、テーブルリフレクション、および基本的な DDL 操作 (CREATE TABLE、CREATE/DROP DATABASE) を含む SQLAlchemy Core の機能をサポートします。高度な ORM 機能や高度な DDL 機能には対応していませんが、ClickHouse の OLAP 指向データベースに対する、ほとんどの分析ワークロードに適した堅牢なクエリ機能を提供します。- 中核ドライバーと ClickHouse Connect SQLAlchemy 実装は、ClickHouse を Apache Superset に接続するための推奨方法です。
ClickHouse Connect データベース接続、または clickhousedb SQLAlchemy dialect 接続文字列を使用してください。
このドキュメントは、clickhouse-connect release 0.9.2 時点の内容です。
公式の ClickHouse Connect Python ドライバーは、ClickHouse サーバーとの通信に HTTP プロトコルを使用します。これにより HTTP ロードバランサーを利用でき、ファイアウォールやプロキシのあるエンタープライズ環境でも適切に動作しますが、native TCP ベースのプロトコルと比べると圧縮率と性能はやや低く、クエリのキャンセルのような一部の高度な機能には対応していません。用途によっては、native TCP ベースのプロトコルを使用する Community Python drivers のいずれかを検討してもよいでしょう。 | Python | | プラットフォーム¹ | | ClickHouse | | SQLAlchemy² | | Apache Superset | | Pandas | | Polars | |
|---|
| 2.x, <3.9 | ❌ | Linux (x86) | ✅ | <25.x³ | 🟡 | <1.4.40 | ❌ | <1.4 | ❌ | ≥1.5 | ✅ | 1.x | ✅ |
| 3.9.x | ✅ | Linux (Aarch64) | ✅ | 25.x³ | 🟡 | ≥1.4.40 | ✅ | 1.4.x | ✅ | 2.x | ✅ | | |
| 3.10.x | ✅ | macOS (x86) | ✅ | 25.3.x (LTS) | ✅ | ≥2.x | ✅ | 1.5.x | ✅ | | | | |
| 3.11.x | ✅ | macOS (ARM) | ✅ | 25.6.x (安定版) | ✅ | | | 2.0.x | ✅ | | | | |
| 3.12.x | ✅ | Windows | ✅ | 25.7.x (安定版) | ✅ | | | 2.1.x | ✅ | | | | |
| 3.13.x | ✅ | | | 25.8.x (LTS) | ✅ | | | 3.0.x | ✅ | | | | |
| | | | 25.9.x (安定版) | ✅ | | | | | | | | |
cibuildwheel プロジェクトでサポートされているすべてのアーキテクチャ向けに、未検証のバイナリホイール (C 最適化あり) もビルドされています。加えて、ClickHouse Connect は pure Python としても動作するため、ソースからのインストールであれば最近の Python 環境なら動作するはずです。
²SQLAlchemy のサポートは Core 機能 (クエリ、基本的な DDL) に限定されます。ORM 機能はサポートされていません。詳しくは SQLAlchemy インテグレーションサポート のドキュメントを参照してください。
³ClickHouse Connect は、公式なサポート対象外のバージョンでも通常は問題なく動作します。
ClickHouse Connect は、pip を使用して PyPI からインストールできます。
pip install clickhouse-connect
ClickHouse Connect は、ソースからインストールすることもできます。
- GitHub リポジトリ を
git clone します。
- (任意) C/Cython の最適化をビルドして有効にするには、
pip install cython を実行します
- プロジェクトのルートディレクトリに移動して、
pip install . を実行します
問題を報告する前に、ClickHouse Connect を最新バージョンにアップデートしてください。問題は GitHub project に報告してください。今後の ClickHouse Connect のリリースは、リリース時点で現在サポート対象となっている ClickHouse のバージョンとの互換性を持つよう設計されています。現在サポート対象の ClickHouse サーバー のバージョンは こちら で確認できます。どのバージョンの ClickHouse サーバー を使うべきか迷った場合は、こちら の解説を参照してください。CI のテストマトリクスでは、最新の 2 つの LTS リリースと最新の 3 つの stable リリースを対象にテストを実施しています。ただし、HTTP プロトコルを使用していること、および ClickHouse の各リリース間で破壊的変更が最小限であることから、ClickHouse Connect は一般に公式サポート範囲外の server バージョンでも問題なく動作します。ただし、一部の高度なデータ型では互換性が異なる場合があります。
HTTP(S) で ClickHouse に接続するには、次の情報が必要です。
| Parameter(s) | Description |
|---|
HOST and PORT | 通常、TLS を使用する場合のポートは 8443、TLS を使用しない場合は 8123 です。 |
DATABASE NAME | デフォルトでは default という名前のデータベースがあります。接続先のデータベース名を使用してください。 |
USERNAME and PASSWORD | デフォルトのユーザー名は default です。用途に応じたユーザー名を使用してください。 |
curl コマンドの例として表示されます。
セルフマネージド ClickHouse を使用している場合、接続情報は ClickHouse 管理者によって設定されます。
ClickHouse に接続する方法として、次の 2 つの例を示します。
- localhost 上の ClickHouse サーバーに接続する。
- ClickHouse Cloud サービスに接続する。
ClickHouse Connect クライアントのインスタンスを使用して、localhost 上の ClickHouseサーバーに接続します:
import clickhouse_connect
client = clickhouse_connect.get_client(host='localhost', username='default', password='password')
ClickHouse Connect クライアントインスタンスを使用して ClickHouse Cloud サービスに接続します。
先ほど取得した接続情報を使用します。ClickHouse Cloud サービスでは TLS が必要なため、ポート 8443 を使用してください。
import clickhouse_connect
client = clickhouse_connect.get_client(host='HOSTNAME.clickhouse.cloud', port=8443, username='default', password='your password')
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'])
query メソッドを使用します。
result = client.query('SELECT max(key), avg(metric) FROM new_table')
print(result.result_rows)
# 出力: [(2000, -50.9035)]
