Python Integration with ClickHouse Connect

Introduction​

ClickHouse Connect は、さまざまな Python アプリケーションとの相互運用性を提供するコアデータベースドライバです。

• 主なインターフェースは、パッケージ clickhouse_connect.driver にある Client オブジェクトです。このコアパッケージには、ClickHouse サーバーとの通信に使用される各種ヘルパークラスとユーティリティ関数、および挿入と選択クエリの高度な管理のための "context" 実装が含まれています。
• clickhouse_connect.datatypes パッケージは、すべての非実験的 ClickHouse データ型のベース実装およびサブクラスを提供します。その主な機能は、ClickHouse データを ClickHouse "Native" バイナリ列指向フォーマットにシリアライズおよびデシリアライズすることで、ClickHouse とクライアントアプリケーション間での最も効率的な輸送を実現します。
• clickhouse_connect.cdriver パッケージの Cython/C クラスは、いくつかの一般的なシリアル化およびデシリアライズを最適化し、純粋な Python よりも大幅にパフォーマンスを向上させます。
• パッケージ clickhouse_connect.cc_sqlalchemy には、datatypes および dbi パッケージから構築された限定された SQLAlchemy ダイアレクトがあります。この制限された実装は、クエリ/カーソル機能に焦点を当てており、一般的には SQLAlchemy の DDL および ORM 操作をサポートしていません。（SQLAlchemy は OLTP データベースを対象としており、ClickHouse の OLAP 指向データベースを管理するには、より専門的なツールやフレームワークを推奨します。）
• コアドライバと ClickHouse Connect SQLAlchemy 実装は、ClickHouse を Apache Superset に接続するための推奨方法です。ClickHouse Connect データベース接続、または clickhousedb SQLAlchemy ダイアレクト接続文字列を使用してください。

このドキュメンテーションは、ベータリリース 0.8.2 の時点での最新情報です。

Requirements and compatibility​

¹ClickHouse Connect は、リストされているプラットフォームに対して明示的にテストされています。さらに、優れた cibuildwheel プロジェクトのために、すべてのアーキテクチャに対して未テストのバイナリホイール（C 最適化付き）がビルドされています。最後に、ClickHouse Connect は純粋な Python としても動作できるため、ソースインストールは最近の Python インストールで動作するはずです。

²再度、SQLAlchemy サポートは主にクエリ機能に制限されています。完全な SQLAlchemy API はサポートされていません。

³ClickHouse Connect は現在サポートされているすべての ClickHouse バージョンに対してテストされています。HTTP プロトコルを使用しているため、ClickHouse の他のバージョンでも正しく動作するはずですが、特定の高度なデータ型において一部の不整合があるかもしれません。

Installation​

ClickHouse Connect を PyPI から pip 経由でインストールします：

pip install clickhouse-connect

ClickHouse Connect はソースからもインストールできます：

• GitHub リポジトリ を git clone します。
• （オプション）pip install cython を実行して、C/Cython 最適化をビルドおよび有効にします。
• プロジェクトのルートディレクトリに cd し、pip install . を実行します。

Support policy​

ClickHouse Connect は現在ベータ版であり、現在のベータリリースのみが積極的にサポートされています。問題を報告する前に最新バージョンにアップデートしてください。問題は GitHub プロジェクト に提出してください。将来の ClickHouse Connect のリリースは、リリース時点で現在アクティブにサポートされている ClickHouse バージョンと互換性があることが保証されています（一般的に、最新の 3 つの stable と 2 つの最新の lts リリース）。

Basic usage​

Gather your connection details​

To connect to ClickHouse with HTTP(S) you need this information:

• The HOST and PORT: typically, the port is 8443 when using TLS or 8123 when not using TLS.

• The DATABASE NAME: out of the box, there is a database named default, use the name of the database that you want to connect to.

• The USERNAME and PASSWORD: out of the box, the username is default. Use the username appropriate for your use case.

The details for your ClickHouse Cloud service are available in the ClickHouse Cloud console. Select the service that you will connect to and click Connect:

Choose HTTPS, and the details are available in an example curl command.

If you are using self-managed ClickHouse, the connection details are set by your ClickHouse administrator.

以下は、ClickHouseにHTTP(S)で接続するために必要な情報です：

• HOSTとPORT: 通常、TLSを使用する場合はポートが8443、使用しない場合は8123です。

• DATABASE NAME: デフォルトでは、defaultという名前のデータベースがあります。接続したいデータベースの名前を使用します。

• USERNAMEとPASSWORD: デフォルトでは、ユーザー名はdefaultです。使用ケースに適したユーザー名を使用します。

ClickHouse Cloudサービスの詳細は、ClickHouse Cloudコンソールで確認できます。 接続するサービスを選択し、Connectをクリックしてください：

HTTPSを選択すると、詳細はexample curlコマンドで確認できます。

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

Establish a connection​

ClickHouse への接続方法には二つの例があります：

• ローカルホストの ClickHouse サーバーへの接続。
• ClickHouse Cloud サービスへの接続。

Use a ClickHouse Connect client instance to connect to a ClickHouse server on localhost:​

import clickhouse_connect

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

Use a ClickHouse Connect client instance to connect to a ClickHouse Cloud service:​

import clickhouse_connect

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

Interact with your database​

ClickHouse SQL コマンドを実行するには、クライアントの command メソッドを使用します：

client.command('CREATE TABLE new_table (key UInt32, value String, metric Float64) ENGINE MergeTree ORDER BY key')

バッチデータを挿入するには、行と値の二次元配列を使用してクライアントの insert メソッドを使用します：

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 を使用してデータを取得するには、クライアントの query メソッドを使用します：

result = client.query('SELECT max(key), avg(metric) FROM new_table')
result.result_rows
Out[13]: [(2000, -50.9035)]

ClickHouse Connect driver API​

