fix(jdbc-v2): support explicit FORMAT JSON queries

Author: 014-code

CHANGELOG.md

@@ -4,6 +4,11 @@
 
 ### Bug Fixes 
 
+- **[jdbc-v2]** Fixed explicit `FORMAT JSON` queries failing in `executeQuery()` with an unsupported output-format
+  error. The driver now exposes the server-rendered JSON as a streaming, single-column `results` string `ResultSet`,
+  with one result row per response line, matching the legacy JDBC behavior. Queries without an explicit text format
+  continue to use the typed `RowBinaryWithNamesAndTypes` path. (https://github.com/ClickHouse/clickhouse-java/issues/2715)
+
 - **[client-v2]** Fixed binary varint decoding for length and count fields so overflowing or overlong values fail with an `IOException` instead of being decoded into corrupted or negative `int` values. (https://github.com/ClickHouse/clickhouse-java/issues/2902)
 
 - **[client-v2]** Fixed container query parameters being sent unquoted, so `Client.query(sql, params, settings)` binding

docs/features.md

@@ -65,7 +65,7 @@ Compatibility-sensitive traits:
 - Prepared statements: Supports `?` parameters through client-side SQL rendering and validates that all parameters are bound before execution.
 - SQL parsing and classification: Classifies SQL to distinguish queries, updates, inserts, `USE`, and role-changing statements, with selectable parser backends.
 - JDBC escape processing: Translates supported JDBC escape syntax for dates, timestamps, and functions before execution.
-- Result set streaming: Streams result sets from ClickHouse binary formats and `FORMAT JSONEachRow`, enforces max-row limits, and manages result-set lifecycle correctly.
+- Result set streaming: Streams result sets from ClickHouse binary formats and `FORMAT JSONEachRow`, and exposes explicit `FORMAT JSON` output as a line-oriented single-column string result set; enforces max-row limits and manages result-set lifecycle correctly.
 - Result-set metadata: Exposes JDBC `ResultSetMetaData` backed by ClickHouse column schema.
 - Database metadata: Implements JDBC `DatabaseMetaData` for ClickHouse catalogs, schemas, tables, columns, and related capability reporting.
 - Parameter metadata: Reports prepared-statement parameter counts.
@@ -87,6 +87,7 @@ Compatibility-sensitive traits:
 - `Geometry` has a stable JDBC mapping: metadata reports SQL type `ARRAY` with type name `Geometry`, read paths return nested Java arrays rather than custom wrappers, and write paths depend on the caller preserving the intended point/array nesting shape.
 - JDBC `Geometry` writes share the same ambiguity as the client serializer: variant selection is inferred from nesting depth, so `Ring` versus `LineString` and `Polygon` versus `MultiLineString` are not currently distinguishable when writing through the generic `Geometry` path.
 - JDBC `FORMAT JSONEachRow` support is opt-in through the `jdbc_json_parser_factory` driver property, whose value must be a fully-qualified `JsonParserFactory` class name with a public no-argument constructor; JSONEachRow numeric and structured value behavior follows the selected parser and configured server output settings. Inferred JSON arrays are returned from `ResultSet.getObject(...)` as parser-native `List` values rather than JDBC `Array` values because JSONEachRow does not include element metadata. JDBC temporal typed accessors such as `getTimestamp(...)` are not guaranteed for JSONEachRow result sets; callers that need stable JDBC temporal conversions should use the binary default format or perform application-level conversion from string/object values.
+- JDBC `FORMAT JSON` preserves the server-rendered payload as a line-oriented, single-column `results` result set, with one JDBC row per response line. It does not reconstruct typed ClickHouse columns from the JSON document; callers that need typed column access should omit the explicit format and use the default binary result path.
 - Binary parameters passed through `setBytes()` are encoded as ClickHouse `unhex(...)` expressions rather than text literals; empty byte arrays map to an empty string expression.
 - Stream and reader setters (`setAsciiStream`, `setUnicodeStream`, `setBinaryStream`, `setCharacterStream`, `setNCharacterStream`) are treated as text input encoded with the same string-escaping rules, including length-based truncation when a length is supplied.
 - `getString()` formatting for temporal values is stable output: `Date` uses `yyyy-MM-dd`, `DateTime` uses `yyyy-MM-dd HH:mm:ss`, and `DateTime64` preserves fractional precision, all interpreted in server timezone context where applicable.

jdbc-v2/src/main/java/com/clickhouse/jdbc/LineAsStringFormatReader.java

@@ -0,0 +1,38 @@
+package com.clickhouse.jdbc;
+
+import com.clickhouse.client.api.data_formats.JSONEachRowFormatReader;
+import com.clickhouse.client.api.data_formats.JsonParser;
+
+import java.io.BufferedReader;
+import java.io.InputStream;
+import java.io.InputStreamReader;
+import java.nio.charset.StandardCharsets;
+import java.util.Collections;
+import java.util.Map;
+
+final class LineAsStringFormatReader extends JSONEachRowFormatReader {
+    static final String COLUMN_NAME = "results";
+
+    LineAsStringFormatReader(InputStream input) {
+        super(new LineParser(input));
+    }
+
+    private static final class LineParser implements JsonParser {
+        private final BufferedReader reader;
+
+        private LineParser(InputStream input) {
+            this.reader = new BufferedReader(new InputStreamReader(input, StandardCharsets.UTF_8));
+        }
+
+        @Override
+        public Map<String, Object> nextRow() throws Exception {
+            String line = reader.readLine();
+            return line == null ? null : Collections.<String, Object>singletonMap(COLUMN_NAME, line);
+        }
+
+        @Override
+        public void close() throws Exception {
+            reader.close();
+        }
+    }
+}

jdbc-v2/src/main/java/com/clickhouse/jdbc/StatementImpl.java

@@ -180,7 +180,9 @@ protected ResultSetImpl executeQueryImpl(String sql, QuerySettings settings) thr
             }
 
             ClickHouseFormatReader reader;
-            if (response.getFormat() == ClickHouseFormat.JSONEachRow) {
+            if (response.getFormat() == ClickHouseFormat.JSON) {
+                reader = new LineAsStringFormatReader(response.getInputStream());
+            } else if (response.getFormat() == ClickHouseFormat.JSONEachRow) {
                 if (connection.getJsonParserFactory() == null) {
                     throw new SQLException("Response is in JSONEachRow format, but " +
                             DriverProperties.JSON_PARSER_FACTORY.getKey() + " is not configured. Set " +
@@ -191,7 +193,7 @@ protected ResultSetImpl executeQueryImpl(String sql, QuerySettings settings) thr
             } else if (!response.getFormat().isText()) {
                 reader = connection.getClient().newBinaryFormatReader(response);
             } else {
-                throw new SQLException("Only RowBinaryWithNameAndTypes and JSONEachRow are supported for output format. Please check your query.",
+                throw new SQLException("Only RowBinaryWithNamesAndTypes, JSON, and JSONEachRow are supported for output format. Please check your query.",
                         ExceptionUtils.SQL_STATE_CLIENT_ERROR);
             }
 

jdbc-v2/src/test/java/com/clickhouse/jdbc/StatementTest.java

@@ -20,6 +20,7 @@
 import java.sql.Array;
 import java.sql.Connection;
 import java.sql.Date;
+import java.sql.PreparedStatement;
 import java.sql.ResultSet;
 import java.sql.ResultSetMetaData;
 import java.sql.SQLException;
@@ -862,10 +863,30 @@ public void testCancelInsertWithSession() throws Exception {
     }
 
     @Test(groups = {"integration"})
-    public void testTextFormatInResponse() throws Exception {
-        try (Connection conn = getJdbcConnection();
-             Statement stmt = conn.createStatement()) {
-            Assert.expectThrows(SQLException.class, () -> stmt.executeQuery("SELECT 1 FORMAT JSON"));
+    public void testJSONFormatInResponse() throws Exception {
+        try (Connection conn = getJdbcConnection()) {
+            try (PreparedStatement stmt = conn.prepareStatement("SELECT 1 AS x FORMAT JSON");
+                 ResultSet rs = stmt.executeQuery()) {
+                assertEquals(rs.getMetaData().getColumnCount(), 1);
+                assertEquals(rs.getMetaData().getColumnLabel(1), LineAsStringFormatReader.COLUMN_NAME);
+
+                StringBuilder json = new StringBuilder();
+                while (rs.next()) {
+                    json.append(rs.getString(1)).append('\n');
+                }
+
+                String output = json.toString();
+                assertTrue(output.contains("\"data\""), output);
+                assertTrue(output.contains("\"x\""), output);
+                assertTrue(output.contains("\"rows\""), output);
+            }
+
+            try (Statement stmt = conn.createStatement();
+                 ResultSet rs = stmt.executeQuery("SELECT 2 AS y")) {
+                assertTrue(rs.next());
+                assertEquals(rs.getInt("y"), 2);
+                assertFalse(rs.next());
+            }
         }
     }