#### Node.js 固有の設定パラメーター
| 設定 | 説明 | デフォルト値 | 関連項目 | |
| ------------------------------------------------------------------------------------------ | --------------------------------------------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **max\_open\_connections**?: number | ホストごとに許可される接続済みソケットの最大数。 | `10` | - | |
| **tls**?: `{ **ca_cert**: Buffer, **cert**?: Buffer, **key**?: Buffer }` | TLS 証明書を設定します。 | - | [TLS ドキュメント](/docs/ja/integrations/language-clients/js/index#tls-certificates-nodejs-only) | |
| **keep\_alive**?: `{ **enabled**?: boolean, **idle_socket_ttl**?: number }` | - | - | [Keep Alive ドキュメント](/docs/ja/integrations/language-clients/js/index#keep-alive-configuration-nodejs-only) | |
| **http\_agent**?: http.Agent | https.Agent
### URL設定
### 接続
#### 接続情報を用意する
HTTP(S) で ClickHouse に接続するには、次の情報が必要です。
| Parameter(s) | Description |
| ------------------------- | --------------------------------------------------------- |
| `HOST` and `PORT` | 通常、TLS を使用する場合のポートは 8443、TLS を使用しない場合は 8123 です。 |
| `DATABASE NAME` | デフォルトでは `default` という名前のデータベースがあります。接続先のデータベース名を使用してください。 |
| `USERNAME` and `PASSWORD` | デフォルトのユーザー名は `default` です。用途に応じたユーザー名を使用してください。 |
ClickHouse Cloud サービスの詳細は、ClickHouse Cloud コンソールで確認できます。
サービスを選択し、**Connect** をクリックします。
#### 接続の概要
このクライアントは、HTTP または HTTPS プロトコル経由の接続を実装しています。RowBinary のサポートも進行中です。詳しくは[関連 issue](https://github.com/ClickHouse/clickhouse-js/issues/216)を参照してください。
次の例では、ClickHouse Cloud への接続を設定する方法を示します。`url` (プロトコルとポートを含む) および `password` の値は環境変数で指定し、`default` ユーザーを使用することを前提としています。
**例:** 設定に環境変数を使用して Node.js のクライアントインスタンスを作成します。
```ts theme={null}
import { createClient } from '@clickhouse/client'
const client = createClient({
url: process.env.CLICKHOUSE_HOST ?? 'http://localhost:8123',
username: process.env.CLICKHOUSE_USER ?? 'default',
password: process.env.CLICKHOUSE_PASSWORD ?? '',
})
```
クライアントリポジトリには、[ClickHouse Cloud でのテーブル作成](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/schema-and-deployments/create_table_cloud.ts)、[非同期 INSERT の使用](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/async_insert.ts) など、環境変数を使用するサンプルが複数あり、そのほかにも多数含まれています。
#### 接続プール (Node.js のみ)
リクエストごとに接続を確立するオーバーヘッドを避けるため、Clientは Keep-Alive メカニズムを利用して ClickHouse への接続プールを作成し、接続を再利用します。デフォルトでは Keep-Alive が有効になっており、接続プールのサイズは `10` に設定されていますが、[設定オプション](/docs/ja/integrations/language-clients/js/index#configuration) `max_open_connections` で変更できます。
ユーザーが `max_open_connections: 1` を設定しない限り、プール内の同じ接続が後続のクエリでも使用されるとは限りません。これが必要になることはまれですが、一時テーブルを使用する場合には必要になることがあります。
関連項目: [Keep-Alive の設定](/docs/ja/integrations/language-clients/js/index#keep-alive-configuration-nodejs-only)。
### Query ID
クエリまたはステートメントを送信するすべてのメソッド (`command`、`exec`、`insert`、`select`) は、結果に `query_id` を含みます。この一意の識別子はクエリごとにクライアントによって割り当てられ、[サーバー設定](/docs/ja/reference/settings/server-settings/settings) で有効になっていれば `system.query_log` からデータを取得したり、長時間実行中のクエリをキャンセルしたりする際に役立つ場合があります ([例](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/troubleshooting/cancel_query.ts) を参照) 。必要に応じて、`query_id` は `command`/`query`/`exec`/`insert` メソッドのパラメータでユーザーが上書きできます。
### すべてのクライアントメソッドに共通の基本パラメータ
すべてのClientメソッド ([query](/docs/ja/integrations/language-clients/js/index#query-method)/[command](/docs/ja/integrations/language-clients/js/index#command-method)/[insert](/docs/ja/integrations/language-clients/js/index#insert-method)/[exec](/docs/ja/integrations/language-clients/js/index#exec-method)) に適用できるパラメーターがいくつかあります。
```ts theme={null}
interface BaseQueryParams {
// ClickHouse settings that can be applied on query level.
clickhouse_settings?: ClickHouseSettings
// Parameters for query binding.
query_params?: Record
### クエリメソッド
これは、`SELECT` のようにレスポンスを返すステートメントのほとんどや、`CREATE TABLE` のような DDL の送信に使用するメソッドで、await する必要があります。返された結果セットは、アプリケーション側で処理することが想定されています。
#### 結果セットと行の抽象化
`ResultSet` には、アプリケーションでのデータ処理に便利なメソッドがいくつか用意されています。
Node.js の `ResultSet` 実装は内部で `Stream.Readable` を使用し、Web 版では Web API の `ReadableStream` を使用します。
`ResultSet` の `text` または `json` メソッドを呼び出すことで、クエリが返した行のセット全体をメモリに読み込んで処理できます。
`ResultSet` はレスポンスストリームを開いたまま保持するため、その間は基盤となる接続が使用中のままになります。そのため、できるだけ早く `ResultSet` の読み取りを開始してください。Clientは、アプリケーションのメモリ使用量が過大になる可能性を避けるため、受信データをバッファリングしません。
また、データが大きすぎて一度にメモリに収まらない場合は、`stream` メソッドを呼び出してストリーミングモードで処理できます。この場合、各レスポンス chunk は比較的小さな行の配列に変換され、1 回に 1 つの chunk ずつ処理されます (この配列のサイズは、Clientがサーバーから受信する chunk のサイズ (可変) と、個々の行のサイズに依存します) 。
どのフォーマットがこのケースのストリーミングに最適かを判断するには、[サポートされているデータフォーマット](/docs/ja/integrations/language-clients/js/index#supported-data-formats) の一覧を参照してください。たとえば、JSON オブジェクトをストリーミングしたい場合は、[JSONEachRow](/docs/ja/reference/formats/JSON/JSONEachRow) を選ぶと、各行が JS オブジェクトとしてパースされます。あるいは、よりコンパクトな [JSONCompactColumns](/docs/ja/reference/formats/JSON/JSONCompactColumns) フォーマットを選べば、各行はコンパクトな値の配列になります。関連項目: [ファイルのストリーミング](/docs/ja/integrations/language-clients/js/index#streaming-files-nodejs-only)。
### Insert メソッド
これはデータを挿入するための主要なメソッドです。
```ts theme={null}
export interface InsertResult {
query_id: string
executed: boolean
}
interface ClickHouseClient {
insert(params: InsertParams): Promise
#### Node.js における Insert メソッドとストリーミング
`insert` メソッドで指定する[データフォーマット](/docs/ja/integrations/language-clients/js/index#supported-data-formats)に応じて、`Stream.Readable` と通常の `Array
#### Web 版の制限
現在、`@clickhouse/client-web` では、insert は `Array
### command メソッド
これは、出力を持たないステートメントや、`FORMAT` 句を適用できない場合、あるいはレスポンス自体が不要な場合に使用できます。そのようなステートメントの例としては、`CREATE TABLE` や `ALTER TABLE` があります。
await する必要があります。
レスポンスストリームは直ちに破棄されるため、基盤となるソケットは解放されます。
```ts theme={null}
interface CommandParams extends BaseQueryParams {
// Statement to execute.
query: string
}
interface CommandResult {
query_id: string
}
interface ClickHouseClient {
command(params: CommandParams): Promise
### Exec メソッド
`query`/`insert` に当てはまらないカスタムクエリがあり、
その結果を扱いたい場合は、`command` の代わりに `exec` を使用できます。
`exec` は、アプリケーション側で必ず消費または破棄する必要がある、読み取り可能なストリームを返します。
```ts theme={null}
interface ExecParams extends BaseQueryParams {
// Statement to execute.
query: string
}
interface ClickHouseClient {
exec(params: ExecParams): Promise
### Ping
接続状態を確認するための `ping` メソッドは、サーバーに到達できる場合に `true` を返します。
サーバーに到達できない場合は、原因となったエラーも結果に含まれます。
```ts theme={null}
type PingResult =
| { success: true }
| { success: false; error: Error }
/** Parameters for the health-check request - using the built-in `/ping` endpoint.
* This is the default behavior for the Node.js version. */
export type PingParamsWithEndpoint = {
select: false
/** AbortSignal instance to cancel a request in progress. */
abort_signal?: AbortSignal
/** Additional HTTP headers to attach to this particular request. */
http_headers?: Record
### Close (Node.js のみ)
開いている接続をすべて閉じ、リソースを解放します。Web 版では no-op です。
```ts theme={null}
await client.close()
```
## ファイルストリーミング (Node.js のみ)
一般的なデータフォーマット (NDJSON、CSV、Parquet) を使ったファイルストリーミングの例が、client repository にいくつかあります。
* [NDJSON ファイルからのストリーミング](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/performance/insert_file_stream_ndjson.ts)
* [CSV ファイルからのストリーミング](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/performance/insert_file_stream_csv.ts)
* [Parquet ファイルからのストリーミング](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/performance/insert_file_stream_parquet.ts)
* [Parquet ファイルへのストリーミング](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/performance/select_parquet_as_file.ts)
他のフォーマットをファイルへストリーミングする場合も、Parquet とほぼ同様です。
異なるのは、`query` 呼び出しで使用するフォーマット (`JSONEachRow`、`CSV` など) と出力ファイル名だけです。
## サポートされるデータフォーマット
クライアントは、データフォーマットを JSON またはテキストとして扱います。
`format` に JSON 系のフォーマット (`JSONEachRow`、`JSONCompactEachRow` など) のいずれかを指定すると、クライアントは通信時にデータを serialize / deserialize します。
「raw」テキストフォーマット (`CSV`、`TabSeparated`、`CustomSeparated` 系) で提供されたデータは、追加の変換を行わずにそのまま送信されます。
## サポートされている ClickHouse データ型
### Date/Date32 型の注意点
クライアントは追加の型変換を行わずに値を挿入するため、`Date`/`Date32` 型のカラムには文字列としてしか挿入できません。
**例:** `Date` 型の値を挿入します。
[ソースコード](https://github.com/ClickHouse/clickhouse-js/blob/ba387d7f4ce375a60982ac2d99cb47391cf76cec/__tests__/integration/date_time.test.ts)
```ts theme={null}
await client.insert({
table: 'my_table',
values: [ { date: '2022-09-05' } ],
format: 'JSONEachRow',
})
```
ただし、`DateTime` または `DateTime64` カラムを使用している場合は、文字列と JS Date オブジェクトの両方を使用できます。JS Date オブジェクトは、`date_time_input_format` を `best_effort` に設定すれば、そのまま `insert` に渡せます。詳しくは、こちらの[例](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/insert_js_dates.ts)を参照してください。
### Decimal\* 型の注意事項
`JSON*` ファミリーのフォーマットを使って Decimal を挿入できます。たとえば、次のようなテーブルが定義されているとします。
```sql theme={null}
CREATE TABLE my_table
(
id UInt32,
dec32 Decimal(9, 2),
dec64 Decimal(18, 3),
dec128 Decimal(38, 10),
dec256 Decimal(76, 20)
)
ENGINE MergeTree()
ORDER BY (id)
```
文字列表現を使えば、精度を損なうことなく値を挿入できます。
```ts theme={null}
await client.insert({
table: 'my_table',
values: [{
id: 1,
dec32: '1234567.89',
dec64: '123456789123456.789',
dec128: '1234567891234567891234567891.1234567891',
dec256: '12345678912345678912345678911234567891234567891234567891.12345678911234567891',
}],
format: 'JSONEachRow',
})
```
ただし、`JSON*`フォーマットでデータをクエリすると、ClickHouse はデフォルトで Decimal を*数値*として返すため、精度が失われる可能性があります。これを避けるには、クエリ内で Decimal を文字列に CAST できます。
```ts theme={null}
await client.query({
query: `
SELECT toString(dec32) AS decimal32,
toString(dec64) AS decimal64,
toString(dec128) AS decimal128,
toString(dec256) AS decimal256
FROM my_table
`,
format: 'JSONEachRow',
})
```
詳しくは、[この例](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/insert_decimals.ts)を参照してください。
### 整数型: Int64, Int128, Int256, UInt64, UInt128, UInt256
サーバーはこれらを数値として受け取れますが、これらの型の最大値は `Number.MAX_SAFE_INTEGER` を超えるため、
整数オーバーフローを避ける目的で、`JSON*` 系の出力フォーマットでは文字列として返されます。
ただし、この動作は
[`output_format_json_quote_64bit_integers` 設定](/docs/ja/reference/settings/formats#output_format_json_quote_64bit_integers)
で変更できます。
**例:** 64 ビット整数の JSON 出力フォーマットを調整します。
```ts theme={null}
const resultSet = await client.query({
query: 'SELECT * from system.numbers LIMIT 1',
format: 'JSONEachRow',
})
expect(await resultSet.json()).toEqual([ { number: '0' } ])
```
```ts theme={null}
const resultSet = await client.query({
query: 'SELECT * from system.numbers LIMIT 1',
format: 'JSONEachRow',
clickhouse_settings: { output_format_json_quote_64bit_integers: 0 },
})
expect(await resultSet.json()).toEqual([ { number: 0 } ])
```
## ClickHouse の設定
クライアントは、[settings](/docs/ja/reference/settings/session-settings)
の仕組みを通じて ClickHouse の動作を調整できます。
設定はクライアントインスタンス単位で指定できるため、ClickHouse に送信されるすべてのリクエストに
適用されます:
```ts theme={null}
const client = createClient({
clickhouse_settings: {}
})
```
また、設定はリクエストレベルで指定することもできます。
```ts theme={null}
client.query({
clickhouse_settings: {}
})
```
サポートされているすべての ClickHouse settings を含む型宣言ファイルは、
[こちら](https://github.com/ClickHouse/clickhouse-js/blob/main/packages/client-common/src/settings.ts)で確認できます。
## 応用トピック
### パラメータ付きクエリ
パラメータ付きのクエリを作成し、クライアントアプリケーションから値を渡せます。これにより、クライアント側で
特定の動的な値を使ってクエリをフォーマットする必要がなくなります。
通常どおりにクエリを記述したら、アプリケーションのパラメータからクエリに渡したい値を、次の形式で
波かっこ内に配置します。
```text theme={null}
{
### 圧縮
注: リクエストの圧縮は現在 Web 版では利用できません。レスポンスの圧縮は通常どおり利用できます。Node.js 版は両方に対応しています。
大規模なデータセットをネットワーク経由で扱うデータアプリケーションでは、圧縮を有効にすることで効果が得られます。現在サポートされているのは、[zlib](https://nodejs.org/docs/latest-v14.x/api/zlib.html) を使用した `GZIP` のみです。
```typescript theme={null}
createClient({
compression: {
response: true,
request: true
}
})
```
設定パラメーターは次のとおりです:
* `response: true` は、ClickHouseサーバーが圧縮されたレスポンスボディを返すようにします。デフォルト値: `response: false`
* `request: true` は、クライアントのリクエストボディの圧縮を有効にします。デフォルト値: `request: false`
### ロギング (Node.js のみ)
### TLS 証明書 (Node.js のみ)
Node.js client は、basic (Certificate Authority のみ) TLS と
mutual (Certificate Authority とクライアント証明書) TLS の両方をオプションでサポートしています。
証明書が `certs` フォルダにあり、
CA ファイル名が `CA.pem` であると仮定した basic TLS の設定例:
```ts theme={null}
const client = createClient({
url: 'https://
### Keep-Alive の設定 (Node.js のみ)
クライアントは、基盤となる HTTP エージェントでデフォルトで Keep-Alive を有効にします。つまり、接続されたソケットは後続のリクエストで再利用され、`Connection: keep-alive` ヘッダーが送信されます。アイドル状態のソケットは、デフォルトでは 2500 ミリ秒のあいだ接続プールに保持されます ([このオプションの調整に関する注意事項](/docs/ja/integrations/language-clients/js/index#adjusting-idle_socket_ttl) を参照) 。
`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` は、`config.xml` を変更しなくても、[ClickHouse 23.11 より前のバージョンでは 3 秒まで短く設定される場合があります](https://github.com/ClickHouse/ClickHouse/commit/1685cdcb89fe110b45497c7ff27ce73cc03e82d1)。
#### トラブルシューティング
最新バージョンの client を使用していても `socket hang up` エラーが発生する場合は、次の対処方法を試してください。
* 少なくとも `WARN` のログレベル (デフォルト) でログを有効にしてください。これにより、application code 内に未消費または宙に浮いた stream がないか確認できます。こうした状態は server 側で socket が閉じられる原因になり得るため、transport layer が WARN レベルでログを出力します。client の設定でログを有効にするには、次のようにします。
```ts theme={null}
const client = createClient({
log: { level: ClickHouseLogLevel.WARN },
})
```
* 意図した設定が正しいクライアントインスタンスに適用されていることを確認してください。アプリケーション内に複数の client instance がある場合は、queries に使用しているものに正しい `keep_alive.idle_socket_ttl` の値が設定されているか再確認してください。
* client 設定の `keep_alive.idle_socket_ttl` を 500 ミリ秒短くしてください。状況によっては、たとえば client と server 間の network latency が高い場合、server がまもなく閉じる socket を送信リクエストが取得してしまう状況を避けるうえで有効です。
* このエラーが、データの入出力がない長時間実行クエリ中 (たとえば長時間実行される `INSERT FROM SELECT`) に発生する場合は、load balancer やその他の network components が長時間維持される connection や長時間実行中のリクエストを閉じている可能性があります。以下の ClickHouse settings を組み合わせて使い、長時間実行クエリ中にも何らかのデータが流入するようにしてみてください。
```ts theme={null}
const client = createClient({
// ここでは、5 分を超える execution time の queries があると想定しています
request_timeout: 400_000,
/** これらの settings を組み合わせることで、データの入出力がない長時間実行クエリにおける LB timeout の問題を回避できます。
* `INSERT FROM SELECT` などでは、connection が LB に idle と見なされ、突然閉じられる可能性があります。
* この場合、LB の idle connection timeout は 120 秒と想定し、安全な値として 110 秒を設定しています。 */
clickhouse_settings: {
send_progress_in_http_headers: 1,
http_headers_progress_interval_ms: '110000', // UInt64, 文字列として渡す必要があります
},
})
```
ただし、最近の Node.js バージョンでは、受信した headers の合計サイズに 16KB の制限がある点に注意してください。一定数の progress headers を受信すると (私たちのテストではおよそ 70～80 個) 、Exception が発生します。
また、on the wire での待機時間を完全になくす、まったく別のアプローチを取ることも可能です。これは、connection が失われても mutations がキャンセルされないという HTTP interface の「feature」を利用する方法です。詳細は [this example (part 2)](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/long_running_queries_timeouts.ts) を参照してください。
* Keep-Alive 機能は完全に無効化することもできます。この場合、client はすべての request に `Connection: close` header も追加し、基盤となる HTTP agent は connections を再利用しません。アイドル状態の sockets が存在しないため、`keep_alive.idle_socket_ttl` 設定は無視されます。その結果、リクエストごとに新しい connection を確立することになり、追加の overhead が発生します。
```ts theme={null}
const client = createClient({
keep_alive: {
enabled: false,
},
})
```
* `curl` などを使って、同じ ClickHouse instance と同じ network path (つまり同じマシンまたは同じ network segment、たとえば Kubernetes pod から) で簡単な command-line テストを実行し、Node.js 自体を含む network stack の残りの部分に問題がないか切り分けてください。
```sh theme={null}
curl -is --user '
### 読み取り専用ユーザー
[readonly=1 ユーザー](/docs/ja/concepts/features/configuration/settings/permissions-for-queries#readonly) でクライアントを使用する場合、レスポンス圧縮は `enable_http_compression` 設定が必要なため、有効にできません。次の設定ではエラーになります。
```ts theme={null}
const client = createClient({
compression: {
response: true, // won't work with a readonly=1 user
},
})
```
`readonly=1` ユーザーの制限についてさらに詳しく説明している[例](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/security/read_only_user.ts)を参照してください。
### パス名付きプロキシ
ClickHouse インスタンスがプロキシの背後にあり、たとえば `http://proxy:8123/clickhouse_server` のように URL にパス名が含まれている場合は、`pathname` 設定オプションに `clickhouse_server` を指定してください (先頭のスラッシュの有無は問いません) 。そうしないと、これを `url` に直接含めた場合、`database` オプションとして扱われます。複数のセグメントにも対応しており、たとえば `/my_proxy/db` のように指定できます。
```ts theme={null}
const client = createClient({
url: 'http://proxy:8123',
pathname: '/clickhouse_server',
})
```
### 認証付きリバースプロキシ
ClickHouse のデプロイメントの前段に認証付きリバースプロキシがある場合は、`http_headers` 設定を使って、そこで必要なヘッダーを指定できます。
```ts theme={null}
const client = createClient({
http_headers: {
'My-Auth-Header': '...',
},
})
```
### カスタム HTTP/HTTPS エージェント (実験的、Node.js のみ)
#### カスタムエージェントの使用例
証明書なしでカスタム HTTP または HTTPS Agent を使用する場合:
```ts theme={null}
const agent = new http.Agent({ // or https.Agent
keepAlive: true,
keepAliveMsecs: 2500,
maxSockets: 10,
maxFreeSockets: 10,
})
const client = createClient({
http_agent: agent,
})
```
basic TLS と CA証明書を使用したカスタムHTTPS Agent:
```ts theme={null}
const agent = new https.Agent({
keepAlive: true,
keepAliveMsecs: 2500,
maxSockets: 10,
maxFreeSockets: 10,
ca: fs.readFileSync('./ca.crt'),
})
const client = createClient({
url: 'https://myserver:8443',
http_agent: agent,
// With a custom HTTPS agent, the client won't use the default HTTPS connection implementation; the headers should be provided manually
http_headers: {
'X-ClickHouse-User': 'username',
'X-ClickHouse-Key': 'password',
},
// Important: authorization header conflicts with the TLS headers; disable it.
set_basic_auth_header: false,
})
```
相互TLSを使用したカスタムHTTPS Agent:
```ts theme={null}
const agent = new https.Agent({
keepAlive: true,
keepAliveMsecs: 2500,
maxSockets: 10,
maxFreeSockets: 10,
ca: fs.readFileSync('./ca.crt'),
cert: fs.readFileSync('./client.crt'),
key: fs.readFileSync('./client.key'),
})
const client = createClient({
url: 'https://myserver:8443',
http_agent: agent,
// With a custom HTTPS agent, the client won't use the default HTTPS connection implementation; the headers should be provided manually
http_headers: {
'X-ClickHouse-User': 'username',
'X-ClickHouse-Key': 'password',
'X-ClickHouse-SSL-Certificate-Auth': 'on',
},
// Important: authorization header conflicts with the TLS headers; disable it.
set_basic_auth_header: false,
})
```
証明書 *と* カスタム *HTTPS* Agent を併用する場合、TLS ヘッダーと競合するため、`set_basic_auth_header` 設定 (導入バージョン 1.2.0) でデフォルトの Authorization ヘッダーを無効にする必要がある可能性があります。TLS ヘッダーはすべて手動で指定する必要があります。
## 既知の制限事項 (Node.js/web)
* 結果セット用のデータマッパーは存在しないため、言語組み込みのプリミティブ型のみが使用されます。特定のデータ型マッパーについては、[RowBinary フォーマットのサポート](https://github.com/ClickHouse/clickhouse-js/issues/216)で対応が予定されています。
* [Decimal\* と Date\* / DateTime\* データ型に関する注意点](/docs/ja/integrations/language-clients/js/index#datedate32-types-caveats)がいくつかあります。
* JSON\* ファミリーのフォーマットを使用する場合、Int64+ 型の最大値は `Number.MAX_SAFE_INTEGER` を超えるため、Int32 を超える数値は文字列として表現されます。詳細は [整数型](/docs/ja/integrations/language-clients/js/index#integral-types-int64-int128-int256-uint64-uint128-uint256) セクションを参照してください。
## 既知の制限事項 (web)
* `select` クエリのストリーミングは動作しますが、`insert` では無効になっています (型レベルでも同様です) 。
* リクエストの圧縮は無効になっており、設定は無視されます。レスポンスの圧縮は動作します。
* ロギングにはまだ対応していません。
## パフォーマンス最適化のヒント
* アプリケーションのメモリ消費を抑えるには、大規模な insert (たとえばファイルからの insert) や、該当する場合は select でストリームを使用することを検討してください。イベント listener や同様のユースケースでは、[非同期 INSERT](/docs/ja/concepts/features/operations/insert/asyncinserts) も有力な選択肢です。これにより、クライアント側でのバッチ化を最小限に抑えたり、完全に不要にしたりできます。非同期 INSERT の例は [client repository](https://github.com/ClickHouse/clickhouse-js/tree/main/examples/node) にあり、ファイル名のプレフィックスとして `async_insert_` が使われています。
* client は、デフォルトではリクエストまたはレスポンスの圧縮を有効にしていません。ただし、大規模なデータセットを select または insert する場合は、`ClickHouseClientConfigOptions.compression` で有効にすることを検討できます (`request` のみ、`response` のみ、またはその両方) 。
* 圧縮には大きな性能上のペナルティがあります。`request` または `response` に対して有効にすると、それぞれ insert または select の速度に悪影響を与えますが、アプリケーションで転送されるネットワークトラフィックの量は削減されます。
## お問い合わせ
ご不明な点やサポートが必要な場合は、[Community Slack](https://clickhouse.com/slack) (`#clickhouse-js` チャンネル) または [GitHub issues](https://github.com/ClickHouse/clickhouse-js/issues) からお気軽にご連絡ください。