ClickHouse / ClickHouse/clickhousectl
Document UTF-8 Query API input and native-client fallback
- Dominant language
- Rust
- Stars
- 74
- Forks
- 5
- Avg merge
- 2d 11h
- Merged PRs (30d)
- 196
Description
## Validated scope and current-PR plan — 2026-09-11
This section records the QA review and the current decision to finalize existing PRs without opening new PRs. It supersedes the proposed routing/fix suggestions in the original report below; the original observations are retained. Central plan: #757.
### Disposition
Deferred from this existing-PR finalization pass. Keep the issue open; no new PR is requested now. This is not a resolution, a severity downgrade, or a waiver of release acceptance.
### Validation and corrections
UTF-8 limitation is supported by the String input path; 4 MB rejection is live QA evidence, not independently remeasured. Document the exact API limit after confirming units and enforcement, and provide native-client guidance. This is not related to [#789](https://github.com/ClickHouse/clickhousectl/pull/789)’s local native-output contract.
---
## Original QA report
Found in the 2026-09-11 QA sweep of the combined PR stack at [`d2c37f81`](https://github.com/ClickHouse/clickhousectl/commit/d2c37f814fff53fe68d636e34103e2d0550bf84d), top PR #823, installed release build (package version still 0.4.2). Reproduced behaviour only; no implementation included.
Severity: medium; hits the README's own stdin-combining example.
```sh
printf 'INSERT INTO bigtab FORMAT CSV\n' | cat - big.csv | clickhousectl cloud service query --id "$SVC" # 4.9 MB
# Error: Query API returned HTTP 400 Bad Request: {"error":"Invalid data","details":[{"message":"sql is too large (maximum size is 4MB)","field":"sql"}]}
printf 'INSERT INTO rawbytes FORMAT RowBinary\n' | cat - rawbytes.rowbinary | clickhousectl cloud service query --id "$SVC"
# Error: stream did not contain valid UTF-8
```
The same RowBinary payload round-trips through `local client`. `service query` reads stdin into a `String`, so RowBinary/Native inserts and any row with a binary blob can never go through this path. The 30-second gateway timeout is documented with a rich native-client fallback message; the size cap and the UTF-8 restriction are documented nowhere.
Suggested: pre-check payload size and emit the same native-protocol fallback guidance used for `query_timeout`; document both limits next to the README stdin example; read stdin as bytes if the Query API accepts them, else document UTF-8-only.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the README stdin-combining example and the service query path that reads stdin into a String; verify the API size limit and UTF-8 behavior against the observed QA evidence. Document the confirmed limits and native-client fallback guidance next to that example, distinguishing service query from local client.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- api, cli, documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 65/100