> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > Python を ClickHouse に接続するための ClickHouse Connect プロジェクトスイート # はじめに 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 の経路は引き続き利用可能です。実験的にオプトインで利用できる [Rust codec](/ja/integrations/language-clients/python/rust-codec) を使うと、Native format の processing を完全に置き換えることができます。 * このパッケージには PEP 561 の型情報が含まれているため、下流の型チェッカーは、公開ドライバー、DB-API、SQLAlchemy の各インターフェイスに対する annotations を利用できます。 * `clickhouse_connect.cc_sqlalchemy` の [SQLAlchemy](https://www.sqlalchemy.org/) ダイアレクトには、同期の `clickhousedb://` 接続と非同期の `clickhousedb+async://` 接続が含まれます。これらは SQLAlchemy Core、スキーマ reflection、ClickHouse 固有のクエリ clauses と table engines、そして Alembic の移行をサポートします。基本的な ORM の reads と inserts は動作しますが、このダイアレクトは完全な unit-of-work ORM の振る舞いではなく、分析ワークロード向けに設計されています。 * 中核ドライバーと [ClickHouse Connect SQLAlchemy](/ja/integrations/language-clients/python/sqlalchemy) 実装は、ClickHouse を Apache Superset に接続するための推奨される方法です。`ClickHouse Connect` データベース接続、または `clickhousedb` SQLAlchemy ダイアレクト接続文字列を使用してください。 0.15.x 以前からアップグレードする場合は、[1.0 migration guide](https://github.com/ClickHouse/clickhouse-connect/blob/main/MIGRATION.md) を参照してください。 標準の ClickHouse Connect クライアントは HTTPインターフェイス を使用します。これにより、HTTP ロードバランサー、プロキシ、および一般的なエンタープライズ向けネットワーク制御に対応できます。ClickHouse Connect には、実験的なインプロセスの [chDB](#embedded-chdb-backend) バックエンドもあります。

要件と互換性

| コンポーネント | サポート対象バージョン | | - | - | | Python | 3.10 〜 3.14。3.14t などのフリースレッドビルドは試験的にサポートされています。 | | ClickHouse | 現在サポート中の ClickHouse リリース。最近の LTS および stable の server リリースに対して CI テストを実施しています。 | | SQLAlchemy | 同期ダイアレクトの場合は 1.4.40 以降、3.0 未満。非同期ダイアレクトの場合は 2.0.44 以降、3.0 未満。 | | Pandas | 2.x および 3.x | | Polars | 1.0 以降 | | aiohttp | 3.9 以降 | | Platforms | 各 Python バージョン向けに公開されている wheel アーキテクチャ上の Linux、macOS、Windows | この package には、利用可能な環境向けのコンパイル済み wheel が含まれており、Cython 拡張機能をビルドできない場合は pure Python 実装にフォールバックします。PyArrow は Python 3.10 〜 3.14 をサポートしています。Python 3.14 では PyArrow 22 以降が必要です。

インストール

