Redesigned to expose less. Added tests. Updated docs

Author: chernser

CHANGELOG.md

@@ -27,6 +27,8 @@
 
 - **[client-v2]** `Client.Builder#useBearerTokenAuth(String)` now stores the bearer token under the `access_token` configuration key (with the `Bearer ` prefix) instead of writing it directly into `http_header_authorization`. The HTTP wire format is unchanged, but the token is no longer observable through `Client#getReadOnlyConfig()` under the `http_header_authorization` key.
 
+- **[client-v2]** The public `ClickHouseBinaryFormatWriter` interface gained two methods, `setString(String, byte[])` and `setString(int, byte[])`, for writing raw `String`/`FixedString` bytes. Code that only *uses* the interface is unaffected, but any third party that *implements* `ClickHouseBinaryFormatWriter` directly is source- and binary-incompatible until it adds these methods (recompiling against the new version is required; otherwise an `AbstractMethodError` can occur at runtime).
+
 ### New Features
 
 - **[client-v2]** Added `Session` API to encapsulate and manage ClickHouse session settings (`session_id`, `session_check`, `session_timeout`, `session_timezone`) as a reusable object. The `Session` instance can be applied to any request settings using `applyTo()`, and session state can be cleared via `clearSession()`. Additionally, added `resetOption(String)` to `InsertSettings`, `QuerySettings`, and `CommonSettings` to allow removing specific settings. Settings explicitly set to `null` will not be sent to the server, which is useful for overriding global settings.
