はじめに
- 主なインターフェイスは、
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データベース接続、またはclickhousedbSQLAlchemy dialect 接続文字列を使用してください。
公式の ClickHouse Connect Python ドライバーは、ClickHouse サーバーとの通信に HTTP プロトコルを使用します。これにより HTTP ロードバランサーを利用でき、ファイアウォールやプロキシのあるエンタープライズ環境でも適切に動作しますが、native TCP ベースのプロトコルと比べると圧縮率と性能はやや低く、クエリのキャンセルのような一部の高度な機能には対応していません。用途によっては、native TCP ベースのプロトコルを使用する Community Python drivers のいずれかを検討してもよいでしょう。
要件と互換性
¹ClickHouse Connect は、一覧に記載されたプラットフォームで明示的にテストされています。さらに、優れた
cibuildwheel プロジェクトでサポートされているすべてのアーキテクチャ向けに、未検証のバイナリホイール (C 最適化あり) もビルドされています。加えて、ClickHouse Connect は pure Python としても動作するため、ソースからのインストールであれば最近の Python 環境なら動作するはずです。
²SQLAlchemy のサポートは Core 機能 (クエリ、基本的な DDL) に限定されます。ORM 機能はサポートされていません。詳しくは SQLAlchemy インテグレーションサポート のドキュメントを参照してください。
³ClickHouse Connect は、公式なサポート対象外のバージョンでも通常は問題なく動作します。
インストール
pip install clickhouse-connect
ClickHouse Connect は、ソースからインストールすることもできます。
- GitHub リポジトリ を
git cloneします。 - (任意) C/Cython の最適化をビルドして有効にするには、
pip install cythonを実行します - プロジェクトのルートディレクトリに移動して、
pip install .を実行します
サポートポリシー
基本的な使い方
接続情報を確認する
ClickHouse Cloud サービスの詳細は、ClickHouse Cloud コンソールで確認できます。
サービスを選択し、Connect をクリックします。
HTTPS を選択します。接続情報は
curl コマンドの例として表示されます。
セルフマネージド ClickHouse を使用している場合、接続情報は ClickHouse 管理者によって設定されます。
接続する
- localhost 上の ClickHouse サーバーに接続する。
- ClickHouse Cloud サービスに接続する。
ClickHouse Connect クライアントのインスタンスを使用して、localhost 上の ClickHouseサーバーに接続します:
ClickHouse Connect クライアントインスタンスを使用して ClickHouse Cloud サービスに接続します。
データベースを操作する
command メソッドを使用します。
insert メソッドを使用します：
query メソッドを使用します。