ClickHouse Connect ドライバー API - ClickHouse Documentation

任意パラメータが多いクライアントファクトリーやメソッドでは、引数をキーワードで渡してください。ここに記載していないメソッドは API の一部とは見なされず、削除または変更される可能性があります。

クライアントの初期化

同期 Client を作成するには clickhouse_connect.get_client を使用します。ネイティブの AsyncClient を作成するには、async エクストラをインストールし、clickhouse_connect.get_async_client を await します。

接続引数

パラメータ	型	デフォルト	説明
`interface`	str	`"http"`	`"http"` または `"https"`。同期ファクトリでは、Experimental の `"chdb"` バックエンドも使用できます。
`host`	str	`"localhost"`	ClickHouseサーバーのホスト名またはIPアドレス。
`port`	int または None	`8123` または `8443`	HTTP では 8123、HTTPS では 8443 がデフォルトです。`None` を渡すとデフォルトが使用されます。
`username`	str または None	`"default"`	ClickHouseのユーザー名。`user` と `user_name` という別名も使用できます。
`password`	str	`""`	`username` のパスワード。ユーザー名/パスワード認証とトークン認証は併用しないでください。
`access_token`	str または None	`None`	ClickHouse Cloud の JWT アクセストークン。`token_provider` およびユーザー名/パスワード認証とは併用できません。
`token_provider`	callable または None	`None`	最初の JWT と、認証が拒否された後の JWT を提供する callable。`get_async_client` では async provider を使用できます。
`database`	str または None	ユーザーの既定値	デフォルトデータベース。`None` を渡すと、そのユーザーのサーバー既定値が使用されます。
`secure`	bool または str	`False`	HTTPS/TLS を有効にします。`interface="https"` を指定した場合も HTTPS が選択され、`interface` が設定されていない場合はポート 443 または 8443 でも HTTPS が選択されます。
`dsn`	str または None	`None`	接続 URL。明示的なキーワード引数は、DSN から解析された値よりも優先されます。認証情報およびデータベース名に含まれる予約文字は、パーセントエンコードしてください。
`settings`	dict または None	`None`	クライアントが行うすべてのリクエストに適用される ClickHouse の設定。
`headers`	dict または None	`None`	クライアントの初期化時を含む、すべてのリクエストに適用される HTTP ヘッダーです。ユーザーのヘッダーはドライバーのデフォルト設定の後に適用され、これらを上書きできます。
`compress`	bool または str	`True`	圧縮を有効にするか、`"lz4"`、`"zstd"`、`"br"`、または`"gzip"`を選択します。詳しくは圧縮を参照してください。
`query_limit`	int	`0`	対象のクエリに追加されるデフォルトの行数制限です。0 は無制限を意味します。大きな結果は、すべてをメモリにマテリアライズするのではなく、ストリームで処理してください。
`query_retries`	int	`2`	再試行可能な読み取り失敗に対する再試行回数の上限です。コマンドやインサートは、再実行によって副作用が重複する可能性があるため、通常は再試行されません。
`connect_timeout`	int	`10`	接続タイムアウト (秒) 。
`send_receive_timeout`	int	`300`	ソケットの読み取りタイムアウト (秒) 。
`client_name`	str or None	`None`	`system.query_log` での識別用に HTTP ユーザーエージェントに追加されるプレフィックス。
`session_id`	str または None	同期時に生成	明示的に指定する ClickHouse のセッション ID。同期 client ではデフォルトで生成されますが、async client では生成されません。
`autogenerate_session_id`	bool または None	同期の場合はグローバル設定、非同期の場合は `False`	セッション ID の自動生成を上書きします。セッション状態が必要な場合を除き、同時実行の操作で共有される client では無効にしてください。
`autogenerate_query_id`	bool または None	グローバル設定、`True`	UUID のクエリ ID の自動生成を上書きします。
`http_proxy`	str または None	環境変数/デフォルト	クライアントごとの HTTP プロキシアドレス。
`https_proxy`	str または None	環境変数/デフォルト	クライアントごとの HTTPS プロキシのアドレス。
`pool_mgr`	`urllib3.PoolManager` または None	共有の既定値	同期クライアントでのみ使用するカスタムのプールマネージャー。
`tz_source`	str or None	`"auto"`	タイムゾーンのメタデータがないカラムに使用するフォールバックのタイムゾーンソース: `"auto"`、`"server"`、または `"local"`。
`tz_mode`	str or None	`"naive_utc"`	UTC の結果ポリシー: `"naive_utc"`、`"aware"`、または `"schema"`。詳細はタイムゾーンを参照してください。
`show_clickhouse_errors`	bool、ブール値を表す文字列、`"scrub"`、または None	`True`	サーバーエラー、トランスポートエラー、およびストリーム途中で発生する `StreamFailureError` における `str(exc)` の内容を制御します。`True` にはリクエスト URL とサーバーバージョン情報が含まれます。`"scrub"` は SQL エラーテキストとシンボリック名を保持しますが、ホスト/URL と `(version ...)` の情報を削除します。`False` は汎用的なメッセージを返します (サーバーエラーでは `code` は引き続き設定されます) 。ブール値を表す文字列も受け入れられます。その他の文字列では `ProgrammingError` が発生します。トランスポートエラーの場合、`__cause__` とトレースバックには引き続き元のトランスポート例外が含まれます。
`proxy_path`	str	`""`	プロキシ経由でルーティングする際にサーバーURLに追加されるパスプレフィックス。
`form_encode_query_params`	bool	`False`	クエリパラメータは常にフォームエンコードされたリクエストボディに配置されます。これが false の場合でも、大きな非バイナリのパラメータペイロードは自動的に移動されます。
`rename_response_column`	str または None	`None`	カラム名の変更戦略: `"remove_prefix"`, `"to_camelcase"`, `"to_camelcase_without_prefix"`, `"to_underscore"`, または `"to_underscore_without_prefix"`。