Note: 引数の数が多く（ほとんどはオプションです）大部分の API メソッドにはキーワード引数を渡すことを推奨します。

ここにドキュメント化されていないメソッドは API の一部とは見なされず、削除または変更される可能性があります。

Client Initialization​

clickhouse_connect.driver.client クラスは、Python アプリケーションと ClickHouse データベースサーバーとの間の主要なインターフェースを提供します。 clickhouse_connect.get_client 関数を使用して Client インスタンスを取得します。このインスタンスは以下の引数を受け入れます：

Connection arguments​

HTTPS/TLS arguments​

Settings argument​

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

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

Client creation examples​

• パラメータなしで ClickHouse Connect クライアントが localhost でデフォルトの HTTP ポートに接続し、デフォルトユーザーおよびパスワードなしで接続します：

import clickhouse_connect

client = clickhouse_connect.get_client()
client.server_version
Out[2]: '22.10.1.98'

• セキュア（https）の外部 ClickHouse サーバーへの接続

import clickhouse_connect

client = clickhouse_connect.get_client(host='play.clickhouse.com', secure=True, port=443, user='play', password='clickhouse')
client.command('SELECT timezone()')
Out[2]: 'Etc/UTC'

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

import clickhouse_connect

client = clickhouse_connect.get_client(host='play.clickhouse.com',
                                       user='play',
                                       password='clickhouse',
                                       port=443,
                                       session_id='example_session_1',
                                       connect_timeout=15,
                                       database='github',
                                       settings={'distributed_ddl_task_timeout':300})
client.database
Out[2]: 'github'

Common method arguments​

いくつかのクライアントメソッドは、共通の parameters および settings 引数のいずれかまたは両方を使用します。これらのキーワード引数は以下に説明します。

Parameters argument​

ClickHouse Connect Client の query* および command メソッドは、ClickHouse 値式に Python 式をバインドするために使用されるオプションの parameters キーワード引数を受け入れます。二種類のバインディングが利用可能です。

Server side binding​

ClickHouse は、バインドされた値がクエリとは別に HTTP クエリパラメータとして送信される、ほとんどのクエリ値に対して サーバー側バインディング をサポートしています。ClickHouse Connect は、{<name>:<datatype>} 形式のバインディング式を検出すると、適切なクエリパラメータを追加します。サーバー側バインディングでは、parameters 引数は Python 辞書である必要があります。

• 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)


# Generates the following query on the server

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

重要 -- サーバー側バインディングは SELECT クエリに対してのみ ClickHouse サーバーによってサポートされています。ALTER、DELETE、INSERT、または他の種類のクエリでは機能しません。将来的に変更される可能性があります。 https://github.com/ClickHouse/ClickHouse/issues/42092 を参照してください。

Client side binding​

ClickHouse Connect は、テンプレート SQL クエリを生成する際により柔軟性を持つことを可能にするクライアント側パラメータバインディングもサポートしています。クライアント側バインディングでは、parameters 引数は辞書またはシーケンスである必要があります。クライアント側バインディングは、パラメータ置換に Python の "printf" スタイル の文字列フォーマットを使用します。

サーバー側バインディングとは異なり、クライアント側バインディングはデータベース識別子（データベース、テーブル、カラム名など）には機能しません。 Python スタイルフォーマッティングは異なる種類の文字列を区別できないため、異なる形式（データベース識別子にはバックティックまたはダブルクォート、データ値にはシングルクォート）でフォーマットする必要があります。

• Python 辞書、DateTime 値および文字列エスケープの例

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 some_table WHERE date >= %(v1)s AND string ILIKE %(v2)s', parameters=parameters)


# Generates the following query:

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

• Python シーケンス（タプル）、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)


# Generates the following query:

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

query = 'SELECT {p1:DateTime64(3)}'  # Server side binding with dictionary
parameters={'p1': DT64Param(dt_value)}

query = 'SELECT %s as string, toDateTime64(%s,6) as dateTime' # Client side binding with list 
parameters=['a string', DT64Param(datetime.now())]

query = 'SELECT {p1:DateTime64(3)}, {a1:Array(DateTime(3))}'  # Server side binding with dictionary

parameters={'p1_64': dt_value, 'a1_64': [dt_value1, dt_value2]}

Settings argument​

すべての重要な ClickHouse Connect Client の "insert" および "select" メソッドは、含まれる SQL 文のために ClickHouse サーバー ユーザー設定 を渡すためのオプションの settings キーワード引数を受け入れます。settings 引数は辞書である必要があります。各アイテムは ClickHouse 設定名とそれに関連する値である必要があります。値は、クエリパラメータとしてサーバーに送信されるときに文字列に変換されることに注意してください。

クライアントレベルの設定と同様に、ClickHouse Connect はサーバーが readonly=1 とマークした設定を削除し、関連するログメッセージを出力します。ClickHouse HTTP インターフェースを介してクエリにのみ適用される設定は常に有効です。これらの設定は、get_client API の下で詳述されています。

ClickHouse 設定を使用する例：

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)

Client command Method​

Client.command メソッドを使用して、通常はデータを返さないか、フルデータセットではなく単一のプリミティブまたは配列値を返す SQL クエリを ClickHouse サーバーに送信します。このメソッドは以下のパラメータを受け取ります：

• command は DDL ステートメントに使用できます。 SQL "コマンド" がデータを返さない場合、"クエリサマリ" 辞書が代わりに返されます。この辞書は ClickHouse の X-ClickHouse-Summary および X-ClickHouse-Query-Id ヘッダーをカプセル化しており、written_rows,written_bytes および query_id の key/value ペアを含みます。

client.command('CREATE TABLE test_command (col_1 String, col_2 DateTime) Engine MergeTree ORDER BY tuple()')
client.command('SHOW CREATE TABLE test_command')
Out[6]: 'CREATE TABLE default.test_command\\n(\\n    `col_1` String,\\n    `col_2` DateTime\\n)\\nENGINE = MergeTree\\nORDER BY tuple()\\nSETTINGS index_granularity = 8192'

