グローバル設定
common パッケージからアクセスできます。
これらの共通設定
autogenerate_session_id、product_name、readonly は、clickhouse_connect.get_client メソッドでクライアントを作成する前に、必ず 変更してください。クライアント作成後にこれらの設定を変更しても、既存のクライアントの動作には影響しません。圧縮
enable_http_compression を 1 に設定するか、ユーザーにクエリごとにこの設定を変更する権限が必要です。
圧縮は、clickhouse_connect.get_client ファクトリーメソッドの呼び出し時に compress パラメータで制御します。デフォルトでは compress は True に設定されており、デフォルトの圧縮設定が適用されます。query、query_np、query_df クライアントメソッドで実行されるクエリでは、ClickHouse Connect は Accept-Encoding header に
lz4、zstd、br (brotli ライブラリがインストールされている場合) 、gzip、deflate のエンコーディングを追加し、query クライアントメソッド (および間接的に query_np と query_df) で実行されるクエリに付与します。 (ほとんどのリクエストでは、ClickHouse
server は zstd で圧縮された payload を返します。) insert では、デフォルトで ClickHouse Connect は insert block を lz4 で圧縮し、Content-Encoding: lz4 HTTP header を送信します。
get_client の compress パラメータには、lz4、zstd、br、gzip のいずれかの圧縮方式を指定することもできます。その場合、その方式が insert とクエリ結果の両方に使用されます (ClickHouse server が対応している場合) 。必要な zstd および lz4 の圧縮ライブラリは、現在では ClickHouse Connect にデフォルトで含まれています。br/brotli を指定する場合は、brotli ライブラリを別途インストールする必要があります。
raw* クライアントメソッドでは、クライアント設定で指定した圧縮は使用されない点に注意してください。
また、gzip 圧縮の使用は推奨しません。データの圧縮・展開の両方で、他の選択肢より大幅に低速だからです。
HTTPプロキシサポート
urllib3 ライブラリを使用して基本的な HTTPプロキシサポートを提供します。標準の HTTP_PROXY および HTTPS_PROXY 環境変数を認識します。これらの環境変数を使用すると、clickhouse_connect.get_client メソッドで作成されたすべてのクライアントに適用される点に注意してください。クライアントごとに設定する場合は、get_client メソッドの http_proxy または https_proxy 引数を使用できます。HTTPプロキシサポートの実装の詳細については、urllib3 のドキュメントを参照してください。
SOCKSプロキシを使用するには、urllib3 の SOCKSProxyManager を pool_mgr 引数として get_client に渡します。これには、PySocks ライブラリを直接インストールするか、urllib3 依存関係の [socks] オプションを使用してインストールする必要があります。
「古い」JSONデータ型
Object (または Object('json')) データ型は非推奨であり、本番環境での使用は避けるべきです。ClickHouse Connect は後方互換性のため、このデータ型に対する限定的なサポートを引き続き提供しています。なお、このサポートには、「トップレベル」または「親」の JSON 値を辞書またはそれに相当する形式で返すことが想定されるクエリは含まれておらず、そのようなクエリでは例外が発生します。
「新しい」Variant/Dynamic/JSON データ型 (実験的機能)
clickhouse-connect は 0.8.0 リリース以降、新しい (これら自体も実験的な) ClickHouse の型 Variant、Dynamic、JSON を試験的にサポートしています。
使用上の注意
- JSON データは、Python の辞書、または JSON オブジェクト
{}を含む JSON 文字列として挿入できます。それ以外の形式の JSON データはサポートされていません。 - これらの型に対してサブカラム/パスを使用するクエリは、サブカラムの型を返します。
- その他の使用上の注意については、ClickHouse のメインのドキュメントを参照してください。
既知の制限事項
- これらの各型は、使用前に ClickHouse settings で有効にする必要があります。
- 「新しい」JSON 型は、ClickHouse 24.8 リリースから利用できます。
- 内部フォーマットの変更により、
clickhouse-connectが Variant 型と互換性を持つのは ClickHouse 24.7 リリース以降のみです。 - 返される JSON オブジェクトには、
max_dynamic_paths個までの要素しか含まれません (デフォルトは 1024) 。これは今後のリリースで修正される予定です。 Dynamicカラムへの insert では、常に Python の値の文字列表現が使用されます。これは https://github.com/ClickHouse/ClickHouse/issues/70395 が修正され次第、今後のリリースで修正される予定です。- 新しい型の実装は C コードで最適化されていないため、より単純で確立されたデータ型と比べて、パフォーマンスがやや低下する可能性があります。