ClickHouse / ClickHouse/clickhousectl

Document UTF-8 Query API input and native-client fallback

Open Beginner friendly
#833 0 comments 0 reactions 0 assignees View on GitHub
bug cloud documentation
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.