メインコンテンツまでスキップ
メインコンテンツまでスキップ

ClickHouse JS

ClickHouseに接続するための公式JSクライアントです。
クライアントはTypeScriptで書かれており、クライアントの公開APIの型定義を提供します。

依存関係はゼロで、最大のパフォーマンスを最適化しており、さまざまなClickHouseのバージョンや構成（オンプレミスの単一ノード、オンプレミスクラスター、ClickHouse Cloud）でテストされています。

異なる環境用に2つの異なるバージョンのクライアントが利用可能です：

  • @clickhouse/client - Node.jsのみ
  • @clickhouse/client-web - ブラウザ（Chrome/Firefox）、Cloudflareワーカー

TypeScriptを使用する場合は、少なくとも version 4.5 が必要で、これにより インラインインポートおよびエクスポート構文 が有効になります。

クライアントのソースコードは ClickHouse-JS GitHubリポジトリ で入手できます。

環境要件 (Node.js)​

Node.jsは、クライアントを実行するために環境に利用可能である必要があります。
クライアントは、すべての メンテナンスされている Node.jsリリースと互換性があります。

Node.jsのバージョンがEnd-Of-Lifeに近づくと、クライアントはそれへのサポートを終了します。これは過去のものと見なされ、安全ではないためです。

現在のNode.jsバージョンのサポート：

Node.jsバージョンサポートされている?
22.x✔
20.x✔
18.x✔
16.xベストエフォート

環境要件 (Web)​

クライアントのWebバージョンは、最新のChrome/Firefoxブラウザで公式にテストされており、React/Vue/AngularアプリケーションやCloudflareワーカーの依存関係として使用できます。

インストール​

最新の安定したNode.jsクライアントバージョンをインストールするには、次のコマンドを実行します：

Webバージョンのインストール：

ClickHouseとの互換性​

クライアントバージョンClickHouse
1.8.023.3+

クライアントは古いバージョンでも機能する可能性がありますが、これはベストエフォートのサポートであり、保証はされていません。もしClickHouseのバージョンが23.3よりも古い場合は、ClickHouseのセキュリティポリシーを参照し、アップグレードを検討してください。

例​

当社は、クライアントの使用シナリオのさまざまなケースを examples の中で取り上げることを目指しています。

概要は examples README で入手できます。

もし例や以下の文書に不明点や不足があれば、自由に ご連絡ください。

クライアントAPI​

明示的に異なると記載されていない限り、ほとんどの例はNode.jsおよびWebバージョンのクライアントの両方で互換性があります。

クライアントインスタンスの作成​

必要に応じて、createClientファクトリーを使ってクライアントインスタンスを作成できます：

環境がESMモジュールをサポートしていない場合は、CJS構文を代わりに使用できます：

クライアントインスタンスは、インスタンス化時に 事前設定 できます。

設定​

クライアントインスタンスを作成する際に、次の接続設定を調整できます：

設定説明デフォルト値詳細情報
url?: stringClickHouseインスタンスのURL。http://localhost:8123URL構成に関するドキュメント
pathname?: stringクライアントによって解析されたClickHouse URLに追加する任意のパス名。''パス名付きプロキシに関するドキュメント
request_timeout?: numberリクエストタイムアウト（ミリ秒単位）。30_000-
compression?: { **response**?: boolean; **request**?: boolean }圧縮を有効にします。-圧縮に関するドキュメント
username?: stringリクエストを行うユーザーの名前。default-
password?: stringユーザーパスワード。''-
application?: stringNode.jsクライアントを使用しているアプリケーションの名前。clickhouse-js-
database?: string使用するデータベース名。default-
clickhouse_settings?: ClickHouseSettingsすべてのリクエストに適用するClickHouseの設定。{}-
log?: { **LoggerClass**?: Logger, **level**?: ClickHouseLogLevel }内部クライアントログの設定。-ログに関するドキュメント
session_id?: string各リクエストに送信するオプションのClickHouseセッションID。--
keep_alive?: { **enabled**?: boolean }Node.jsとWebバージョンの両方でデフォルトで有効です。--
http_headers?: Record<string, string>ClickHouseリクエストのための追加のHTTPヘッダー。-認証付きリバースプロキシに関するドキュメント
roles?: string | string[]アウトゴーイングリクエストにアタッチするClickHouseのロール名。-HTTPインターフェースでのロールの使用

Node.js特有の設定パラメータ​

