> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.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 の経路は引き続き利用可能です。
* このパッケージには PEP 561 の型情報が含まれているため、下流の型チェッカーは、公開ドライバー、DB-API、SQLAlchemy の各インターフェイスに対する annotations を利用できます。
* `clickhouse_connect.cc_sqlalchemy` の [SQLAlchemy](https://www.sqlalchemy.org/) dialect は、SQLAlchemy Core、スキーマ reflection、ClickHouse 固有のクエリ clauses と table engines、そして Alembic の移行をサポートします。基本的な ORM の reads と inserts は動作しますが、この dialect は完全な unit-of-work ORM の振る舞いではなく、分析ワークロード向けに設計されています。
* 中核ドライバーと [ClickHouse Connect SQLAlchemy](/ja/integrations/language-clients/python/sqlalchemy) 実装は、ClickHouse を Apache Superset に接続するための推奨される方法です。`ClickHouse Connect` データベース接続、または `clickhousedb` SQLAlchemy dialect 接続文字列を使用してください。

このドキュメントは clickhouse-connect 1.6.0 時点の内容です。0.15.x 以前からアップグレードする場合は、[1.0 migration guide](https://github.com/ClickHouse/clickhouse-connect/blob/main/MIGRATION.md) を参照してください。

<Note>
  標準の ClickHouse Connect クライアントは HTTPインターフェイス を使用します。これにより、HTTP ロードバランサー、プロキシ、および一般的なエンタープライズ向けネットワーク制御に対応できます。ClickHouse Connect には、実験的なインプロセスの [chDB](#embedded-chdb-backend) バックエンドもあります。
</Note>

<div id="requirements-and-compatibility">
  ## 要件と互換性
</div>

| コンポーネント    | サポート対象バージョン                                                                   |
| ---------- | ----------------------------------------------------------------------------- |
| Python     | 3.10 〜 3.14。3.14t などのフリースレッドビルドは試験的にサポートされています。                               |
| ClickHouse | 現在サポート中の ClickHouse リリース。最近の LTS および stable の server リリースに対して CI テストを実施しています。 |
| SQLAlchemy | 1.4.40 以降、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 以降が必要です。

<div id="installation">
  ## インストール
</div>

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[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 リポジトリ](https://github.com/ClickHouse/clickhouse-connect) を `git clone` します。
* プロジェクトのルートディレクトリに移動し、`pip install .` を実行します。ビルドシステムにより、オプションの C 拡張機能をコンパイルするための Cython が自動的にインストールされます。

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

<div id="support-policy">
  ## サポートポリシー
</div>

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

<div id="basic-usage">
  ## 基本的な使い方
</div>

<div id="gather-your-connection-details">
  ### 接続情報を確認する
</div>

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** をクリックします。

<div className="ch-image-md">
  <Frame>
    <img src="https://mintcdn.com/private-7c7dfe99-trino-dialect/APktBmhebGV1n1ZA/images/_snippets/cloud-connect-button.webp?fit=max&auto=format&n=APktBmhebGV1n1ZA&q=85&s=119293dc89fd9bb8fa178d0bec957ecc" alt="ClickHouse Cloud サービスの接続ボタン" width="998" height="932" data-path="images/_snippets/cloud-connect-button.webp" />
  </Frame>
</div>

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

<div className="ch-image-md">
  <Frame>
    <img src="https://mintcdn.com/private-7c7dfe99-trino-dialect/APktBmhebGV1n1ZA/images/_snippets/connection-details-https.webp?fit=max&auto=format&n=APktBmhebGV1n1ZA&q=85&s=16a5a08d3a2c44601d981b9ee5a75216" alt="ClickHouse Cloud HTTPS 接続情報" width="1320" height="1184" data-path="images/_snippets/connection-details-https.webp" />
  </Frame>
</div>

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

<div id="establish-a-connection">
  ### 接続する
</div>

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

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

<div id="use-a-clickhouse-connect-client-instance-to-connect-to-a-clickhouse-server-on-localhost">
  #### ClickHouse Connect クライアントインスタンスを使用して、localhost 上の ClickHouseサーバーに接続します:
</div>

```python theme={null}
import clickhouse_connect

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

<div id="use-a-clickhouse-connect-client-instance-to-connect-to-a-clickhouse-cloud-service">
  #### ClickHouse Connect クライアントインスタンスを使用して ClickHouse Cloud サービスに接続します。
</div>

<Tip>
  先ほど取得した接続情報を使用します。ClickHouse Cloud サービスでは TLS が必要なため、ポート 8443 を使用してください。
</Tip>

```python theme={null}
import clickhouse_connect

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

<div id="interact-with-your-database">
  ### データベースを操作する
</div>

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

<div id="embedded-chdb-backend">
  ## 埋め込み chDB バックエンド
</div>

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 クライアントや外部データには対応していません。