Fixed breaking change and documented more

Author: chernser

client-v2/src/main/java/com/clickhouse/client/api/Client.java

@@ -3,7 +3,6 @@
 import com.clickhouse.client.api.command.CommandResponse;
 import com.clickhouse.client.api.command.CommandSettings;
 import com.clickhouse.client.api.data_formats.ClickHouseBinaryFormatReader;
-import com.clickhouse.client.api.data_formats.JsonParserFactory;
 import com.clickhouse.client.api.data_formats.NativeFormatReader;
 import com.clickhouse.client.api.data_formats.RowBinaryFormatReader;
 import com.clickhouse.client.api.data_formats.RowBinaryWithNamesAndTypesFormatReader;
@@ -2223,21 +2222,21 @@ private Map<String, Object> buildRequestSettings(Map<String, Object> opSettings)
      * Must be called after {@link #buildRequestSettings(Map)} and after the request format has been resolved
      * (either provided by the caller or defaulted), so that the inspected format reflects the final value.
      *
-     * <p>For {@link ClickHouseFormat#JSONEachRow} the JSON output flags below are forced to {@code 0} so that the
-     * stream contains plain JSON numbers (and not quoted strings or non-standard tokens), which is what
-     * {@link com.clickhouse.client.api.data_formats.JSONEachRowFormatReader} expects:</p>
+     * <p>For {@link ClickHouseFormat#JSONEachRow}, callers may opt in to plain JSON numbers by setting
+     * {@link ClientConfigProperties#JSON_DISABLE_NUMBER_QUOTING}. Explicit server settings are otherwise
+     * left untouched.</p>
      * <ul>
      *     <li>{@code output_format_json_quote_64bit_integers}</li>
      *     <li>{@code output_format_json_quote_64bit_floats}</li>
-     *     <li>{@code output_format_json_quote_denormals}</li>
      *     <li>{@code output_format_json_quote_decimals}</li>
      * </ul>
      */
     private static void applyFormatSpecificSettings(QuerySettings requestSettings) {
-        if (requestSettings.getFormat() == ClickHouseFormat.JSONEachRow) {
+        boolean disableNumberQuoting = ClientConfigProperties.JSON_DISABLE_NUMBER_QUOTING
+                .getOrDefault(requestSettings.getAllSettings());
+        if (requestSettings.getFormat() == ClickHouseFormat.JSONEachRow && disableNumberQuoting) {
             requestSettings.serverSetting("output_format_json_quote_64bit_integers", "0");
             requestSettings.serverSetting("output_format_json_quote_64bit_floats", "0");
-            requestSettings.serverSetting("output_format_json_quote_denormals", "0");
             requestSettings.serverSetting("output_format_json_quote_decimals", "0");
         }
     }

client-v2/src/main/java/com/clickhouse/client/api/ClientConfigProperties.java

@@ -190,6 +190,11 @@ public Object parseValue(String value) {
      */
     HTTP_SEND_PARAMS_IN_BODY("client.http.use_form_request_for_query", Boolean.class, "false"),
 
+    /**
+     * When enabled for JSONEachRow queries, asks ClickHouse to emit large integer,
+     * floating-point, and decimal values as JSON numbers instead of quoted strings.
+     */
+    JSON_DISABLE_NUMBER_QUOTING("json_disable_number_quoting", Boolean.class, "false"),
 
     /**
      *  Prefix for custom settings. Should be aligned with server configuration.

client-v2/src/test/java/com/clickhouse/client/ClientTests.java

@@ -329,7 +329,7 @@ public void testDefaultSettings() {
                     Assert.assertEquals(config.get(p.getKey()), p.getDefaultValue(), "Default value doesn't match");
                 }
             }
-            Assert.assertEquals(config.size(), 34); // to check everything is set. Increment when new added.
+            Assert.assertEquals(config.size(), 35); // to check everything is set. Increment when new added.
         }
 
         try (Client client = new Client.Builder()
@@ -362,7 +362,7 @@ public void testDefaultSettings() {
                 .setSocketSndbuf(100000)
                 .build()) {
             Map<String, String> config = client.getConfiguration();
-            Assert.assertEquals(config.size(), 35); // to check everything is set. Increment when new added.
+            Assert.assertEquals(config.size(), 36); // to check everything is set. Increment when new added.
             Assert.assertEquals(config.get(ClientConfigProperties.DATABASE.getKey()), "mydb");
             Assert.assertEquals(config.get(ClientConfigProperties.MAX_EXECUTION_TIME.getKey()), "10");
             Assert.assertEquals(config.get(ClientConfigProperties.COMPRESSION_LZ4_UNCOMPRESSED_BUF_SIZE.getKey()), "300000");
@@ -429,7 +429,7 @@ public void testWithOldDefaults() {
                     Assert.assertEquals(config.get(p.getKey()), p.getDefaultValue(), "Default value doesn't match");
                 }
             }
-            Assert.assertEquals(config.size(), 34); // to check everything is set. Increment when new added.
+            Assert.assertEquals(config.size(), 35); // to check everything is set. Increment when new added.
         }
     }
 

client-v2/src/test/java/com/clickhouse/client/query/QueryTests.java

@@ -7,6 +7,7 @@
 import com.clickhouse.client.ClickHouseProtocol;
 import com.clickhouse.client.ClickHouseServerForTest;
 import com.clickhouse.client.api.Client;
+import com.clickhouse.client.api.ClientConfigProperties;
 import com.clickhouse.client.api.ClientException;
 import com.clickhouse.client.api.ServerException;
 import com.clickhouse.client.api.command.CommandSettings;
@@ -380,6 +381,28 @@ public void testQueryJSONEachRow() throws ExecutionException, InterruptedExcepti
         }
     }
 
+    @Test(groups = {"integration"})
+    public void testJsonEachRowNumberQuoteSettingsAreOptIn() throws Exception {
+        String sql = "SELECT toInt64(1234567890123) AS v";
+
+        QuerySettings settings = new QuerySettings()
+                .setFormat(ClickHouseFormat.JSONEachRow)
+                .serverSetting("output_format_json_quote_64bit_integers", "1");
+        try (QueryResponse response = client.query(sql, settings).get();
+             BufferedReader reader = new BufferedReader(new InputStreamReader(response.getInputStream()))) {
+            Assert.assertTrue(reader.readLine().contains("\"v\":\"1234567890123\""));
+        }
+
+        QuerySettings unquotedSettings = new QuerySettings()
+                .setFormat(ClickHouseFormat.JSONEachRow)
+                .serverSetting("output_format_json_quote_64bit_integers", "1")
+                .setOption(ClientConfigProperties.JSON_DISABLE_NUMBER_QUOTING.getKey(), true);
+        try (QueryResponse response = client.query(sql, unquotedSettings).get();
+             BufferedReader reader = new BufferedReader(new InputStreamReader(response.getInputStream()))) {
+            Assert.assertTrue(reader.readLine().contains("\"v\":1234567890123"));
+        }
+    }
+
     @DataProvider(name = "rowBinaryFormats")
     ClickHouseFormat[] getRowBinaryFormats() {
         return new ClickHouseFormat[]{

docs/client-v2-json-support.md

@@ -67,9 +67,9 @@ provides additional advantages beyond what the format alone delivers:
   `com.clickhouse.client.api.data_formats`, consisting of `JsonParser`,
   `JsonParserFactory`, `JacksonJsonParserFactory`, and
   `GsonJsonParserFactory`.
-- Forces a fixed set of server settings for `JSONEachRow` requests so that
-  the response stream contains plain JSON numbers (see
-  [Forced server settings](#forced-server-settings-for-jsoneachrow)).
+- Adds an opt-in client flag for `JSONEachRow` requests that asks ClickHouse
+  to emit large integers, floats, and decimals as plain JSON numbers (see
+  [JSON number output settings](#json-number-output-settings)).
 - Declares Jackson and Gson as `provided` Maven dependencies, so that
   applications must include the chosen processor on their own classpath.
 
@@ -179,6 +179,18 @@ have a public no-argument constructor. There is no equivalent `client-v2`
 configuration key; direct client users pass a factory instance to their own
 reader construction code.
 
+### JSON number quoting flag
+
+`client-v2` can opt in to numeric JSON output settings through
+`ClientConfigProperties.JSON_DISABLE_NUMBER_QUOTING`:
+
+| Property key                                  | Default | Effect |
+| --------------------------------------------- | ------- | ------ |
+| `json_disable_number_quoting`                 | `false` | When `true` and the resolved request format is `JSONEachRow`, sets `output_format_json_quote_64bit_integers=0`, `output_format_json_quote_64bit_floats=0`, and `output_format_json_quote_decimals=0` for that request. |
+
+The flag can be set on the client builder or on a specific `QuerySettings`
+instance. It does not change `output_format_json_quote_denormals`.
+
 ## Runtime dependencies
 
 `client-v2` and `jdbc-v2` declare the JSON libraries with `provided` scope,
@@ -216,7 +228,8 @@ Client client = new Client.Builder()
 JsonParserFactory parserFactory = new JacksonJsonParserFactory();
 
 QuerySettings settings = new QuerySettings()
-        .setFormat(ClickHouseFormat.JSONEachRow);
+        .setFormat(ClickHouseFormat.JSONEachRow)
+        .setOption(ClientConfigProperties.JSON_DISABLE_NUMBER_QUOTING.getKey(), true);
 
 try (QueryResponse response = client.query(
         "SELECT id, name, active, score, payload FROM events ORDER BY id",
@@ -237,9 +250,9 @@ try (QueryResponse response = client.query(
 Notes:
 
 - Set `ClickHouseFormat.JSONEachRow` in `QuerySettings`. Do not rely on an SQL
-  `FORMAT JSONEachRow` clause for direct `client-v2` examples, because the
-  client applies JSON-specific server settings only when the request settings
-  identify the format as `JSONEachRow`.
+  `FORMAT JSONEachRow` clause for direct `client-v2` examples when you also
+  want client-side JSON number output settings, because those settings are
+  applied only when the request settings identify the format as `JSONEachRow`.
 - `client.newBinaryFormatReader(response)` continues to return a
   `ClickHouseBinaryFormatReader` for binary output formats and rejects text
   formats such as `JSONEachRow` with `IllegalArgumentException`. Callers that
@@ -267,7 +280,6 @@ props.setProperty(DriverProperties.JSON_PARSER_FACTORY.getKey(),
 props.setProperty(ClientConfigProperties.serverSetting("allow_experimental_json_type"), "1");
 props.setProperty(ClientConfigProperties.serverSetting("output_format_json_quote_64bit_integers"), "0");
 props.setProperty(ClientConfigProperties.serverSetting("output_format_json_quote_64bit_floats"), "0");
-props.setProperty(ClientConfigProperties.serverSetting("output_format_json_quote_denormals"), "0");
 props.setProperty(ClientConfigProperties.serverSetting("output_format_json_quote_decimals"), "0");
 
 try (Connection conn = DriverManager.getConnection(
@@ -294,35 +306,46 @@ Behavior:
   and `JSONEachRow` as output formats; any other text format causes
   `SQLException("Only RowBinaryWithNameAndTypes and JSONEachRow are supported
   for output format. ...")` to be thrown.
-- `ResultSet.getObject(...)` returns parser-native `Map` and scalar values
-  without an additional string round-trip. JSON arrays are exposed as JDBC
-  `Array` values, wrapping the parser-produced list.
+- `ResultSet.getObject(...)` returns parser-native `Map`, `List`, and scalar
+  values without an additional string round-trip. JSON arrays are returned as
+  the `List` implementation produced by the selected JSON library. Because
+  `JSONEachRow` has no array element metadata, `ResultSet.getArray(...)` is
+  not supported for these inferred JSON arrays.
 - The JSON processor is selected at the connection level through the
   `jdbc_json_parser_factory` driver property. It cannot be changed per
   statement, in line with the lifecycle of other connection options.
 - Because JDBC selects `JSONEachRow` through SQL text, set the JSON output
   server settings explicitly as connection properties when integer or decimal
   numeric accessors are used.
 
-## Forced server settings for `JSONEachRow`
+## JSON number output settings
 
 `Client.applyFormatSpecificSettings(...)` runs after request settings have
 been merged and after the request format has been resolved. When the format
-is `JSONEachRow`, the following server-side settings are forced for the
-request:
+is `JSONEachRow` and
+`ClientConfigProperties.JSON_DISABLE_NUMBER_QUOTING` is enabled, the
+following server-side settings are set to `0` for the request:
 
-| Setting                                   | Forced value | Rationale                                                                  |
+| Setting                                   | Value | Rationale                                                                  |
 | ----------------------------------------- | ------------ | -------------------------------------------------------------------------- |
-| `output_format_json_quote_64bit_integers` | `0`          | Emits `Int64` and `UInt64` as JSON numbers rather than quoted strings.     |
-| `output_format_json_quote_64bit_floats`   | `0`          | Emits 64-bit floating-point values as JSON numbers.                        |
-| `output_format_json_quote_denormals`      | `0`          | Avoids quoting `NaN` and `Inf`, allowing materialization as `Double`.      |
-| `output_format_json_quote_decimals`       | `0`          | Emits decimals as JSON numbers, allowing materialization as `BigDecimal` or `Double`. |
+| `output_format_json_quote_64bit_integers` | `0`   | Emits `Int64` and `UInt64` as JSON numbers rather than quoted strings.     |
+| `output_format_json_quote_64bit_floats`   | `0`   | Emits 64-bit floating-point values as JSON numbers.                        |
+| `output_format_json_quote_decimals`       | `0`   | Emits decimals as JSON numbers, allowing materialization as `BigDecimal` or `Double`. |
+
+These overrides are scoped to the individual request and apply only when both
+conditions are true: the request format in `QuerySettings` is `JSONEachRow`,
+and `json_disable_number_quoting` is enabled through the client
+or request settings. Explicit server settings are otherwise preserved.
+
+Denormal floating-point values (`NaN`, `Inf`, `-Inf`) are not yet handled by
+the built-in JSON reader. The client does not set
+`output_format_json_quote_denormals`; keep the server default or set
+`output_format_json_quote_denormals=1` so these values are quoted, then handle
+them as strings at the application boundary.
 
-These overrides are scoped to the individual request and apply only when the
-request format in `QuerySettings` is `JSONEachRow`. They are required for the
-typed accessors of the reader to operate correctly. JDBC callers that use SQL
-`FORMAT JSONEachRow` should set the same server settings explicitly through
-connection properties.
+JDBC callers that use SQL `FORMAT JSONEachRow` should set the same numeric
+server settings explicitly through connection properties when integer or
+decimal numeric accessors are used.
 
 ## Row parsing, schema, and typed accessors
 
@@ -349,9 +372,10 @@ behavior.
 ### Integer precision with Gson
 
 ClickHouse `Int64` and `UInt64` values can exceed the exactly representable
-integer range of a JSON floating-point number. The client intentionally emits
-them as JSON numbers for `JSONEachRow`, so the selected JSON library's number
-materialization policy matters.
+integer range of a JSON floating-point number. When
+`json_disable_number_quoting` is enabled, the client asks
+ClickHouse to emit them as JSON numbers for `JSONEachRow`, so the selected
+JSON library's number materialization policy matters.
 
 Jackson's default `Map.class` materialization keeps ordinary integer tokens as
 integer `Number` implementations. Gson's default `Map<String, Object>`

docs/features.md

@@ -40,7 +40,7 @@ Compatibility-sensitive traits:
 - `Geometry` handling is shape-sensitive: supported values are 1D through 4D Java arrays representing the nested geometry variants, and unsupported shapes or non-array values are rejected during serialization.
 - `Geometry` write inference is dimension-based rather than fully type-specific: point, ring/line string, polygon/multi-line string, and multi-polygon are selected from array depth, so writing `Geometry` cannot currently distinguish `Ring` from `LineString` or `Polygon` from `MultiLineString`.
 - Session precedence is part of the contract: client session defaults apply to each request, operation settings may override them, and only the client `session_id` is mutable at runtime while other client session properties remain fixed for the lifetime of the client.
-- JSONEachRow reading depends on the selected parser factory and request format settings: parser materialization determines Java value types, the reader infers minimal schema from the first row, and JSON-specific server settings are applied only when `QuerySettings` resolves to `ClickHouseFormat.JSONEachRow`.
+- JSONEachRow reading depends on the selected parser factory and request format settings: parser materialization determines Java value types, the reader infers minimal schema from the first row, and JSON number server settings are applied only when `QuerySettings` resolves to `ClickHouseFormat.JSONEachRow` and `json_disable_number_quoting` is enabled.
 - JSONEachRow schema inference is intentionally best-effort: scalar values use Java-to-ClickHouse type mappings, while JSON arrays and objects are identified structurally as `Array` and `Map`. For arrays, maps, and some nested or ambiguous values, the inferred type may not include the most specific element, key, value, or nested ClickHouse type.
 
 
@@ -80,7 +80,7 @@ Compatibility-sensitive traits:
 - String-like ClickHouse values have stable JDBC expectations: `String`, `FixedString`, and `Enum` values are returned as strings, while `UUID` is available both as `getString()` and `getObject(..., UUID.class)`.
 - `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.
+- 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.
 - 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.

examples/client-v2-json-processors/README.md

@@ -46,8 +46,8 @@ Each read call in `run()` follows the same three-step shape:
 The client example selects the output format with
 `new QuerySettings().setFormat(ClickHouseFormat.JSONEachRow)`. Use that form
 instead of appending `FORMAT JSONEachRow` to the SQL when calling `client-v2`
-directly, because the client applies JSON-specific server settings from the
-request format.
+directly when you enable client-side JSON number output settings, because
+those settings depend on the request format.
 
 ## Integer Precision