pip を使用して、[PyPI](https://pypi.org/project/clickhouse-connect/) から ClickHouse Connect をインストールします。 ```bash theme={null} pip install clickhouse-connect ``` オプションのインテグレーションは、extras を使ってインストールします: ```bash theme={null} 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[sqlalchemy-async]" # Async SQLAlchemy dialect pip install "clickhouse-connect[alembic]" # SQLAlchemy and Alembic pip install "clickhouse-connect[chdb]" # Embedded chDB backend pip install "clickhouse-connect[rust,arrow]" # Experimental Rust codec evaluation setup pip install "clickhouse-connect[tzdata]" # IANA time zones on minimal systems ``` ClickHouse Connect は、ソースコードからインストールすることもできます。 * [GitHub リポジトリ](https://github.com/ClickHouse/clickhouse-connect) を `git clone` します。 * プロジェクトのルートディレクトリに移動し、`pip install .` を実行します。ビルドシステムにより、オプションの C 拡張機能をコンパイルするための Cython が自動的にインストールされます。

ソースビルドモード

ソースビルドは3つのモードをサポートします。デフォルトモードと必須モードでは、Cythonが利用できない場合や `cythonize()` が失敗した場合にビルドが失敗します。スキップモードではCythonをインポートしません。 | モード | コマンド | 動作 | | - | - | - | | デフォルト | `pip install .` | C拡張機能のコンパイルを試みます。コンパイラまたはリンカが失敗した場合、ビルドはpure Pythonインストールにフォールバックします。 | | pure Python | `CLICKHOUSE_CONNECT_SKIP_CYTHON=1 pip install .` | 拡張機能のビルドを試みずにpure Pythonでビルドします。 | | 必須 | `CLICKHOUSE_CONNECT_REQUIRE_C=1 pip install .` | 拡張機能をコンパイルできない場合はビルドを失敗させます。CIや再配布可能なwheelのビルドに推奨されます。 | `CLICKHOUSE_CONNECT_SKIP_CYTHON=1` と `CLICKHOUSE_CONNECT_REQUIRE_C=1` を同時に設定するとエラーになります。 デフォルトのフォールバックwheelにはコンパイル済み拡張機能は含まれませんが、プラットフォームとインタプリタのタグは保持されます。`py3-none-any` を生成するのはスキップモードのみです。`pip` はインデックスのsdistからビルドしたフォールバックwheelをキャッシュすることがあり、コンパイラの問題を解消した後も、互換性のあるPythonとプラットフォームに対してそのwheelを再利用してしまう場合があります。次のコマンドでキャッシュをクリアしてください: ```bash theme={null} pip cache remove clickhouse_connect ``` 3つの拡張機能モジュールがすべて存在するかを確認します。存在する場合は `True` と出力されます: ```bash theme={null} python -c "from importlib.util import find_spec; print(all(find_spec(m) for m in ('clickhouse_connect.driverc.buffer', 'clickhouse_connect.driverc.dataconv', 'clickhouse_connect.driverc.npconv')))" ``` `clickhouse_connect.driverc.npconv` を直接インポートする場合も、NumPy がインストールされている必要があります。 インストールされているバージョンは `clickhouse_connect.__version__` で確認できます。

サポートポリシー

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

基本的な使い方

接続情報を確認する

HTTP(S) で ClickHouse に接続するには、次の情報が必要です。 | Parameter(s) | Description | | - | - | | `HOST` and `PORT` | 通常、TLS を使用する場合のポートは 8443、TLS を使用しない場合は 8123 です。 | | `DATABASE NAME` | デフォルトでは `default` という名前のデータベースがあります。接続先のデータベース名を使用してください。 | | `USERNAME` and `PASSWORD` | デフォルトのユーザー名は `default` です。用途に応じたユーザー名を使用してください。 | ClickHouse Cloud サービスの詳細は、ClickHouse Cloud コンソールで確認できます。 サービスを選択し、**Connect** をクリックします。
ClickHouse Cloud サービスの接続ボタン
**HTTPS** を選択します。接続情報は `curl` コマンドの例として表示されます。
ClickHouse Cloud HTTPS 接続情報
セルフマネージド ClickHouse を使用している場合、接続情報は ClickHouse 管理者によって設定されます。

接続する

ClickHouse に接続する方法として、次の 2 つの例を示します。 * localhost 上の ClickHouse サーバーに接続する。 * ClickHouse Cloud サービスに接続する。

ClickHouse Connect クライアントインスタンスを使用して、localhost 上の ClickHouseサーバーに接続します:

```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client( host="localhost", username="default", password="password", ) ```

ClickHouse Connect クライアントインスタンスを使用して ClickHouse Cloud サービスに接続します。

先ほど取得した接続情報を使用します。ClickHouse Cloud サービスでは TLS が必要なため、ポート 8443 を使用してください。 ```python theme={null} import clickhouse_connect client = clickhouse_connect.get_client( host="HOSTNAME.clickhouse.cloud", port=8443, username="default", password="your password", ) ```

データベースを操作する

ClickHouse SQL コマンドを実行するには、クライアントの `command` メソッドを使用します。 ```python theme={null} client.command( "CREATE TABLE new_table " "(key UInt32, value String, metric Float64) " "ENGINE MergeTree ORDER BY key" ) ``` バッチデータを挿入するには、クライアントの `insert` メソッドを使用し、行と値で構成された二次元配列を渡します。 ```python theme={null} 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` メソッドを使用します。 ```python theme={null} result = client.query("SELECT max(key), avg(metric) FROM new_table") print(result.result_rows) # Output: [(2000, -50.9035)] client.close() ```

埋め込み chDB バックエンド

Experimental の chDB バックエンドでは、HTTP サーバーを介さずに Python プロセス内で ClickHouse クエリを実行します。まず `chdb` extra をインストールし、`interface="chdb"` または `chdb://` DSN でバックエンドを選択します。 ```python theme={null} 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 クライアントや外部データには対応していません。