fix(client-v2): address QBit review — reject QBit in Native format, reject null QBit, await DDL in test

Review response on PR #2939:

- NativeFormatReader: reject reading any column that is or contains a QBit
  (recursive check). The server transmits QBit in the Native format using its
  internal bit-transposed Tuple(FixedString(...)) layout, not the Array-like
  RowBinary representation this reader decodes, so the previous fall-through
  misread the bytes and desynchronized the block. Fail loud with a clear
  ClientException pointing to a RowBinary format instead of decoding garbage.
- SerializerUtils.serializeQBitData: reject a null value. A fixed-dimension QBit
  cannot be null; a QBit nested in a container (Tuple/Map/Array) reaches this
  path via serializeNestedData without the top-level preamble, so without the
  guard the null was written as a zero-length vector, desynchronizing the stream.
- DataTypeTests.writeReadVerify: await client.execute(tableDef) in the no-ddl
  branch (it was unawaited, racing the subsequent getTableSchema).
- Tests: Native rejection (top-level + nested Map(String,QBit)); null QBit
  rejection (direct + nested-in-Tuple). docs/features.md + CHANGELOG updated.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: polyglotAI-bot

CHANGELOG.md

@@ -19,7 +19,9 @@
   `BFloat16`/`Float32`, `double[]` for `Float64`) through generic records, binary readers, and POJO binding. In the
   JDBC driver (`jdbc-v2`) `QBit` maps to `java.sql.Types.ARRAY` and is returned as a `java.sql.Array` from
   `getObject`/`getArray`. Previously `QBit` was an unimplemented type constant and reading or writing such a column
