Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

ClickHouse Connect ドライバー API

View as MarkdownEdit this pageReport an issueSet up docs MCP

クライアントの初期化

同期 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()

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

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

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 の辞書として渡します。

パラメータ名は ClickHouse の ASCII BareWord 名である必要があります。ドライバーは、{$tenant_id:String} のようにサーバーが受け入れる場合、名前の先頭、途中、末尾にある $ を受け入れます。$ で始まり $ で終わる辞書キーで、bytes、bytearray、memoryview などのバッファ値を持つものは、ClickHouse Connect's raw binary パラメータ規約用に予約されています。このようなキーを非バイナリのサーバーサイドパラメータに使用する場合は、{name:Type} プレースホルダーを 1 つだけ使用してください。繰り返される $tag$ 名は、ClickHouse によってヒアドキュメントマーカーとして解析される可能性があります。

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\''

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

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'

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) を参照してください。

例

以下の例は、スキーマ (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 型ごとに読み取りフォーマットを適用します。Cursor.execute は、キーワード専用の pyformat_encoded 引数も受け付けます。デフォルト値の True は、DB-API の pyformat 契約に従います。SQLAlchemy dialect は、ステートメントコンパイラが生のパーセント記号を出力した場合にこれを False に設定するため、通常、アプリケーションで設定する必要はありません。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接続プールのカスタマイズ) を参照してください。

Navigation