From d75e32c48c28369d6e857ba6a851188759bbe88e Mon Sep 17 00:00:00 2001 From: Shawn Chen Date: Wed, 23 Sep 2026 23:56:24 +0000 Subject: [PATCH] Open the README with a quick start that runs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The first snippet queried `url('https://example.com/logs.jsonl')`, three lines below "no server, no network". That URL 404s, so the first thing a reader copied failed with `Code: 86. RECEIVED_ERROR_FROM_REMOTE_IO_SERVER`. The snippet was right about what to show — querying JSON with no schema and no load step is the reason to reach for this driver — and wrong only about where the JSON came from. So it keeps its shape: a bound parameter, `JSONEachRow`, an aggregate. The data is now inline, through `format(JSONEachRow, ?)`, which needs no file and no network, and it groups rather than counting so the result is visibly the engine's work and not a JSON parser's. `format()` is also the only variant of this that runs verbatim out of a README. Two things nothing else in the README said: that there is no `Class.forName`, and that `chdb-examples/QuickStart.java` exists — now linked, not just named in the repository layout table. Everything else stays where it lives: the platform artifact ids in the support matrix, the coordinates in Installing, the URL forms in Connecting, the build commands in Building from source. The dependency is a link to `#installing`, not a second copy of the XML. Verified against 1.0.0-rc.1 resolved from maven.chdb.io: the block extracted from README.md verbatim compiles at `-source 11` — a text block would not have, and the support matrix promises Java 11 — and prints `/ 2`. Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 27 +++++++++++++++++++++------ 1 file changed, 21 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 000f786..b4056de 100644 --- a/README.md +++ b/README.md @@ -9,18 +9,33 @@ streaming, forward-only result sets over ClickHouse SQL. > public API is not frozen. See > [What works today](#what-works-today). +## Quick start + ```java -try (Connection connection = DriverManager.getConnection("jdbc:chdb::memory:"); +String logs = "{\"path\":\"/\",\"status\":200}{\"path\":\"/admin\",\"status\":403}{\"path\":\"/\",\"status\":200}"; + +try (Connection connection = DriverManager.getConnection("jdbc:chdb:"); PreparedStatement statement = connection.prepareStatement( - "SELECT count() FROM url(?, 'JSONEachRow') WHERE status = 200")) { - statement.setString(1, "https://example.com/logs.jsonl"); - try (ResultSet rs = statement.executeQuery()) { - rs.next(); - System.out.println(rs.getLong(1)); + "SELECT path, count() FROM format(JSONEachRow, ?) WHERE status = 200 GROUP BY path")) { + statement.setString(1, logs); + try (ResultSet results = statement.executeQuery()) { + while (results.next()) { + System.out.println(results.getString(1) + " " + results.getLong(2)); // / 2 + } } } ``` +One dependency ([Installing](#installing)) and that runs: JSON in, an aggregate out, with no +schema declared, no load step and no server — and no `Class.forName`, because the driver +registers itself and the first `getConnection` maps the engine into this JVM. + +Swap `format(JSONEachRow, ?)` for `file(?, 'JSONEachRow')` or `url(?, 'JSONEachRow')` and the +rest of the query is unchanged. That is the whole of it. + +[`QuickStart.java`](chdb-examples/src/main/java/org/chdb/examples/QuickStart.java) carries on +from here: the type matrix, `ResultSetMetaData`, and streaming a result larger than the heap. + ## Support matrix Every one of the four platforms builds, passes the full test suite on Java 11, 17, 21 and 25,