非同期ファクトリでは、aiohttp の接続プールを設定するために、connector_limit=100、connector_limit_per_host=20、keepalive_timeout=30.0 も指定できます。pool_mgr は指定できません。同期 chDB バックエンドでは path と chdb_options を指定できます。詳しくは埋め込み chDB バックエンドを参照してください。

HTTPS/TLS 引数

Parameter	Type	Default	Description
`verify`	bool or str	`True`	サーバー証明書とホスト名を検証します。`verify="proxy"` を指定すると、プロキシ TLS モードが有効になります。
`ca_cert`	str or None	`None`	CA バンドルのパス。`certifi` パッケージに同梱されているバンドルを選択するには、`"certifi"` を使用します。
`client_cert`	str or None	`None`	PEM 形式のクライアント証明書。必要に応じて中間証明書も含めます。
`client_cert_key`	str or None	`None`	秘密鍵が `client_cert` に含まれていない場合の秘密鍵のパス。
`server_host_name`	str or None	`None`	トンネルやプライベートエンドポイント経由などで `host` と異なる場合に使用する、TLS 証明書/SNI のホスト名。
`tls_mode`	str or None	`None`	`"mutual"` は ClickHouse の mutual TLS 認証を使用します。`"proxy"` と `"strict"` は、ClickHouse の証明書認証ヘッダーを有効にせず、TLS レイヤーで証明書を送信します。既定の `None` は、クライアント証明書が指定されている場合は `"mutual"` として動作します。

settings 引数

最後に、get_client の settings 引数は、各クライアントリクエストで追加の ClickHouse設定をサーバーに渡すために使用します。なお、ほとんどの場合、readonly=1 アクセスのユーザーはクエリとともに送信される設定を変更できないため、ClickHouse Connect はそのような設定を最終リクエストから除外し、警告をログに記録します。以下の設定は、ClickHouse Connect で使用される HTTP クエリ/セッションにのみ適用されるもので、一般的な ClickHouse設定としては文書化されていません。

Setting	Description
`buffer_size`	サーバー側 HTTP レスポンスのバッファサイズ (バイト単位)。
`session_id`	関連するリクエストを関連付けるために使用するセッション ID。一時テーブルとセッション状態に必要です。
`compress`	HTTP レスポンスを圧縮するようサーバーに要求します。通常はクライアントの圧縮オプションによって管理されます。
`decompress`	リクエストボディを展開するようサーバーに指示します。事前に圧縮された raw insert に使用します。
`quota_key`	リクエストに関連付けられた quota key。
`session_check`	セッションが存在することを検証するようサーバーに要求します。
`session_timeout`	セッションが非アクティブなまま timeout するまでの時間 (秒単位)。
`wait_end_of_query`	サーバー上でレスポンス全体をバッファリングします。クライアントは、非ストリーミングのサマリー情報で必要な場合にこれを設定します。
`query_id`	リクエストの明示的なクエリ ID。
`client_protocol_version`	ネイティブフォーマットのクライアントプロトコルの対応レベル。通常は自動的にネゴシエートされます。
`role`	リクエスト/セッションで使用する ClickHouse ロール。

各クエリとともに送信できるその他の ClickHouse設定については、ClickHouse ドキュメントを参照してください。

クライアント作成の例

パラメータを指定しない場合、ClickHouse Connect クライアントは localhost のデフォルトの HTTP ポートに、デフォルトユーザー default、パスワードなしで接続します:

import clickhouse_connect

client = clickhouse_connect.get_client()
print(client.server_version)

セキュアな (HTTPS) 外部 ClickHouse サーバーへの接続

import clickhouse_connect

client = clickhouse_connect.get_client(
    host="play.clickhouse.com",
    secure=True,
    port=443,
    username="play",
    password="clickhouse",
)
print(client.command("SELECT timezone()"))

セッション ID、その他のカスタム接続パラメータ、および ClickHouse 設定を使用した接続。

import clickhouse_connect

client = clickhouse_connect.get_client(
    host="play.clickhouse.com",
    username="play",
    password="clickhouse",
    port=443,
    secure=True,
    session_id="example_session_1",
    connect_timeout=15,
    database="github",
    settings={"distributed_ddl_task_timeout": 300},
)
print(client.database)
# Output: github

埋め込み chDB バックエンド

実験的なインプロセス chDB バックエンドを使用するには、clickhouse-connect[chdb] をインストールします。これにより、同期クライアントのクエリ、insert、streaming、Arrow の各メソッドを利用できます。

import clickhouse_connect

with clickhouse_connect.get_client(interface="chdb") as client:
    result = client.query("SELECT sum(number) FROM numbers(10)")
    print(result.first_row)
    # Output: (45,)

デフォルトはインメモリデータベースです。永続ストレージを使用するには、path="/data/my_chdb" を渡すか、dsn="chdb:///data/my_chdb" を使用します。バックエンドでは、プロセスごとに指定できる engine の path は 1 つだけで、get_async_client や external data には対応していません。

クライアントのライフサイクルとベストプラクティス

