From 985a92d98d751cd60a1c0ac01f775f1f0fabf32d Mon Sep 17 00:00:00 2001 From: Kaviraj Date: Mon, 22 Jun 2026 13:33:01 +0200 Subject: [PATCH 1/3] chore: link official specs of Native protocol and format Given the original PR on core got merged. Now we can link it in the docs repo https://github.com/ClickHouse/ClickHouse/pull/106720 Signed-off-by: Kaviraj --- docs/integrations/interfaces/tcp.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/integrations/interfaces/tcp.md b/docs/integrations/interfaces/tcp.md index 2085d026724..b51318a617d 100644 --- a/docs/integrations/interfaces/tcp.md +++ b/docs/integrations/interfaces/tcp.md @@ -8,4 +8,9 @@ doc_type: 'reference' --- -The native protocol is used in the [command-line client](/interfaces/cli), for inter-server communication during distributed query processing, and also in other C++ programs. Unfortunately, native ClickHouse protocol doesn't have formal specification yet, but it can be reverse-engineered from ClickHouse source code (starting [around here](https://github.com/ClickHouse/ClickHouse/tree/master/src/Client)) and/or by intercepting and analyzing TCP traffic. +The native protocol is used in the [command-line client](/interfaces/cli), for inter-server communication during distributed query processing, and also in other C++ programs. + +ClickHouse provides official specifications for the native protocol and the columnar format it carries: + +- [Native Protocol](/interfaces/specs/NativeProtocol) — packet framing, the connection state machine, version negotiation, and the body of every non-`Block` message. +- [Native Format](/interfaces/specs/NativeFormat) — the `Block` and column structure, the per-type encodings, and the compression frame. This format also appears outside the TCP protocol, for example with `FORMAT Native` over HTTP. From be697a25203901d571e846978070a69cf37f539d Mon Sep 17 00:00:00 2001 From: Kaviraj Date: Mon, 22 Jun 2026 13:35:35 +0200 Subject: [PATCH 2/3] chore: remove the deprecated TODO from floating exceptions Signed-off-by: Kaviraj --- plugins/floating-pages-exceptions.txt | 5 ----- 1 file changed, 5 deletions(-) diff --git a/plugins/floating-pages-exceptions.txt b/plugins/floating-pages-exceptions.txt index 0e6068e8df3..69e434951c2 100644 --- a/plugins/floating-pages-exceptions.txt +++ b/plugins/floating-pages-exceptions.txt @@ -20,8 +20,3 @@ use-cases/observability/clickstack/managed-onboarding/instrument-application.md use-cases/observability/clickstack/managed-onboarding/tuning-clickstack-schema.md use-cases/observability/clickstack/managed-onboarding/managed-getting-started.md -# NOTE(kavi): To be removed after core PRs are merged -# https://github.com/ClickHouse/ClickHouse/pull/106723 - -interfaces/specs/NativeProtocol.md -interfaces/specs/NativeFormat.md From 647706d2b6e5cb524ed87fa2bb62b466b1631a0a Mon Sep 17 00:00:00 2001 From: Kaviraj Date: Mon, 22 Jun 2026 14:03:37 +0200 Subject: [PATCH 3/3] chore: add specs to sidebar Signed-off-by: Kaviraj --- docs/integrations/interfaces/tcp.md | 2 +- sidebars.js | 10 ++++++++++ 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/integrations/interfaces/tcp.md b/docs/integrations/interfaces/tcp.md index b51318a617d..f1438dfb1b1 100644 --- a/docs/integrations/interfaces/tcp.md +++ b/docs/integrations/interfaces/tcp.md @@ -8,7 +8,7 @@ doc_type: 'reference' --- -The native protocol is used in the [command-line client](/interfaces/cli), for inter-server communication during distributed query processing, and also in other C++ programs. +The native protocol is used in the [command-line client](/interfaces/cli), for inter-server communication during distributed query processing, and also in some language clients (e.g. [clickhouse-go](/integrations/go#connection-details)). ClickHouse provides official specifications for the native protocol and the columnar format it carries: diff --git a/sidebars.js b/sidebars.js index 977e76e65e2..6e930aba098 100644 --- a/sidebars.js +++ b/sidebars.js @@ -963,6 +963,16 @@ const sidebars = { 'integrations/interfaces/arrowflight', ], }, + { + type: 'category', + label: 'Specifications', + collapsed: true, + collapsible: true, + items: [ + 'interfaces/specs/NativeProtocol', + 'interfaces/specs/NativeFormat', + ], + }, 'integrations/sql-clients/sql-console', 'interfaces/third-party/index', ],