@@ -37,7 +39,7 @@
 
 - **[client-v2, jdbc-v2]** Added support for ClickHouse `Geometry` type for ClickHouse `25.11+`, where `Geometry` changed from a `String` alias to `Variant(Point, Ring, LineString, MultiLineString, Polygon, MultiPolygon)` (client still compatible with older versions). Includes client read/write handling and JDBC type mapping for retrieving and inserting geometry values. Current writes infer the target geometry variant from array nesting depth, so `Ring` vs `LineString` and `Polygon` vs `MultiLineString` are not yet distinguishable through the generic `Geometry` write path. (https://github.com/ClickHouse/clickhouse-java/pull/2815)
 
-- **[client-v2, jdbc-v2]** Added opt-in binary string support through the `binary_string_support` configuration property (or `Client.Builder#binaryStringSupport(boolean)`), disabled by default. When enabled, top-level `String` and `FixedString` columns are read into a `StringValue` that preserves the raw bytes instead of decoding them into a `String`, allowing non-UTF-8/binary content to round-trip byte-for-byte. `StringValue` exposes the bytes via `toByteArray()`/`asByteBuffer()` and lazily decodes a `String` via `asString()` (UTF-8 by default, or a caller-supplied `Charset`). Values nested inside containers (`Array`, `Map`, `Tuple`, `Nested`, `Variant`) continue to be read as `String`, since those types are not expected to carry large/binary strings. On the JDBC side, `ResultSet#getBinaryStream(int)` and `ResultSet#getBinaryStream(String)` are now implemented (previously unsupported) and, together with `getBytes(...)`, return the raw column bytes.
+- **[client-v2, jdbc-v2]** Added opt-in binary string support through the `binary_string_support` configuration property (or `Client.Builder#binaryStringSupport(boolean)`), disabled by default. The setting is resolved per operation from the merged client and query settings, so it can be overridden for a single request via the `binary_string_support` operation option (e.g. `QuerySettings#setOption(ClientConfigProperties.BINARY_STRING_SUPPORT.getKey(), true)`) independently of the client-level default. When enabled, top-level `String` and `FixedString` columns are read into a `StringValue` that preserves the raw bytes instead of decoding them into a `String`, allowing non-UTF-8/binary content to round-trip byte-for-byte. `StringValue` exposes the bytes via `toByteArray()`/`asByteBuffer()` and lazily decodes a `String` via `asString()` (UTF-8 by default, or a caller-supplied `Charset`). Values nested inside containers (`Array`, `Map`, `Tuple`, `Nested`, `Variant`) continue to be read as `String`, since those types are not expected to carry large/binary strings. On the JDBC side, `ResultSet#getBinaryStream(int)` and `ResultSet#getBinaryStream(String)` are now implemented (previously unsupported) and, together with `getBytes(...)`, return the raw column bytes.
 
 - **[jdbc-v2]** `ResultSet#getObject(int|String, Map<String, Class<?>>)` now accepts ClickHouse type names as map keys in addition to the JDBC `SQLType` names it has always accepted. Only unwrapped type names are used for the lookup — `Nullable(...)` and `LowCardinality(...)` wrappers are stripped and do not affect resolution, so a key like `"Int32"` matches both `Int32` and `Nullable(Int32)` columns; keys like `"Nullable(Int32)"` are not recognized. Lookup order is the `ClickHouseDataType` enum name (e.g. `"Int32"`, `"String"`, `"DateTime"`) then the JDBC `SQLType` name (e.g. `"INTEGER"`, `"VARCHAR"`, `"TIMESTAMP"`); a missing entry leaves the value uncoerced. The feature is supported for primitive ClickHouse types only — `Array`, `Tuple`, `Map`, `Nested`, and geometry types are not supported and continue to be returned in their native form regardless of the user-supplied map. Existing maps keyed only by JDBC `SQLType` names continue to work unchanged.
 

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

@@ -3,6 +3,7 @@
 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.ClickHouseFormatReader;
 import com.clickhouse.client.api.data_formats.NativeFormatReader;
 import com.clickhouse.client.api.data_formats.RowBinaryFormatReader;
 import com.clickhouse.client.api.data_formats.RowBinaryWithNamesAndTypesFormatReader;
@@ -135,8 +136,6 @@ public class Client implements AutoCloseable {
 
     private final Map<ClickHouseDataType, Class<?>> typeHintMapping;
 
-    private final boolean binaryStringSupport;
-
     // Server context
     private String dbUser;
     private String serverVersion;
@@ -202,7 +201,6 @@ private Client(Collection<Endpoint> endpoints, Map<String,String> configuration,
         this.serverVersion = configuration.getOrDefault(ClientConfigProperties.SERVER_VERSION.getKey(), "unknown");
         this.dbUser = configuration.getOrDefault(ClientConfigProperties.USER.getKey(), ClientConfigProperties.USER.getDefObjVal());
         this.typeHintMapping = (Map<ClickHouseDataType, Class<?>>) this.configuration.get(ClientConfigProperties.TYPE_HINT_MAPPING.getKey());
-        this.binaryStringSupport = ClientConfigProperties.BINARY_STRING_SUPPORT.getOrDefault(this.configuration);
     }
 
     /**
@@ -1123,10 +1121,10 @@ public Builder typeHintMapping(Map<ClickHouseDataType, Class<?>> typeHintMapping
         }
 
         /**
-         * Enables reading top-level {@code String} and {@code FixedString} columns as
-         * {@link com.clickhouse.client.api.data_formats.StringValue}, preserving the raw bytes instead of
-         * decoding them into a {@link String}. Values nested inside containers (Array, Map, Tuple, Nested,
-         * Variant) are still read as {@link String}.
+         * Enables reading {@code String} and {@code FixedString} columns into an intermediate {@code byte[]}
+         * (a new array each time) instead of decoding them into a {@link String}. This improves working with
+         * large strings and allows {@link ClickHouseFormatReader#getByteArray} to be used more effectively. Can also be configured
+         * per operation.
          *
          * @param enable - if the feature is enabled
          * @return this builder instance
@@ -2126,17 +2124,17 @@ public ClickHouseBinaryFormatReader newBinaryFormatReader(QueryResponse response
         switch (response.getFormat()) {
             case Native:
                 reader = new NativeFormatReader(response.getInputStream(), response.getSettings(),
-                        byteBufferPool, typeHintMapping, binaryStringSupport);
+                        byteBufferPool, typeHintMapping);
                 break;
             case RowBinaryWithNamesAndTypes:
-                reader = new RowBinaryWithNamesAndTypesFormatReader(response.getInputStream(), response.getSettings(), byteBufferPool, typeHintMapping, binaryStringSupport);
+                reader = new RowBinaryWithNamesAndTypesFormatReader(response.getInputStream(), response.getSettings(), byteBufferPool, typeHintMapping);
                 break;
             case RowBinaryWithNames:
-                reader = new RowBinaryWithNamesFormatReader(response.getInputStream(), response.getSettings(), schema, byteBufferPool, typeHintMapping, binaryStringSupport);
+                reader = new RowBinaryWithNamesFormatReader(response.getInputStream(), response.getSettings(), schema, byteBufferPool, typeHintMapping);
                 break;
             case RowBinary:
                 reader = new RowBinaryFormatReader(response.getInputStream(), response.getSettings(), schema,
-                        byteBufferPool, typeHintMapping, binaryStringSupport);
+                        byteBufferPool, typeHintMapping);
                 break;
             default:
                 throw new IllegalArgumentException("Binary readers doesn't support format: " + response.getFormat());

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

@@ -1,5 +1,6 @@
 package com.clickhouse.client.api;
 
+import com.clickhouse.client.api.data_formats.ClickHouseFormatReader;
 import com.clickhouse.client.api.data_formats.internal.AbstractBinaryFormatReader;
 import com.clickhouse.client.api.enums.SSLMode;
 import com.clickhouse.client.api.internal.ClickHouseLZ4OutputStream;
@@ -182,10 +183,9 @@ public Object parseValue(String value) {
     TYPE_HINT_MAPPING("type_hint_mapping", Map.class),
 
     /**
-     * When enabled, top-level {@code String} and {@code FixedString} columns are read into a
-     * {@link com.clickhouse.client.api.data_formats.StringValue} that preserves the raw bytes instead of
-     * decoding them into a {@link String}. Values nested inside containers (Array, Map, Tuple, Nested, Variant)
-     * are still read as {@link String}, since those types are not expected to carry large/binary strings.
+     * When enabled, {@code String} and {@code FixedString} columns are read into an intermediate {@code byte[]}
+     * instead of decoding them into a {@link String}. Improves working with large strings and lets
+     * {@link ClickHouseFormatReader#getByteArray} be used more effectively. Can be configured per operation.
      */
     BINARY_STRING_SUPPORT("binary_string_support", Boolean.class, "false"),
 

client-v2/src/main/java/com/clickhouse/client/api/data_formats/NativeFormatReader.java

@@ -29,14 +29,7 @@ public class NativeFormatReader extends AbstractBinaryFormatReader {
     public NativeFormatReader(InputStream inputStream, QuerySettings settings,
                               BinaryStreamReader.ByteBufferAllocator byteBufferAllocator,
                               Map<ClickHouseDataType, Class<?>> typeHintMapping) {
-        this(inputStream, settings, byteBufferAllocator, typeHintMapping, false);
-    }
-
-    public NativeFormatReader(InputStream inputStream, QuerySettings settings,
-                              BinaryStreamReader.ByteBufferAllocator byteBufferAllocator,
-                              Map<ClickHouseDataType, Class<?>> typeHintMapping,
-                              boolean binaryStringSupport) {
-        super(inputStream, settings, null, byteBufferAllocator, typeHintMapping, binaryStringSupport);
+        super(inputStream, settings, null, byteBufferAllocator, typeHintMapping);
         try {
             readBlock();
         } catch (IOException e) {

client-v2/src/main/java/com/clickhouse/client/api/data_formats/RowBinaryFormatReader.java

@@ -19,16 +19,7 @@ public RowBinaryFormatReader(InputStream inputStream,
                                  TableSchema schema,
                                  BinaryStreamReader.ByteBufferAllocator byteBufferAllocator,
                                  Map<ClickHouseDataType, Class<?>> typeHintMapping) {
-        this(inputStream, querySettings, schema, byteBufferAllocator, typeHintMapping, false);
-    }
-
-    public RowBinaryFormatReader(InputStream inputStream,
-                                 QuerySettings querySettings,
-                                 TableSchema schema,
-                                 BinaryStreamReader.ByteBufferAllocator byteBufferAllocator,
-                                 Map<ClickHouseDataType, Class<?>> typeHintMapping,
-                                 boolean binaryStringSupport) {
-        super(inputStream, querySettings, schema, byteBufferAllocator, typeHintMapping, binaryStringSupport);
+        super(inputStream, querySettings, schema, byteBufferAllocator, typeHintMapping);
         readNextRecord();
     }
 

client-v2/src/main/java/com/clickhouse/client/api/data_formats/RowBinaryWithNamesAndTypesFormatReader.java

@@ -22,15 +22,7 @@ public RowBinaryWithNamesAndTypesFormatReader(InputStream inputStream,
                                                   QuerySettings querySettings,
                                                   BinaryStreamReader.ByteBufferAllocator byteBufferAllocator,
                                                   Map<ClickHouseDataType, Class<?>> typeHintMapping) {
-        this(inputStream, querySettings, byteBufferAllocator, typeHintMapping, false);
-    }
-
-    public RowBinaryWithNamesAndTypesFormatReader(InputStream inputStream,
-                                                  QuerySettings querySettings,
-                                                  BinaryStreamReader.ByteBufferAllocator byteBufferAllocator,
-                                                  Map<ClickHouseDataType, Class<?>> typeHintMapping,
-                                                  boolean binaryStringSupport) {
-        super(inputStream, querySettings, null, byteBufferAllocator, typeHintMapping, binaryStringSupport);
+        super(inputStream, querySettings, null, byteBufferAllocator, typeHintMapping);
         readSchema();
     }
 

client-v2/src/main/java/com/clickhouse/client/api/data_formats/RowBinaryWithNamesFormatReader.java

@@ -23,16 +23,7 @@ public RowBinaryWithNamesFormatReader(InputStream inputStream,
                                           TableSchema schema,
                                           BinaryStreamReader.ByteBufferAllocator byteBufferAllocator,
                                           Map<ClickHouseDataType, Class<?>> typeHintMapping) {
-        this(inputStream, querySettings, schema, byteBufferAllocator, typeHintMapping, false);
-    }
-
-    public RowBinaryWithNamesFormatReader(InputStream inputStream,
-                                          QuerySettings querySettings,
-                                          TableSchema schema,
-                                          BinaryStreamReader.ByteBufferAllocator byteBufferAllocator,
-                                          Map<ClickHouseDataType, Class<?>> typeHintMapping,
-                                          boolean binaryStringSupport) {
-        super(inputStream, querySettings, schema, byteBufferAllocator, typeHintMapping, binaryStringSupport);
+        super(inputStream, querySettings, schema, byteBufferAllocator, typeHintMapping);
         int nCol = 0;
         try {
             nCol = BinaryStreamReader.readVarInt(input);

client-v2/src/main/java/com/clickhouse/client/api/data_formats/internal/AbstractBinaryFormatReader.java

@@ -4,7 +4,6 @@
 import com.clickhouse.client.api.ClientException;
 import com.clickhouse.client.api.DataTypeUtils;
 import com.clickhouse.client.api.data_formats.ClickHouseBinaryFormatReader;
-import com.clickhouse.client.api.data_formats.StringValue;
 import com.clickhouse.client.api.internal.DataTypeConverter;
 import com.clickhouse.client.api.internal.MapUtils;
 import com.clickhouse.client.api.internal.ServerSettings;
@@ -78,10 +77,6 @@ public abstract class AbstractBinaryFormatReader implements ClickHouseBinaryForm
     private long lastNextCallTs; // for exception to detect slow reader
 
     protected AbstractBinaryFormatReader(InputStream inputStream, QuerySettings querySettings, TableSchema schema, BinaryStreamReader.ByteBufferAllocator byteBufferAllocator, Map<ClickHouseDataType, Class<?>> defaultTypeHintMap) {
-        this(inputStream, querySettings, schema, byteBufferAllocator, defaultTypeHintMap, false);
-    }
-
-    protected AbstractBinaryFormatReader(InputStream inputStream, QuerySettings querySettings, TableSchema schema, BinaryStreamReader.ByteBufferAllocator byteBufferAllocator, Map<ClickHouseDataType, Class<?>> defaultTypeHintMap, boolean binaryStringSupport) {
         this.input = inputStream;
         Map<String, Object> settings = querySettings == null ? Collections.emptyMap() : querySettings.getAllSettings();
         Boolean useServerTimeZone = (Boolean) settings.get(ClientConfigProperties.USE_SERVER_TIMEZONE.getKey());
@@ -93,6 +88,10 @@ protected AbstractBinaryFormatReader(InputStream inputStream, QuerySettings quer
         }
         boolean jsonAsString = MapUtils.getFlag(settings,
                 ClientConfigProperties.serverSetting(ServerSettings.OUTPUT_FORMAT_BINARY_WRITE_JSON_AS_STRING), false);
+        // Binary string support is resolved from the (already merged client + operation) query settings so it can be
+        // toggled per operation, not just per client.
+        boolean binaryStringSupport = MapUtils.getFlag(settings,
+                ClientConfigProperties.BINARY_STRING_SUPPORT.getKey(), false);
         this.binaryStreamReader = new BinaryStreamReader(inputStream, timeZone, LOG, byteBufferAllocator, jsonAsString,
                 defaultTypeHintMap, binaryStringSupport);
         if (schema != null) {