feat(client-v2): add BFloat16 data type support

BFloat16 (ClickHouse 24.11+) was registered in ClickHouseDataType but
client-v2 threw "BFloat16 is not supported yet" on read and
UnsupportedOperationException on write. Implement read and write for it,
mapping BFloat16 to the Java float type.

On the wire BFloat16 is the high 16 bits of the IEEE-754 float32
(little-endian, 2 bytes). Reads widen the value losslessly; writes keep
the high 16 bits of the float, matching the server's own Float32 ->
BFloat16 conversion (the low mantissa bits are truncated).

Covers the generic read path, the numeric accessors (getFloat/...),
POJO read/write, Nullable(BFloat16), and BFloat16 held in Dynamic/Variant
columns. Adds a deterministic codec unit test and integration tests
(round-trip, server truncation parity, Dynamic column). Updates CHANGELOG
and docs/features.md.

Implements: #2279

Author: polyglotAI-bot

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 [Release Migration Guide](docs/releases/0_11_0.md)
 
+### New Features
+
+- **[client-v2]** Added support for the `BFloat16` data type (ClickHouse `24.11+`). `BFloat16` columns are read as Java
+  `float` values (widening is lossless) and written from `float`/`Float` values, including through generic records, POJO
+  binding, `Nullable(BFloat16)`, and `BFloat16` values held in `Dynamic`/`Variant` columns. On write the client keeps the
+  high 16 bits of the `float`, matching the ClickHouse server's own `Float32` → `BFloat16` conversion. Previously reading
+  or writing a `BFloat16` column threw "BFloat16 is not supported yet". (https://github.com/ClickHouse/clickhouse-java/issues/2279)
+
 ### Bug Fixes 
 
 - **[client-v2]** Fixed POJO insert error classification so transport write failures such as java.net.SocketException:

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

@@ -202,6 +202,7 @@ static Map<ClickHouseDataType, Set<Class<?>>> dataTypeClassMap() {
         map.put(String, setOf(String.class));
         map.put(Float64, setOf(float.class, Float.class, double.class, Double.class));
         map.put(Float32, setOf(float.class, Float.class));
+        map.put(BFloat16, setOf(float.class, Float.class));
         map.put(Decimal, setOf(float.class, Float.class, double.class, Double.class, BigDecimal.class));
         map.put(Decimal256, setOf(float.class, Float.class, double.class, Double.class, BigDecimal.class));
         map.put(Decimal128, setOf(float.class, Float.class, double.class, Double.class, BigDecimal.class));

clickhouse-data/src/main/java/com/clickhouse/data/format/BinaryStreamUtils.java

@@ -985,6 +985,21 @@ public static void writeFloat32(OutputStream output, float value) throws IOExcep
         writeInt32(output, Float.floatToIntBits(value));
     }
 
+    /**
+     * Write a bfloat16 value to given output stream. {@code BFloat16} occupies the
+     * high 16 bits of the IEEE-754 {@code float} representation, so the low 16 bits of
+     * the mantissa are dropped (truncated toward zero), which matches how the ClickHouse
+     * server converts {@code Float32} to {@code BFloat16}.
+     *
+     * @param output non-null output stream
+     * @param value  float value to be stored as bfloat16
+     * @throws IOException when failed to write value to output stream or reached
+     *                     end of the stream
+     */
+    public static void writeBFloat16(OutputStream output, float value) throws IOException {
+        writeInt16(output, (short) (Float.floatToIntBits(value) >>> 16));
+    }
+
     /**
      * Read a double value from given input stream.
      *

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

@@ -323,6 +323,7 @@ protected void setSchema(TableSchema schema) {
                 case Int256:
                 case UInt128:
                 case UInt256:
+                case BFloat16:
                 case Float32:
                 case Float64:
                 case Decimal:

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

@@ -164,6 +164,8 @@ public <T> T readValue(ClickHouseColumn column, Class<?> typeHint) throws IOExce
                     return (T) readDecimal(ClickHouseDataType.Decimal128.getMaxPrecision(), scale);
                 case Decimal256:
                     return (T) readDecimal(ClickHouseDataType.Decimal256.getMaxPrecision(), scale);
+                case BFloat16:
+                    return (T) (Float)readBFloat16LE();
                 case Float32:
                     return (T) (Float)readFloatLE();
                 case Float64:
@@ -509,6 +511,18 @@ public float readFloatLE() throws IOException {
         return Float.intBitsToFloat(readIntLE());
     }
 
+    /**
+     * Reads a little-endian {@code BFloat16} value from the internal input stream and
+     * widens it to a {@code float}. {@code BFloat16} carries the high 16 bits of the
+     * IEEE-754 {@code float} representation, so widening (shifting them back into the
+     * high bits) is lossless.
+     * @return float value
+     * @throws IOException when IO error occurs
+     */
+    public float readBFloat16LE() throws IOException {
+        return Float.intBitsToFloat(readUnsignedShortLE() << 16);
+    }
+
     private static final byte[] B1 = new byte[8];
     /**
      * Reads a double value from the internal input stream.
@@ -1205,6 +1219,7 @@ public static boolean isReadToPrimitive(ClickHouseDataType dataType) {
             case Int32:
             case UInt32:
             case Int64:
+            case BFloat16:
             case Float32:
             case Float64:
             case Bool:
@@ -1410,8 +1425,6 @@ private ClickHouseColumn readDynamicData() throws IOException {
             }
             case AggregateFunction:
                 throw new ClientException("Aggregate functions are not supported yet");
-            case BFloat16:
-                throw new ClientException("BFloat16 is not supported yet");
             default:
                 return ClickHouseColumn.of("v", type, false, 0, 0);
         }

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

@@ -554,6 +554,9 @@ private static void serializePrimitiveData(OutputStream stream, Object value, Cl
             case UInt256:
                 BinaryStreamUtils.writeUnsignedInt256(stream, NumberConverter.toBigInteger(value));
                 break;
+            case BFloat16:
+                BinaryStreamUtils.writeBFloat16(stream, (float) value);
+                break;
             case Float32:
                 BinaryStreamUtils.writeFloat32(stream, (float) value);
                 break;
@@ -1112,6 +1115,11 @@ private static void binaryReaderMethodForType(MethodVisitor mv, Class<?> targetT
                 readerMethodReturnType = Type.getDescriptor(long.class);
                 convertOpcode = longToOpcode(targetType);
                 break;
+            case BFloat16:
+                readerMethod = "readBFloat16LE";
+                readerMethodReturnType = Type.getDescriptor(float.class);
+                convertOpcode = floatToOpcode(targetType);
+                break;
             case Float32:
                 readerMethod = "readFloatLE";
                 readerMethodReturnType = Type.getDescriptor(float.class);

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

@@ -5,6 +5,7 @@
 import com.clickhouse.data.ClickHouseColumn;
 import com.clickhouse.data.format.BinaryStreamUtils;
 import org.testng.Assert;
+import org.testng.annotations.DataProvider;
 import org.testng.annotations.Test;
 
 import java.io.ByteArrayInputStream;
@@ -45,6 +46,31 @@ public void testSerializeDecimalTargetFromGenericNumberValue() throws IOExceptio
         Assert.assertEquals(reader.getBigDecimal("value"), new BigDecimal("987654.321"));
     }
 
+    @DataProvider(name = "bFloat16Values")
+    public static Object[][] bFloat16Values() {
+        // input float, expected float after a BFloat16 round-trip. BFloat16 keeps the high
+        // 16 bits of the float32 representation, so writing truncates the low mantissa bits
+        // (matching the ClickHouse server) and reading widens the value back losslessly.
+        return new Object[][] {
+                {0.0f, 0.0f},                    // zero
+                {1.5f, 1.5f},                    // exactly representable
+                {-2.5f, -2.5f},                  // exactly representable, sign preserved
+                {100.0f, 100.0f},                // exactly representable
+                {256.0f, 256.0f},                // exactly representable
+                {3.14f, 3.125f},                 // 0x4048F5C3 -> 0x40480000 (low bits dropped)
+                {0.1f, 0.099609375f},            // 0x3DCCCCCD -> 0x3DCC0000 (low bits dropped)
+        };
+    }
+
+    @Test(dataProvider = "bFloat16Values")
+    public void testSerializeBFloat16RoundTrip(float input, float expected) throws IOException {
+        RowBinaryWithNamesAndTypesFormatReader reader = serializeSingleValue("BFloat16", input);
+
+        reader.next();
+
+        Assert.assertEquals(reader.getFloat("value"), expected, 0.0f);
+    }
+
     private RowBinaryWithNamesAndTypesFormatReader serializeSingleValue(String type, Object value)
             throws IOException {
         ByteArrayOutputStream out = new ByteArrayOutputStream();

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

@@ -154,6 +154,89 @@ public static String tblCreateSQL(String table) {
         }
     }
 
+    @Data
+    @AllArgsConstructor
+    @NoArgsConstructor
+    public static class DTOForBFloat16Tests {
+        private int rowId;
+        private float bFloat16;
+        private Float bFloat16Nullable;
+
+        public static String tblCreateSQL(String table) {
+            return tableDefinition(table, "rowId Int16", "bFloat16 BFloat16",
+                    "bFloat16Nullable Nullable(BFloat16)");
+        }
+    }
+
+    // BFloat16 was introduced in ClickHouse 24.11.
+    private static final String BFLOAT16_UNSUPPORTED_VERSIONS = "(,24.10]";
+
+    @Test(groups = {"integration"})
+    public void testBFloat16() throws Exception {
+        if (isVersionMatch(BFLOAT16_UNSUPPORTED_VERSIONS)) {
+            return;
+        }
+
+        final String table = "test_bfloat16";
+        // Only exactly-representable BFloat16 values are used here so a client-side write
+        // followed by a read returns the same value. Truncation of non-representable values
+        // is covered by testBFloat16TruncationMatchesServer.
+        writeReadVerify(table,
+                DTOForBFloat16Tests.tblCreateSQL(table),
+                DTOForBFloat16Tests.class,
+                Arrays.asList(
+                        new DTOForBFloat16Tests(0, 1.5f, -2.5f),
+                        new DTOForBFloat16Tests(1, 0.0f, null),
+                        new DTOForBFloat16Tests(2, 256.0f, 100.0f)),
+                (data, dto) -> {
+                    DTOForBFloat16Tests expected = data.get(dto.getRowId());
+                    Assert.assertEquals(dto.getBFloat16(), expected.getBFloat16(), 0.0f);
+                    Assert.assertEquals(dto.getBFloat16Nullable(), expected.getBFloat16Nullable());
+                });
+    }
+
+    @Test(groups = {"integration"})
+    public void testBFloat16TruncationMatchesServer() throws Exception {
+        if (isVersionMatch(BFLOAT16_UNSUPPORTED_VERSIONS)) {
+            return;
+        }
+
+        // (a) The client must decode a BFloat16 produced by the server (Float32 -> BFloat16
+        //     drops the low mantissa bits) to the same value.
+        List<GenericRecord> cast = client.queryAll(
+                "SELECT CAST(3.14 AS BFloat16) AS v, CAST(0.1 AS BFloat16) AS v2");
+        Assert.assertEquals(cast.get(0).getFloat("v"), 3.125f, 0.0f);        // 0x4048F5C3 -> 0x40480000
+        Assert.assertEquals(cast.get(0).getFloat("v2"), 0.099609375f, 0.0f); // 0x3DCCCCCD -> 0x3DCC0000
+
+        // (b) A value written by the client must be stored byte-for-byte identically to the
+        //     server's own Float32 -> BFloat16 conversion of the same value.
+        final String table = "test_bfloat16_truncation";
+        writeReadVerify(table,
+                DTOForBFloat16Tests.tblCreateSQL(table),
+                DTOForBFloat16Tests.class,
+                Arrays.asList(new DTOForBFloat16Tests(0, 3.14f, 0.1f)),
+                (data, dto) -> {
+                    Assert.assertEquals(dto.getBFloat16(), 3.125f, 0.0f);
+                    Assert.assertEquals(dto.getBFloat16Nullable(), Float.valueOf(0.099609375f));
+                });
+        List<GenericRecord> parity = client.queryAll(
+                "SELECT reinterpretAsUInt16(bFloat16) AS written, " +
+                        "reinterpretAsUInt16(CAST(toFloat32(3.14) AS BFloat16)) AS server FROM " + table);
+        Assert.assertEquals(parity.get(0).getInteger("written"), parity.get(0).getInteger("server"));
+    }
+
+    @Test(groups = {"integration"})
+    public void testBFloat16InDynamicColumn() throws Exception {
+        if (isVersionMatch("(,24.8]") || isVersionMatch(BFLOAT16_UNSUPPORTED_VERSIONS)) {
+            return;
+        }
+
+        // Reading a BFloat16 held in a Dynamic column exercises the dynamic type-tag read path.
+        List<GenericRecord> rows = client.queryAll(
+                "SELECT CAST(CAST(1.5 AS BFloat16) AS Dynamic) AS v SETTINGS allow_experimental_dynamic_type = 1");
+        Assert.assertEquals(rows.get(0).getObject("v"), Float.valueOf(1.5f));
+    }
+
     @Test(groups = {"integration"})
     public void testVariantWithSimpleDataTypes() throws Exception {
         if (isVersionMatch("(,24.8]")) {

docs/features.md

@@ -18,6 +18,7 @@ This document lists stable, user-visible behavior in `client-v2` and `jdbc-v2` t
 - Binary format readers: Reads ClickHouse binary result formats including `Native`, `RowBinary`, `RowBinaryWithNames`, and `RowBinaryWithNamesAndTypes`.
 - 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`.
 - 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.
@@ -39,6 +40,7 @@ Compatibility-sensitive traits:
 - String escaping behavior in `SQLUtils` is compatibility-sensitive: `enquoteLiteral()` uses SQL-style doubled single quotes, while `escapeSingleQuotes()` escapes both backslashes and single quotes with backslashes.
 - 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.
 - 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`.