clickhouse-js-node-coding/reference/compression.md

Compression

Applies to: all versions support boolean compression. The explicit codec object form, per-codec request options, and zstd support are a Node-only addition in @clickhouse/client >= 1.22.0; Brotli ({ codec: "br" }) is also added (any Node.js version, no minimum). Request compression is Node-only regardless of codec; response decompression on the web client is handled by the browser.

The client can compress the outgoing request (insert) body and ask the server to compress the response (read) body. Both are configured under compression on createClient.

Answer checklist

When answering compression questions, include the relevant points:

• The option shape is boolean | { codec }, not a bare string. true means gzip (backwards compatible); { codec: "zstd" } selects zstd. There is no compression: { request: "zstd" } shorthand — it must be { request: { codec: "zstd" } }.
• zstd is Node-only (@clickhouse/client) and requires Node.js >= 22.15.0 (the built-in zlib zstd APIs). On @clickhouse/client-web or an older Node runtime, requesting zstd throws a clear error at createClient.
• Supported codecs are gzip, zstd, and br (Brotli). Unlike zstd, br works on any supported Node.js version (it ships in zlib). Request-body compression is Node-only for every codec (the web client sends requests uncompressed); for responses, the web client rejects zstd but allows gzip/br, which the browser decompresses.
• The request object takes a per-codec tuning option: a level for gzip/zstd, a quality for br ({ codec: "br", quality }). Brotli defaults to quality 4 — zlib's brotli default of 11 is far too slow for a streaming insert.
• Response compression cannot be enabled for a readonly=1 user — the server rejects the required enable_http_compression setting change.
• Prefer zstd for write-heavy (insert) workloads: a similar-or-better ratio than gzip at materially lower CPU, and ClickHouse decompresses gzip single-threaded.

gzip (default, all versions)

import { createClient } from "@clickhouse/client";

const client = createClient({
  compression: {
    request: true, // compress insert bodies with gzip
    response: true, // ask the server for a gzip-compressed response
  },
});

request: true / response: true are equivalent to { codec: "gzip" }.

zstd (Node.js >= 22.15.0)

const client = createClient({
  compression: {
    request: { codec: "zstd" },
    response: { codec: "zstd" },
  },
});

You can mix codecs and directions, e.g. zstd inserts with uncompressed reads:

const client = createClient({
  compression: {
    request: { codec: "zstd" },
    // response omitted → uncompressed reads
  },
});

Brotli (any Node.js version)

const client = createClient({
  compression: {
    request: { codec: "br" }, // brotli insert bodies (quality 4 by default)
    response: { codec: "br" }, // ask the server for a brotli-compressed response
  },
});

Unlike zstd, Brotli needs no minimum Node.js version. Request-body compression is Node-only (the web client sends requests uncompressed); br responses also work on the web client, decompressed by the browser. Its tuning option is quality (0-11), not level:

const client = createClient({
  compression: {
    request: { codec: "br", quality: 6 },
  },
});

Request compression options (Node.js)

The request object accepts a per-codec tuning option — a level for gzip (zlib level) and zstd (zstd compression level), or a quality for br (Brotli quality, 0-11). When omitted, the codec default is used (Brotli defaults to 4). This applies to the request direction only; the response compression options are chosen by the ClickHouse server.

const client = createClient({
  compression: {
    request: { codec: "zstd", level: 19 }, // higher ratio, more CPU
  },
});

Common pitfalls

• compression: { request: "zstd" } is a type error. Use the object form: { request: { codec: "zstd" } }.
• zstd on the web client throws. @clickhouse/client-web does not compress request bodies, and zstd response handling depends on the browser; the web client rejects the zstd codec at createClient. Use Node, or gzip.
• zstd on Node < 22.15 throws at client creation, not deep inside a later insert/query. The error names the running Node version and tells you to use gzip instead.
• Response compression + readonly=1 user fails. Response decompression needs enable_http_compression=1, which a readonly user cannot set.