設定説明デフォルト値詳細情報
max_open_connections?: numberホストごとに許可する接続ソケットの最大数。10-
tls?: { **ca_cert**: Buffer, **cert**?: Buffer, **key**?: Buffer }TLS証明書の構成。-TLSに関するドキュメント
keep_alive?: { **enabled**?: boolean, **idle_socket_ttl**?: number }--Keep Aliveに関するドキュメント
http_agent?: http.Agent | https.Agent
Experimental feature. Learn more.
クライアント用のカスタムHTTPエージェント。-HTTPエージェントに関するドキュメント
set_basic_auth_header?: boolean
Experimental feature. Learn more.
ベーシック認証資格情報でAuthorizationヘッダーを設定します。trueHTTPエージェントドキュメントでのこの設定の使用

URL構成​

参考

URL構成は、常にハードコーディングされた値をオーバーライドし、この場合には警告がログに記録されます。

クライアントインスタンスのほとんどのパラメータをURLで構成することができます。URL形式は http[s]://[username:password@]hostname:port[/database][?param1=value1&param2=value2] です。ほとんどのケースで、特定のパラメータの名前は、設定オプションインターフェース内のそのパスを反映していますが、いくつかの例外があります。サポートされるパラメータは以下の通りです：

パラメータ型
pathname任意の文字列。
application_id任意の文字列。
session_id任意の文字列。
request_timeout非負の数。
max_open_connections非負の数、ゼロより大きい。
compression_requestブール値。下記参照 (1)
compression_responseブール値。
log_level許可される値: OFF, TRACE, DEBUG, INFO, WARN, ERROR。
keep_alive_enabledブール値。
clickhouse_setting_* または ch_*下記参照 (2)
http_header_*下記参照 (3)
(Node.jsのみ) keep_alive_idle_socket_ttl非負の数。
  • (1) ブール値の場合、有効な値は true/1 と false/0 です。
  • (2) clickhouse_setting_ または ch_ で始まる任意のパラメータは、このプレフィックスが削除され、残りがクライアントの clickhouse_settings に追加されます。たとえば、 ?ch_async_insert=1&ch_wait_for_async_insert=1 は次のように同じになります：

注意：clickhouse_settings のブール値は、URL内で 1/0 として渡す必要があります。

  • (3) (2) と同様ですが、 http_header 構成用です。たとえば、 ?http_header_x-clickhouse-auth=foobar は次のように相当します：

接続​

接続詳細を収集する​

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、TLSを使用しない場合は8123です。

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

  • USERNAMEとPASSWORD: デフォルトでは、ユーザー名はdefaultです。ご利用のケースに適したユーザー名を使用してください。

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

HTTPSを選択すると、詳細が例のcurlコマンドで提供されます。

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

接続の概要​

クライアントは、HTTP(S)プロトコルを介して接続を実装しています。RowBinaryのサポートは進行中であり、関連の問題を参照してください。

次の例は、ClickHouse Cloudに対する接続の設定方法を示しています。url（プロトコルとポートを含む）および password の値が環境変数を介して指定されていると仮定し、default ユーザーが使用されます。

例： 環境変数を使用してNode.jsクライアントインスタンスを作成します。

クライアントリポジトリには、環境変数を使用した複数の例が含まれています。たとえば、ClickHouse Cloudでのテーブルの作成、非同期挿入の使用、その他多数があります。

接続プール (Node.jsのみ)​

毎回リクエストごとに接続を確立するオーバーヘッドを避けるために、クライアントはClickHouseへの接続のプールを作成し、再利用します。Keep-Aliveメカニズムを利用しています。デフォルトでは、Keep-Aliveは有効で、接続プールのサイズは 10 に設定されていますが、max_open_connections 設定オプション を使って変更できます。

プール内の同じ接続が後続のクエリに使用される保証はありませんが、ユーザーが max_open_connections: 1 を設定した場合は、必要に応じて使用されることがあります。これは稀に必要ですが、ユーザーが一時テーブルを使用している場合には必要になることがあります。

さらに、Keep-Aliveの構成も参照してください。

クエリID​

クエリやステートメントを送信するすべてのメソッド（command、exec、insert、select）は、結果に query_id を提供します。このユニーク識別子は、クエリごとにクライアントによって割り当てられ、system.query_log からデータを取得する際に役立つ可能性があります。これは、サーバー設定で有効になっている場合、または長時間実行されているクエリをキャンセルする際に役立ちます（例を参照）。必要に応じて、query_id は command、query、exec、insert メソッドのパラメータでユーザーによって上書きすることができます。

ヒント