ClickHouse Connect クライアントの作成は、connection の確立、server メタデータの取得、設定の初期化を伴うため、負荷の高い処理です。最適なパフォーマンスを得るため、以下のベストプラクティスに従ってください。

基本原則

クライアントを再利用する: クライアントはアプリケーションの起動時に一度だけ作成し、その後はアプリケーションのライフサイクル全体を通して再利用します
頻繁な作成を避ける: クエリやリクエストのたびに新しいクライアントを作成しないでください
適切にクリーンアップする: シャットダウン時には、接続プールのリソースを解放するため、必ずクライアントを閉じてください
可能なら共有する: 1 つのクライアントで、接続プールを通じて多数の同時実行クエリを処理できます (詳しくは下記のスレッドに関する注記を参照してください)

基本パターン

単一のクライアントを使い回す:

import clickhouse_connect

# Create once at startup
client = clickhouse_connect.get_client(
    host="my-host",
    username="default",
    password="password",
)

# Reuse for all queries
for i in range(1000):
    result = client.query("SELECT count() FROM users")

# Close on shutdown
client.close()

クライアントを何度も作成するのは避けてください:

# BAD: Creates 1000 clients with expensive initialization overhead
for i in range(1000):
    client = clickhouse_connect.get_client(
        host="my-host",
        username="default",
        password="password",
    )
    result = client.query("SELECT count() FROM users")
    client.close()

マルチスレッドアプリケーション

セッションIDを使用する場合、クライアントインスタンスはスレッドセーフではありません。クライアントにはデフォルトで自動生成されたセッションIDが割り当てられており、同じセッション内でクエリを同時実行すると ProgrammingError が発生します。

クライアントを複数のスレッド間で安全に共有するには、次のようにします。

import clickhouse_connect
import threading

# Option 1: Disable sessions (recommended for shared clients)
client = clickhouse_connect.get_client(
    host="my-host",
    username="default",
    password="password",
    autogenerate_session_id=False,
)

def worker(thread_id):
    # All threads can now safely use the same client
    result = client.query(f"SELECT {thread_id}")
    print(f"Thread {thread_id}: {result.result_rows[0][0]}")

threads = [threading.Thread(target=worker, args=(i,)) for i in range(10)]
for t in threads:
    t.start()
for t in threads:
    t.join()

client.close()

セッションの代替手段: セッション (例: 一時テーブルの利用) が必要な場合は、スレッドごとに別のクライアントを作成してください。

def worker(thread_id):
    # Each thread gets its own client with isolated session
    client = clickhouse_connect.get_client(
        host="my-host",
        username="default",
        password="password",
    )
    client.command("CREATE TEMPORARY TABLE temp (id UInt32) ENGINE = Memory")
    # ... use temp table ...
    client.close()

適切なクリーンアップ

シャットダウン時には、必ずクライアントを閉じてください。client.close() は、クライアントが自身のプールマネージャーを所有している場合にのみ (たとえば、カスタムの TLS/プロキシオプションを指定して作成された場合) 、クライアントを破棄し、プールされた HTTP 接続を閉じます。デフォルトの共有プールを使用している場合は、ソケットを明示的に解放するために client.close_connections() を使用してください。そうしない場合、接続はアイドル期限切れ時およびプロセス終了時に自動的に回収されます。

client = clickhouse_connect.get_client(
    host="my-host",
    username="default",
    password="password",
)
try:
    result = client.query("SELECT 1")
finally:
    client.close()

または、コンテキストマネージャーを使用します:

with clickhouse_connect.get_client(
    host="my-host",
    username="default",
    password="password",
) as client:
    result = client.query("SELECT 1")

複数のクライアントを使用する場面

複数のクライアントが適しているのは、次のような場合です。

異なるサーバー: ClickHouse サーバーまたはクラスターごとに 1 つのクライアントを使用する
異なる認証情報: ユーザーやアクセスレベルごとにクライアントを分ける
異なるデータベース: 複数のデータベースを扱う必要がある場合
分離されたセッション: 一時テーブルやセッション固有の設定のために、別々のセッションが必要な場合
スレッドごとの分離: スレッドごとに独立したセッションが必要な場合 (前述のとおり)

共通のメソッド引数

複数のクライアントメソッドでは、共通の parameters 引数または settings 引数、あるいはその両方を使用します。これらのキーワード引数については以下で説明します。

Parameters 引数

ClickHouse Connect クライアントの query* メソッドと command メソッドでは、Python の式を ClickHouse の値式にバインドするための、省略可能な parameters キーワード引数を指定できます。バインドには 2 種類あります。

サーバーサイドバインディング

ClickHouse は、クエリの値に対するサーバーサイドバインディングをサポートしています。バインドする値は、クエリとは別に HTTP パラメータとして送信されます。ClickHouse Connect は、{<name>:<datatype>} 形式の式を検出すると、このモードを使用します。値は Python の辞書として渡します。 null 許容値には Python の None を使用します。ネストされた None 値は、Array および Tuple パラメータ内、ならびに dict_parameter_format が "map" に設定されている場合は Map リテラル内でサポートされます。

Python の辞書、DateTime 値、文字列値を使用したサーバーサイドバインディング

import datetime

my_date = datetime.datetime(2022, 10, 1, 15, 20, 5)

parameters = {
    "table": "my_table",
    "v1": my_date,
    "v2": "a string with a single quote'",
}
client.query(
    "SELECT * FROM {table:Identifier} "
    "WHERE date >= {v1:DateTime} AND string ILIKE {v2:String}",
    parameters=parameters,
)

