test(client-v2, jdbc-v2): address review on BFloat16 support (#2279)

Per @chernser's review on #2934:
- Throw SkipException (instead of a silent return) when a BFloat16 test is
  skipped on a server older than 24.11.
- Add exhaustive integration read tests in both client-v2 and jdbc-v2 covering
  all 2^16 BFloat16 bit patterns. The dataset is written with SQL text literals
  so the server - not the client's binary writer - produces the stored bytes,
  decoupling the read path under test from any write-side error. The read is
  verified against the server's stored bits (reinterpretAsUInt16), which stays
  correct regardless of how the server converts a literal to BFloat16 (e.g. it
  flushes subnormals to zero).
- Add a jdbc-v2 setFloat write-as-Float test and assert the JDBC BFloat16 ->
  FLOAT / java.lang.Float mapping via ResultSetMetaData and getObject.
- Document the jdbc-v2 BFloat16 = Float mapping in CHANGELOG and docs/features.md.

No production changes: jdbc-v2 already mapped BFloat16 to Float and works via
the (now BFloat16-capable) client-v2 reader/writer.

Implements: #2279

Author: polyglotAI-bot

CHANGELOG.md

@@ -4,11 +4,13 @@
 
 ### 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
+- **[client-v2, jdbc-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 failed with an unsupported-data-type error. (https://github.com/ClickHouse/clickhouse-java/issues/2279)
+  high 16 bits of the `float`, matching the ClickHouse server's own `Float32` → `BFloat16` conversion. In the JDBC driver
+  (`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. Previously reading or writing a `BFloat16` column failed with an
+  unsupported-data-type error. (https://github.com/ClickHouse/clickhouse-java/issues/2279)
 
 ### Bug Fixes 
 

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

@@ -23,6 +23,7 @@
 import lombok.NoArgsConstructor;
 import org.apache.commons.lang3.StringUtils;
 import org.testng.Assert;
+import org.testng.SkipException;
 import org.testng.annotations.AfterMethod;
 import org.testng.annotations.BeforeMethod;
 import org.testng.annotations.DataProvider;
@@ -174,7 +175,7 @@ public static String tblCreateSQL(String table) {
     @Test(groups = {"integration"})
     public void testBFloat16() throws Exception {
         if (isVersionMatch(BFLOAT16_UNSUPPORTED_VERSIONS)) {
-            return;
+            throw new SkipException("BFloat16 requires ClickHouse 24.11+");
         }
 
         // Exhaustively cover every one of the 2^16 BFloat16 bit patterns through a full client
@@ -217,10 +218,82 @@ private static void assertBFloat16Equals(Float actual, Float expected) {
         }
     }
 
+    @Test(groups = {"integration"})
+    public void testBFloat16ReadFromServerWrittenValues() throws Exception {
+        if (isVersionMatch(BFLOAT16_UNSUPPORTED_VERSIONS)) {
+            throw new SkipException("BFloat16 requires ClickHouse 24.11+");
+        }
+
+        // Exhaustively cover reading every one of the 2^16 BFloat16 bit patterns. The dataset is
+        // written with SQL text literals so the *server* produces the stored bytes; this decouples
+        // the read path under test from the client's binary write path. Row b holds the BFloat16
+        // whose bit pattern is b, so a read must widen it to Float.intBitsToFloat(b << 16) (NaN
+        // inputs collapse to a single canonical NaN on the server and only read back as NaN).
+        final String table = "test_bfloat16_read";
+        final int count = 1 << 16;
+        final int batchSize = 4096; // keep each INSERT well under max_query_size
+        client.execute("DROP TABLE IF EXISTS " + table).get();
+        client.execute("CREATE TABLE " + table
+                + " (rowId Int32, v BFloat16, vNull Nullable(BFloat16)) ENGINE = MergeTree ORDER BY rowId").get();
+
+        for (int start = 0; start < count; start += batchSize) {
+            int end = Math.min(start + batchSize, count);
+            StringBuilder insert = new StringBuilder("INSERT INTO ").append(table).append(" VALUES ");
+            for (int b = start; b < end; b++) {
+                String literal = bFloat16Literal(b);
+                if (b > start) {
+                    insert.append(',');
+                }
+                insert.append('(').append(b).append(',').append(literal).append(',')
+                        .append(b == 0 ? "NULL" : literal).append(')');
+            }
+            client.execute(insert.toString()).get();
+        }
+
+        // The server's stored bits are the ground truth for the read: reinterpretAsUInt16(v) yields
+        // the exact 16-bit pattern the server wrote, so a correct read must widen it to
+        // Float.intBitsToFloat(bits << 16). Deriving the expectation from the stored bits (rather than
+        // from rowId) keeps the read assertion correct regardless of how the server converts the text
+        // literal to BFloat16 - in particular the server flushes BFloat16 subnormals to zero, so those
+        // patterns are stored as +/-0 even though the literal named a tiny subnormal.
+        AtomicInteger rowCount = new AtomicInteger(0);
+        client.queryAll("SELECT rowId, v, reinterpretAsUInt16(v) AS bits, vNull FROM " + table + " ORDER BY rowId")
+                .forEach(row -> {
+                    int b = row.getInteger("rowId");
+                    float expected = Float.intBitsToFloat(row.getInteger("bits") << 16);
+                    assertBFloat16Equals(row.getFloat("v"), expected);
+                    if (b == 0) {
+                        Assert.assertNull(row.getObject("vNull"));
+                    } else {
+                        assertBFloat16Equals((Float) row.getObject("vNull"), expected);
+                    }
+                    rowCount.incrementAndGet();
+                });
+        Assert.assertEquals(rowCount.get(), count);
+    }
+
+    // Text form of the exact BFloat16 whose bit pattern is {@code pattern}, suitable for use as a
+    // SQL numeric literal. Non-finite patterns use ClickHouse's nan/inf/-inf tokens; every other
+    // pattern uses the shortest round-trippable decimal of Float.intBitsToFloat(pattern << 16),
+    // which is exactly representable in BFloat16 (its low 16 mantissa bits are zero).
+    private static String bFloat16Literal(int pattern) {
+        float value = Float.intBitsToFloat(pattern << 16);
+        if (Float.isNaN(value)) {
+            return "nan";
+        }
+        if (value == Float.POSITIVE_INFINITY) {
+            return "inf";
+        }
+        if (value == Float.NEGATIVE_INFINITY) {
+            return "-inf";
+        }
+        return Float.toString(value);
+    }
+
     @Test(groups = {"integration"})
     public void testBFloat16TruncationMatchesServer() throws Exception {
         if (isVersionMatch(BFLOAT16_UNSUPPORTED_VERSIONS)) {
-            return;
+            throw new SkipException("BFloat16 requires ClickHouse 24.11+");
         }
 
         // (a) The client must decode a BFloat16 produced by the server (Float32 -> BFloat16
@@ -250,7 +323,7 @@ public void testBFloat16TruncationMatchesServer() throws Exception {
     @Test(groups = {"integration"})
     public void testBFloat16InDynamicColumn() throws Exception {
         if (isVersionMatch("(,24.8]") || isVersionMatch(BFLOAT16_UNSUPPORTED_VERSIONS)) {
-            return;
+            throw new SkipException("BFloat16 requires ClickHouse 24.11+");
         }
 
         // Reading a BFloat16 held in a Dynamic column exercises the dynamic type-tag read path.

docs/features.md

@@ -18,7 +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`.
+- 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.
 - 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.

jdbc-v2/src/test/java/com/clickhouse/jdbc/JdbcDataTypeTests.java

@@ -13,6 +13,7 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.testng.Assert;
+import org.testng.SkipException;
 import org.testng.annotations.BeforeClass;
 import org.testng.annotations.DataProvider;
 import org.testng.annotations.Test;
@@ -495,6 +496,151 @@ public void testUnsignedIntegerTypes() throws Exception {
     }
 
 
+    // BFloat16 was introduced in ClickHouse 24.11.
+    private static final String BFLOAT16_UNSUPPORTED_VERSIONS = "(,24.10]";
+
+    @Test(groups = { "integration" })
+    public void testBFloat16() throws SQLException {
+        if (ClickHouseVersion.of(getServerVersion()).check(BFLOAT16_UNSUPPORTED_VERSIONS)) {
+            throw new SkipException("BFloat16 was introduced in ClickHouse 24.11");
+        }
+
+        // Exhaustively cover reading every one of the 2^16 BFloat16 bit patterns through the JDBC
+        // driver, which must expose BFloat16 as java.lang.Float. The dataset is written with SQL
+        // text literals so the *server* produces the stored bytes, decoupling the read path under
+        // test from any write-side codec error. Row b holds the BFloat16 whose bit pattern is b, so
+        // a read must widen it to Float.intBitsToFloat(b << 16) (NaN inputs collapse to a single
+        // canonical NaN on the server and only read back as NaN).
+        final String table = "test_bfloat16";
+        final int count = 1 << 16;
+        final int batchSize = 4096; // keep each INSERT well under max_query_size
+        runQuery("DROP TABLE IF EXISTS " + table);
+        runQuery("CREATE TABLE " + table
+                + " (rowId Int32, v BFloat16, vNull Nullable(BFloat16)) ENGINE = MergeTree ORDER BY rowId");
+
+        try (Connection conn = getJdbcConnection();
+                Statement stmt = conn.createStatement()) {
+            for (int start = 0; start < count; start += batchSize) {
+                int end = Math.min(start + batchSize, count);
+                StringBuilder insert = new StringBuilder("INSERT INTO ").append(table).append(" VALUES ");
+                for (int b = start; b < end; b++) {
+                    String literal = bFloat16Literal(b);
+                    if (b > start) {
+                        insert.append(',');
+                    }
+                    insert.append('(').append(b).append(',').append(literal).append(',')
+                            .append(b == 0 ? "NULL" : literal).append(')');
+                }
+                stmt.executeUpdate(insert.toString());
+            }
+        }
+
+        // The server's stored bits are the ground truth for the read: reinterpretAsUInt16(v) yields
+        // the exact 16-bit pattern the server wrote, so a correct read must widen it to
+        // Float.intBitsToFloat(bits << 16). Deriving the expectation from the stored bits keeps the
+        // assertion correct regardless of how the server converts the text literal to BFloat16 - in
+        // particular the server flushes BFloat16 subnormals to zero, so those patterns are stored as
+        // +/-0 even though the literal named a tiny subnormal.
+        try (Connection conn = getJdbcConnection();
+                Statement stmt = conn.createStatement();
+                ResultSet rs = stmt.executeQuery(
+                        "SELECT rowId, v, reinterpretAsUInt16(v) AS bits, vNull FROM " + table + " ORDER BY rowId")) {
+            ResultSetMetaData meta = rs.getMetaData();
+            assertEquals(meta.getColumnType(2), Types.FLOAT, "BFloat16 should map to Types.FLOAT");
+            assertEquals(meta.getColumnClassName(2), Float.class.getName(), "BFloat16 should map to java.lang.Float");
+
+            int rows = 0;
+            while (rs.next()) {
+                int b = rs.getInt("rowId");
+                float expected = Float.intBitsToFloat(rs.getInt("bits") << 16);
+                Object obj = rs.getObject("v");
+                assertTrue(obj instanceof Float,
+                        "BFloat16 getObject should return Float but was "
+                                + (obj == null ? "null" : obj.getClass().getName()));
+                assertBFloat16Equals((Float) obj, expected);
+                assertBFloat16Equals(rs.getFloat("v"), expected);
+                if (b == 0) {
+                    assertNull(rs.getObject("vNull"));
+                } else {
+                    assertBFloat16Equals((Float) rs.getObject("vNull"), expected);
+                }
+                rows++;
+            }
+            assertEquals(rows, count);
+        }
+    }
+
+    @Test(groups = { "integration" })
+    public void testBFloat16WriteAsFloat() throws SQLException {
+        if (ClickHouseVersion.of(getServerVersion()).check(BFLOAT16_UNSUPPORTED_VERSIONS)) {
+            throw new SkipException("BFloat16 was introduced in ClickHouse 24.11");
+        }
+
+        // Writing through the JDBC Float surface: setFloat must store a BFloat16. Exactly
+        // representable values round-trip unchanged; 3.14f is truncated to the high 16 bits
+        // (0x4048F5C3 -> 0x40480000 = 3.125f), matching the server's Float32 -> BFloat16 cast.
+        final String table = "test_bfloat16_write";
+        runQuery("DROP TABLE IF EXISTS " + table);
+        runQuery("CREATE TABLE " + table
+                + " (rowId Int32, v BFloat16, vNull Nullable(BFloat16)) ENGINE = MergeTree ORDER BY rowId");
+
+        float[] inputs = { 0f, 0.5f, 1.5f, -2.5f, 3.14f, 128.0f };
+        try (Connection conn = getJdbcConnection();
+                PreparedStatement ps = conn.prepareStatement("INSERT INTO " + table + " VALUES (?, ?, ?)")) {
+            for (int i = 0; i < inputs.length; i++) {
+                ps.setInt(1, i);
+                ps.setFloat(2, inputs[i]);
+                ps.setFloat(3, inputs[i]);
+                ps.executeUpdate();
+            }
+        }
+
+        try (Connection conn = getJdbcConnection();
+                Statement stmt = conn.createStatement();
+                ResultSet rs = stmt.executeQuery("SELECT rowId, v, vNull FROM " + table + " ORDER BY rowId")) {
+            for (int i = 0; i < inputs.length; i++) {
+                assertTrue(rs.next());
+                float expected = Float.intBitsToFloat(Float.floatToIntBits(inputs[i]) & 0xFFFF0000);
+                assertEquals(rs.getFloat("v"), expected, 0f);
+                assertEquals(rs.getObject("v"), Float.valueOf(expected));
+                assertEquals(rs.getFloat("vNull"), expected, 0f);
+                assertEquals(rs.getObject("vNull"), Float.valueOf(expected));
+            }
+            assertFalse(rs.next());
+        }
+    }
+
+    // Text form of the exact BFloat16 whose bit pattern is {@code pattern}, suitable for use as a
+    // SQL numeric literal. Non-finite patterns use ClickHouse's nan/inf/-inf tokens; every other
+    // pattern uses the shortest round-trippable decimal of Float.intBitsToFloat(pattern << 16),
+    // which is exactly representable in BFloat16 (its low 16 mantissa bits are zero).
+    private static String bFloat16Literal(int pattern) {
+        float value = Float.intBitsToFloat(pattern << 16);
+        if (Float.isNaN(value)) {
+            return "nan";
+        }
+        if (value == Float.POSITIVE_INFINITY) {
+            return "inf";
+        }
+        if (value == Float.NEGATIVE_INFINITY) {
+            return "-inf";
+        }
+        return Float.toString(value);
+    }
+
+    // BFloat16 keeps the high 16 bits of a float32, so every non-NaN value round-trips bit-for-bit;
+    // NaN inputs collapse to a single canonical NaN on the server and only read back as NaN.
+    private static void assertBFloat16Equals(Float actual, Float expected) {
+        if (expected == null) {
+            assertNull(actual);
+        } else if (Float.isNaN(expected)) {
+            assertTrue(actual != null && Float.isNaN(actual), "expected a NaN but got " + actual);
+        } else {
+            assertTrue(actual != null, "expected " + expected + " but got null");
+            assertEquals(Float.floatToRawIntBits(actual), Float.floatToRawIntBits(expected));
+        }
+    }
+
     @Test(groups = { "integration" })
     public void testUUIDTypes() throws Exception {
         Random rand = new Random();