docs(jdbc-v2): document raw FORMAT JSON access via client

Document how jdbc-v2 callers can unwrap ConnectionImpl and use the underlying client to consume document-oriented FORMAT JSON responses through QueryResponse. Add integration coverage for the supported path while preserving existing ResultSet format constraints.

Refs #2715

Author: 014-code

docs/client-v2-json-support.md

@@ -352,6 +352,34 @@ Notes:
 
 ## Usage in `jdbc-v2`
 
+### Document-oriented JSON output
+
+The standard ClickHouse `FORMAT JSON` response is a single JSON document that
+contains metadata, data, row counts, and statistics together. It is not mapped
+to a JDBC `ResultSet` by `Statement.executeQuery(...)`; callers that need the
+server-rendered JSON should use the underlying `client-v2` instance exposed by
+the JDBC connection and consume the `QueryResponse` stream directly.
+
+```java
+try (Connection conn = DriverManager.getConnection(
+        "jdbc:clickhouse://localhost:8123/default", props);
+     QueryResponse response = conn.unwrap(ConnectionImpl.class)
+             .getClient()
+             .query("SELECT 1 AS x FORMAT JSON")
+             .get();
+     BufferedReader reader = new BufferedReader(new InputStreamReader(
+             response.getInputStream(), StandardCharsets.UTF_8))) {
+    String json = reader.lines().collect(Collectors.joining("\n"));
+    // consume the JSON document
+}
+```
+
+The returned `Client` is owned by the JDBC connection. Close each
+`QueryResponse`, as shown above, but do not close the client returned by
+`ConnectionImpl#getClient()`.
+
+### Row-oriented JSONEachRow output
+
 The output format is selected by appending `FORMAT JSONEachRow` to the SQL
 statement. The driver does not rewrite the SQL and does not apply a default
 format on the caller's behalf.

docs/features.md

@@ -57,6 +57,7 @@ Compatibility-sensitive traits:
 - Driver and client properties: Separates JDBC-specific properties from passthrough client options used by the underlying `client-v2` transport.
 - DataSource support: Provides a JDBC `DataSource` implementation backed by the same driver configuration model.
 - Connection lifecycle: Supports connection close, validity checks, ping-based health checks, and network timeout management.
+- Underlying client access: `ConnectionImpl#getClient()` exposes the connection-owned `client-v2` instance for operations that are not representable through the JDBC API, including direct consumption of raw response streams.
 - Schema and database context: Supports database selection through URL, `setSchema`, `USE`, and statement-level settings.
 - Non-transactional operation: Exposes ClickHouse-appropriate transaction behavior with auto-commit semantics and unsupported transactional features.
 - Statement execution: Supports `execute`, `executeQuery`, `executeUpdate`, large update counts, and forward-only/read-only statements.
@@ -87,6 +88,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.
+- Standard `FORMAT JSON` output is document-oriented and is not exposed as a JDBC `ResultSet`. JDBC callers that need the server-rendered JSON document should unwrap to `ConnectionImpl`, call `getClient()`, and read the `QueryResponse` stream directly.
 - 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/ConnectionImpl.java

@@ -706,8 +706,15 @@ public int getNetworkTimeout() throws SQLException {
     }
 
     /**
-     * Returns instance of the client used to execute queries by this connection.
-     * @return - client instance
+     * Returns the {@link Client} instance used by this connection.
+     * <p>
+     * This can be used for operations that are not representable through the JDBC
+     * API, such as consuming raw or document-oriented response formats directly
+     * from {@link com.clickhouse.client.api.query.QueryResponse#getInputStream()}.
+     * The returned client is owned by this connection and must not be closed by
+     * callers; closing the connection closes the client.
+     *
+     * @return client instance
      */
     public Client getClient() throws SQLException {
         ensureOpen();

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

@@ -8,6 +8,8 @@
 import com.clickhouse.client.api.DataTypeUtils;
 import com.clickhouse.client.api.ServerException;
 import com.clickhouse.client.api.internal.ServerSettings;
+import com.clickhouse.client.api.query.QueryResponse;
+import com.clickhouse.data.ClickHouseFormat;
 import com.github.tomakehurst.wiremock.WireMockServer;
 import com.github.tomakehurst.wiremock.client.WireMock;
 import com.github.tomakehurst.wiremock.common.ConsoleNotifier;
@@ -17,6 +19,8 @@
 import org.testng.annotations.DataProvider;
 import org.testng.annotations.Test;
 
+import java.io.BufferedReader;
+import java.io.InputStreamReader;
 import java.math.BigDecimal;
 import java.net.Inet4Address;
 import java.net.Inet6Address;
@@ -47,6 +51,7 @@
 import java.util.concurrent.ScheduledExecutorService;
 import java.util.concurrent.TimeUnit;
 import java.util.function.BiConsumer;
+import java.util.stream.Collectors;
 
 import static org.testng.Assert.assertEquals;
 import static org.testng.Assert.assertFalse;
@@ -921,11 +926,31 @@ public void testUnwrapping() throws Exception {
         Connection conn = getJdbcConnection();
         Assert.assertTrue(conn.isWrapperFor(Connection.class));
         Assert.assertTrue(conn.isWrapperFor(JdbcV2Wrapper.class));
+        Assert.assertTrue(conn.isWrapperFor(ConnectionImpl.class));
         Assert.assertEquals(conn.unwrap(Connection.class), conn);
         Assert.assertEquals(conn.unwrap(JdbcV2Wrapper.class), conn);
+        Assert.assertEquals(conn.unwrap(ConnectionImpl.class), conn);
         assertThrows(SQLException.class, () -> conn.unwrap(ResultSet.class));
     }
 
+    @Test(groups = { "integration" })
+    public void testRawJSONQueryThroughUnderlyingClient() throws Exception {
+        try (Connection conn = getJdbcConnection();
+             QueryResponse response = conn.unwrap(ConnectionImpl.class).getClient()
+                     .query("SELECT 1 AS x FORMAT JSON")
+                     .get();
+             BufferedReader reader = new BufferedReader(
+                     new InputStreamReader(response.getInputStream(), StandardCharsets.UTF_8))) {
+            assertEquals(response.getFormat(), ClickHouseFormat.JSON);
+
+            String output = reader.lines().collect(Collectors.joining("\n"));
+            assertTrue(output.contains("\"meta\""), output);
+            assertTrue(output.contains("\"data\""), output);
+            assertTrue(output.contains("\"rows\""), output);
+            assertTrue(output.matches("(?s).*\"x\"\\s*:\\s*1.*"), output);
+        }
+    }
+
     @Test(groups = { "integration" })
     public void testBearerTokenAuth() throws Exception {
         if (isCloud()) {