これは以下と同等です:

SELECT *
FROM my_table
WHERE date >= '2022-10-01 15:20:05'
  AND string ILIKE 'a string with a single quote\''

サーバーサイドバインディングは SELECT クエリでサポートされています。ALTER、DELETE、INSERT、その他の種類のステートメントでは使用できません。

クライアントサイドバインディング

ClickHouse Connect はクライアントサイドのパラメータバインディングにも対応しており、テンプレート化された SQL クエリをより柔軟に生成できます。クライアントサイドバインディングでは、parameters 引数には辞書またはシーケンスを指定する必要があります。クライアントサイドバインディングでは、パラメータの置換に Python の “printf” スタイルの文字列フォーマットを使用します。サーバーサイドバインディングとは異なり、クライアントサイドバインディングは、データベース、テーブル、カラム名などのデータベース識別子には使用できない点に注意してください。Python スタイルのフォーマットでは文字列の種類の違いを区別できず、それぞれ異なる形式でフォーマットする必要があるためです (データベース識別子にはバッククォートまたは二重引用符、データ値には単一引用符を使用します) 。

Python の Dictionary、DateTime 値、文字列のエスケープを使用した Example

import datetime

my_date = datetime.datetime(2022, 10, 1, 15, 20, 5)

parameters = {"v1": my_date, "v2": "a string with a single quote'"}
client.query(
    "SELECT * FROM my_table "
    "WHERE date >= %(v1)s AND string ILIKE %(v2)s",
    parameters=parameters,
)

これにより、サーバーでは次のクエリが生成されます。

SELECT *
FROM my_table
WHERE date >= '2022-10-01 15:20:05'
  AND string ILIKE 'a string with a single quote\''

PythonのSequence (Tuple) 、Float64、IPv4Addressを使用した例

import ipaddress

parameters = (35200.44, ipaddress.IPv4Address(0x443d04fe))
client.query(
    "SELECT * FROM some_table WHERE metric >= %s AND ip_address = %s",
    parameters=parameters,
)

これにより、サーバーでは次のクエリが生成されます。

SELECT *
FROM some_table
WHERE metric >= 35200.44
  AND ip_address = '68.61.4.254'

Datetime バインディングでは、naive 値を wall time として扱います。クライアントは naive datetime をそのままフォーマットします。ClickHouse は、まず {dt:DateTime('Europe/Berlin')} のようなサーバーサイドプレースホルダーで宣言されたタイムゾーン、次に設定されている場合は session_timezone、最後にサーバーのタイムゾーンを使用して解釈します。タイムゾーン対応の datetime は、プレースホルダーにタイムゾーンが指定されている場合はそのタイムゾーンに変換され、指定されていない場合は接続時に報告されたサーバーのタイムゾーンに変換されます。session_timezone 設定が報告されたサーバーのタイムゾーンと異なる場合は、タイムゾーン対応の値で意図した時点を維持するために、プレースホルダーでタイムゾーンを宣言してください。以前のホストローカル変換との一時的な互換性を確保するには、パラメータをバインドする前に common.set_setting("naive_datetime_binding", "legacy") を設定します。時点を保持するには、datetime 値をパラメータとして渡す前に、意図した tzinfo を付加してください。client.insert を介した挿入では、naive datetime 値はデフォルトでプロセスのローカルタイムゾーンで解釈されます。グローバルの naive_datetime_insert 設定を "server" にすると、カラムのタイムゾーンで wall time として解釈され、カラムにタイムゾーンがない場合はサーバーのタイムゾーンで解釈されます。Timezone-naive datetime objects を参照してください。サーバーサイドの {value:DateTime64(precision)} プレースホルダーでは、宣言された型によって、Array や Tuple のヒント内であっても秒未満の精度が自動的に保持されます。クライアントサイドの %s バインディングには宣言された型がありません。秒未満の精度で出力する必要がある場合は、datetime を DT64Param でラップしてください。

from datetime import datetime

from clickhouse_connect.driver.binding import DT64Param

query = "SELECT toDateTime64(%s, 6)"
parameters = [DT64Param(datetime.now())]
client.query(query, parameters=parameters)

後方互換性のため、辞書パラメータ名が _64 で終わっている場合も、クエリ内にその接尾辞付きの完全一致の名前が存在しなければ、DateTime64 フォーマットが要求されます。datetime.time または datetime.timedelta パラメータは、両方のバインディングスタイルおよび Array と Tuple の値内で、ClickHouse の Time および Time64 カラム用に [-]HH:MM:SS[.ffffff] リテラルとしてフォーマットされます。クライアントが引用符を追加するため、クエリ内でプレースホルダーを引用符で囲まないでください。timedelta は負の値にすることができ、24 時間を超えることもできます。pandas の Timedelta はナノ秒を保持し、Time64(9) では 9 桁の小数部としてフォーマットされます。タイムゾーン対応の time のタイムゾーン情報は、ClickHouse の Time にはタイムゾーンがないため無視されます。

Settings 引数

主要な ClickHouse Connect Client の “insert” メソッドと “select” メソッドはすべて、含まれる SQL ステートメントに対して ClickHouse サーバーのユーザー設定を渡すための、省略可能な settings キーワード引数を受け付けます。settings 引数には辞書を指定する必要があります。各項目は、ClickHouse の設定名とそれに対応する値で構成されます。なお、値はサーバーにクエリパラメータとして送信される際に文字列に変換されます。クライアントレベルの settings と同様に、ClickHouse Connect は、サーバーが readonly=1 としてマークした settings を、対応するログメッセージを出力したうえで除外します。ClickHouse HTTP インターフェイス経由のクエリにのみ適用される settings は常に有効です。これらの settings については、get_client API で説明しています。 ClickHouse settings の使用例:

