feat(client-v2, jdbc-v2): add QBit data type support

QBit(element_type, dimension) is transmitted over RowBinary exactly like
Array(element_type) - a var-int length followed by that many element values -
so it is read and written as a Java array of its element type (float[] for
BFloat16/Float32, double[] for Float64) reusing the existing array codec,
while keeping dataType == QBit for metadata fidelity. In jdbc-v2 QBit maps to
java.sql.Types.ARRAY and is exposed as a java.sql.Array. Element types:
BFloat16, Float32, Float64. The bit-transposed on-disk layout is a server
storage detail and is not exposed to the client.

Implements: #2610

Author: polyglotAI-bot

CHANGELOG.md

@@ -12,6 +12,14 @@
   `getFloat`/`setFloat` and `getObject` accessors, and reported as such by `ResultSetMetaData` and `DatabaseMetaData`.
   Previously reading or writing a `BFloat16` column failed with an
   unsupported-data-type error. (https://github.com/ClickHouse/clickhouse-java/issues/2279)
+- **[client-v2, jdbc-v2]** Added support for the experimental `QBit(element_type, dimension)` vector data type
+  (ClickHouse `25.10+`; the `allow_experimental_qbit_type` server setting is required to create a column), with
+  `BFloat16`, `Float32`, or `Float64` element types. A `QBit` value is transmitted over `RowBinary` exactly like
+  `Array(element_type)`, so it is read and written as a Java array of the element type (`float[]` for
+  `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)
 - **[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

clickhouse-data/src/main/java/com/clickhouse/data/ClickHouseColumn.java

@@ -73,6 +73,7 @@ public final class ClickHouseColumn implements Serializable {
     private static final String KEYWORD_NESTED = ClickHouseDataType.Nested.name();
     private static final String KEYWORD_VARIANT = ClickHouseDataType.Variant.name();
     private static final String KEYWORD_JSON = ClickHouseDataType.JSON.name();
+    private static final String KEYWORD_QBIT = ClickHouseDataType.QBit.name();
 
     private int columnCount;
     private int columnIndex;
@@ -146,6 +147,17 @@ private static ClickHouseColumn update(ClickHouseColumn column) {
                     }
                 }
                 break;
+            case QBit:
+                // QBit(element_type, dimension) is a one-level array of its element type on the
+                // wire; the dimension parameter is kept as the column precision.
+                if (!column.nested.isEmpty()) {
+                    column.arrayLevel = 1;
+                    column.arrayBaseColumn = column.nested.get(0);
+                }
+                if (size > 1) {
+                    column.precision = Integer.parseInt(column.parameters.get(1).trim());
+                }
+                break;
             case Bool:
                 column.template = ClickHouseBoolValue.ofNull();
                 break;
@@ -567,6 +579,26 @@ protected static int readColumn(String args, int startIndex, int len, String nam
                 fixedLength = false;
                 estimatedLength++;
             }
+        } else if (args.startsWith(KEYWORD_QBIT, i)) {
+            int index = args.indexOf('(', i + KEYWORD_QBIT.length());
+            if (index < i) {
+                throw new IllegalArgumentException(ERROR_MISSING_NESTED_TYPE);
+            }
+            List<String> params = new LinkedList<>();
+            i = ClickHouseUtils.readParameters(args, index, len, params);
+            if (params.size() < 2) {
+                throw new IllegalArgumentException(
+                        "QBit requires an element type and a dimension, e.g. QBit(Float32, 8)");
+            }
+            // QBit(element_type, dimension) is transmitted over RowBinary exactly like
+            // Array(element_type): a var-int length followed by that many element values. The
+            // first parameter is the element type and drives the nested (item) column.
+            List<ClickHouseColumn> nestedColumns = new LinkedList<>();
+            nestedColumns.add(ClickHouseColumn.of("", params.get(0)));
+            column = new ClickHouseColumn(ClickHouseDataType.QBit, name, args.substring(startIndex, i),
+                    nullable, lowCardinality, params, nestedColumns);
+            fixedLength = false;
+            estimatedLength++;
         }
 
         if (column == null) {

clickhouse-data/src/test/java/com/clickhouse/data/ClickHouseColumnTest.java

@@ -508,4 +508,33 @@ public Object[][] testJSONBinaryFormat_dp() {
                 {"JSON(max_dynamic_types=3,max_dynamic_paths=3, SKIP REGEXP '^-.*',SKIP ff,   flags Array(Array(Array(Int8))), SKIP alt_count)", 2, Arrays.asList("flags")},
         };
     }
+
+    @DataProvider(name = "qbitTypesProvider")
+    private static Object[][] qbitTypesProvider() {
+        return new Object[][] {
+                { "QBit(BFloat16, 4)", ClickHouseDataType.BFloat16, 4 },
+                { "QBit(Float32, 8)", ClickHouseDataType.Float32, 8 },
+                { "QBit(Float64, 1536)", ClickHouseDataType.Float64, 1536 },
+        };
+    }
+
+    @Test(groups = { "unit" }, dataProvider = "qbitTypesProvider")
+    public void testParseQBit(String typeName, ClickHouseDataType elementType, int dimension) {
+        ClickHouseColumn column = ClickHouseColumn.of("vec", typeName);
+        Assert.assertEquals(column.getDataType(), ClickHouseDataType.QBit);
+        Assert.assertEquals(column.getOriginalTypeName(), typeName);
+        // QBit(element_type, dimension) is a one-level array of its element type on the wire.
+        Assert.assertEquals(column.getArrayNestedLevel(), 1);
+        Assert.assertNotNull(column.getArrayBaseColumn());
+        Assert.assertEquals(column.getArrayBaseColumn().getDataType(), elementType);
+        Assert.assertEquals(column.getNestedColumns().size(), 1);
+        Assert.assertEquals(column.getNestedColumns().get(0).getDataType(), elementType);
+        // The fixed vector dimension is retained as the column precision.
+        Assert.assertEquals(column.getPrecision(), dimension);
+    }
+
+    @Test(groups = { "unit" }, expectedExceptions = IllegalArgumentException.class)
+    public void testParseQBitRequiresDimension() {
+        ClickHouseColumn.of("vec", "QBit(Float32)");
+    }
 }

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

@@ -234,6 +234,8 @@ public <T> T readValue(ClickHouseColumn column, Class<?> typeHint) throws IOExce
                         return (T) readJsonData(input, actualColumn);
                     }
 //                case Object: // deprecated https://clickhouse.com/docs/en/sql-reference/data-types/object-data-type
+                case QBit:
+                    // QBit(element_type, dimension) is transmitted like Array(element_type).
                 case Array:
                     if (typeHint == null) { typeHint = arrayDefaultTypeHint;}
                     return convertArray(readArray(actualColumn), typeHint);

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

@@ -63,6 +63,8 @@ public class SerializerUtils {
     public static void serializeData(OutputStream stream, Object value, ClickHouseColumn column) throws IOException {
         //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).
             case Array:
                 serializeArrayData(stream, value, column);
                 break;

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

@@ -67,6 +67,8 @@ public String convertToString(Object value, ClickHouseColumn column) {
             case IPv4:
             case IPv6:
                 return ipvToString(value, column);
+            case QBit:
+                // QBit is rendered as an array literal of its element type, like Array(element_type).
             case Array:
                 return  arrayToString(value, column);
             case Point:

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

@@ -92,8 +92,17 @@ public void tearDown() {
 
     private <T> void writeReadVerify(String table, String tableDef, Class<T> dtoClass, List<T> data,
                                      BiConsumer<List<T>, T> rowVerifier) throws Exception {
+        writeReadVerify(table, tableDef, dtoClass, data, rowVerifier, null);
+    }
+
+    private <T> void writeReadVerify(String table, String tableDef, Class<T> dtoClass, List<T> data,
+                                     BiConsumer<List<T>, T> rowVerifier, CommandSettings ddlSettings) throws Exception {
         client.execute("DROP TABLE IF EXISTS " + table).get();
-        client.execute(tableDef);
+        if (ddlSettings == null) {
+            client.execute(tableDef);
+        } else {
+            client.execute(tableDef, ddlSettings).get();
+        }
 
         final TableSchema tableSchema = client.getTableSchema(table);
         client.register(dtoClass, tableSchema);
@@ -107,6 +116,88 @@ private <T> void writeReadVerify(String table, String tableDef, Class<T> dtoClas
         Assert.assertEquals(rowCount.get(), data.size());
     }
 
+    // QBit was introduced in ClickHouse 25.10.
+    private static final String QBIT_UNSUPPORTED_VERSIONS = "(,25.9]";
+
+    @Data
+    @AllArgsConstructor
+    @NoArgsConstructor
+    public static class QBitFloat32DTO {
+        private long rowId;
+        private float[] vec;
+        private int tail;
+
+        public static String tblCreateSQL(String table) {
+            return tableDefinition(table, "rowId Int64", "vec QBit(Float32, 8)", "tail Int32");
+        }
+    }
+
+    @Data
+    @AllArgsConstructor
+    @NoArgsConstructor
+    public static class QBitFloat64DTO {
+        private long rowId;
+        private double[] vec;
+        private int tail;
+
+        public static String tblCreateSQL(String table) {
+            return tableDefinition(table, "rowId Int64", "vec QBit(Float64, 8)", "tail Int32");
+        }
+    }
+
+    @Data
+    @AllArgsConstructor
+    @NoArgsConstructor
+    public static class QBitBFloat16DTO {
+        private long rowId;
+        private float[] vec;
+        private int tail;
+
+        public static String tblCreateSQL(String table) {
+            return tableDefinition(table, "rowId Int64", "vec QBit(BFloat16, 8)", "tail Int32");
+        }
+    }
+
+    @Test(groups = {"integration"})
+    public void testQBit() throws Exception {
+        if (isVersionMatch(QBIT_UNSUPPORTED_VERSIONS)) {
+            throw new SkipException("QBit requires ClickHouse 25.10+");
+        }
+
+        // A QBit(element_type, dimension) value is transmitted over RowBinary exactly like an
+        // Array(element_type): a var-int length followed by that many element values. The full
+        // client write -> server -> client read round-trip is verified for every supported
+        // element type. The trailing Int32 column would shift (and the assertion fail) if the
+        // QBit codec consumed the wrong number of bytes.
+        CommandSettings ddl = (CommandSettings) new CommandSettings()
+                .serverSetting("allow_experimental_qbit_type", "1");
+
+        final float[] f32 = {1f, -2f, 3.5f, 4f, 5f, 6f, 7f, 8f};
+        writeReadVerify("test_qbit_f32", QBitFloat32DTO.tblCreateSQL("test_qbit_f32"),
+                QBitFloat32DTO.class, Arrays.asList(new QBitFloat32DTO(0, f32, 42)),
+                (all, dto) -> {
+                    Assert.assertEquals(dto.getVec(), f32);
+                    Assert.assertEquals(dto.getTail(), 42);
+                }, ddl);
+
+        final double[] f64 = {1d, -2d, 3.5d, 4d, 5d, 6d, 7d, 8d};
+        writeReadVerify("test_qbit_f64", QBitFloat64DTO.tblCreateSQL("test_qbit_f64"),
+                QBitFloat64DTO.class, Arrays.asList(new QBitFloat64DTO(0, f64, 42)),
+                (all, dto) -> {
+                    Assert.assertEquals(dto.getVec(), f64);
+                    Assert.assertEquals(dto.getTail(), 42);
+                }, ddl);
+
+        // Integers up to 256 are exactly representable in BFloat16, so these round-trip bit-for-bit.
+        final float[] bf16 = {1f, 2f, 4f, 8f, 16f, 32f, 64f, 128f};
+        writeReadVerify("test_qbit_bf16", QBitBFloat16DTO.tblCreateSQL("test_qbit_bf16"),
+                QBitBFloat16DTO.class, Arrays.asList(new QBitBFloat16DTO(0, bf16, 42)),
+                (all, dto) -> {
+                    Assert.assertEquals(dto.getVec(), bf16);
+                    Assert.assertEquals(dto.getTail(), 42);
+                }, ddl);
+    }
+
     @Test(groups = {"integration"})
     public void testNestedDataTypes() throws Exception {
         final String table = "test_nested_types";

docs/features.md

@@ -21,6 +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.
 - 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.
@@ -43,6 +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`.
 - 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`.
@@ -76,6 +78,7 @@ Compatibility-sensitive traits:
 - Database metadata: Implements JDBC `DatabaseMetaData` for ClickHouse catalogs, schemas, tables, columns, and related capability reporting.
 - Parameter metadata: Reports prepared-statement parameter counts.
 - Type mapping and conversions: Maps ClickHouse types to JDBC types and Java classes, including date/time handling and `java.time` support.
+- QBit type mapping: For ClickHouse `25.10+`, JDBC exposes the experimental `QBit(element_type, dimension)` type as `ARRAY`, returning the vector as a `java.sql.Array` of the element type from `getObject()`/`getArray()`. Supported element types are `BFloat16` and `Float32` (both `java.lang.Float`) and `Float64` (`java.lang.Double`). The `allow_experimental_qbit_type` server setting is required to create a `QBit` column.
 - Custom result-set type map: `ResultSet#getObject(int|String, Map<String, Class<?>>)` accepts both ClickHouse type names and JDBC `SQLType` names as map keys. Only unwrapped type names are used — `Nullable(...)` and `LowCardinality(...)` wrappers are stripped before lookup, so a key like `"Int32"` matches both `Int32` and `Nullable(Int32)` columns, and keys like `"Nullable(Int32)"` are not recognized. Lookup order is `ClickHouseColumn#getDataType().name()` (e.g. `"Int32"`, `"String"`, `"DateTime"`) then `SQLType.getName()` (e.g. `"INTEGER"`, `"VARCHAR"`, `"TIMESTAMP"`); a missing entry leaves the value uncoerced (read as-is). The feature is supported for primitive ClickHouse types only — `Array`, `Tuple`, `Map`, `Nested`, and geometry types (`Point`, `Ring`, `LineString`, `Polygon`, `MultiPolygon`, `MultiLineString`, `Geometry`) bypass the type map and are returned in their native form.
 - Arrays and tuples: Supports JDBC arrays plus ClickHouse tuple values through custom `Array` and `Struct` implementations.
 - Geometry type mapping: For ClickHouse `25.11+`, where `Geometry` changed from a string alias to `Variant(Point, Ring, LineString, MultiLineString, Polygon, MultiPolygon)`, JDBC exposes `Geometry` as `ARRAY`, returns nested Java arrays from `getObject()`/`getArray()`, and accepts `Struct` or nested `Array` inputs for prepared-statement inserts depending on the geometry shape.

jdbc-v2/src/main/java/com/clickhouse/jdbc/internal/JdbcUtils.java

@@ -117,7 +117,7 @@ private static Map<ClickHouseDataType, SQLType> generateTypeMap() {
         map.put(ClickHouseDataType.AggregateFunction, JDBCType.OTHER);
         map.put(ClickHouseDataType.Variant, JDBCType.OTHER);
         map.put(ClickHouseDataType.Dynamic, JDBCType.OTHER);
-        map.put(ClickHouseDataType.QBit, JDBCType.OTHER);
+        map.put(ClickHouseDataType.QBit, JDBCType.ARRAY);
 
 
         return ImmutableMap.copyOf(map);

jdbc-v2/src/main/java/com/clickhouse/jdbc/types/Array.java

@@ -27,7 +27,9 @@ public class Array implements java.sql.Array {
     public Array(ClickHouseColumn column, Object[] elements) throws SQLException {
         this.column = column;
         this.array = elements;
-        ClickHouseColumn baseColumn = (this.column.isArray() ? this.column.getArrayBaseColumn() : this.column);
+        // QBit is not an Array (isArray() == false) but is still a one-level array of its element
+        // type, so use the array nesting level (set for both Array and QBit) to find the element column.
+        ClickHouseColumn baseColumn = (this.column.getArrayNestedLevel() > 0 ? this.column.getArrayBaseColumn() : this.column);
         this.baseDataType = baseColumn.getDataType();
         this.elementTypeName = baseColumn.getOriginalTypeName();
         this.type = JdbcUtils.CLICKHOUSE_TO_SQL_TYPE_MAP.getOrDefault(baseDataType, JDBCType.OTHER).getVendorTypeNumber();