• command は単一の行のみを返すシンプルなクエリにも使用できます。

result = client.command('SELECT count() FROM system.tables')
result
Out[7]: 110

Client query Method​

Client.query メソッドは、ClickHouse サーバーから単一の "バッチ" データセットを取得するための主要な方法です。これは、HTTP 経由でネイティブな ClickHouse 形式を利用して、大規模なデータセット（約 100 万行まで）を効率的に転送します。このメソッドは以下のパラメータを受け取ります。

The QueryResult object​

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

• result_rows -- 行のシーケンスの形で返されたデータのマトリックス。各行の要素はカラム値のシーケンスです。
• result_columns -- カラムのシーケンスの形で返されたデータのマトリックス。各カラムの要素はそのカラムの行値のシーケンスです。
• column_names -- result_set 内のカラム名を表す文字列のタプル。
• column_types -- result_columns 内の各カラムに対する ClickHouse データ型を表す ClickHouseType インスタンスのタプル。
• query_id -- ClickHouse の query_id（system.query_log テーブルでクエリを調べるのに便利です）。
• summary -- X-ClickHouse-Summary HTTP レスポンスヘッダーによって返されたデータ。
• first_item -- レスポンスの最初の行を辞書として取得するための便利なプロパティ（キーはカラム名です）。
• first_row -- 結果の最初の行を返すための便利なプロパティ。
• column_block_stream -- カラム指向形式のクエリ結果のジェネレータ。このプロパティは直接参照すべきではありません（下記を参照）。
• row_block_stream -- 行指向形式のクエリ結果のジェネレータ。このプロパティは直接参照すべきではありません（下記を参照）。
• rows_stream -- 各呼び出しで一つの行を返すクエリ結果のジェネレータ。このプロパティは直接参照すべきではありません（下記を参照）。
• summary -- command メソッドの下で説明されている、ClickHouse が返すサマリー情報の辞書。

*_stream プロパティは、返されたデータのイテレータとして使用できる Python コンテキストを返します。これらは Client *_stream メソッドを使用して間接的にアクセスする必要があります。

クエリ結果をストリーミングする完全な詳細（StreamContext オブジェクトを使用）は、Advanced Queries (Streaming Queries) に記載されています。

Consuming query results with NumPy, Pandas or Arrow​

主な query メソッドには、3つの特化したバージョンがあります:

• query_np -- このバージョンは、ClickHouse Connect QueryResult の代わりに NumPy 配列を返します。
• query_df -- このバージョンは、ClickHouse Connect QueryResult の代わりに Pandas DataFrame を返します。
• query_arrow -- このバージョンは、PyArrow テーブルを返します。ClickHouse Arrow 形式を直接使用するため、メインの query メソッドと共通の 3つの引数：query、parameters、および settings のみを受け付けます。さらに、Arrow テーブルが ClickHouse の文字列型を文字列（Trueの場合）またはバイト（Falseの場合）として表現するかどうかを決定する use_strings という追加の引数があります。

Client streaming query methods​

ClickHouse Connect Client は、ストリームとしてデータを取得するための複数のメソッドを提供します（Python ジェネレータとして実装されています）：

• query_column_block_stream -- ネイティブ Python オブジェクトを使用してカラムのシーケンスとしてクエリデータをブロックで返します。
• query_row_block_stream -- ネイティブ Python オブジェクトを使用して行のブロックのクエリデータを返します。
• query_rows_stream -- ネイティブ Python オブジェクトを使用して行のシーケンスとしてクエリデータを返します。
• query_np_stream -- 各 ClickHouse ブロックを NumPy 配列として返します。
• query_df_stream -- 各 ClickHouse ブロックを Pandas DataFrame として返します。
• query_arrow_stream -- PyArrow RecordBlocks 形式のクエリデータを返します。

これらの各メソッドは、ストリームを消費するために with ステートメントを通じて開かれなければならない ContextStream オブジェクトを返します。詳細と例については、Advanced Queries (Streaming Queries) を参照してください。

Client insert method​

ClickHouse への複数レコードの挿入という一般的なユースケースのために、Client.insert メソッドがあります。以下のパラメータを受け取ります：

このメソッドは、「クエリサマリー」辞書を返します。挿入が何らかの理由で失敗した場合、例外が発生します。

主な insert メソッドの2つの特化バージョンがあります：

• insert_df -- Python の Sequences of Sequences data 引数の代わりに、このメソッドの第2パラメータは Pandas DataFrame インスタンスでなければなりません。ClickHouse Connect は DataFrame をカラム指向のデータソースとして自動的に処理するため、column_oriented パラメータは必要ありませんし、利用できません。
• insert_arrow -- Python の Sequences of Sequences data 引数の代わりに、このメソッドは arrow_table を必要とします。ClickHouse Connect は Arrow テーブルを変更せずに ClickHouse サーバーに渡します。そのため、table と arrow_table に加えて database と settings の引数のみが利用可能です。

注: NumPy 配列は有効な Sequence of Sequences であり、主な insert メソッドの data 引数として使用することができますので、特化メソッドは必要ありません。

File Inserts​

clickhouse_connect.driver.tools には、ファイルシステムから既存の ClickHouse テーブルに直接データを挿入する insert_file メソッドが含まれています。解析は ClickHouse サーバーに委任されています。insert_file は次のパラメータを受け入れます：

不正確なデータや特殊な形式の日付/時間値を含むファイルについては、データインポートに適用される設定（例えば input_format_allow_errors_num や input_format_allow_errors_num）がこのメソッドでも認識されます。

import clickhouse_connect
from clickhouse_connect.driver.tools import insert_file

