Repository navigation
Description
Description
When a client is configured with ClientOptions().SetCompressionMethod(CompressionMethod::ZSTD), only the client → server direction actually uses ZSTD. The server → client direction still uses the server's default codec (LZ4).
The reason is that the native TCP query packet only carries a boolean "compression enabled" flag; the selected codec is never propagated to the server:
clickhouse/client.cpp:349-351—compression_is set toCompressionState::Enablefor any method other thanNone; the specific method is discarded.clickhouse/client.cpp:1087—WireFormat::WriteUInt64(*output_, compression_);writes only that enable flag.clickhouse/client.cpp:447—CompressedOutputcorrectly usesoptions_.compression_methodfor the outgoing (client → server) data blocks.
To make the server compress its responses with ZSTD, the client must send the network_compression_method (and, for a configured level, network_zstd_compression_level) setting in the per-query settings section of the query packet (clickhouse/client.cpp:1067-1080). It never does.
The read path is not broken — CompressedInput::Decompress (clickhouse/base/compressed.cpp:105-131) accepts both LZ4 and ZSTD method bytes — so nothing fails; the selected codec is just silently not honored in one direction.
Additionally, there is no option to configure a ZSTD compression level at all: ClientOptions (clickhouse/client.h:107) only exposes compression_method.
This is the C++ equivalent of ClickHouse/clickhouse-go#1993.
ClickHouse server version
26.7.5.10 (verified against a running server over the native protocol on port 9000).
Reproduction
The server-side effective value of network_compression_method for the query is what determines how the server compresses the result blocks it sends back, so it can be observed directly from the client:
#include <clickhouse/client.h>
#include <iostream>
using namespace clickhouse;
int main() {
Client client(ClientOptions()
.SetHost("localhost")
.SetPort(9000)
.SetCompressionMethod(CompressionMethod::ZSTD));
client.Select(
"SELECT name, value FROM system.settings WHERE name IN "
"('network_compression_method', 'network_zstd_compression_level')",
[](const Block& block) {
for (size_t i = 0; i < block.GetRowCount(); ++i) {
std::cout << (*block[0]->As<ColumnString>())[i] << " = "
<< (*block[1]->As<ColumnString>())[i] << std::endl;
}
});
return 0;
}Expected output (codec honored in both directions):
network_compression_method = ZSTD
network_zstd_compression_level = <configured level>
Actual output:
network_compression_method = LZ4
network_zstd_compression_level = 1
i.e. the server compresses everything it sends back to this client with LZ4, even though ZSTD was requested.
Suggested fix
In Client::Impl::SendQuery (clickhouse/client.cpp, per-query settings block around lines 1067-1080), when options_.compression_method != CompressionMethod::None and the setting is not already present in query.GetQuerySettings(), send:
network_compression_method="ZSTD"/"LZ4"matchingoptions_.compression_methodnetwork_zstd_compression_level= the configured level, if a newClientOptionsfield for it is added (e.g.SetCompressionLevel), when the method is ZSTD
Link
Original report against the Go client: ClickHouse/clickhouse-go#1993
Activity
polyglotAI-bot commentedon Nov 18, 2026
Recommendation: Keep open — maintainer decision, then review PR #568
PR #568 sends the selected codec, but with it every query of a user with
readonly = 1fails when that codec is not the server default (output below). Decide if the client sendsnetwork_compression_methodalways or only when the caller opts in. Then review PR #568: its test file needs a rebase onmaster.master: Reproduced on main —master58453c2: on ClickHouse 26.7.38, ZSTD is selected and the server uses LZ4; on 26.10.4, LZ4 is selected and the server uses ZSTD (program below).ClientOptionsfield, or a newCH_*option thatCH_USE_3X_APIenables). If the client always sends the setting, as PR Honor selected compression method for native TCP responses #568 does, the queries of areadonly = 1user fail when the codec is not the server default.ut/client_protocol_ut.cppdoes not apply tomaster. Related: Honor CompressionZSTD for native TCP response compression clickhouse-go#1993 (the same defect in the Go client), Add ZSTD compression #367 (added ZSTD for client-to-server blocks).Analysis: The query packet carries only the compression flag (
clickhouse/client.cpp:1104).compression_methodselects only the codec of the blocks that the client sends (clickhouse/client.cpp:347,:446). The per-query settings (clickhouse/client.cpp:1084-1096) never containnetwork_compression_method, so the server compresses its blocks with its own default. ClickHouse 26.9 changed that default from LZ4 (level 1) to ZSTD (level 3) (system.settings_changes): servers up to 26.8 (26.3 and 26.8 LTS in the CI matrix) ignore a ZSTD choice, and 26.9 and later ignore an LZ4 choice. The client decodes both codecs, so no error shows; a per-querynetwork_compression_methodsetting is a workaround for users that can change settings.ClientOptionshas no field for the ZSTD level (clickhouse/client.h:107).Reproduction: complete program and output
Built with the default options (2.x API), Release,
-DWITH_OPENSSL=ON. WithCompressionMethod::Nonethe server does not compress, so the value in the first line has no effect.Output on
master(58453c2), ClickHouse 26.10.4.207:Output on
master(58453c2), ClickHouse 26.7.38.18:Output with the library changes of PR #568 (
clickhouse/client.cpp,clickhouse/client.h) applied onmaster, ClickHouse 26.10.4.207:The same, ClickHouse 26.7.38.18:
Automated triage by Polyglot AI. Classification added on 2026-11-19. A maintainer makes the final decision.