Merge pull request #2747 from ClickHouse/02/15/26/array_getters_in_reader

Added getting arrays of objects and other types of arrays

Author: chernser

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

@@ -240,74 +240,75 @@ public interface ClickHouseBinaryFormatReader extends AutoCloseable {
     ClickHouseGeoMultiPolygonValue getGeoMultiPolygon(String colName);
 
     /**
-     * Reads column with name `colName` as a string.
-     *
+     * @see #getList(int)
      * @param colName - column name
-     * @return
+     * @return list of values, or {@code null} if the value is null
      */
     <T> List<T> getList(String colName);
 
     /**
-     * Reads column with name `colName` as a string.
-     *
+     * @see #getByteArray(int)
      * @param colName - column name
-     * @return
+     * @return array of bytes, or {@code null} if the value is null
      */
     byte[] getByteArray(String colName);
 
     /**
-     * Reads column with name `colName` as a string.
-     *
+     * @see #getIntArray(int)
      * @param colName - column name
-     * @return
+     * @return array of int values, or {@code null} if the value is null
      */
     int[] getIntArray(String colName);
 
     /**
-     * Reads column with name `colName` as a string.
-     *
+     * @see #getLongArray(int)
      * @param colName - column name
-     * @return
+     * @return array of long values, or {@code null} if the value is null
      */
     long[] getLongArray(String colName);
 
     /**
-     * Reads column with name `colName` as a string.
-     *
+     * @see #getFloatArray(int)
      * @param colName - column name
-     * @return
+     * @return array of float values, or {@code null} if the value is null
      */
     float[] getFloatArray(String colName);
 
     /**
-     * Reads column with name `colName` as a string.
-     *
+     * @see #getDoubleArray(int)
      * @param colName - column name
-     * @return
+     * @return array of double values, or {@code null} if the value is null
      */
     double[] getDoubleArray(String colName);
 
     /**
-     *
-     * @param colName
-     * @return
+     * @see #getBooleanArray(int)
+     * @param colName - column name
+     * @return array of boolean values, or {@code null} if the value is null
      */
     boolean[] getBooleanArray(String colName);
 
     /**
-     *
-     * @param colName
-     * @return
+     * @see #getShortArray(int)
+     * @param colName - column name
+     * @return array of short values, or {@code null} if the value is null
      */
     short[] getShortArray(String colName);
 
     /**
-     *
-     * @param colName
-     * @return
+     * @see #getStringArray(int)
+     * @param colName - column name
+     * @return array of string values, or {@code null} if the value is null
      */
     String[] getStringArray(String colName);
 
+    /**
+     * @see #getObjectArray(int)
+     * @param colName - column name
+     * @return array of objects, or {@code null} if the value is null
+     */
+    Object[] getObjectArray(String colName);
+
     /**
      * Reads column with name `colName` as a string.
      *
@@ -483,59 +484,100 @@ public interface ClickHouseBinaryFormatReader extends AutoCloseable {
     ClickHouseGeoMultiPolygonValue getGeoMultiPolygon(int index);
 
     /**
-     * Reads column with name `colName` as a string.
+     * Returns the value of the specified column as a {@link List}. Suitable for reading Array columns of any type.
+     * <p>For nested arrays (e.g. {@code Array(Array(Int64))}), returns a {@code List<List<Long>>}.
+     * For nullable arrays (e.g. {@code Array(Nullable(Int32))}), list elements may be {@code null}.</p>
      *
-     * @param index - column name
-     * @return
+     * @param index - column index (1-based)
+     * @return list of values, or {@code null} if the value is null
+     * @throws com.clickhouse.client.api.ClientException if the column is not an array type
      */
     <T> List<T> getList(int index);
 
     /**
-     * Reads column with name `colName` as a string.
+     * Returns the value of the specified column as a {@code byte[]}. Suitable for 1D Array columns only.
      *
-     * @param index - column name
-     * @return
+     * @param index - column index (1-based)
+     * @return array of bytes, or {@code null} if the value is null
+     * @throws com.clickhouse.client.api.ClientException if the value cannot be converted to a byte array
      */
     byte[] getByteArray(int index);
 
     /**
-     * Reads column with name `colName` as a string.
+     * Returns the value of the specified column as an {@code int[]}. Suitable for 1D Array columns only.
      *
-     * @param index - column name
-     * @return
+     * @param index - column index (1-based)
+     * @return array of int values, or {@code null} if the value is null
+     * @throws com.clickhouse.client.api.ClientException if the value cannot be converted to an int array
      */
     int[] getIntArray(int index);
 
     /**
-     * Reads column with name `colName` as a string.
+     * Returns the value of the specified column as a {@code long[]}. Suitable for 1D Array columns only.
      *
-     * @param index - column name
-     * @return
+     * @param index - column index (1-based)
+     * @return array of long values, or {@code null} if the value is null
+     * @throws com.clickhouse.client.api.ClientException if the value cannot be converted to a long array
      */
     long[] getLongArray(int index);
 
     /**
-     * Reads column with name `colName` as a string.
+     * Returns the value of the specified column as a {@code float[]}. Suitable for 1D Array columns only.
      *
-     * @param index - column name
-     * @return
+     * @param index - column index (1-based)
+     * @return array of float values, or {@code null} if the value is null
+     * @throws com.clickhouse.client.api.ClientException if the value cannot be converted to a float array
      */
     float[] getFloatArray(int index);
 
     /**
-     * Reads column with name `colName` as a string.
+     * Returns the value of the specified column as a {@code double[]}. Suitable for 1D Array columns only.
      *
-     * @param index - column name
-     * @return
+     * @param index - column index (1-based)
+     * @return array of double values, or {@code null} if the value is null
+     * @throws com.clickhouse.client.api.ClientException if the value cannot be converted to a double array
      */
     double[] getDoubleArray(int index);
 
+    /**
+     * Returns the value of the specified column as a {@code boolean[]}. Suitable for 1D Array columns only.
+     *
+     * @param index - column index (1-based)
+     * @return array of boolean values, or {@code null} if the value is null
+     * @throws com.clickhouse.client.api.ClientException if the value cannot be converted to a boolean array
+     */
     boolean[] getBooleanArray(int index);
 
-    short [] getShortArray(int index);
+    /**
+     * Returns the value of the specified column as a {@code short[]}. Suitable for 1D Array columns only.
+     *
+     * @param index - column index (1-based)
+     * @return array of short values, or {@code null} if the value is null
+     * @throws com.clickhouse.client.api.ClientException if the value cannot be converted to a short array
+     */
+    short[] getShortArray(int index);
 
+    /**
+     * Returns the value of the specified column as a {@code String[]}. Suitable for 1D Array columns only.
+     * Cannot be used for none string element types.
+     *
+     * @param index - column index (1-based)
+     * @return array of string values, or {@code null} if the value is null
+     * @throws com.clickhouse.client.api.ClientException if the column is not an array type
+     */
     String[] getStringArray(int index);
 
+    /**
+     * Returns the value of the specified column as an {@code Object[]}. Suitable for multidimensional Array columns.
+     * Nested arrays are recursively converted to {@code Object[]}.
+     * Note: result is not cached so avoid repetitive calls on same column.
+     *
+     * @param index - column index (1-based)
+     * @return array of objects, or {@code null} if the value is null
+     * @throws com.clickhouse.client.api.ClientException if the column is not an array type
+     */
+    Object[] getObjectArray(int index);
+
     Object[] getTuple(int index);
 
     Object[] getTuple(String colName);

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

@@ -562,6 +562,11 @@ public String[] getStringArray(String colName) {
         return getStringArray(schema.nameToColumnIndex(colName));
     }
 
+    @Override
+    public Object[] getObjectArray(String colName) {
+        return getObjectArray(schema.nameToColumnIndex(colName));
+    }
+
     @Override
     public boolean hasValue(int colIndex) {
         return currentRecord[colIndex - 1] != null;
@@ -816,16 +821,30 @@ public String[] getStringArray(int index) {
         }
         if (value instanceof BinaryStreamReader.ArrayValue) {
             BinaryStreamReader.ArrayValue array = (BinaryStreamReader.ArrayValue) value;
-            int length = array.length;
-            if (!array.itemType.equals(String.class))
-                throw new ClientException("Not A String type.");
-            String[] values = new String[length];
-            for (int i = 0; i < length; i++) {
-                values[i] = (String)((BinaryStreamReader.ArrayValue) value).get(i);
+            if (array.itemType == String.class) {
+                return (String[]) array.getArray();
+            } else if (array.itemType == BinaryStreamReader.EnumValue.class) {
+                BinaryStreamReader.EnumValue[] enumValues = (BinaryStreamReader.EnumValue[]) array.getArray();
+                return Arrays.stream(enumValues).map(BinaryStreamReader.EnumValue::getName).toArray(String[]::new);
+            } else {
+                throw new ClientException("Not an array of strings");
             }
-            return values;
         }
-        throw new ClientException("Not ArrayValue type.");
+        throw new ClientException("Column is not of array type");
+    }
+
+    @Override
+    public Object[] getObjectArray(int index) {
+        Object value = readValue(index);
+        if (value == null) {
+            return null;
+        }
+        if (value instanceof BinaryStreamReader.ArrayValue) {
+            return ((BinaryStreamReader.ArrayValue) value).toObjectArray();
+        } else if (value instanceof List<?>) {
+            return ((List<?>) value).toArray(new Object[0]);
+        }
+        throw new ClientException("Column is not of array type");
     }
 
     @Override

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

@@ -175,6 +175,11 @@ public String[] getStringArray(String colName) {
         return reader.getStringArray(colName);
     }
 
+    @Override
+    public Object[] getObjectArray(String colName) {
+        return reader.getObjectArray(colName);
+    }
+
     @Override
     public String getString(int index) {
         return reader.getString(index);
@@ -335,6 +340,11 @@ public String[] getStringArray(int index) {
         return reader.getStringArray(index);
     }
 
+    @Override
+    public Object[] getObjectArray(int index) {
+        return reader.getObjectArray(index);
+    }
+
     @Override
     public Object[] getTuple(int index) {
         return reader.getTuple(index);

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

@@ -604,15 +604,14 @@ public static byte[] readNBytesLE(InputStream input, byte[] buffer, int offset,
      */
     public ArrayValue readArray(ClickHouseColumn column) throws IOException {
         int len = readVarInt(input);
-        if (len == 0) {
-            return new ArrayValue(Object.class, 0);
-        }
 
         ArrayValue array;
         ClickHouseColumn itemTypeColumn = column.getNestedColumns().get(0);
-        if (column.getArrayNestedLevel() == 1) {
+        if (len == 0) {
+            Class<?> itemClass = itemTypeColumn.getDataType().getPrimitiveClass();
+            array = new ArrayValue(itemClass == null ? Object.class : itemClass, 0);
+        } else if (column.getArrayNestedLevel() == 1) {
             array = readArrayItem(itemTypeColumn, len);
-
         } else {
             array = new ArrayValue(ArrayValue.class, len);
             for (int i = 0; i < len; i++) {
@@ -645,6 +644,10 @@ public ArrayValue readArrayItem(ClickHouseColumn itemTypeColumn, int len) throws
                 itemClass = long.class;
             } else if (firstValue instanceof Boolean) {
                 itemClass = boolean.class;
+            } else if (firstValue instanceof Float) {
+                itemClass = float.class;
+            } else if (firstValue instanceof Double) {
+                itemClass = double.class;
             }
 
             array = new ArrayValue(itemClass, len);
@@ -752,6 +755,23 @@ public Object[] getArrayOfObjects() {
                 return (Object[]) array;
             }
         }
+
+        /**
+         * Returns array of objects, recursively converting nested ArrayValue elements to Object[].
+         * This is useful for nested arrays (e.g. Array(Array(Int64))) where elements are ArrayValue instances.
+         *
+         * @return Object[] with nested ArrayValue elements converted to Object[]
+         */
+        public Object[] toObjectArray() {
+            Object[] result = new Object[length];
+            for (int i = 0; i < length; i++) {
+                Object item = get(i);
+                result[i] = (item instanceof ArrayValue) ? ((ArrayValue) item).toObjectArray() : item;
+            }
+            return result;
+        }
+
+
     }
 
     public static class EnumValue extends Number {
@@ -785,6 +805,10 @@ public double doubleValue() {
             return value;
         }
 
+        public String getName() {
+            return name;
+        }
+
         @Override
         public String toString() {
             return name;