Repository navigation
fix: return a clear error when Query over HTTP gets a non-Native format - #2140
Open
Indian-boult wants to merge 1 commit into
Open
Indian-boult wants to merge 1 commit into
Indian-boult wants to merge 1 commit into
Conversation
Over HTTP, a FORMAT clause in the query text takes priority over the default_format=Native that the connection sends, so the server sends the body in that format. Query decoded the body as Native anyway. JSONEachRow and CSV failed with a block decode error that did not tell the cause, and RowBinary gave an empty result and no error. Query now reads the X-ClickHouse-Format response header. When the header names a format other than Native or Null, Query reads at most 64 KiB of the body, closes it, puts the connection back in the pool and returns an error that names the format and points to QueryFormat. FORMAT Null and responses without the header keep the old behavior. Fixes ClickHouse#2130
Indian-boult
requested review from
a team,
kavirajk and
polyglotAI-bot
as code owners
November 18, 2026 04:23
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes #2130
Over HTTP,
Querydecoded every response body asNative.dialHttpputsdefault_format=Nativeon the connection URL, but aFORMATclause in the query text takes priority, so the server sends the body in that format.JSONEachRowandCSVthen failed withreadData: block decode for exception: unexpected value 34 for boolean, andRowBinarygave an empty result with no error.QueryRow,Selectanddatabase/sqlgo through the samehttpConnect.query.The server names the body format in the
X-ClickHouse-Formatresponse header. I checked it with curl against ClickHouse 26.10.4.207 with the parameters the driver sends. It isNativewith noFORMATclause, the format name as written for anyFORMATclause, also one placed beforeSETTINGS,Nullwith an empty body forFORMAT Null, and missing for statements without a result. It was the same withwait_end_of_query=1,send_progress_in_http_headers=1,compress=1and gzip.httpConnect.querynow reads this header aftersendQuery. When it names a format other thanNativeorNull, without regard to case,Queryreads at mostmaxCloseDrainBytesof the body, closes it, puts the healthy connection back in the pool withrelease(h, nil), the same ashttpFormatStream.Close, and returns this error.FORMAT Nullstays allowed because the body is empty and the native protocol also returns no rows. A response without the header keeps the old path.Execdoes not read the body and does not change.QueryFormatandInsertFormatdo not use this path. The change is aftersendQuery, away from the compression switch that #2121 changes.One behavior changes. Over HTTP, a
FORMATclause other thanNativeorNullnow gives this error also for an empty result, where before an emptyJSONEachRow,CSVorRowBinaryresult gave no rows and no error.tests/issues/issue_2130_test.goaddsTest2130forclickhouse.OpenandTest2130Stdfordatabase/sql. Over HTTP, theJSONEachRow,CSV,RowBinary, lowercaseformat jsoneachrowandFORMAT JSONEachRow SETTINGS max_threads = 1cases expect the exact error fromQuery,QueryRowandSelect, and fromQueryContextandQueryRowContext, with LZ4 and GZIP too. After each error the tests check that the connection is back in the pool and that the next query returns rows. The native protocol,Nativebodies,FORMAT NullandExecare control cases. Onmainthe 12 HTTP error cases fail and the control cases pass. With the fix all pass. The root package tests, the HTTP and format tests intests/, the HTTP tests intests/std/andtests/issues/pass against 26.10.4.207, exceptTest1421BatchFlushBrokenConn, which starts its own Docker container and was skipped.Checklist
Note
Medium Risk
Touches the core HTTP query path used by Query/QueryRow/Select, but the new branch is narrow and preserves connection pooling; empty non-Native results now error instead of returning no rows.
Overview
HTTP
Querynow inspectsX-ClickHouse-FormataftersendQueryinstead of always decoding the body as Native. When the header names a format other thanNativeorNull(case-insensitive), it partially drains the body, closes it, returns the connection to the pool, and returns an error that names the format and suggests removing theFORMATclause or usingQueryFormat.Previously, a
FORMATclause in the SQL could overridedefault_format=Native, leading to misleading decode errors or silent empty results for formats likeJSONEachRoworRowBinary.FORMAT Null, missing headers, and Native responses are unchanged.Adds
tests/issues/issue_2130_test.gocovering driver anddatabase/sqlpaths, multiple non-Native formats, compression, pool reuse after the error, and control cases (native protocol,Exec, etc.).Reviewed by Cursor Bugbot for commit d734e04. Bugbot is set up for automated code reviews on this repo. Configure here.