ClickHouse JS
ClickHouseに接続するための公式JSクライアントです。
このクライアントはTypeScriptで書かれており、クライアントの公開APIに対する型定義を提供します。
依存関係はなく、最大のパフォーマンスに最適化されており、さまざまなClickHouseのバージョンおよび構成（オンプレミスのシングルノード、オンプレミスのクラスター、ClickHouse Cloud）でテストされています。
さまざまな環境用に2つの異なるバージョンのクライアントがあります：
@clickhouse/client- Node.js専用@clickhouse/client-web- ブラウザ（Chrome/Firefox）、Cloudflareワーカー
TypeScriptを使用する場合は、少なくともバージョン4.5であることを確認してください。このバージョンではインラインインポートおよびエクスポート構文が有効になります。
クライアントのソースコードはClickHouse-JS GitHubリポジトリで入手できます。
環境要件 (Node.js)
クライアントを実行するためには、環境にNode.jsが必要です。
クライアントはすべてのメンテナンスされているNode.jsリリースと互換性があります。
Node.jsのバージョンがエンドオブライフに近づくと、クライアントはそのサポートを終了します。これは時代遅れであり、安全でないと見なされるためです。
現在の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.0 | 23.3+ |
おそらくクライアントは古いバージョンでも動作しますが、これはベストエフォートのサポートであり、保証はされません。ClickHouseのバージョンが23.3未満の場合は、ClickHouseのセキュリティポリシーを参照し、アップグレードを検討してください。
例
クライアントの使用に関するさまざまなシナリオを、クライアントリポジトリの例でカバーすることを目指しています。
概要は例のREADMEで入手可能です。
例や以下のドキュメントに不明瞭な点や欠落がある場合は、お問い合わせください。
クライアントAPI
ほとんどの例は、明示的に異なると記載されていない限り、Node.jsおよびWebバージョンのクライアントの両方と互換性があります。
クライアントインスタンスの作成
createClientファクトリーを使用して、必要なだけのクライアントインスタンスを作成できます：
環境がESMモジュールをサポートしていない場合は、代わりにCJS構文を使用できます：
クライアントインスタンスは、インスタンス化中に事前設定できます。
設定
クライアントインスタンスを作成する際に、以下の接続設定を調整できます：
| 設定 | 説明 | デフォルト値 | その他 |
|---|---|---|---|
| url?: string | ClickHouseインスタンスのURL。 | http://localhost:8123 | URL設定ドキュメント |
| pathname?: string | クライアントがクリックハウスのURLを解析した後に追加するオプションのパス名。 | '' | パス名付きプロキシに関するドキュメント |
| request_timeout?: number | リクエストのタイムアウト（ミリ秒）。 | 30_000 | - |
compression?: { **response**?: boolean; **request**?: boolean } | 圧縮を有効にする。 | - | 圧縮に関するドキュメント |
| username?: string | リクエストを行うユーザーの名前。 | default | - |
| password?: string | ユーザーパスワード。 | '' | - |
| application?: string | Node.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ヘッダーを設定します。 | true | HTTPエージェントドキュメントでのこの設定の使用 |
URL設定
URL設定は常にハードコードされた値を上書きし、この場合は警告がログに記録されます。
ほとんどのクライアントインスタンスパラメータはURLで構成可能です。URLの形式はhttp[s]://[username:password@]hostname:port[/database][?param1=value1¶m2=value2]です。ほとんどの場合、特定のパラメータ名はそのパスが設定オプションインターフェースでの位置を反映しており、いくつかの例外があります。次のパラメータがサポートされています：
| パラメータ | タイプ |
|---|---|
pathname | 任意の文字列。 |
application_id | 任意の文字列。 |
session_id | 任意の文字列。 |
request_timeout | 非負の数。 |
max_open_connections | 非負の数、ゼロより大きい。 |
compression_request | boolean。以下を参照（1） |
compression_response | boolean。 |
log_level | 許可されている値：OFF、TRACE、DEBUG、INFO、WARN、ERROR。 |
keep_alive_enabled | boolean。 |
clickhouse_setting_*またはch_* | 以下を参照（2） |
(Node.js専用)keep_alive_idle_socket_ttl | 非負の数。 |
- (1) booleanの場合、有効な値は
true/1およびfalse/0です。 - (2)
clickhouse_setting_またはch_で始まる任意のパラメータは、このプレフィックスが削除され、残りがクライアントのclickhouse_settingsに追加されます。たとえば、?ch_async_insert=1&ch_wait_for_async_insert=1は次のようになります：
注意：clickhouse_settingsのboolean値は、URLで1/0として渡す必要があります。
- (3) (2)と似ていますが、
http_header設定用です。たとえば、?http_header_x-clickhouse-auth=foobarは次のようになります：
接続
接続情報の収集
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からデータを取得するのに役立ちます。また、長時間実行されているクエリをキャンセルするためにも使用できます（例を参照）。必要に応じて、ユーザーはcommand/query/exec/insertメソッドのパラメータでquery_idを上書きすることができます。
query_idパラメータを上書きする場合は、各呼び出しに対して一意であることを確認する必要があります。ランダムUUIDが良い選択です。
すべてのクライアントメソッドのベースパラメータ
すべてのクライアントメソッドに適用できるいくつかのパラメータがあります（query/command/insert/exec）。
クエリメソッド
これは、SELECTのように応答を持つ可能性のあるほとんどの文や、CREATE TABLEのようなDDLを送信するために使用され、awaitする必要があります。返される結果セットは、アプリケーションで消費することが期待されています。
他にも、すべてのクライアントメソッドのベースパラメータも参照してください。
queryにFORMAT句を指定しないでください。代わりにformatパラメータを使用してください。
結果セットと行の抽象化
ResultSetは、アプリケーションでのデータ処理のための便利なメソッドをいくつか提供します。
Node.jsのResultSet実装はStream.Readableを使用していますが、Web版はWeb APIのReadableStreamを使用しています。
ResultSetは、ResultSet上でtextまたはjsonメソッドを呼び出すことで消費でき、クエリによって返されたすべての行をメモリにロードします。
ResultSetは可能な限り早く消費を開始する必要があります。なぜなら、これによって応答ストリームがオープンされたままとなり、したがって基盤となる接続がビジーになります。クライアントは、アプリケーションによる潜在的な過剰なメモリ使用を避けるために、受信データをバッファリングしません。
代わりに、メモリに一度に収まらないほど大きい場合は、streamメソッドを呼び出してストリーミングモードでデータを処理できます。応答の各チャンクは、代わりに比較的小さな行の配列に変換されます（この配列のサイズは、サーバーからクライアントが受信する特定のチャンクのサイズによって変わり、個々の行のサイズにも依存します）。
どのデータ形式があなたのケースにとって最適かを判断するためには、サポートされているデータ形式のリストを参照してください。たとえば、JSONオブジェクトをストリーミングしたい場合は、JSONEachRowを選択できます。この場合、各行はJSオブジェクトとして解析されます。または、よりコンパクトなJSONCompactColumns形式を選ぶこともできます。この場合、各行は値のコンパクトな配列になります。ストリーミングファイルについても参照してください。Node.js専用のストリーミングファイル。
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を反復処理します。
挿入メソッド
これはデータ挿入用の主要なメソッドです。
戻り値の型は最小限で、サーバーからデータが返されることは期待しておらず、応答ストリームを即座に消費します。
挿入メソッドに空の配列が提供された場合、挿入ステートメントはサーバーに送信されず、その代わりにメソッドはすぐに{ query_id: '...', executed: false }で解決されます。この場合、もしquery_idがメソッドパラメータに提供されていなければ、結果の中の値は空の文字列になります。これは、クライアントによって生成されたランダムUUIDを返すことが混乱を招く可能性があるためです。そのため、このようなquery_idを持つクエリはsystem.query_logテーブルに存在しません。
挿入ステートメントがサーバーに送信された場合、executedフラグはtrueになります。
Insert method and streaming in Node.js
Stream.Readable または プレイン Array<T> と連携可能で、これは insert メソッドに指定された データフォーマット に依存します。また、ファイルストリーミングに関するこのセクションも参照してください。
Insert メソッドは await されるべきですが、入力ストリームを指定した後、ストリーム完了時に insert 操作を await することも可能です（これにより insert プロミスも解決します）。これはイベントリスナーや同様のシナリオにおいて便利かもしれませんが、クライアント側で多くのエッジケースを伴うエラーハンドリングは、やや非トリビアルです。代わりに、非同期挿入 の使用を検討してください。この例に示されています。
このメソッドでモデル化するのが難しいカスタム INSERT ステートメントがある場合、コマンドメソッドの使用を検討してください。
INSERT INTO ... VALUES や INSERT INTO ... SELECT の例での使用方法を参照できます。
他のお知らせ: すべてのクライアントメソッドのための基本パラメータ。
abort_signal でキャンセルされたリクエストは、サーバーがキャンセル前にストリーミングデータの一部を受信している可能性があるため、データの挿入が行われていないことを保証しません。
例: (Node.js/Web) 値の配列を挿入します。 ソースコード。
例: (Node.js のみ) CSV ファイルからのストリームを挿入します。 ソースコード。 また、ファイルストリーミングも参照してください。
例: 挿入ステートメントから特定のカラムを除外します。
次のようなテーブル定義があるとします:
特定のカラムのみを挿入します:
特定のカラムを除外します:
詳細については、ソースコードを参照してください。
例: クライアントインスタンスに提供されたのとは異なるデータベースに挿入します。 ソースコード。
Web version limitations
現在、@clickhouse/client-web での挿入は、Array<T> と JSON* フォーマットのみで機能します。
ストリームの挿入は、ブラウザの互換性が悪いため、ウェブ版ではまだサポートされていません。
そのため、ウェブ版の InsertParams インターフェイスは Node.js 版とは少し異なります。
values は ReadonlyArray<T> 型のみに制限されます:
これは将来的に変更される可能性があります。他のお知らせ: すべてのクライアントメソッドのための基本パラメータ。
Command method
出力のないステートメント、フォーマット句が適用できない場合、またはレスポンスにまったく興味がない場合に使用できます。そのようなステートメントの例は CREATE TABLE または ALTER TABLE です。
await されるべきです。
レスポンスストリームは即座に破棄されるため、基盤となるソケットは解放されます。
他のお知らせ: すべてのクライアントメソッドのための基本パラメータ。
例: (Node.js/Web) ClickHouse Cloud にテーブルを作成します。 ソースコード。
例: (Node.js/Web) セルフホスト ClickHouse インスタンスにテーブルを作成します。 ソースコード。
例: (Node.js/Web) SELECT から INSERT します。
abort_signal でキャンセルされたリクエストは、サーバーでステートメントが実行されなかったことを保証しません。
Exec method
query / insert に収まらないカスタムクエリがあり、結果に関心がある場合は、command の代わりに exec を使用できます。
exec は読み取り可能なストリームを返しますが、これはアプリケーション側で消費または破棄されなければなりません。
他のお知らせ: すべてのクライアントメソッドのための基本パラメータ。
ストリームの戻り型は、Node.js とウェブ版で異なります。
Node.js:
ウェブ:
Ping
接続状況を確認するために提供された ping メソッドは、サーバーに到達可能な場合は true を返します。
サーバーに到達できない場合、基盤となるエラーが結果に含まれます。
Ping は、特に ClickHouse Cloud でインスタンスがアイドリングしており、Ping の後に起動するため、アプリケーション開始時にサーバーが利用可能かどうかを確認するための便利なツールです。
例: (Node.js/Web) ClickHouse サーバーインスタンスに Ping を送信します。NB: ウェブバージョンでは、キャプチャされたエラーは異なる場合があります。 ソースコード。
NB: /ping エンドポイントが CORS を実装していないため、ウェブ版はシンプルな SELECT 1 を使用して同様の結果を達成します。
Close (Node.js only)
すべてのオープン接続を閉じ、リソースを解放します。ウェブ版では何も実行しません。
Streaming files (Node.js only)
クライアントリポジトリ内には、一般的なデータフォーマット (NDJSON, CSV, Parquet) を使用したいくつかのファイルストリーミングの例があります。
他のフォーマットをファイルにストリーミングするのも Parquet に似た手法で行うことができ、唯一の違いは query コールに使用されるフォーマット（JSONEachRow, CSV, など）と出力ファイル名になります。
Supported Data formats
クライアントは、データフォーマットを 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 の場合、選択の主な用途は、結果のストリームをファイルに書き込むことになるでしょう。クライアントリポジトリ内の例を参照してください。
JSONEachRowWithProgress は、ストリーム内での進捗報告をサポートする出力専用フォーマットです。詳細についてはこの例を参照してください。
ClickHouse の入力および出力フォーマットの全リストは、こちらで利用可能です。
Supported ClickHouse data types
関連する 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[] |
| (new) JSON | ✔️ | object |
| Variant(T1, T2...) | ✔️ | T (バリアントに依存) |
| Dynamic | ✔️ | T (バリアントに依存) |
| Nested | ✔️ | T[] |
| Tuple | ✔️ | Tuple |
| Nullable(T) | ✔️ | T 用の JS タイプまたは null |
| 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 types caveats
クライアントは値を追加の型変換なしで挿入するため、Date / Date32 型のカラムは文字列としてのみ挿入できます。
例: Date 型の値を挿入します。
ソースコード。
ただし、DateTime または DateTime64 カラムを使用している場合は、文字列と JS Date オブジェクトの両方を使用できます。JS Date オブジェクトは、date_time_input_format を best_effort に設定して、insert にそのまま渡すことができます。詳細については、この例を参照してください。
Decimal* types caveats
JSON* ファミリーのフォーマットを使用して Decimals を挿入することが可能です。次のようなテーブルが定義されていると仮定します:
値を文字列表現を用いて精度損失なしに挿入することができます:
ただし、JSON* フォーマットでデータを問い合わせると、ClickHouse はデフォルトでは Decimals を 数値 として返すため、精度が失われる可能性があります。これを避けるために、クエリで Decimals を文字列に変換することができます:
詳細については、この例を参照してください。
Integral types: Int64, Int128, Int256, UInt64, UInt128, UInt256
サーバーが数値として受け入れることができる一方で、これらの型の最大値が Number.MAX_SAFE_INTEGER よりも大きいため、JSON* ファミリーの出力フォーマットでは文字列として返されます。
ただし、この動作は output_format_json_quote_64bit_integers 設定 によって変更できます。
例: 64 ビット数値のための JSON 出力フォーマットを調整します。
ClickHouse settings
クライアントは設定メカニズムを介して ClickHouse の動作を調整できます。 設定はクライアントインスタンスレベルで設定でき、すべてのリクエストに適用されます:
またはリクエストレベルで設定を構成できます:
サポートされているすべての ClickHouse 設定を含む型宣言ファイルは、こちらで見つけることができます。
クエリが実行されるユーザーには、設定を変更する十分な権利があることを確認してください。
Advanced topics
Queries with parameters
パラメータを持つクエリを作成し、クライアントアプリケーションからそれらに値を渡すことができます。これにより、クライアント側で特定の動的値を持つクエリをフォーマットすることが避けられます。
クエリを通常通りフォーマットし、アプリのパラメータからクエリに渡す値を次の書式で中括弧内に配置します:
ここで:
name— プレースホルダー識別子。data_type- アプリパラメータ値の データ型。
例: パラメータを持つクエリ。 ソースコード。
詳細については https://clickhouse.com/docs/interfaces/cli#cli-queries-with-parameters-syntax を参照してください。
Compression
NB: リクエスト圧縮は現在ウェブ版では利用できません。レスポンス圧縮は通常通り機能します。Node.js 版は両方をサポートしています。
大規模データセットを通信を介して処理するデータアプリケーションは、圧縮を有効にすることで恩恵を受けることができます。現在、 GZIP のみが、zlib を使用してサポートされています。
設定パラメータは次のとおりです:
response: trueは、ClickHouse サーバーに圧縮されたレスポンスボディで応答するように指示します。デフォルト値:response: falserequest: trueは、クライアントリクエストボディの圧縮を有効にします。デフォルト値:request: false
Logging (Node.js only)
ロギングは実験的な機能であり、将来的に変更される可能性があります。
デフォルトのロガー実装は、console.debug/info/warn/error メソッドを介してログレコードを stdout に出力します。
LoggerClass を提供することでロギングロジックをカスタマイズでき、希望するログレベルを level パラメータで選択できます（デフォルトは OFF）:
現在のところ、クライアントは次のイベントをログに記録します：
TRACE- Keep-Alive ソケットのライフサイクルに関する低レベルの情報DEBUG- レスポンス情報（認証ヘッダーやホスト情報は除外）INFO- 主に未使用で、クライアントが初期化されると現在のログレベルを印刷しますWARN- 非致命的なエラー; 失敗したpingリクエストは警告としてログに記録されます。ERROR-query/insert/exec/commandメソッドからの致命的エラー、失敗したリクエストなど。
デフォルトの Logger 実装は こちら で確認できます。
TLS certificates (Node.js only)
Node.js クライアントは、基本的な (証明書機関のみ) および相互 (証明書機関とクライアント証明書) TLS をオプションでサポートします。
基本的な TLS 構成の例、certs フォルダーに証明書があり、CA ファイル名が CA.pem の場合:
クライアント証明書を使用した相互 TLS 構成の例:
基本的な TLSと相互 TLSのフルサンプルは、リポジトリ内でそれぞれこちらとこちらで確認できます。
Keep-Alive configuration (Node.js only)
クライアントは、デフォルトで基盤となる 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 構成と同期させる必要があります。これは、その値が 常に低く なるべきであり、サーバーが最初にオープン接続を閉じないことを保証します。
Adjusting 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 バージョンでは受信したヘッダーの合計サイズには 16KB の制限があります。ヘッダーの進捗が受信された後、私たちのテストでは約 70～80 が受信され、その後例外が生成されます。
まったく異なるアプローチを使用することも可能で、ワイヤ上での待機時間を完全に回避することができます。接続が失われたときにミューテーションがキャンセルされないという HTTP インターフェースの「機能」を活用することで実現できます。詳細については、この例（パート 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 ソケット管理は引き続き機能しますが（これはエージェントではなく特定のソケット自体に tied されていますが）、
keep_alive.idle_socket_ttl値を0に設定することで完全に無効にすることができます。
カスタムエージェント使用例
証明書なしでカスタム HTTP(s) エージェントを使用する：
基本的な TLS と CA 証明書を使用したカスタム HTTPS エージェント：
相互 TLS を使用したカスタム HTTPS エージェント：
証明書とカスタム HTTPS エージェントを使用する場合、デフォルトの認証ヘッダーを set_basic_auth_header 設定（1.2.0 で導入されました）を介して無効にする必要がある可能性が高いです。すべての TLS ヘッダーは手動で提供される必要があります。
既知の制限 (Node.js/Web)
- 結果セットに対するデータマッパーはないため、言語のプimitivesのみが使用されます。特定のデータ型マッパーは、RowBinary フォーマットサポートが計画されています。
- 一部の Decimal* および Date* / DateTime* データ型の注意点 があります。
- JSON* ファミリ形式を使用する場合、Int32 より大きな数字は文字列として表されます。これは、Int64+ 型の最大値が
Number.MAX_SAFE_INTEGERより大きいためです。詳細については、整数型 セクションを参照してください。
既知の制限 (Web)
- 選択クエリのストリーミングは機能しますが、挿入時（型レベルでも）は無効です。
- リクエスト圧縮は無効で、設定は無視されます。レスポンス圧縮は機能します。
- 現在のところログ記録サポートはありません。
パフォーマンス最適化のためのヒント
- アプリケーションのメモリ消費を削減するために、大きな挿入（たとえばファイルから）や必要に応じてセレクト用のストリームを使用することを検討してください。イベントリスナーや同様のユースケースに対しては、非同期挿入がもう一つの良い選択肢であり、クライアント側でのバッチ処理を最小限に抑えるか、完全に回避することができます。非同期挿入の例は、クライアントリポジトリにあり、
async_insert_がファイル名のプレフィックスです。 - クライアントはデフォルトでリクエストまたはレスポンス圧縮を有効にしません。しかし、大きなデータセットを選択または挿入する場合は、
ClickHouseClientConfigOptions.compressionを介して有効にすることを検討してください（requestまたはresponse、または両方に対して）。 - 圧縮はパフォーマンスに大きな影響を与えます。
requestまたはresponseに対して有効にすると、それぞれの選択または挿入の速度に悪影響を与えますが、アプリケーションによって転送されるネットワークトラフィックの量は減少します。
お問い合わせ
ご質問やサポートが必要な場合は、コミュニティ Slack（#clickhouse-js チャンネル）または GitHub issues を通じてお気軽にお問い合わせください。