query_id パラメータを上書きしている場合は、各呼び出しに対してその一意性を確保する必要があります。ランダムUUIDは良い選択です。

すべてのクライアントメソッドの基本パラメータ​

すべてのクライアントメソッドに適用できるいくつかのパラメータがあります（query/command/insert/exec）。

クエリメソッド​

これは、SELECTなどの応答を持つ可能性のあるほとんどのステートメントや、CREATE TABLEのようなDDLを送信するために使用され、待機する必要があります。戻り値の結果セットはアプリケーションで消費されることが期待されます。

注記

データ挿入用には専用のメソッド insert があり、DDL用には command があります。

さらに情報： すべてのクライアントメソッドの基本パラメータ。

ヒント

query にはFORMAT句を指定しないでください。 format パラメータを使用してください。

結果セットと行の抽象化​

ResultSet は、アプリケーション内のデータ処理のためにいくつかの便利なメソッドを提供します。

Node.jsの ResultSet 実装は内部で Stream.Readable を使っていますが、WebバージョンはWeb APIの ReadableStream を使用しています。

ResultSet を消費するには、 text または json メソッドを呼び出して、クエリによって返されたすべての行のセットをメモリにロードできます。

ResultSet はできるだけ早く消費し始めるべきです。これはレスポンスストリームをオープンに保ち、結果として基礎となる接続をビジー状態にします。クライアントはアプリケーションが潜在的に過剰なメモリ使用量を避けるために、受信データをバッファリングしません。

一方、大きすぎて一度にメモリに収まらない場合は、 stream メソッドを呼び出し、ストリーミングモードでデータを処理できます。レスポンスチャンクのそれぞれは、各チャンクのサイズによって異なるおおよそ小さな行の配列に変換され、サーバーから受け取ります（一度に一つのチャンク）。チャンクサイズは特定のチャンク、個別の行のサイズに依存します。

ストリーミングに適したデータフォーマットのリストについては、サポートされるデータフォーマットを参照して、あなたのケースに最適なフォーマットを決定してください。たとえば、JSONオブジェクトをストリーミングしたい場合は、JSONEachRowを選択すると、各行がJSオブジェクトとして解析されます。また、各行が値のコンパクトな配列になるよりコンパクトなJSONCompactColumnsフォーマットも選択できます。ストリーミングファイルも参照してください。streaming files。

参考

ResultSet またはそのストリームが完全に消費されない場合、非活動期間の request_timeout の後に破棄されます。

例: (Node.js/Web) JSONEachRowフォーマットでの結果データセットを持つクエリで、ストリーム全体を消費し、内容をJSオブジェクトとして解析する。
ソースコード。

例: (Node.jsのみ) JSONEachRowフォーマットでのクエリ結果をストリーミングする、古典的な on('data') アプローチを使用。これは for await const 構文と交換可能です。
ソースコード。

例: (Node.jsのみ) CSVフォーマットでのクエリ結果をストリーミングする、古典的な on('data') アプローチを使用。これは for await const 構文と交換可能です。
ソースコード。

例: (Node.jsのみ) JSONEachRowフォーマットでJSオブジェクトとしてストリーミングクエリ結果を消費する、 for await const 構文を使用。これは古典的な on('data') アプローチと交換可能です。
ソースコード。

注記

for await const 構文は、 on('data') アプローチよりもコードが少なくなりますが、パフォーマンスに悪影響を与える可能性があります。
詳細は Node.jsリポジトリのこの問題 を参照してください。

例: (Webのみ) オブジェクトの ReadableStream を反復処理します。

挿入メソッド​

これはデータ挿入のための主要なメソッドです。

戻り値の型は最小限です。サーバーからデータが返されないことを期待しており、レスポンスストリームは即座に排出されます。

挿入メソッドに空の配列が提供された場合、INSERT文はサーバーに送信されません。その代わり、メソッドは即座に { query_id: '...', executed: false } で解決されます。この場合、メソッドのパラメータに query_id が指定されていなければ、結果の中で空の文字列になります。クライアントによって生成されたランダムUUIDを返すと、そんな query_id のクエリは system.query_log テーブルに存在しないため、混乱を避けるためです。

もし挿入文がサーバーに送信された場合、 executed フラグは true になります。

挿入メソッドとNode.jsでのストリーミング​

これは、指定された データフォーマット に応じて Stream.Readable またはプレーンな Array<T> のいずれかとして動作することができます。ファイルストリーミングに関するこのセクションも参照してください。file streaming。

