}` 形式の式を検出すると、このモードを使用します。値は Python の辞書として渡します。
null 許容値には Python の `None` を使用します。ネストされた `None` 値は、`Array` および `Tuple` パラメータ内、ならびに `dict_parameter_format` が `"map"` に設定されている場合は `Map` リテラル内でサポートされます。
* Python の辞書、DateTime 値、文字列値を使用したサーバーサイドバインディング
```python theme={null}
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,
)
```
これは以下と同等です:
```sql theme={null}
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" スタイル](https://docs.python.org/3/library/stdtypes.html#old-string-formatting) の文字列フォーマットを使用します。
サーバーサイドバインディングとは異なり、クライアントサイドバインディングは、データベース、テーブル、カラム名などのデータベース識別子には使用できない点に注意してください。Python スタイルのフォーマットでは文字列の種類の違いを区別できず、それぞれ異なる形式でフォーマットする必要があるためです (データベース識別子にはバッククォートまたは二重引用符、データ値には単一引用符を使用します) 。
* Python の Dictionary、DateTime 値、文字列のエスケープを使用した Example
```python theme={null}
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,
)
```
これにより、サーバーでは次のクエリが生成されます。
```sql theme={null}
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を使用した例
```python theme={null}
import ipaddress
parameters = (35200.44, ipaddress.IPv4Address(0x443d04fe))
client.query(
"SELECT * FROM some_table WHERE metric >= %s AND ip_address = %s",
parameters=parameters,
)
```
これにより、サーバーでは次のクエリが生成されます。
```sql theme={null}
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](/ja/integrations/language-clients/python/advanced-inserting#timezone-naive-datetime-objects) を参照してください。
サーバーサイドの `{value:DateTime64(precision)}` プレースホルダーでは、宣言された型によって、`Array` や `Tuple` のヒント内であっても秒未満の精度が自動的に保持されます。
クライアントサイドの `%s` バインディングには宣言された型がありません。秒未満の精度で出力する必要がある場合は、`datetime` を `DT64Param` でラップしてください。
```python theme={null}
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 サーバー の [ユーザー設定](/ja/reference/settings/session-settings) を渡すための、省略可能な `settings` キーワード引数を受け付けます。`settings` 引数には辞書を指定する必要があります。各項目は、ClickHouse の設定名とそれに対応する値で構成されます。なお、値はサーバーにクエリパラメータとして送信される際に文字列に変換されます。
クライアントレベルの settings と同様に、ClickHouse Connect は、サーバーが *readonly*=*1* としてマークした settings を、対応するログメッセージを出力したうえで除外します。ClickHouse HTTP インターフェイス 経由のクエリにのみ適用される settings は常に有効です。これらの settings については、`get_client` [API](#settings-argument) で説明しています。
ClickHouse settings の使用例:
```python theme={null}
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 の説明](#parameters-argument)を参照してください。 |
| data | str or bytes | *None* | コマンドとともに POST ボディに含める省略可能なデータです。 |
| settings | dict | *None* | [settings の説明](#settings-argument-1)を参照してください。 |
| use\_database | bool | True | クライアントのデータベース (クライアント作成時に指定) を使用します。False の場合、コマンドは接続中のユーザーのデフォルトの ClickHouse サーバーのデータベースを使用します。 |
| external\_data | ExternalData | *None* | クエリで使用するファイルまたは実行可能バイナリデータを含む `ExternalData` オブジェクトです。[高度なクエリ (External Data)](/ja/integrations/language-clients/python/advanced-querying#external-data)を参照してください。 |
| transport\_settings | dict | *None* | このリクエストに含める省略可能な HTTPヘッダーの辞書です。各キー・バリューの組は HTTPヘッダーとして追加されます (例: `{'X-Custom-Header': 'value'}`) 。プロキシ認証、リクエストのトレーシング、または中間インフラストラクチャで必要なヘッダーの受け渡しに役立ちます。 |
### コマンドの例
#### DDL文
```python theme={null}
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")
```
#### 単一の値を返すシンプルなクエリ
```python theme={null}
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)
```
#### パラメータを指定するコマンド
```python theme={null}
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"}
)
```
#### 設定付きのコマンド
```python theme={null}
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 引数](#parameters-argument)を参照してください。 |
| `settings` | dict | `None` | [Settings 引数](#settings-argument-1)を参照してください。 |
| `query_formats` | dict | `None` | ClickHouse 型ごとの読み取りフォーマットです。[Read formats](/ja/integrations/language-clients/python/advanced-querying#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](/ja/integrations/language-clients/python/advanced-querying#external-data)を参照してください。 |
| `transport_settings` | dict | `None` | このリクエストに追加される HTTP ヘッダーです。 |
| `tz_mode` | str | Client default | `"naive_utc"`、`"aware"`、または `"schema"` のタイムゾーン処理をクエリ単位で上書きします。 |
### クエリ例
#### 基本的なクエリ
```python theme={null}
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']
```
#### クエリ結果へのアクセス
```python theme={null}
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')
```
#### クライアント側パラメータを使用するクエリ
```python theme={null}
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)
```
#### サーバー側パラメータを使用したクエリ
```python theme={null}
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)
```
#### 設定を指定したクエリ
```python theme={null}
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 については、[ストリーミングクエリ](/ja/integrations/language-clients/python/advanced-querying#streaming-queries)を参照してください。
## NumPy、Pandas、Arrowでクエリ結果を処理する
ClickHouse Connect には、NumPy、Pandas、Arrow のデータフォーマット向けに特化したクエリメソッドが用意されています。これらのメソッドの使用方法の詳細 (例、ストリーミング機能、高度な型処理を含む) については、[Advanced Querying (NumPy, Pandas and Arrow Queries)](/ja/integrations/language-clients/python/advanced-querying#numpy-pandas-and-arrow-queries) を参照してください。
## クライアントのストリーミングクエリメソッド
大規模な結果セットをストリーミングするために、ClickHouse Connect には複数のストリーミングメソッドが用意されています。詳しくは、[高度なクエリ (ストリーミングクエリ) ](/ja/integrations/language-clients/python/advanced-querying#streaming-queries)をご覧ください。
## クライアント `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](#settings-argument-1) を参照してください。 |
| `context` | `InsertContext` | `None` | 再利用可能な挿入コンテキストです。[InsertContexts](/ja/integrations/language-clients/python/advanced-inserting#insertcontexts) を参照してください。 |
| `transport_settings` | dict | `None` | このリクエストに追加される HTTP ヘッダーです。 |
このメソッドは `QuerySummary` を返します。その `summary` 辞書にはサーバーから報告された値が含まれます。`written_rows` は簡便なプロパティで、`written_bytes()` と `query_id()` はそれぞれ対応する値を返します。挿入に失敗した場合は例外が発生します。
Pandas DataFrames、PyArrow Tables、Arrow バックエンドの DataFrames で動作する専用の挿入メソッドについては、[高度な挿入 (Specialized Insert Methods)](/ja/integrations/language-clients/python/advanced-inserting#specialized-insert-methods) を参照してください。
A NumPy 配列は有効な Sequence of Sequences であり、メインの `insert` メソッドの `data` 引数として使用できるため、専用メソッドは必要ありません。
### 例
以下の例は、スキーマ `(id UInt32, name String, age UInt8)` を持つ既存のテーブル `users` があることを前提としています。
#### 基本的な行指向 insert
```python theme={null}
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
```python theme={null}
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
```python theme={null}
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
```python theme={null}
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) ](/ja/integrations/language-clients/python/advanced-inserting#file-inserts)を参照してください。
## Raw API
型変換を行わずに ClickHouse HTTP インターフェイスへ直接アクセスする必要がある高度なユースケースについては、[高度な使用方法 (Raw API)](/ja/integrations/language-clients/python/advanced-usage#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` 関数も提供します。
```python theme={null}
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 の同時実行ルール](/ja/integrations/language-clients/python/advanced-usage#managing-clickhouse-session-ids) は引き続き適用されます。
## ユーティリティクラスと関数
以下のモジュールは、クライアントアプリケーションで使用される追加の公開ヘルパーを提供します。
インストールされている 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 をマルチスレッド、マルチプロセス、非同期／イベント駆動のアプリケーションで使用する場合の詳細については、[高度な使用方法 (マルチスレッド、マルチプロセス、非同期／イベント駆動のユースケース) ](/ja/integrations/language-clients/python/advanced-usage#multithreaded-multiprocess-and-asyncevent-driven-use-cases)を参照してください。
## AsyncClient
ネイティブな asyncio の使用方法については、[高度な使用方法 (AsyncClient)](/ja/integrations/language-clients/python/advanced-usage#asyncclient)を参照してください。
## ClickHouse セッション ID の管理
マルチスレッドまたは同時実行のアプリケーションで ClickHouse セッション ID を管理する方法については、[高度な使用方法 (ClickHouse セッション ID の管理) ](/ja/integrations/language-clients/python/advanced-usage#managing-clickhouse-session-ids)を参照してください。
## HTTP接続プールのカスタマイズ
大規模なマルチスレッドアプリケーション向けにHTTP接続プールをカスタマイズする方法については、[高度な使用方法 (HTTP接続プールのカスタマイズ) ](/ja/integrations/language-clients/python/advanced-usage#customizing-the-http-connection-pool)を参照してください。