client = clickhouse_connect.get_client()
insert_file(client, 'example_table', 'my_data.csv',
            settings={'input_format_allow_errors_ratio': .2,
                      'input_format_allow_errors_num': 5})

Saving query results as files​

ClickHouse からローカルファイルシステムにファイルをストリーム保存するには、raw_stream メソッドを使用します。たとえば、クエリの結果を CSV ファイルに保存したい場合、以下のコードスニペットを使用できます：

import clickhouse_connect

if __name__ == '__main__':
    client = clickhouse_connect.get_client()
    query = 'SELECT number, toString(number) AS number_as_str FROM system.numbers LIMIT 5'
    fmt = 'CSVWithNames'  # or CSV, or CSVWithNamesAndTypes, or TabSeparated, etc.
    stream = client.raw_stream(query=query, fmt=fmt)
    with open("output.csv", "wb") as f:
        for chunk in stream:
            f.write(chunk)

上記のコードは、次の内容を持つ output.csv ファイルを生成します：

"number","number_as_str"
0,"0"
1,"1"
2,"2"
3,"3"
4,"4"

同様に、TabSeparated や他の形式でデータを保存できます。利用可能なすべての形式オプションの概要については、Formats for Input and Output Data を参照してください。

Raw API​

ClickHouse データとネイティブまたはサードパーティのデータタイプおよび構造の間の変換を必要としないユースケースのために、ClickHouse Connect クライアントは ClickHouse 接続の直接使用のための2つのメソッドを提供します。

Client raw_query Method​

Client.raw_query メソッドは、クライアント接続を使用して ClickHouse HTTP クエリインターフェースの直接利用を可能にします。返り値は未処理の bytes オブジェクトです。これは引数のバインディング、エラーハンドリング、リトライ、および設定管理を備えた便利なラッパーを提供します：

結果の bytes オブジェクトの処理は呼び出し側の責任です。注意点として、Client.query_arrow は ClickHouse の Arrow 出力形式を使ったこのメソッドの薄いラッパーであることを指摘しておきます。

Client raw_stream Method​

Client.raw_stream メソッドは raw_query メソッドと同じ API を持ちますが、bytes オブジェクトのジェネレータ/ストリームソースとして使用できる io.IOBase オブジェクトを返します。これは query_arrow_stream メソッドによって現在利用されています。

Client raw_insert Method​

Client.raw_insert メソッドは、クライアント接続を使用して bytes オブジェクトまたは bytes オブジェクトのジェネレータの直接挿入を可能にします。挿入ペイロードに対する処理を行わないため、高速です。このメソッドは設定や挿入形式を指定するオプションを提供します：

呼び出し側は insert_block が指定された形式であり、指定された圧縮方法を使用していることを確認する責任があります。ClickHouse Connect はファイルアップロードや PyArrow テーブルのためにこれらの生挿入を使用し、解析を ClickHouse サーバーに委任します。

Utility classes and functions​

以下のクラスと関数も「公開された」clickhouse-connect API の一部と見なされ、上記の文書化されたクラスやメソッドと同様に、マイナーバージョン間で安定しています。これらのクラスや関数に対する破壊的な変更は、マイナー（パッチではなく）リリースでのみ発生し、少なくとも1つのマイナーバージョンで非推奨のステータスで利用可能です。

Exceptions​

すべてのカスタム例外（DB API 2.0 仕様で定義されているものを含む）は、clickhouse_connect.driver.exceptions モジュールで定義されています。ドライバーによって実際に検出された例外は、これらのタイプのいずれかを使用します。

Clickhouse SQL utilities​

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

Multithreaded, multiprocess, and async/event driven use cases​

ClickHouse Connect はマルチスレッド、マルチプロセス、およびイベントループ駆動/非同期アプリケーションでうまく機能します。すべてのクエリおよび挿入処理は、単一スレッド内で実行されるため、操作は一般にスレッドセーフです。（低レベルでの一部の操作の並行処理は、単一スレッドのパフォーマンスペナルティを克服するための将来の改良の可能性がありますが、その場合でもスレッドセーフは維持されます）。

各クエリまたは挿入は、それぞれ独自の QueryContext または InsertContext オブジェクト内で状態を維持するため、これらのヘルパーオブジェクトはスレッドセーフではなく、複数の処理ストリーム間で共有するべきではありません。コンテキストオブジェクトについての追加の議論は、次のセクションで行っています。

また、同時に 2 つ以上のクエリや挿入が「フライト」にあるアプリケーションでは、考慮すべき2つの要素があります。1つ目は、クエリ/挿入に関連付けられた ClickHouse「セッション」であり、2つ目は ClickHouse Connect クライアントインスタンスによって使用される HTTP 接続プールです。

Asyncclient wrapper​

0.7.16 以降、ClickHouse Connect は通常の Client に対する非同期ラッパーを提供しており、asyncio 環境でクライアントを使用することが可能です。

AsyncClient のインスタンスを取得するには、標準の get_client と同じパラメータを受け入れる get_async_client ファクトリ関数を使用します：

import asyncio

import clickhouse_connect

async def main():
    client = await clickhouse_connect.get_async_client()
    result = await client.query("SELECT name FROM system.databases LIMIT 1")
    print(result.result_rows)

asyncio.run(main())

AsyncClient は、標準の Client と同じメソッドおよびパラメータを持ちますが、それらは適用可能な場合コルーチンです。内部では、I/O 操作を実行する Client のこれらのメソッドは、run_in_executor コール内でラップされています。

AsyncClient ラッパーを使用することでマルチスレッド性能が向上します。I/O 操作が完了するのを待つ間、実行スレッドと GIL が解放されます。

注: 通常の Client とは異なり、AsyncClient はデフォルトで autogenerate_session_id を False に設定します。

参考: run_async example。

Managing ClickHouse Session Ids​