挿入メソッドは待機されるべきですが、入力ストリームを指定し、ストリームが完成したときに insert 操作を待機することも可能です（これにより、insert プロミスが解決されます）。これは、イベントリスナーや類似のシナリオで有用である可能性がありますが、エラー処理はクライアント側で多くのエッジケースがあるため、重要でない場合があります。その代わりに、非同期挿入の使用を検討してください。これについては この例が示されています。

ヒント

挿入文がこのメソッドでモデル化するのが難しい場合は、commandメソッドの使用を検討してください。

INSERT INTO ... VALUES や INSERT INTO ... SELECT の例での使用方法も面白いと思います。

さらに情報： すべてのクライアントメソッドの基本パラメータ。

参考

abort_signal でキャンセルされたリクエストは、挿入が行われなかったことを保証するものではありません。サーバーはキャンセルの前にストリーミングされたデータの一部を受け取っている可能性があるためです。

例: (Node.js/Web) 値の配列を挿入します。
ソースコード。

例: (Node.jsのみ) CSVファイルからのストリームを挿入します。
ソースコード。また、ファイルストリーミングも参照してください。

例: 挿入文から特定のカラムを除外します。

次のようなテーブル定義があるとします：

特定のカラムのみを挿入します：

特定のカラムを除外します：

詳細については ソースコード を参照してください。

例: クライアントインスタンスに提供されたデータベースとは異なるデータベースに挿入します。
ソースコード。

Webバージョンの制限​

現在、@clickhouse/client-webでの挿入はArray<T>およびJSON*形式のみがサポートされています。 ストリームの挿入は、ブラウザの互換性が低いため、まだウェブバージョンではサポートされていません。

その結果、ウェブバージョンのInsertParamsインターフェースはNode.jsバージョンとは少し異なり、valuesはReadonlyArray<T>型のみに制限されています：

これは将来的に変更される可能性があります。詳細については、すべてのクライアントメソッドの基本パラメーターを参照してください。

コマンドメソッド​

出力がないステートメントや、形式句が適用できない場合、またはレスポンスにまったく興味がない場合に使用できます。このようなステートメントの例として、CREATE TABLEやALTER TABLEがあります。

awaitが必要です。

レスポンスストリームは即座に破棄され、基盤となるソケットは解放されます。

詳細については、すべてのクライアントメソッドの基本パラメーターを参照してください。

例: (Node.js/Web) ClickHouse Cloudでテーブルを作成します。 ソースコード。

例: (Node.js/Web) セルフホストのClickHouseインスタンスでテーブルを作成します。 ソースコード。

例: (Node.js/Web) INSERT FROM SELECT

参考

abort_signalでキャンセルされたリクエストは、ステートメントがサーバーによって実行されなかったことを保証しません。

Execメソッド​

query/insertに適合しないカスタムクエリがあり、その結果に興味がある場合、commandの代わりにexecを使用できます。

execは、アプリケーション側で消費するか、破棄する必要があるリーダブルストリームを返します。

詳細については、すべてのクライアントメソッドの基本パラメーターを参照してください。

ストリームの戻り値の型はNode.jsとWebバージョンで異なります。

Node.js:

Web:

Ping​

接続状態を確認するために提供されるpingメソッドは、サーバーに到達可能であればtrueを返します。

サーバーに到達できない場合、基盤となるエラーも結果に含まれます。

Pingは、アプリケーションのスタート時にサーバーが利用可能かどうかを確認するのに役立つツールです。特にClickHouse Cloudでは、インスタンスがアイドル状態でping後に起動する可能性があります。

例: (Node.js/Web) ClickHouseサーバーインスタンスにpingを送信します。注意: Webバージョンでは、キャプチャされたエラーは異なります。 ソースコード。

注意: /pingエンドポイントはCORSを実装していないため、Webバージョンでは同様の結果を得るためにSELECT 1を使用します。

Close (Node.jsのみ)​

すべてのオープン接続を閉じ、リソースを解放します。Webバージョンでは効果がありません。

ストリーミングファイル (Node.jsのみ)​

クライアントリポジトリには、一般的なデータ形式（NDJSON、CSV、Parquet）のいくつかのファイルストリーミングの例があります。

他の形式をファイルにストリーミングするのはParquetと似たようなもので、唯一の違いはquery呼び出しで使用される形式（JSONEachRow、CSVなど）と出力ファイル名のみです。

サポートされているデータ形式​

クライアントはデータ形式をJSONまたはテキストとして扱います。

formatをJSONファミリーのいずれか（JSONEachRow、JSONCompactEachRowなど）として指定すると、クライアントはワイヤー経由の通信中にデータをシリアライズおよびデシリアライズします。