settings = {
    "merge_tree_min_rows_for_concurrent_read": 65535,
    "session_id": "session_1234",
    "use_skip_indexes": False,
}
client.query(
    "SELECT event_type, sum(timeout) "
    "FROM event_errors WHERE event_time > '2022-08-01'",
    settings=settings,
)

クライアント `command` メソッド

Client.command は、表形式のデータセットを返さない文や、単一のプリミティブ値または 1 行を返すクエリに使用します。レスポンスに応じて、文字列、整数、文字列のシーケンス、または QuerySummary を返します。空の結果セットを返す読み取りでは、空文字列が返されます。

Parameter	Type	Default	Description
cmd	str	Required	単一の値、または値を 1 行だけ返す ClickHouse SQL 文。
parameters	dict or sequence	None	parameters の説明を参照してください。
data	str or bytes	None	コマンドとともに POST ボディに含める省略可能なデータです。
settings	dict	None	settings の説明を参照してください。
use_database	bool	True	クライアントのデータベース (クライアント作成時に指定) を使用します。False の場合、コマンドは接続中のユーザーのデフォルトの ClickHouse サーバーのデータベースを使用します。
external_data	ExternalData	None	クエリで使用するファイルまたは実行可能バイナリデータを含む `ExternalData` オブジェクトです。高度なクエリ (External Data)を参照してください。
transport_settings	dict	None	このリクエストに含める省略可能な HTTPヘッダーの辞書です。各キー・バリューの組は HTTPヘッダーとして追加されます (例: `{'X-Custom-Header': 'value'}`) 。プロキシ認証、リクエストのトレーシング、または中間インフラストラクチャで必要なヘッダーの受け渡しに役立ちます。

コマンドの例

DDL文

import clickhouse_connect

client = clickhouse_connect.get_client()

# Create a table. A successful DDL returns QuerySummary.
summary = client.command(
    "CREATE TABLE test_command "
    "(col_1 String, col_2 DateTime) "
    "ENGINE MergeTree ORDER BY tuple()"
)
print(summary.query_id())

# Show table definition
result = client.command("SHOW CREATE TABLE test_command")
print(result)
# Output:
# CREATE TABLE default.test_command
# (
#     `col_1` String,
#     `col_2` DateTime
# )
# ENGINE = MergeTree
# ORDER BY tuple()

# Drop table
client.command("DROP TABLE test_command")

単一の値を返すシンプルなクエリ

import clickhouse_connect

client = clickhouse_connect.get_client()

# Single value result
count = client.command("SELECT count() FROM system.tables")
print(count)

# Server version
version = client.command("SELECT version()")
print(version)

パラメータを指定するコマンド

import clickhouse_connect

client = clickhouse_connect.get_client()

# クライアント側パラメータを使用する場合
table_name = "system"
result = client.command(
    "SELECT count() FROM system.tables WHERE database = %(db)s",
    parameters={"db": table_name}
)

# サーバー側パラメータを使用する場合
result = client.command(
    "SELECT count() FROM system.tables WHERE database = {db:String}",
    parameters={"db": "system"}
)

設定付きのコマンド

import clickhouse_connect

client = clickhouse_connect.get_client()

# 特定の設定でコマンドを実行する
result = client.command(
    "OPTIMIZE TABLE large_table FINAL",
    settings={"optimize_throw_if_noop": 1}
)

Client `query` メソッド

Client.query は、ClickHouse Native フォーマットの表形式データセットを取得し、QueryResult を返します。結果全体は、結果のプロパティにアクセスした時点で実体化されます。メモリに保持したくない結果には、ストリーミングメソッドを使用してください。

パラメータ	型	デフォルト	説明
`query`	str	必須	表形式の結果を返す ClickHouse クエリです。通常は `SELECT` または `DESCRIBE` です。`context` で指定する場合は省略できます。
`parameters`	dict or sequence	`None`	Parameters 引数を参照してください。
`settings`	dict	`None`	Settings 引数を参照してください。
`query_formats`	dict	`None`	ClickHouse 型ごとの読み取りフォーマットです。Read formatsを参照してください。
`column_formats`	dict	`None`	結果カラムごとの読み取りフォーマットです。Nested 型のフォーマットマッピングも含まれます。
`encoding`	str	`None`	String 型のカラムのエンコーディングです。デフォルトは UTF-8 です。
`use_none`	bool	`True`	SQL の NULL に対して `None` を返します。false の場合は、その型のデフォルトの NULL 値を返します。NumPy/Pandas のメソッドでは、パフォーマンス重視のデフォルトが選択されます。
`column_oriented`	bool	`False`	結果を行ではなくカラム指向で扱います。
`use_numpy`	bool	`False`	互換性のある結果カラムを、`QueryResult` 内の NumPy 配列として読み込みます。必要な結果が 1 つの NumPy 行列である場合は、`query_np` の使用を推奨します。
`max_str_len`	int	`0`	`use_numpy` 使用時、この長さまでの String 型のカラムには固定幅の Unicode dtype を使用します。0 の場合はオブジェクト配列を使用します。
`context`	`QueryContext`	`None`	再利用可能なクエリコンテキストです。明示的に指定したメソッド引数は、context の値より優先されます。
`query_tz`	str or `tzinfo`	`None`	すべての `DateTime` および `DateTime64` の結果カラムに適用されるタイムゾーンです。
`column_tzs`	dict	`None`	カラムごとのタイムゾーンマッピングです。
`external_data`	`ExternalData`	`None`	外部ファイルまたはバイナリデータです。External dataを参照してください。
`transport_settings`	dict	`None`	このリクエストに追加される HTTP ヘッダーです。
`tz_mode`	str	Client default	`"naive_utc"`、`"aware"`、または `"schema"` のタイムゾーン処理をクエリ単位で上書きします。