各 ClickHouse クエリは ClickHouse「セッション」のコンテキスト内で発生します。セッションは現在、2つの目的で使用されています：

• 複数のクエリに特定の ClickHouse 設定を関連付けるため（user settings を参照してください）。ClickHouse の SET コマンドはユーザーセッションの範囲の設定を変更するために使用されます。
• temporary tables を追跡するため。

デフォルトでは、ClickHouse Connect クライアントインスタンスで実行される各クエリは、同じセッション ID を使用してこのセッション機能を有効にします。つまり、SET ステートメントと一時テーブルは、単一の ClickHouse クライアントを使用していると期待通りに動作します。しかし、設計上、ClickHouse サーバーは同じセッション内での同時クエリを許可しません。したがって、同時クエリを実行する ClickHouse Connect アプリケーションには2つのオプションがあります。

• 各実行スレッド（スレッド、プロセス、またはイベントハンドラー）に対して別の Client インスタンスを作成し、それぞれが独自のセッション ID を持つようにします。一般的にはこのアプローチが最良です。クライアントごとにセッション状態を維持します。
• 各クエリにユニークなセッション ID を使用します。これにより、一時テーブルや共有セッション設定が不要な場合の同時セッションの問題を回避します。（共有設定はクライアント作成時にも提供できますが、リクエストごとに送信され、セッションとは関連付けられません）。ユニークな session_id は、各リクエストの settings 辞書に追加できます。また、autogenerate_session_id 一般設定を無効にすることもできます：

from clickhouse_connect import common

common.set_setting('autogenerate_session_id', False)  # This should always be set before creating a client
client = clickhouse_connect.get_client(host='somehost.com', user='dbuser', password=1234)

この場合、ClickHouse Connect はセッション ID を送信せず、ClickHouse サーバーによってランダムなセッション ID が生成されます。繰り返しますが、一時テーブルおよびセッションレベルの設定は利用できません。

Customizing the HTTP connection pool​

ClickHouse Connect は、サーバーへの基盤となる HTTP 接続を処理するために urllib3 接続プールを使用します。デフォルトでは、すべてのクライアントインスタンスは同じ接続プールを共有し、これは大多数のユースケースには十分です。このデフォルトプールは、アプリケーションで使用する各 ClickHouse サーバーへの最大 8 つの HTTP Keep Alive 接続を維持します。

大規模なマルチスレッドアプリケーションの場合、別々の接続プールが適切な場合があります。カスタマイズされた接続プールは、主な clickhouse_connect.get_client 関数に pool_mgr キーワード引数として提供できます：

import clickhouse_connect
from clickhouse_connect.driver import httputil

big_pool_mgr = httputil.get_pool_manager(maxsize=16, num_pools=12)

client1 = clickhouse_connect.get_client(pool_mgr=big_pool_mgr)
client2 = clickhouse_connect.get_client(pool_mgr=big_pool_mgr)

上記の例が示すように、クライアントはプールマネージャを共有することができますし、各クライアントのために別個のプールマネージャを作成することもできます。プールマネージャを作成する際の利用可能なオプションの詳細については、urllib3 documentation を参照してください。

Querying data with ClickHouse Connect: Advanced usage​

QueryContexts​

ClickHouse Connect は標準クエリを QueryContext 内で実行します。QueryContext には、ClickHouse データベースに対してクエリを構築するために使用される主要な構造と、結果を QueryResult やその他のレスポンスデータ構造に処理するための設定が含まれています。それには、クエリ自体、パラメータ、設定、読み取り形式、その他の属性が含まれます。

QueryContext は、クライアントの create_query_context メソッドを使用して取得できます。このメソッドは、コアクエリメソッドと同じパラメータを受け取ります。このクエリコンテキストは、query、query_df、または query_np メソッドに context キーワード引数として渡すことができ、これによりこれらのメソッドへの他の引数を一切使用しなくても済みます。注意点として、メソッド呼び出しのために指定された追加の引数は QueryContext のプロパティを上書きします。

QueryContext の最も明確なユースケースは、異なるバインディングパラメータ値で同じクエリを送信することです。すべてのパラメータ値は、QueryContext.set_parameters メソッドを辞書で呼び出すことで更新できます。また、任意の単一値は QueryContext.set_parameter を desired key, value ペアで呼び出すことで更新できます。

client.create_query_context(query='SELECT value1, value2 FROM data_table WHERE key = {k:Int32}',
                            parameters={'k': 2},
                            column_oriented=True)
result = client.query(context=qc)
assert result.result_set[1][0] == 'second_value2'
qc.set_parameter('k', 1)
result = test_client.query(context=qc)
assert result.result_set[1][0] == 'first_value2'

QueryContexts はスレッドセーフではありませんが、マルチスレッド環境で QueryContext.updated_copy メソッドを呼び出すことでコピーを取得できます。

Streaming queries​

Data blocks​

ClickHouse Connect は、主な query メソッドからのすべてのデータを ClickHouse サーバーから受信するブロックのストリームとして処理します。これらのブロックは、ClickHouse との間でカスタム「ネイティブ」形式で送信されます。「ブロック」は、指定されたデータ型のデータ値の数が等しい各カラムを含むバイナリデータのカラムのシーケンスです。（カラム型データベースとして、ClickHouse は同様の形でこのデータを格納します。）クエリから返されるブロックのサイズは、複数のレベル（ユーザープロファイル、ユーザー、セッション、またはクエリ）で設定できる2つのユーザー設定によって制御されます。それは：

• max_block_size -- 行数のブロックのサイズの制限。デフォルトは 65536。
• preferred_block_size_bytes -- バイトのブロックのサイズに対するソフトリミット。デフォルトは 1,000,0000。

preferred_block_size_setting に関係なく、各ブロックは max_block_size 行を超えることは決してありません。クエリのタイプに応じて、実際に返されるブロックは任意のサイズである場合があります。たとえば、多くのシャードをカバーする分散テーブルへのクエリは、各シャードから直接取得された小さなブロックを含む場合があります。