「生」のテキスト形式（CSV、TabSeparatedおよびCustomSeparatedファミリー）で提供されるデータは、追加の変換なしでワイヤーを介して送信されます。

ヒント

JSONを一般的な形式として扱うことと、ClickHouse JSON形式との間で混乱が生じる可能性があります。

クライアントは、JSONEachRowなどの形式でストリーミングJSONオブジェクトをサポートしています（他のストリーミングフレンドリーな形式のテーブル概要も参照；クライアントリポジトリのselect_streaming_ 例も参照）。

ClickHouse JSONやその他のいくつかの形式は、レスポンス内で単一オブジェクトとして表され、クライアントによってストリーミングできないことに注意してください。

フォーマット入力 (配列)入力 (オブジェクト)入力/出力 (ストリーム)出力 (JSON)出力 (テキスト)
JSON❌✔️❌✔️✔️
JSONCompact❌✔️❌✔️✔️
JSONObjectEachRow❌✔️❌✔️✔️
JSONColumnsWithMetadata❌✔️❌✔️✔️
JSONStrings❌❌️❌✔️✔️
JSONCompactStrings❌❌❌✔️✔️
JSONEachRow✔️❌✔️✔️✔️
JSONEachRowWithProgress❌️❌✔️ ❗- 詳細は以下を参照✔️✔️
JSONStringsEachRow✔️❌✔️✔️✔️
JSONCompactEachRow✔️❌✔️✔️✔️
JSONCompactStringsEachRow✔️❌✔️✔️✔️
JSONCompactEachRowWithNames✔️❌✔️✔️✔️
JSONCompactEachRowWithNamesAndTypes✔️❌✔️✔️✔️
JSONCompactStringsEachRowWithNames✔️❌✔️✔️✔️
JSONCompactStringsEachRowWithNamesAndTypes✔️❌✔️✔️✔️
CSV❌❌✔️❌✔️
CSVWithNames❌❌✔️❌✔️
CSVWithNamesAndTypes❌❌✔️❌✔️
TabSeparated❌❌✔️❌✔️
TabSeparatedRaw❌❌✔️❌✔️
TabSeparatedWithNames❌❌✔️❌✔️
TabSeparatedWithNamesAndTypes❌❌✔️❌✔️
CustomSeparated❌❌✔️❌✔️
CustomSeparatedWithNames❌❌✔️❌✔️
CustomSeparatedWithNamesAndTypes❌❌✔️❌✔️
Parquet❌❌✔️❌✔️❗- 詳細は以下を参照

Parquetでは、SELECTの主な使用ケースは、結果のストリームをファイルに書き込むことになるでしょう。クライアントリポジトリの例を参照してください。

JSONEachRowWithProgressは、ストリーム内で進行状況を報告することをサポートする出力専用形式です。詳細についてはこの例を参照してください。

ClickHouseの入力および出力形式の完全なリストは ここで入手できます。

サポートされているClickHouseデータ型​

注記

関連するJS型は、すべてのJSON*形式に関連していますが、すべてを文字列として表す形式（例:JSONStringEachRow）を除きます。

型ステータスJS型
UInt8/16/32✔️number
UInt64/128/256✔️ ❗- 以下を参照string
Int8/16/32✔️number
Int64/128/256✔️ ❗- 以下を参照string
Float32/64✔️number
Decimal✔️ ❗- 以下を参照number
Boolean✔️boolean
String✔️string
FixedString✔️string
UUID✔️string
Date32/64✔️string
DateTime32/64✔️ ❗- 以下を参照string
Enum✔️string
LowCardinality✔️string
Array(T)✔️T[]
(新) JSON✔️object
Variant(T1, T2...)✔️T (バリアントによって異なる)
Dynamic✔️T (バリアントによって異なる)
Nested✔️T[]
Tuple✔️Tuple
Nullable(T)✔️TまたはnullのJS型
IPv4✔️string
IPv6✔️string
Point✔️[ number, number ]
Ring✔️Array<Point>
Polygon✔️Array<Ring>
MultiPolygon✔️Array<Polygon>
Map(K, V)✔️Record<K, V>

ClickHouseのサポートされている形式の完全なリストは ここで入手できます。

Date/Date32型の注意点​

クライアントは追加の型変換なしで値を挿入するため、Date/Date32型のカラムには文字列としてのみ挿入できます。

例: Date型の値を挿入します。 ソースコード。

