feat(client-v2): validate QBit vector dimension on write

QBit(element_type, dimension) is a fixed-size vector: the server requires
exactly `dimension` elements and rejects any other length over RowBinary with
a late SERIALIZATION_ERROR (verified against server 26.5). The write path
reused serializeArrayData, which wrote the actual array/list length without
checking it, so a wrong-sized (including empty) vector was serialized like a
normal Array and only failed on the server after a round-trip.

Split the QBit case out of the Array fall-through into serializeQBitData, which
validates the element count against column.getPrecision() (the dimension) and
throws a clear IllegalArgumentException naming the column, expected dimension,
and actual length before delegating to serializeArrayData. This mirrors the
client-side length enforcement already applied to the other fixed-size type,
FixedString(N). A correctly-sized QBit is still byte-for-byte identical to
Array(element_type).

Addresses Cursor Bugbot review on PR #2939.

Author: polyglotAI-bot

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

@@ -64,7 +64,8 @@ public static void serializeData(OutputStream stream, Object value, ClickHouseCo
         //Serialize the value to the stream based on the data type
         switch (column.getDataType()) {
             case QBit:
-                // QBit(element_type, dimension) is serialized like Array(element_type).
+                serializeQBitData(stream, value, column);
+                break;
             case Array:
                 serializeArrayData(stream, value, column);
                 break;
@@ -472,6 +473,32 @@ public static void serializeArrayData(OutputStream stream, Object value, ClickHo
         }
     }
 
+    /**
+     * Serializes a {@code QBit(element_type, dimension)} value. On the wire a {@code QBit} is
+     * transmitted exactly like {@code Array(element_type)} — a var-int length followed by that many
+     * element values — but the element count is fixed and must equal the declared dimension. The
+     * count is validated up-front so a wrong-sized (including empty) vector fails fast on the client
+     * with a clear message instead of a late server {@code SERIALIZATION_ERROR}, mirroring the
+     * client-side length enforcement already applied to the other fixed-size type,
+     * {@code FixedString(N)}.
+     */
+    private static void serializeQBitData(OutputStream stream, Object value, ClickHouseColumn column) throws IOException {
+        if (value != null) {
+            int length = -1;
+            if (value.getClass().isArray()) {
+                length = Array.getLength(value);
+            } else if (value instanceof List) {
+                length = ((List<?>) value).size();
+            }
+            int dimension = column.getPrecision();
+            if (length >= 0 && length != dimension) {
+                throw new IllegalArgumentException("QBit column '" + column.getColumnName()
+                        + "' expects exactly " + dimension + " elements but got " + length);
+            }
+        }
+        serializeArrayData(stream, value, column);
+    }
+
     /**
      DO NOT USE - part of internal API that will be changed
      */

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

@@ -143,6 +143,47 @@ public void testGeometrySerializationRejectsMalformedList() {
                         ClickHouseColumn.of("v", "Geometry")));
     }
 
+    @Test(dataProvider = "qbitWrongDimension")
+    public void testQBitSerializationRejectsWrongDimension(String typeName, Object value, int actualLength) {
+        ClickHouseColumn column = ClickHouseColumn.of("vec", typeName);
+
+        IllegalArgumentException ex = Assert.expectThrows(IllegalArgumentException.class,
+                () -> SerializerUtils.serializeData(new ByteArrayOutputStream(), value, column));
+        String message = ex.getMessage();
+        Assert.assertTrue(message.contains("vec"), "Message should name the column: " + message);
+        Assert.assertTrue(message.contains("8"), "Message should state the expected dimension: " + message);
+        Assert.assertTrue(message.contains("got " + actualLength),
+                "Message should state the actual length: " + message);
+    }
+
+    @DataProvider(name = "qbitWrongDimension")
+    private Object[][] qbitWrongDimension() {
+        // A QBit(E, 8) column requires exactly 8 elements: empty, too-short, and too-long vectors are
+        // all invalid, for both the Java-array and List representations and every element type.
+        return new Object[][] {
+                {"QBit(Float32, 8)", new float[0], 0},
+                {"QBit(Float32, 8)", new float[] {1f, 2f, 3f, 4f, 5f}, 5},
+                {"QBit(Float32, 8)", new float[] {1f, 2f, 3f, 4f, 5f, 6f, 7f, 8f, 9f, 10f}, 10},
+                {"QBit(Float64, 8)", new double[] {1d, 2d, 3d, 4d, 5d}, 5},
+                {"QBit(BFloat16, 8)", new float[] {1f, 2f, 3f}, 3},
+                {"QBit(Float32, 8)", Arrays.asList(1f, 2f, 3f), 3},
+        };
+    }
+
+    @Test
+    public void testQBitSerializationAcceptsExactDimensionAndMatchesArray() throws Exception {
+        float[] vec = {1f, -2f, 3.5f, 4f, 5f, 6f, 7f, 8f};
+
+        ByteArrayOutputStream qbitOut = new ByteArrayOutputStream();
+        SerializerUtils.serializeData(qbitOut, vec, ClickHouseColumn.of("vec", "QBit(Float32, 8)"));
+
+        // A correctly-sized QBit passes validation and is serialized byte-for-byte identically to
+        // Array(element_type), which is the wire contract the reader relies on.
+        ByteArrayOutputStream arrayOut = new ByteArrayOutputStream();
+        SerializerUtils.serializeData(arrayOut, vec, ClickHouseColumn.of("vec", "Array(Float32)"));
+        Assert.assertEquals(qbitOut.toByteArray(), arrayOut.toByteArray());
+    }
+
     @Test(dataProvider = "nonNullableEnumTypes")
     public void testNullIntoNonNullableEnumThrowsIllegalArgument(String typeName) {
         ClickHouseColumn column = ClickHouseColumn.of("bs_flag", typeName);

docs/features.md

@@ -44,7 +44,7 @@ Compatibility-sensitive traits:
 - Identifier quoting behavior is stable API for helper callers: identifiers are double-quoted, embedded double quotes are doubled, and optional quoting keeps simple identifiers unchanged.
 - Instant formatting is type-sensitive and should not drift: `Date` formatting depends on an explicit timezone, `DateTime` is serialized as epoch seconds, and higher-precision timestamps preserve up to 9 fractional digits.
 - `BFloat16` conversion is precision-sensitive and should not drift: a write keeps only the high 16 bits of the `float` (the low mantissa bits are truncated toward zero, matching the server's `Float32` → `BFloat16` conversion), so values that are not exactly representable in `BFloat16` change when written; a read widens the 16-bit value back to `float` losslessly.
-- `QBit` is wire-compatible with `Array(element_type)` and should not drift: the client transmits the logical vector as a length-prefixed array of its element type (`float[]` for `BFloat16`/`Float32`, `double[]` for `Float64`) rather than the server's bit-transposed on-disk layout, so a `QBit(E, N)` value read from or written to the server round-trips as an array of `E`.
+- `QBit` is wire-compatible with `Array(element_type)` and should not drift: the client transmits the logical vector as a length-prefixed array of its element type (`float[]` for `BFloat16`/`Float32`, `double[]` for `Float64`) rather than the server's bit-transposed on-disk layout, so a `QBit(E, N)` value read from or written to the server round-trips as an array of `E`. A written `QBit(E, N)` value must contain exactly `N` elements: a wrong-sized (including empty) vector is rejected during binary serialization with an `IllegalArgumentException` rather than deferred to a server error, matching the fixed dimension the server enforces.
 - Timezone conversion helpers preserve nanoseconds and can intentionally shift local date or time when interpreted in a different timezone; this behavior is covered by tests and should not be normalized away.
 - `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`.