Client query_*_stream メソッドの1つを使用する場合、結果はブロックごとに返されます。ClickHouse Connect は単一のブロックを一度にのみロードします。これにより、多くのデータを処理する際に大きな結果セットをすべてメモリにロードする必要がなくなります。アプリケーションは、任意の数のブロックを処理できるように準備する必要があります。各ブロックの正確なサイズを制御することはできません。

HTTP data buffer for slow processing​

HTTP プロトコルの制限のため、ブロックが ClickHouse サーバーがデータをストリーミングする速度よりも著しく遅い速度で処理される場合、ClickHouse サーバーは接続を閉じ、処理スレッドで例外が発生します。これは、共通の http_buffer_size 設定を使用して HTTP ストリーミングバッファのサイズを増やすことで軽減できます（デフォルトは 10 メガバイト）。十分なメモリがアプリケーションに利用可能な場合、大きな http_buffer_size 値はこの状況で問題ありません。バッファ内のデータは、lz4 または zstd 圧縮を使用して圧縮されるので、これらの圧縮タイプを使用することで全体のバッファが増加します。

StreamContexts​

query_*_stream メソッドの各メソッド（query_row_block_stream のような）は、ClickHouse StreamContext オブジェクトを返します。これは、Python コンテキスト/ジェネレータの組み合わせです。基本的な使用法は次のとおりです：

with client.query_row_block_stream('SELECT pickup, dropoff, pickup_longitude, pickup_latitude FROM taxi_trips') as stream:
    for block in stream:
        for row in block:
            <do something with each row of Python trip data>

注意：with ステートメントなしで StreamContext を使用しようとするとエラーが発生します。Python コンテキストの使用により、ストリーム（この場合、ストリーミング HTTP レスポンス）がすべてのデータが消費されない場合や、処理中に例外が発生した場合でも適切に閉じられることが保証されます。また、StreamContexts はストリームを消費するためにのみ一度使用できます。StreamContext が終了した後に使用しようとすると、StreamClosedError が発生します。

StreamContext の source プロパティを使用して親の QueryResult オブジェクトにアクセスできます。これにはカラム名や型が含まれます。

Stream types​

query_column_block_stream メソッドは、ネイティブ Python データ型として保存されたカラムデータのシーケンスとしてブロックを返します。上記の taxi_trips クエリを使用すると、返されたデータはそれぞれのリストの要素が関連付けられたカラムのすべてのデータを含む別のリスト（またはタプル）になるリストとなります。したがって、block[0] は文字列のみを含むタプルです。カラム指向形式は、カラム内のすべての値に対して集約操作を行うためによく使用されます。

query_row_block_stream メソッドは、従来の関係データベースのように行のシーケンスとしてブロックを返します。タクシートリップに対する返されたデータは、リストの各要素がデータの行を表す別のリストになります。したがって、block[0] は最初のタクシートリップのすべてのフィールド（順序付け）を含んでおり、block[1] は2番目のタクシートリップのすべてのフィールドの行を含みます。行指向結果は通常、表示または変換プロセスに使用されます。

query_row_stream は便利なメソッドで、ストリームを反復処理する際に自動的に次のブロックに移動します。それ以外は、query_row_block_stream と同一です。

query_np_stream メソッドは、各ブロックを 2 次元の NumPy 配列として返します。内部では NumPy 配列は（通常）カラムとして保存されるため、特に行またはカラムメソッドは必要ありません。NumPy 配列の「形状」は (columns, rows) として表現されます。NumPy ライブラリは、NumPy 配列を操作する多くのメソッドを提供します。すべてのカラムが同じ NumPy dtype を共有している場合、返される NumPy 配列も同じ dtype しか持たず、内部構造を変更せずに再成形/回転できます。

query_df_stream メソッドは、各 ClickHouse ブロックを 2 次元の Pandas DataFrame として返します。次に示す例では、StreamContext オブジェクトが遅延的にコンテキストとして使用でき（ただし、1 回のみ）、示されています。

最後に、query_arrow_stream メソッドは ClickHouse の ArrowStream 形式の結果を pyarrow.ipc.RecordBatchStreamReader として返します。ストリームの各反復は PyArrow RecordBlock を返します。

df_stream = client.query_df_stream('SELECT * FROM hits')
column_names = df_stream.source.column_names
with df_stream:
    for df in df_stream:
        <do something with the pandas DataFrame>

Read formats​

読み取り形式は、クライアントの query、query_np、および query_df メソッドから返された値のデータ型を制御します。（raw_query と query_arrow は ClickHouse からの受信データを変更しないため、形式制御は適用されません。）たとえば、UUID の読み取り形式をデフォルトの native 形式から代替の string 形式に変更すると、ClickHouse の UUID カラムに対するクエリは Python UUID オブジェクトの代わりに文字列値（標準の 8-4-4-4-12 RFC 1422 形式）として返されます。

形式設定関数の「データ型」引数には、ワイルドカードを含めることができます。形式は単一の小文字の文字列です。

読み取り形式は、いくつかのレベルで設定できます：

• clickhouse_connect.datatypes.format パッケージで定義されたメソッドを使用してグローバルに設定します。これにより、すべてのクエリに対して設定されたデータ型の形式が制御されます。

from clickhouse_connect.datatypes.format import set_read_format


# Return both IPv6 and IPv4 values as strings
set_read_format('IPv*', 'string')


# Return all Date types as the underlying epoch second or epoch day
set_read_format('Date*', 'int')

• クエリ全体に対して、オプションの query_formats 辞書引数を使用します。その場合、特定のデータ型のいずれかのカラム（またはサブカラム）は設定された形式を使用します。

# Return any UUID column as a string
client.query('SELECT user_id, user_uuid, device_uuid from users', query_formats={'UUID': 'string'})