ただし、DateTimeまたはDateTime64型のカラムを使用している場合、文字列とJS日付オブジェクトの両方を使用できます。JS日付オブジェクトは、そのままinsertに渡すことができ、date_time_input_formatがbest_effortに設定されています。詳細についてはこの例を参照してください。

Decimal*型の注意点​

JSON*ファミリー形式を使用してDecimalを挿入することが可能です。次のように定義されたテーブルがあるとします：

値を文字列表現を使用して精度損失なく挿入できます：

ただし、JSON*形式でデータをクエリすると、ClickHouseはデフォルトでDecimalsを_数字_として返すため、精度が損なわれる可能性があります。これを避けるために、クエリでDecimalsを文字列にキャストできます：

詳細についてはこの例を参照してください。

整数型: Int64, Int128, Int256, UInt64, UInt128, UInt256​

サーバーは数値として受け入れることができますが、JSON*ファミリー出力形式ではオーバーフローを避けるために文字列として返されます。これらの型の最大値はNumber.MAX_SAFE_INTEGERよりも大きいためです。

ただし、この動作はoutput_format_json_quote_64bit_integers設定で変更できます。

例: 64ビット数のJSON出力形式を調整します。

ClickHouseの設定​

クライアントは設定メカニズムを介してClickHouseの動作を調整できます。 設定はクライアントインスタンスレベルで設定でき、すべてのリクエストに対して適用されます。

または、リクエストレベルで設定できます：

サポートされているClickHouse設定のすべての型宣言ファイルは こちらで見つけることができます。

参考

クエリが行われるユーザーが設定を変更するための十分な権限を持っていることを確認してください。

高度なトピック​

パラメーター付きクエリ​

パラメーター付きのクエリを作成し、クライアントアプリケーションからその値を渡すことができます。これにより、クライアント側で特定の動的値でクエリをフォーマットすることを避けることができます。

クエリを通常通りフォーマットし、アプリパラメーターからクエリに渡す値を波括弧内に以下の形式で置きます：

ここで：

  • name — プレースホルダー識別子。
  • data_type - アプリパラメーター値のデータ型。

例: パラメーター付きクエリ。 ソースコード。

詳細については https://clickhouse.com/docs/interfaces/cli#cli-queries-with-parameters-syntax を確認してください。

圧縮​

注意: リクエストの圧縮は現在Webバージョンで利用できません。レスポンスの圧縮は通常通り機能します。Node.jsバージョンは両方をサポートしています。

大規模データセットをワイヤー経由で処理するアプリケーションは、圧縮を有効にすることで利点を得ることができます。現在、サポートされているのはGZIPのみで、zlibを使用します。

構成パラメーターは次の通りです：

  • response: trueは、ClickHouseサーバーに圧縮されたレスポンスボディで応答するように指示します。デフォルト値: response: false
  • request: trueは、クライアントリクエストボディの圧縮を有効にします。デフォルト値: request: false

ロギング (Node.jsのみ)​

参考

ロギングは実験的機能であり、将来的に変更される可能性があります。

デフォルトのロガー実装は、stdoutにconsole.debug/info/warn/errorメソッドを介してログレコードを出力します。 LoggerClassを提供することでロギングロジックをカスタマイズでき、levelパラメーター（デフォルトはOFF）を介して希望のログレベルを選択できます。

現在、クライアントは以下のイベントをログに記録します：

  • TRACE - Keep-Aliveソケットのライフサイクルに関する低レベルの情報
  • DEBUG - レスポンス情報（認証ヘッダーとホスト情報は除く）
  • INFO - 主に未使用で、クライアントが初期化されると現在のログレベルが表示されます
  • WARN - 非致命的なエラー；pingリクエストの失敗が警告としてログに記録され、基盤となるエラーが返された結果に含まれます
  • ERROR - query/insert/exec/commandメソッドからの致命的なエラー、例えばリクエストの失敗など

デフォルトのロガー実装はこちらで見つけることができます。

TLS証明書 (Node.jsのみ)​

Node.jsクライアントは、オプションで基本（証明書機関のみ）および相互（証明書機関およびクライアント証明書）TLSをサポートします。

基本TLSの構成例。証明書がcertsフォルダーにあり、CAファイル名がCA.pemであると仮定します：

クライアント証明書を使用した相互TLS構成の例：

基本的なTLSと相互TLSの完全な例については基本と相互をリポジトリで参照してください。

Keep-Aliveの構成 (Node.jsのみ)​