クエリ例

基本的なクエリ

import clickhouse_connect

client = clickhouse_connect.get_client()

# Simple SELECT query
result = client.query(
    "SELECT number, toString(number) AS label FROM numbers(3)"
)

# Access results as rows
for row in result.result_rows:
    print(row)
# Output:
# (0, '0')
# (1, '1')
# (2, '2')

# Access column names and types
print(result.column_names)
# Output: ('number', 'label')
print([col_type.name for col_type in result.column_types])
# Output: ['UInt64', 'String']

クエリ結果へのアクセス

import clickhouse_connect

client = clickhouse_connect.get_client()

result = client.query("SELECT number, toString(number) AS str FROM system.numbers LIMIT 3")

# Row-oriented access (default)
print(result.result_rows)
# Output: [(0, '0'), (1, '1'), (2, '2')]

# Column-oriented access
print(result.result_columns)
# Output: [[0, 1, 2], ['0', '1', '2']]

# Named results (list of dictionaries)
for row_dict in result.named_results():
    print(row_dict)
# Output:
# {'number': 0, 'str': '0'}
# {'number': 1, 'str': '1'}
# {'number': 2, 'str': '2'}

# First row as dictionary
print(result.first_item)
# Output: {'number': 0, 'str': '0'}

# First row as tuple
print(result.first_row)
# Output: (0, '0')

クライアント側パラメータを使用するクエリ

import clickhouse_connect

client = clickhouse_connect.get_client()

# Dictionaryパラメータを使用する場合（printf形式）
query = "SELECT * FROM system.tables WHERE database = %(db)s AND name LIKE %(pattern)s"
parameters = {"db": "system", "pattern": "%query%"}
result = client.query(query, parameters=parameters)

# Tupleパラメータを使用する場合
query = "SELECT * FROM system.tables WHERE database = %s LIMIT %s"
parameters = ("system", 5)
result = client.query(query, parameters=parameters)

サーバー側パラメータを使用したクエリ

import clickhouse_connect

client = clickhouse_connect.get_client()

# サーバーサイドバインディング（より安全で、SELECTクエリのパフォーマンスが向上）
query = "SELECT * FROM system.tables WHERE database = {db:String} AND name = {tbl:String}"
parameters = {"db": "system", "tbl": "query_log"}

result = client.query(query, parameters=parameters)

設定を指定したクエリ

import clickhouse_connect

client = clickhouse_connect.get_client()

# クエリにClickHouseの設定を渡す
result = client.query(
    "SELECT sum(number) FROM numbers(1000000)",
    settings={
        "max_block_size": 100000,
        "max_execution_time": 30
    }
)

`QueryResult` オブジェクト

基本の query メソッドは、以下の公開プロパティを持つ QueryResult オブジェクトを返します。

result_rows — 行指向の結果マトリクス。
result_columns — カラム指向の結果マトリクス。
result_set — クエリの向きに応じて、result_rows または result_columns。
column_names — 結果カラム名のタプル。
column_types — ClickHouseType オブジェクトのタプル。
row_count — 実体化された結果行数。
query_id — リクエストに対して報告または生成されたクエリ ID。空文字列は、利用可能なものがなかったことを意味します。
summary — X-ClickHouse-Summary レスポンスヘッダーからデコードされた辞書。
first_item — 辞書として表した最初の行。結果が空の場合は None。
first_row — シーケンスとして表した最初の行。結果が空の場合は None。
column_block_stream、row_block_stream、および rows_stream — 内部ストリームコンテキストです。代わりに対応するクライアントのストリーミングメソッドを使用してください。

サポートされている StreamContext API については、ストリーミングクエリを参照してください。

NumPy、Pandas、Arrowでクエリ結果を処理する

ClickHouse Connect には、NumPy、Pandas、Arrow のデータフォーマット向けに特化したクエリメソッドが用意されています。これらのメソッドの使用方法の詳細 (例、ストリーミング機能、高度な型処理を含む) については、Advanced Querying (NumPy, Pandas and Arrow Queries) を参照してください。

クライアントのストリーミングクエリメソッド

大規模な結果セットをストリーミングするために、ClickHouse Connect には複数のストリーミングメソッドが用意されています。詳しくは、高度なクエリ (ストリーミングクエリ) をご覧ください。

クライアント `insert` メソッド

ClickHouse に複数のレコードを挿入する一般的なユースケースでは、Client.insert メソッドを使用します。このメソッドは次のパラメータを受け取ります。