• 特定のカラムの値に対しては、オプションの column_formats 辞書引数を使用します。キーは ClickHouse によって返されたカラム名で、データカラムの形式や ClickHouse 型名の 2 番目のレベル「形式」辞書とその値を持ちます。この二次辞書は、タプルやマップなどのネストされたカラム型のためにも使用できます。

# Return IPv6 values in the `dev_address` column as strings
client.query('SELECT device_id, dev_address, gw_address from devices', column_formats={'dev_address':'string'})

Read format options (Python types)​

External data​

ClickHouseのクエリは、任意のClickHouseフォーマットの外部データを受け入れることができます。このバイナリデータは、データを処理するためにクエリ文字列と共に送信されます。外部データ機能の詳細はこちらで確認できます。クライアントのquery*メソッドは、この機能を利用するためにオプショナルなexternal_dataパラメータを受け入れます。external_dataパラメータの値は、clickhouse_connect.driver.external.ExternalDataオブジェクトである必要があります。そのオブジェクトのコンストラクタは次の引数を受け入れます：

"映画"データを含む外部CSVファイルを使ってクエリを送信し、そのデータをClickHouseサーバ上に既存のdirectorsテーブルと結合する方法：

import clickhouse_connect
from clickhouse_connect.driver.external import ExternalData

client = clickhouse_connect.get_client()
ext_data = ExternalData(file_path='/data/movies.csv',
                        fmt='CSV',
                        structure=['movie String', 'year UInt16', 'rating Decimal32(3)', 'director String'])
result = client.query('SELECT name, avg(rating) FROM directors INNER JOIN movies ON directors.name = movies.director GROUP BY directors.name',
                      external_data=ext_data).result_rows

初期のExternalDataオブジェクトに追加の外部データファイルを追加するには、コンストラクタと同じパラメータを受け入れるadd_fileメソッドを使用します。HTTPの場合、すべての外部データはmulti-part/form-dataファイルアップロードの一部として送信されます。

Time zones​

ClickHouseのDateTimeおよびDateTime64値にタイムゾーンを適用するための複数のメカニズムがあります。内部的に、ClickHouseサーバは、すべてのDateTimeまたはDateTime64オブジェクトをエポック（1970-01-01 00:00:00 UTC時間）以降の秒数を表す、タイムゾーンに依存しない数値として保存します。DateTime64値の場合、表現は精度に応じてエポック以降のミリ秒、マイクロ秒、またはナノ秒となることがあります。そのため、タイムゾーン情報の適用は常にクライアント側で行われます。この計算は重要な追加計算を伴うため、パフォーマンスが重要なアプリケーションでは、ユーザー表示と変換（たとえば、PandasのTimestampsなど）を除いて、DateTime型をエポックタイムスタンプとして扱うことをお勧めします。

タイムゾーンを意識したデータ型をクエリで使用する場合 - 特にPythonのdatetime.datetimeオブジェクトで -- clickhouse-connectは次の優先順位ルールに従ってクライアント側のタイムゾーンを適用します：

1. クエリのメソッドパラメータclient_tzsが指定されている場合、特定のカラムタイムゾーンが適用されます。
2. ClickHouseのカラムにタイムゾーンメタデータがある場合（すなわち、DateTime64(3, 'America/Denver')のような型の場合）、そのClickHouseのカラムタイムゾーンが適用されます。（このタイムゾーンメタデータは、ClickHouseバージョン23.2より前のDateTimeカラムに対してclickhouse-connectでは利用できません）
3. クエリメソッドパラメータquery_tzが指定されている場合、「クエリタイムゾーン」が適用されます。
4. クエリまたはセッションにタイムゾーン設定が適用された場合、そのタイムゾーンが適用されます。（この機能は現在のClickHouseサーバにはまだリリースされていません）
5. 最後に、クライアントのapply_server_timezoneパラメータがTrueに設定されている場合（デフォルト）、ClickHouseサーバのタイムゾーンが適用されます。

これらのルールに基づいて適用されたタイムゾーンがUTCである場合、clickhouse-connectは常にタイムゾーンに依存しないPythonのdatetime.datetimeオブジェクトを返します。このタイムゾーンに依存しないオブジェクトには、必要に応じてアプリケーションコードで追加のタイムゾーン情報を加えることができます。

Inserting data with ClickHouse Connect: Advanced usage​

InsertContexts​

ClickHouse Connectは、すべての挿入操作をInsertContext内で実行します。InsertContextには、クライアントのinsertメソッドに引数として渡されるすべての値が含まれています。さらに、InsertContextが元々構築されるとき、ClickHouse Connectは効果的なネイティブフォーマットの挿入に必要な挿入カラムのデータ型を取得します。複数の挿入にInsertContextを再利用することで、この「前クエリ」を回避し、挿入をより迅速かつ効率的に実行できます。

InsertContextは、クライアントのcreate_insert_contextメソッドを使用して取得できます。このメソッドは、insert関数と同じ引数を受け取ります。InsertContextsは、再利用のためにデータプロパティが変更されるべきであることに注意してください。これは、同じテーブルに新しいデータを繰り返し挿入するための再利用可能なオブジェクトを提供するという意図した目的に一致しています。

test_data = [[1, 'v1', 'v2'], [2, 'v3', 'v4']]
ic = test_client.create_insert_context(table='test_table', data=test_data)
client.insert(context=ic)
assert client.command('SELECT count() FROM test_table') == 2
new_data = [[3, 'v5', 'v6'], [4, 'v7', 'v8']]
ic.data = new_data
client.insert(context=ic)
qr = test_client.query('SELECT * FROM test_table ORDER BY key DESC')
assert qr.row_count == 4
assert qr[0][0] == 4

InsertContextsは、挿入プロセス中に更新される可変状態を含むため、スレッドセーフではありません。