クライアントはデフォルトで基盤となるHTTPエージェントのKeep-Aliveを有効にしているため、接続されたソケットはその後のリクエストに再利用され、Connection: keep-aliveヘッダーが送信されます。アイドル状態のソケットはデフォルトで2500ミリ秒接続プールに保持されます（このオプションの調整に関するノートを参照）。

keep_alive.idle_socket_ttlはサーバー/LBの設定よりもかなり低い値にする必要があります。主な理由は、HTTP/1.1がサーバーにソケットをクライアントに通知せずに閉じることを許可するためです。サーバーまたはロードバランサーがクライアントの前に接続を閉じる場合、クライアントが閉じたソケットを再利用しようとしてsocket hang upエラーが発生する可能性があります。

keep_alive.idle_socket_ttlを変更する場合、サーバー/LBのKeep-Alive設定と常に同期させ、常にそれよりも低く設定して、サーバーがオープン接続を先に閉じないようにする必要があります。

idle_socket_ttlの調整​

クライアントはkeep_alive.idle_socket_ttlを2500ミリ秒に設定しています。これは安全なデフォルトとみなされます; サーバー側では、keep_alive_timeoutがClickHouseのバージョン23.11以前で3秒以下に設定されている場合がありますが、config.xmlの変更なしで行われます。

危険

パフォーマンスに満足していて、問題が発生しない場合は、keep_alive.idle_socket_ttl設定の値を増やさないことをお勧めします。この設定を増やすと、潜在的な「Socket hang-up」エラーが発生する可能性があります。さらに、アプリケーションが多くのクエリを送信し、クエリ間のダウンタイムがあまりない場合、デフォルト値は十分です。ソケットが長時間アイドル状態になることはなく、クライアントはそれらをプール内に保持します。

サーバーレスポンスヘッダーで正しいKeep-Aliveタイムアウト値を確認するには、以下のコマンドを実行します。

レスポンスでConnectionとKeep-Aliveヘッダーの値を確認してください。例えば：

この場合、keep_alive_timeoutは10秒であり、keep_alive.idle_socket_ttlを9000ミリ秒または9500ミリ秒に増加させて、アイドル状態のソケットをデフォルトよりも少し長く開いたままにすることができます。サーバーがクライアントよりも先に接続を閉じる場合に発生する可能性のある「Socket hang-up」エラーに注意し、エラーが消えるまで値を下げてください。

Keep-Aliveのトラブルシューティング​

Keep-Aliveを使用しているときにsocket hang upエラーが発生する場合は、次のオプションでこの問題を解決できます：

  • ClickHouseサーバー設定でkeep_alive.idle_socket_ttl設定をわずかに減らします。クライアントとサーバーの間に高いネットワーク遅延がある場合、サーバーが閉じようとしているソケットを取得した場合に発生する可能性があります。この場合、keep_alive.idle_socket_ttlを200〜500ミリ秒減らすことが有効な場合があります。

  • このエラーが、データが出入りしないまま長時間実行されているクエリ（例えば、長時間のINSERT FROM SELECT）中に発生する場合、ロードバランサーがアイドル接続を閉じている可能性があります。この場合、長時間実行されるクエリの間にデータを強制的に送信することをお勧めします。これを次のClickHouse設定の組み合わせを使用して行うことができます：

    ただし、最近のNode.jsバージョンで受信するヘッダーの合計サイズには制限があり、特定の進捗ヘッダーを受信後、約70〜80回のテストまで例外が発生します。

    また、ワイヤ上の待機時間を完全に回避するまったく異なるアプローチを利用することも可能です。この機能により、接続が失われた場合に変異がキャンセルされることはありません。詳細についてはこの例（パート2）を参照してください。

  • Keep-Alive機能を完全に無効にすることも可能です。この場合、クライアントはすべてのリクエストにConnection: closeヘッダーを追加し、基盤となるHTTPエージェントは接続を再利用しません。keep_alive.idle_socket_ttl設定は無視され、アイドル状態のソケットは存在しなくなります。これにより、すべてのリクエストに新しい接続を確立する追加のオーバーヘッドが発生します。

読み取り専用ユーザー​

readonly=1 ユーザーを使用してクライアントを使用すると、レスポンス圧縮は有効にできません。これは、enable_http_compression設定が必要です。この構成はエラーになります：

詳細なreadonly=1ユーザーの制限事項についてはこの例を参照してください。

パス名を持つプロキシ​

ClickHouseインスタンスがプロキシの背後にあり、URLにパス名がある場合（例えば、http://proxy:8123/clickhouse_serverのように）、`clickhouse_server`を`pathname`構成オプションとして指定します（先頭スラッシュがあってもなくても可）。そうでなければ、`url`に直接指定すると、`database`オプションとみなされます。複数のセグメントがサポートされています。例：`/my_proxy/db`。