パラメータ	型	デフォルト	説明
`table`	str	必須	ターゲットテーブルです。データベース修飾名も指定できます。`context` で指定する場合は省略できます。
`data`	Sequence of Sequences	必須	行指向またはカラム指向のデータ行列です。`InsertContext` を通じてあとから指定することもできます。
`column_names`	str or Sequence[str]	`"*"`	順序付きのカラムです。`"*"` を指定すると、挿入可能なすべてのカラムを検出するためのメタデータクエリが実行されます。
`database`	str or None	クライアントのデータベース	`table` が修飾されていない場合のターゲットデータベースです。
`column_types`	Sequence[`ClickHouseType`]	`None`	明示的なカラム型です。指定するとメタデータクエリを回避できます。
`column_type_names`	Sequence[str]	`None`	明示的な ClickHouse 型名です。`column_types` の代替です。
`column_oriented`	bool	`False`	`data` を行ではなくカラムとして解釈します。
`settings`	dict	`None`	Settings argument を参照してください。
`context`	`InsertContext`	`None`	再利用可能な挿入コンテキストです。InsertContexts を参照してください。
`transport_settings`	dict	`None`	このリクエストに追加される HTTP ヘッダーです。

このメソッドは QuerySummary を返します。その summary 辞書にはサーバーから報告された値が含まれます。written_rows は簡便なプロパティで、written_bytes() と query_id() はそれぞれ対応する値を返します。挿入に失敗した場合は例外が発生します。 Pandas DataFrames、PyArrow Tables、Arrow バックエンドの DataFrames で動作する専用の挿入メソッドについては、高度な挿入 (Specialized Insert Methods) を参照してください。

A NumPy 配列は有効な Sequence of Sequences であり、メインの insert メソッドの data 引数として使用できるため、専用メソッドは必要ありません。

例

以下の例は、スキーマ (id UInt32, name String, age UInt8) を持つ既存のテーブル users があることを前提としています。

基本的な行指向 insert

import clickhouse_connect

client = clickhouse_connect.get_client()

# Row-oriented data: each inner list is a row
data = [
    [13, "user_1", 25],
    [79, "user_2", 30],
]

client.insert("users", data, column_names=["id", "name", "age"])

カラム指向の insert

import clickhouse_connect

client = clickhouse_connect.get_client()

# Column-oriented data: each inner list is a column
data = [
    [13, 79],  # id column
    ["user_1", "user_2"],  # name column
    [25, 30],  # age column
]

client.insert("users", data, column_names=["id", "name", "age"], column_oriented=True)

明示的なカラム型を指定した insert

import clickhouse_connect

client = clickhouse_connect.get_client()

# Useful when you want to avoid a DESCRIBE query to the server
data = [
    [13, "user_1", 25],
    [79, "user_2", 30],
]

client.insert(
    "users",
    data,
    column_names=["id", "name", "age"],
    column_type_names=["UInt32", "String", "UInt8"],
)

特定のデータベースにinsert

import clickhouse_connect

client = clickhouse_connect.get_client()

data = [
    [13, "user_1", 25],
    [79, "user_2", 30],
]

# Insert into a table in a specific database
client.insert(
    "users",
    data,
    column_names=["id", "name", "age"],
    database="production",
)

ファイルからのinsert

ファイルから ClickHouse テーブルに直接データをinsertする方法については、高度な挿入 (ファイルからのinsert) を参照してください。

Raw API

型変換を行わずに ClickHouse HTTP インターフェイスへ直接アクセスする必要がある高度なユースケースについては、高度な使用方法 (Raw API) を参照してください。

Python DB-API 2.0

clickhouse_connect.dbapi モジュールは、PEP 249 で定義された接続およびカーソルのインターフェイスを実装しています。API レベル 2.0、threadsafety=2、および paramstyle="pyformat" を宣言しています。このモジュールは、PEP 249 の型コンストラクター Date、Time、Timestamp、および Binary、ならびに DateFromTicks、TimeFromTicks、および TimestampFromTicks 関数も提供します。

from clickhouse_connect import dbapi

connection = dbapi.connect(
    host="localhost",
    username="default",
    password="password",
    database="default",
)
cursor = connection.cursor()

try:
    cursor.execute(
        "SELECT name FROM system.tables "
        "WHERE database = %(database)s ORDER BY name LIMIT 5",
        {"database": "system"},
    )
    print(cursor.description)
    print(cursor.fetchall())
finally:
    cursor.close()
    connection.close()

Cursor.execute と Cursor.executemany は、追加の settings および query_formats キーワード引数を受け付けます。settings は ClickHouse 設定を渡します。query_formats は、ステートメントが行を返す場合に、Client.query と同じマッピングを使用して、ClickHouse 型ごとに読み取りフォーマットを適用します。executemany は、実体化済みの行シーケンスを伴う互換性のある INSERT ... VALUES ステートメントに対して、ドライバーの Native 一括挿入パスを使用します。fetchone、fetchmany、および fetchall は、現在の実体化済みの結果を消費します。 Cursor.description は、各結果カラムの型から null_ok を導出します。null 非許容型は False を返し、Nullable ラッパー、Variant、および Dynamic を含む null 許容型は True を返します。None は null 許容性が不明であることを意味します。先頭のコメントを無視して SELECT または WITH で始まるクエリが、行もカラムメタデータも返さない場合、カーソルは description を設定するために LIMIT 0 メタデータクエリを実行します。そのメタデータクエリが失敗した場合、description は空のままになります。 ClickHouse は、この HTTP インターフェイス経由では従来型のトランザクションを提供しません。Connection.commit() と Connection.rollback() は no-op です。接続が共有される場合でも、セッション ID の同時実行ルールは引き続き適用されます。

ユーティリティクラスと関数