Write formats​

書き込みフォーマットは、現在限られた数の型に対して実装されています。ほとんどの場合、ClickHouse Connectは最初の（非null）データ値の型を確認することによって各カラムの正しい書き込みフォーマットを自動的に判断しようとします。たとえば、DateTimeカラムに挿入する場合、そのカラムの最初の挿入値がPythonの整数であれば、ClickHouse Connectはそれが実際にはエポック秒であるという仮定の下、その整数値を直接挿入します。

ほとんどの場合、データ型の書き込みフォーマットをオーバーライドする必要はありませんが、clickhouse_connect.datatypes.formatパッケージ内の関連メソッドを使用してグローバルレベルで行うことができます。

Write format options​

Additional options​

ClickHouse Connectは、高度な使用ケースのための追加のオプションを多数提供します。

Global settings​

ClickHouse Connectの動作をグローバルに制御する設定が少数あります。それらは最上位のcommonパッケージからアクセスされます：

from clickhouse_connect import common

common.set_setting('autogenerate_session_id', False)
common.get_setting('invalid_setting_action')
'drop'

現在定義されているグローバル設定は10個です：

Compression​

ClickHouse Connectは、クエリ結果と挿入の両方のためのlz4、zstd、brotli、gzip圧縮をサポートしています。圧縮を使用することは通常、ネットワーク帯域幅/転送速度とCPU使用率（クライアントとサーバの両方）とのトレードオフを伴うことを常に念頭に置いてください。

圧縮されたデータを受け取るためには、ClickHouseサーバのenable_http_compressionを1に設定する必要があります。または、ユーザーは「クエリごと」の基準で設定を変更する権限を持っている必要があります。

圧縮は、clickhouse_connect.get_clientファクトリメソッドを呼び出す際のcompressパラメータで制御されます。デフォルトでは、compressはTrueに設定されており、これがデフォルトの圧縮設定をトリガーします。query、query_np、およびquery_dfクライアントメソッドで実行されたクエリに対して、ClickHouse ConnectはAccept-Encodingヘッダーを追加し、lz4、zstd、br（brotli、brotliライブラリがインストールされている場合）、gzip、およびdeflateエンコーディングをqueryクライアントメソッドで直接実行します（そして間接的に、query_npおよびquery_df）。 （ほとんどのリクエストの場合、ClickHouseサーバはzstdで圧縮されたペイロードを返します。）挿入に関しては、デフォルトでClickHouse Connectは挿入ブロックをlz4圧縮で圧縮し、Content-Encoding: lz4 HTTPヘッダーを送信します。

get_clientのcompressパラメータも、lz4、zstd、br、またはgzipのいずれか特定の圧縮メソッドに設定できます。そのメソッドは、挿入とクエリ結果の両方に使用されます（ClickHouseサーバがサポートする場合）。 必要なzstdおよびlz4圧縮ライブラリは現在ClickHouse Connectにデフォルトでインストールされています。br/brotliが指定された場合、brotliライブラリは別途インストールする必要があります。

raw*クライアントメソッドはクライアント設定で指定された圧縮を使用しないことに注意してください。

gzip圧縮の使用は推奨されません。なぜなら、データの圧縮と解凍の両方で代替手段に比べて著しく遅いためです。

HTTP proxy support​

ClickHouse Connectは、urllib3ライブラリを使用して基本的なHTTPプロキシサポートを追加します。標準のHTTP_PROXYおよびHTTPS_PROXY環境変数を認識します。これらの環境変数を使用すると、clickhouse_connect.get_clientメソッドで作成されたクライアントに適用されます。別の方法として、各クライアントに対して構成するには、get_clientメソッドのhttp_proxyまたはhttps_proxy`引数を使用できます。HTTPプロキシサポートの実装に関する詳細は、urllib3のドキュメントを参照してください。

Socksプロキシを使用するには、urllib3のSOCKSProxyManagerをget_clientのpool_mgr引数として送信できます。これは、PySocksライブラリを直接インストールするか、urllib3の依存関係に対して[socks]オプションを使用することを必要とします。

"Old" JSON data type​

実験的なObject（またはObject('json')）データ型は非推奨であり、本番環境での使用は避けるべきです。ClickHouse Connectは後方互換性のためにこのデータ型に対する制限されたサポートを提供し続けています。ただし、このサポートには、辞書や等価物として返される「トップレベル」または「親」JSON値を期待するクエリは含まれておらず、そのようなクエリは例外を引き起こします。

"New" Variant/Dynamic/JSON datatypes (experimental feature)​

0.8.0リリースから、clickhouse-connectは新しい（実験的な）ClickHouse型であるVariant、Dynamic、JSONのサポートを提供します。

Usage notes​

• JSONデータは、Python辞書またはJSONオブジェクト{}を含むJSON文字列として挿入できます。他の形式のJSONデータはサポートされていません。
• これらの型のためのサブカラム/パスを使用するクエリは、サブカラムの型を返します。
• その他の使用ノートについては、主要なClickHouseドキュメントを参照してください。

Known limitations​

• これらの型は使用する前にClickHouse設定で有効にする必要があります。
• 「新しい」JSON型はClickHouse 24.8リリースから利用可能です。
• 内部フォーマットの変更により、clickhouse-connectはClickHouse 24.7リリース以降のVariant型とのみ互換性があります。
• 返されたJSONオブジェクトは、max_dynamic_paths数の要素のみを返します（デフォルトは1024）。これは将来のリリースで修正される予定です。
• Dynamicカラムへの挿入は常にPython値の文字列表現となります。これは、https://github.com/ClickHouse/ClickHouse/issues/70395が修正されると、将来のリリースで修正される予定です。
• 新しい型の実装はCコードで最適化されていないため、パフォーマンスは単純で確立されたデータ型よりもやや遅くなるかもしれません。