認証のあるリバースプロキシ​

ClickHouseデプロイの前に認証を持つリバースプロキシがある場合、http_headers設定を使用して、そこに必要なヘッダーを提供できます。

カスタム HTTP/HTTPS エージェント (実験的, Node.js のみ)​

危険

これは実験的な機能であり、将来のリリースで後方互換性のない方法で変更される可能性があります。クライアントが提供するデフォルトの実装と設定は、ほとんどのユースケースに対して十分であるはずです。この機能は、本当に必要な場合にのみ使用してください。

デフォルトでは、クライアントはクライアント設定（max_open_connections, keep_alive.enabled, tls など）で提供された設定を使用して、基礎となる HTTP(s) エージェントを構成し、ClickHouse サーバーへの接続を処理します。さらに、TLS 証明書が使用される場合、基礎となるエージェントは必要な証明書で構成され、正しい TLS 認証ヘッダーが適用されます。

1.2.0以降、カスタム HTTP(s) エージェントをクライアントに提供して、デフォルトの基礎エージェントを置き換えることが可能です。これは、複雑なネットワーク構成の場合に便利です。カスタムエージェントが提供された場合、次の条件が適用されます：

  • max_open_connections および tls オプションは 無効 となり、クライアントによって無視されます。これは基礎エージェントの構成の一部だからです。
  • keep_alive.enabled は Connection ヘッダーのデフォルト値だけを調整します（true -> Connection: keep-alive, false -> Connection: close）。
  • アイドルキープアライブソケット管理はまだ機能します（これはエージェントに結びついているのではなく、特定のソケットに結びついているため）が、keep_alive.idle_socket_ttl の値を 0 に設定することで、完全に無効にすることが可能になりました。

カスタムエージェント使用例​

証明書なしでカスタム HTTP(s) エージェントを使用する：

基本的な TLS と CA 証明書を使用したカスタム HTTPS エージェント：

相互 TLS を使用したカスタム HTTPS エージェント：

証明書 および カスタム HTTPS エージェントを使用する場合、TLS ヘッダーと競合するため、デフォルトの認証ヘッダーを set_basic_auth_header 設定（1.2.0で導入）で無効にする必要があるでしょう。すべての TLS ヘッダーは手動で提供する必要があります。

既知の制限 (Node.js/Web)​

  • 結果セットのデータマッパーはないため、言語のプリミティブのみが使用されます。特定のデータ型マッパーは、RowBinary 形式のサポートで計画されています。
  • 一部の Decimal* と Date* / DateTime* データ型に関する注意事項 があります。
  • JSON* 系フォーマットを使用している場合、Int32 よりも大きい数は文字列として表現されます。これは、Int64+ 型の最大値が Number.MAX_SAFE_INTEGER より大きいためです。詳細は 整数型 セクションをご覧ください。

既知の制限 (Web)​

  • SELECT クエリのストリーミングは機能しますが、INSERT では無効になっています（タイプレベルでも）。
  • リクエスト圧縮は無効で、構成は無視されます。レスポンス圧縮は機能します。
  • ロギングサポートはまだありません。

パフォーマンス最適化のためのヒント​

  • アプリケーションのメモリ消費を減らすためには、大きな INSERT (例えばファイルから) や SELECT の際にストリームを使用することを検討してください。イベントリスナーやそれに類するユースケースでは、非同期 INSERT がもう一つの良い選択肢となり、クライアント側のバッチ処理を最小限に抑えるか、完全に回避することができます。非同期 INSERT の例は、クライアントリポジトリ に、ファイル名のプレフィックスが async_insert_ として提供されています。
  • クライアントはデフォルトでリクエストまたはレスポンス圧縮を有効にしません。ただし、大規模なデータセットを選択または挿入する際に、ClickHouseClientConfigOptions.compression を介して有効にすることを検討できます（リクエストまたはレスポンスのいずれか、または両方のために）。
  • 圧縮は重大なパフォーマンスペナルティを伴います。リクエストまたはレスポンスで圧縮を有効にすると、それぞれの SELECT または INSERT の速度に悪影響を与えるが、アプリケーションによって転送されるネットワークトラフィックの量を減少させます。

お問い合わせ​

ご質問がある場合や支援が必要な場合は、コミュニティ Slack （#clickhouse-js チャンネル）や GitHub Issues を通じてお気軽にお問い合わせください。