以下のモジュールは、クライアントアプリケーションで使用される追加の公開ヘルパーを提供します。インストールされている package のバージョンは、文字列 clickhouse_connect.__version__ として公開されています。

Exceptions

DB-API 2.0 の例外階層を含むカスタム例外は、clickhouse_connect.driver.exceptions で定義されています。DatabaseError と OperationalError では、ClickHouse のエラーコードを表す数値の code 属性と、UNKNOWN_TABLE のようなシンボリック名を表す name 属性が公開されているため、アプリケーションはメッセージをパースする代わりに exc.code に基づいて分岐できます。code は show_clickhouse_errors が無効でも設定されますが、name を取得するにはエラーの詳細情報 (True または "scrub") が必要です。どちらも、トランスポートエラーなどで利用できない場合は None になります。エンドユーザーにホストやサーバーバージョンの情報を含めずに SQL エラーを表示する場合は、show_clickhouse_errors="scrub" を使用してください。この設定は、ストリーム途中の StreamFailureError メッセージおよび汎用トランスポートメッセージも制御します。制御対象は str(exc) のみです。トランスポートエラーは引き続き __cause__ として関連付けられ、トレースバックには元のホスト、URL、またはライブラリのエラーテキストが含まれる場合があります。

ClickHouse SQL ユーティリティ

clickhouse_connect.driver.binding モジュールの関数と DT64Param クラスを使用すると、ClickHouse SQL クエリを適切に構築し、エスケープできます。同様に、clickhouse_connect.driver.parser モジュールの関数を使用すると、ClickHouse のデータ型名をパースできます。

マルチスレッド、マルチプロセス、非同期／イベント駆動のユースケース

ClickHouse Connect をマルチスレッド、マルチプロセス、非同期／イベント駆動のアプリケーションで使用する場合の詳細については、高度な使用方法 (マルチスレッド、マルチプロセス、非同期／イベント駆動のユースケース) を参照してください。

AsyncClient

ネイティブな asyncio の使用方法については、高度な使用方法 (AsyncClient)を参照してください。

ClickHouse セッション ID の管理

マルチスレッドまたは同時実行のアプリケーションで ClickHouse セッション ID を管理する方法については、高度な使用方法 (ClickHouse セッション ID の管理) を参照してください。

HTTP接続プールのカスタマイズ

大規模なマルチスレッドアプリケーション向けにHTTP接続プールをカスタマイズする方法については、高度な使用方法 (HTTP接続プールのカスタマイズ) を参照してください。

最終更新日 2026年8月14日

​クライアントの初期化

​接続引数

​HTTPS/TLS 引数

​settings 引数

​クライアント作成の例

​埋め込み chDB バックエンド

​クライアントのライフサイクルとベストプラクティス

​基本原則

​基本パターン

​マルチスレッドアプリケーション

​適切なクリーンアップ

​複数のクライアントを使用する場面

​共通のメソッド引数

​Parameters 引数

​サーバーサイドバインディング

​クライアントサイドバインディング

​Settings 引数

​クライアント command メソッド

​コマンドの例

​DDL文

​単一の値を返すシンプルなクエリ

​パラメータを指定するコマンド

​設定付きのコマンド

​Client query メソッド

​クエリ例

​基本的なクエリ

​クエリ結果へのアクセス

​クライアント側パラメータを使用するクエリ

​サーバー側パラメータを使用したクエリ

​設定を指定したクエリ

​QueryResult オブジェクト

​NumPy、Pandas、Arrowでクエリ結果を処理する

​クライアントのストリーミングクエリメソッド

​クライアント insert メソッド

​例

​基本的な行指向 insert

​カラム指向の insert

​明示的なカラム型を指定した insert

​特定のデータベースにinsert

​ファイルからのinsert

​Raw API

​Python DB-API 2.0

​ユーティリティクラスと関数

​Exceptions

​ClickHouse SQL ユーティリティ

​マルチスレッド、マルチプロセス、非同期／イベント駆動のユースケース

​AsyncClient

​ClickHouse セッション ID の管理

​HTTP接続プールのカスタマイズ

クライアントの初期化

接続引数

HTTPS/TLS 引数

settings 引数

クライアント作成の例

埋め込み chDB バックエンド

クライアントのライフサイクルとベストプラクティス

基本原則

基本パターン

マルチスレッドアプリケーション

適切なクリーンアップ

複数のクライアントを使用する場面

共通のメソッド引数

Parameters 引数

サーバーサイドバインディング

クライアントサイドバインディング

Settings 引数

クライアント `command` メソッド

コマンドの例

DDL文

単一の値を返すシンプルなクエリ

パラメータを指定するコマンド

設定付きのコマンド

Client `query` メソッド

クエリ例

基本的なクエリ

クエリ結果へのアクセス

クライアント側パラメータを使用するクエリ

サーバー側パラメータを使用したクエリ

設定を指定したクエリ

`QueryResult` オブジェクト

NumPy、Pandas、Arrowでクエリ結果を処理する

クライアントのストリーミングクエリメソッド

クライアント `insert` メソッド

例

基本的な行指向 insert

カラム指向の insert

明示的なカラム型を指定した insert

特定のデータベースにinsert

ファイルからのinsert

Raw API

Python DB-API 2.0

ユーティリティクラスと関数

Exceptions

ClickHouse SQL ユーティリティ

マルチスレッド、マルチプロセス、非同期／イベント駆動のユースケース

AsyncClient

ClickHouse セッション ID の管理

HTTP接続プールのカスタマイズ