Add getSchema() to Records for schema access with empty results

PierceAndy · PierceAndy · commit ab709af92d3a · 2026-03-05T13:47:06.000+08:00
Expose TableSchema from Records to enable access to column metadata even
when query results are empty
diff --git a/client-v2/src/main/java/com/clickhouse/client/api/query/Records.java b/client-v2/src/main/java/com/clickhouse/client/api/query/Records.java
@@ -2,6 +2,7 @@
 
 import com.clickhouse.client.api.data_formats.ClickHouseBinaryFormatReader;
 import com.clickhouse.client.api.data_formats.internal.BinaryReaderBackedRecord;
+import com.clickhouse.client.api.metadata.TableSchema;
 import com.clickhouse.client.api.metrics.OperationMetrics;
 import com.clickhouse.client.api.metrics.ServerMetrics;
 
@@ -64,6 +65,15 @@ public boolean isEmpty() {
         return empty;
     }
 
+    /**
+     * Returns the schema of the collection.
+     *
+     * @return table schema with column definitions
+     */
+    public TableSchema getSchema() {
+        return reader.getSchema();
+    }
+
     Stream<GenericRecord> stream() {
         return StreamSupport.stream(spliterator(), false);
     }
diff --git a/client-v2/src/test/java/com/clickhouse/client/query/QueryTests.java b/client-v2/src/test/java/com/clickhouse/client/query/QueryTests.java
@@ -678,6 +678,36 @@ public void testQueryRecordsEmptyResult() throws Exception {
         }
     }
 
+    @Test(groups = {"integration"})
+    public void testGetSchemaWithEmptyResult() throws Exception {
+        try (Records records = client.queryRecords("SELECT 1 as id, 'test' as name LIMIT 0").get(3, TimeUnit.SECONDS)) {
+            Assert.assertTrue(records.isEmpty());
+
+            TableSchema schema = records.getSchema();
+            Assert.assertNotNull(schema);
+            Assert.assertEquals(schema.getColumns().size(), 2);
+            Assert.assertEquals(schema.getColumnByIndex(1).getColumnName(), "id");
+            Assert.assertEquals(schema.getColumnByIndex(2).getColumnName(), "name");
+        }
+    }
+
+    @Test(groups = {"integration"})
+    public void testGetSchemaWithResults() throws Exception {
+        try (Records records = client.queryRecords("SELECT 1 as id, 'test' as name").get(3, TimeUnit.SECONDS)) {
+            Assert.assertFalse(records.isEmpty());
+
+            TableSchema recordsSchema = records.getSchema();
+            Assert.assertNotNull(recordsSchema);
+            Assert.assertEquals(recordsSchema.getColumns().size(), 2);
+
+            for (GenericRecord record : records) {
+                Assert.assertEquals(record.getInteger("id"), Integer.valueOf(1));
+                Assert.assertEquals(record.getString("name"), "test");
+                Assert.assertEquals(record.getSchema(), recordsSchema);
+            }
+        }
+    }
+
     @Test(description = "Verifies that queryRecords reads all values from the response", groups = {"integration"})
     public void testQueryRecordsReadsAllValues() throws Exception {
         try (Records records = client.queryRecords("SELECT toInt32(number) FROM system.numbers LIMIT 3").get(3, TimeUnit.SECONDS)) {