-  failed. (https://github.com/ClickHouse/clickhouse-java/issues/2610)
+  failed. Reading `QBit` through the `Native` output format is not supported — the server transmits it there using a
+  different internal layout — and fails fast with a clear error; use a `RowBinary` format instead.
+  (https://github.com/ClickHouse/clickhouse-java/issues/2610)
 - **[client-v2, jdbc-v2]** Added TLS cipher suite selection. `Client.Builder.setSSLCipherSuites(String...)` (client-v2)
   and the comma-separated `ssl_cipher_suites` connection property (client-v2 and jdbc-v2) restrict the cipher suites
   enabled on secure connections; when unset, the transport defaults are used. Cipher-suite selection is independent of the

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

@@ -91,6 +91,21 @@ private boolean readBlock() throws IOException {
             names.add(column.getColumnName());
             types.add(column.getDataType().name());
 
+            if (containsQBit(column)) {
+                // QBit is transmitted in the Native format using its internal bit-transposed
+                // Tuple(FixedString(...)) layout, which is NOT the Array(element_type)-like
+                // representation used in RowBinary (the only representation this reader decodes for
+                // QBit). Reading it through the columnar/per-row paths below would misread those bytes
+                // and desynchronize the block, corrupting the columns that follow. Fail loudly instead
+                // of silently decoding garbage. This also covers a QBit nested inside another type
+                // (e.g. Map(String, QBit(...))). QBit can be read through a RowBinary format.
+                throw new ClientException("Reading column '" + column.getColumnName() + "' ("
+                        + column.getOriginalTypeName() + ") from the Native format is not supported "
+                        + "because it contains a QBit type: QBit is serialized in the Native format "
+                        + "using an internal layout this reader does not decode. Use a RowBinary format "
+                        + "(e.g. RowBinaryWithNamesAndTypes) to read QBit values");
+            }
+
             List<Object> values = new ArrayList<>(nRows);
             if (column.isArray()) {
                 int[] sizes = new int[nRows];
@@ -116,6 +131,26 @@ private boolean readBlock() throws IOException {
         return true;
     }
 
+    /**
+     * Returns {@code true} if {@code column} is a {@code QBit} or contains a {@code QBit} anywhere in
+     * its nested type tree (e.g. {@code Array(QBit(...))}, {@code Tuple(..., QBit(...))},
+     * {@code Map(String, QBit(...))}). {@code QBit} uses a different, internal wire layout in the
+     * Native format than in RowBinary, so this reader cannot decode it and rejects such columns
+     * up-front rather than misreading the block. {@code Nullable}/{@code LowCardinality} wrappers are
+     * flags on the column, so a wrapped {@code QBit} still reports {@code dataType == QBit} here.
+     */
+    private static boolean containsQBit(ClickHouseColumn column) {
+        if (column.getDataType() == ClickHouseDataType.QBit) {
+            return true;
+        }
+        for (ClickHouseColumn nested : column.getNestedColumns()) {
+            if (nested != column && containsQBit(nested)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
     private static class Block {
         final List<String> names;
         final List<String> types;

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

@@ -484,24 +484,37 @@ public static void serializeArrayData(OutputStream stream, Object value, ClickHo
      * carry a vector and is rejected as well — otherwise it would fall through to
      * {@link #serializeArrayData} and write no bytes for the column, desynchronizing the
      * {@code RowBinary} stream and corrupting the columns that follow.
+     * <p>
+     * A {@code null} value is rejected for the same reason: a fixed-dimension {@code QBit} cannot be
+     * represented by {@code null}. A top-level {@code null} non-nullable {@code QBit} is already
+     * rejected by
+     * {@link com.clickhouse.client.api.data_formats.RowBinaryFormatSerializer#writeValuePreamble},
+     * but a {@code QBit} nested inside a container ({@code Tuple}/{@code Map}/{@code Array}) is written
+     * through {@link #serializeNestedData}, which does not route a non-nullable element through that
+     * preamble; without this guard the {@code null} would delegate to {@link #serializeArrayData} and
+     * be written as a zero-length vector (var-int {@code 0}), again desynchronizing the stream. (A
+     * {@code Nullable(QBit)} {@code null} never reaches here: its null-marker is written earlier by the
+     * preamble or by {@link #serializeNestedData}, which then return.)
      */
     private static void serializeQBitData(OutputStream stream, Object value, ClickHouseColumn column) throws IOException {
-        if (value != null) {
-            int length;
-            if (value.getClass().isArray()) {
-                length = Array.getLength(value);
-            } else if (value instanceof List) {
-                length = ((List<?>) value).size();
-            } else {
-                throw new IllegalArgumentException("QBit column '" + column.getColumnName()
-                        + "' expects a Java array or List of its element type but got "
-                        + value.getClass().getName());
-            }
-            int dimension = column.getPrecision();
-            if (length != dimension) {
-                throw new IllegalArgumentException("QBit column '" + column.getColumnName()
-                        + "' expects exactly " + dimension + " elements but got " + length);
-            }
+        if (value == null) {
+            throw new IllegalArgumentException("QBit column '" + column.getColumnName()
+                    + "' cannot be null; expected exactly " + column.getPrecision() + " elements");
+        }
+        int length;
+        if (value.getClass().isArray()) {
+            length = Array.getLength(value);
+        } else if (value instanceof List) {
+            length = ((List<?>) value).size();
+        } else {
+            throw new IllegalArgumentException("QBit column '" + column.getColumnName()
+                    + "' expects a Java array or List of its element type but got "
+                    + value.getClass().getName());
+        }
+        int dimension = column.getPrecision();
+        if (length != dimension) {
+            throw new IllegalArgumentException("QBit column '" + column.getColumnName()
+                    + "' expects exactly " + dimension + " elements but got " + length);
         }
         serializeArrayData(stream, value, column);
     }

client-v2/src/test/java/com/clickhouse/client/api/data_formats/internal/SerializerUtilsTest.java

@@ -213,6 +213,47 @@ public void testQBitSerializationAcceptsExactDimensionAndMatchesArray() throws E
         Assert.assertEquals(qbitOut.toByteArray(), arrayOut.toByteArray());
     }
 
+    @Test
+    public void testQBitSerializationRejectsNull() {
+        // A QBit has a fixed dimension, so a null value cannot satisfy it. A top-level null
+        // non-nullable QBit is already rejected by RowBinaryFormatSerializer.writeValuePreamble, but a
+        // QBit nested inside a Tuple/Map/Array is serialized through serializeNestedData, which does
+        // NOT route a non-nullable element through that preamble. Without an explicit guard the null
+        // would delegate to the Array serializer and be written as a zero-length vector (var-int 0),
+        // desynchronizing the RowBinary stream and corrupting the following columns. Writing into a
+        // byte sink so any (wrongly) emitted payload would be observable.
+        ClickHouseColumn column = ClickHouseColumn.of("vec", "QBit(Float32, 8)");
+        ByteArrayOutputStream out = new ByteArrayOutputStream();
+
+        IllegalArgumentException ex = Assert.expectThrows(IllegalArgumentException.class,
+                () -> SerializerUtils.serializeData(out, null, column));
+        Assert.assertTrue(ex.getMessage().contains("vec"),
+                "Message should name the column: " + ex.getMessage());
+        Assert.assertTrue(ex.getMessage().contains("null"),
+                "Message should state the value cannot be null: " + ex.getMessage());
+        Assert.assertEquals(out.size(), 0,
+                "Nothing should be written to the stream when a null QBit is rejected");
+    }
+
+    @Test
+    public void testQBitNestedInTupleRejectsNullElement() throws Exception {
+        // Exercises the production-reachable path for the null guard: a non-nullable QBit nested in a
+        // Tuple is written through serializeNestedData, which does NOT apply the top-level
+        // writeValuePreamble null-into-non-nullable check to a non-nullable element. Without the guard
+        // in serializeQBitData the null element would be written as a zero-length vector (var-int 0),
+        // desynchronizing the stream and corrupting the rest of the row.
+        ClickHouseColumn tuple = ClickHouseColumn.of("t", "Tuple(QBit(Float32, 8))");
+        ByteArrayOutputStream out = new ByteArrayOutputStream();
+        List<Object> tupleValue = Arrays.asList((Object) null);
+
+        IllegalArgumentException ex = Assert.expectThrows(IllegalArgumentException.class,
+                () -> SerializerUtils.serializeData(out, tupleValue, tuple));
+        Assert.assertTrue(ex.getMessage().contains("cannot be null"),
+                "Message should explain the null QBit is rejected: " + ex.getMessage());
+        Assert.assertEquals(out.size(), 0,
+                "Nothing should be written when the nested null QBit element is rejected");
+    }
+
     @Test(dataProvider = "nonNullableEnumTypes")
     public void testNullIntoNonNullableEnumThrowsIllegalArgument(String typeName) {
         ClickHouseColumn column = ClickHouseColumn.of("bs_flag", typeName);

client-v2/src/test/java/com/clickhouse/client/datatypes/DataTypeTests.java

@@ -17,6 +17,7 @@
 import com.clickhouse.client.api.query.QuerySettings;
 import com.clickhouse.client.api.sql.SQLUtils;
 import com.clickhouse.data.ClickHouseDataType;
+import com.clickhouse.data.ClickHouseFormat;
 import com.clickhouse.data.ClickHouseVersion;
 import lombok.AllArgsConstructor;
 import lombok.Data;
@@ -99,7 +100,7 @@ private <T> void writeReadVerify(String table, String tableDef, Class<T> dtoClas
                                      BiConsumer<List<T>, T> rowVerifier, CommandSettings ddlSettings) throws Exception {
         client.execute("DROP TABLE IF EXISTS " + table).get();
         if (ddlSettings == null) {
-            client.execute(tableDef);
+            client.execute(tableDef).get();
         } else {
             client.execute(tableDef, ddlSettings).get();
         }
@@ -198,6 +199,42 @@ public void testQBit() throws Exception {
                 }, ddl);
     }
 
+    @Test(groups = {"integration"})
+    public void testQBitNativeFormatRejected() throws Exception {
+        if (isVersionMatch(QBIT_UNSUPPORTED_VERSIONS)) {
+            throw new SkipException("QBit requires ClickHouse 25.10+");
+        }
+
+        // In the Native format the server transmits a QBit column using its internal bit-transposed
+        // layout, which is NOT the Array(element_type)-like representation the client decodes for QBit
+        // over RowBinary. Reading QBit via Native must therefore fail loudly with a clear error rather
+        // than silently decoding garbage and misaligning the trailing column that follows it.
+        QuerySettings settings = new QuerySettings()
+                .setFormat(ClickHouseFormat.Native)
+                .serverSetting("allow_experimental_qbit_type", "1");
+        try (QueryResponse response = client.query(
+                "SELECT CAST([1, 2, 3, 4, 5, 6, 7, 8] AS QBit(Float32, 8)) AS q, 42 AS tail", settings).get()) {
+            ClientException ex = Assert.expectThrows(ClientException.class,
+                    () -> client.newBinaryFormatReader(response));
+            Assert.assertTrue(ex.getMessage().contains("QBit"),
+                    "Expected a clear QBit message, got: " + ex.getMessage());
+            Assert.assertTrue(ex.getMessage().contains("Native"),
+                    "Expected the message to mention the Native format, got: " + ex.getMessage());
+        }
+
+        // The same rejection applies to a QBit nested inside another type (here Map(String, QBit)),
+        // which the server does support and would otherwise be misread column-by-column.
+        try (QueryResponse response = client.query(
+                "SELECT CAST(map('a', [1, 2, 3]) AS Map(String, QBit(Float32, 3))) AS m", settings).get()) {
+            ClientException ex = Assert.expectThrows(ClientException.class,
+                    () -> client.newBinaryFormatReader(response));
+            Assert.assertTrue(ex.getMessage().contains("QBit"),
+                    "Expected a clear QBit message for the nested case, got: " + ex.getMessage());
+            Assert.assertTrue(ex.getMessage().contains("Native"),
+                    "Expected the message to mention the Native format, got: " + ex.getMessage());
+        }
+    }
+
     @Test(groups = {"integration"})
     public void testNestedDataTypes() throws Exception {
         final String table = "test_nested_types";

docs/features.md

@@ -21,7 +21,7 @@ This document lists stable, user-visible behavior in `client-v2` and `jdbc-v2` t
 - JSONEachRow text reader: Can stream `JSONEachRow` responses through a caller-supplied `JsonParser`, with Jackson and Gson parser factory implementations available as optional classpath dependencies, and infers a best-effort schema from the first row.
 - Data type conversion: Maps ClickHouse types to Java values for binary reads, POJO binding, and SQL parameter formatting, including date/time handling.
 - BFloat16 type support: For ClickHouse `24.11+`, reads and writes the `BFloat16` type through generic records, binary readers, POJO binding, and `Nullable`/`Dynamic`/`Variant` wrappers. `BFloat16` maps to the Java `float` type: a read widens the stored 16-bit value losslessly, while a write keeps the high 16 bits of the `float`. In `jdbc-v2`, `BFloat16` maps to `java.sql.Types.FLOAT` / `java.lang.Float` and is read and written through the standard `getFloat`/`setFloat` and `getObject` accessors.
-- QBit type support: For ClickHouse `25.10+` (requires the `allow_experimental_qbit_type` server setting to create a column), reads and writes the experimental `QBit(element_type, dimension)` vector type, where `element_type` is `BFloat16`, `Float32`, or `Float64`. On the wire a `QBit` value is encoded exactly like `Array(element_type)` (a length-prefixed list of elements), so the client reads and writes it as a Java array of the element type — `float[]` for `BFloat16`/`Float32`, `double[]` for `Float64` — through generic records, binary readers, and POJO binding, using the same code path as `Array(element_type)`. The bit-transposed on-disk layout is a server storage detail and is not exposed to the client.
+- QBit type support: For ClickHouse `25.10+` (requires the `allow_experimental_qbit_type` server setting to create a column), reads and writes the experimental `QBit(element_type, dimension)` vector type, where `element_type` is `BFloat16`, `Float32`, or `Float64`. On the wire a `QBit` value is encoded exactly like `Array(element_type)` (a length-prefixed list of elements), so the client reads and writes it as a Java array of the element type — `float[]` for `BFloat16`/`Float32`, `double[]` for `Float64` — through generic records, binary readers, and POJO binding, using the same code path as `Array(element_type)`. This `Array`-like encoding is what the server uses over `RowBinary` formats; the `Native` format instead transmits `QBit` using its internal bit-transposed `Tuple(FixedString(...))` layout, which the client does not decode, so reading any column that is or contains a `QBit` (including a nested `QBit`, e.g. `Map(String, QBit(...))`) through the `Native` format is rejected with a clear `ClientException` (use a `RowBinary` format such as `RowBinaryWithNamesAndTypes` instead).
 - Geometry type support: For ClickHouse `25.11+`, where `Geometry` changed from a string alias to `Variant(Point, Ring, LineString, MultiLineString, Polygon, MultiPolygon)`, the client reads and writes `Geometry` values through generic records, binary readers, POJO binding, and SQL parameter formatting, using Java array dimensionality to represent the geometry shape.
 - Insert APIs: Supports inserting registered POJOs, raw streams, and callback-driven writers, with optional column lists and format selection.
 - Insert controls: Supports insert-specific settings such as deduplication token, query id, compression behavior, and request headers.