jdbc-v2: Array#getResultSet() fails for createArrayOf arrays and geo columns (IndexOutOfBoundsException / wrong VALUE type)

Start in jdbc-v2/src/main/java/com/clickhouse/jdbc/types/ArrayResultSet.java at elementColumn (around line 96), and compare it with how types/Array.java handles nesting level 0. The factory that builds the level-0 column is ConnectionImpl#createArrayOf. Done means that createArrayOf and geo (Ring, Polygon) arrays return one (INDEX, VALUE) row per element with the correct element type, and that a DataProvider test covers the scalar, Tuple, Map, empty, Ring and Polygon cases while the read-path Array(Tuple) case stays unchanged.

Description

java.sql.Array#getResultSet() fails, or returns the wrong VALUE column, when the column of the Array has array nesting level 0. Two entry points create such an Array:

1. Connection#createArrayOf(typeName, elements). typeName is the element type (JDBC javadoc, and the javadoc of ConnectionImpl#createArrayOf). The driver builds the column from that element type, so the column has nesting level 0.
2. ResultSet#getArray on a geo column (Ring, Polygon). The geo column metadata has nesting level 0 and no nested columns.

Observed results:

• Scalar element type (Int32, String, Nullable(String), LowCardinality(String), Date, and also an empty Int32 array): getResultSet() and getResultSet(index, count) throw an unchecked java.lang.IndexOutOfBoundsException: Index: 0, not a SQLException.
• Ring and Polygon read with getArray: the same IndexOutOfBoundsException.
• Tuple(...) element type: the VALUE column gets the type of the first tuple field (String for Tuple(String, Int8), Int8 for Tuple(Int8, String)). Then getObject(2) and getString(2) throw Value of class [Ljava.lang.Object; cannot be converted to class java.lang.String.
• Map(String, Int32) element type: the VALUE column gets the key type String. Then getObject(2) throws Value of class java.util.HashMap cannot be converted to class java.lang.String.

The same Array object reports the correct element type in getBaseTypeName() (Int32, Tuple(String, Int8), Ring), so the array and its own result set disagree. For an array read from the server with the same element types ([...]::Array(Int32), [...]::Array(Tuple(String, Int8))), getResultSet() works.

Steps to reproduce

1. conn.createArrayOf("Int32", new Integer[]{1, 2}).getResultSet() → IndexOutOfBoundsException.
2. conn.createArrayOf("Tuple(String, Int8)", new Object[]{new Object[]{"a", (byte) 1}}).getResultSet() → the VALUE column type is String. rs.next(); rs.getObject(2) → SQLException.
3. SELECT [(1.0, 2.0), (3.0, 4.0)]::Ring, then rs.getArray(1).getResultSet() → IndexOutOfBoundsException.

Error Log or Exception StackTrace

Scalar element type, and the Ring / Polygon read path:

java.lang.IndexOutOfBoundsException: Index: 0
	at java.base/java.util.Collections$EmptyList.get(Collections.java:4587)
	at com.clickhouse.jdbc.types.ArrayResultSet.elementColumn(ArrayResultSet.java:96)
	at com.clickhouse.jdbc.types.ArrayResultSet.<init>(ArrayResultSet.java:67)
	at com.clickhouse.jdbc.types.Array.getResultSet(Array.java:97)

Tuple(String, Int8) element type, getObject(2):

java.sql.SQLException: Value of class [Ljava.lang.Object; cannot be converted to class java.lang.String

Expected Behaviour

getResultSet() returns one (INDEX, VALUE) row per element, and the VALUE column has the element type. This is the result that the driver already gives for an array read from the server.

Element types from the server (toTypeName(x[1]), 26.9.1.1629), compared with the driver:

• [1, 2]::Array(Int32) → Int32. Read path: VALUE is Int32, getObject(2) is 1. createArrayOf("Int32", ...): exception.
• [('a', 1)]::Array(Tuple(String, Int8)) → Tuple(String, Int8). Read path: VALUE is Tuple(String, Int8), getObject(2) is [a, 1]. createArrayOf("Tuple(String, Int8)", ...): VALUE is String, getObject(2) throws.
• [map('k', 1)]::Array(Map(String, Int32)) → Map(String, Int32). createArrayOf("Map(String, Int32)", ...): VALUE is String.
• [(1.0, 2.0), (3.0, 4.0)]::Ring → Point. getArray(1).getResultSet(): exception.
• [[(1.0, 2.0)], [(3.0, 4.0)]]::Polygon → Ring. getArray(1).getResultSet(): exception.

Code Example

try (Connection conn = DriverManager.getConnection("jdbc:clickhouse://localhost:8123/default", "default", "")) {
    // 1. scalar element type
    Array ints = conn.createArrayOf("Int32", new Integer[]{1, 2});
    ints.getResultSet(); // IndexOutOfBoundsException: Index: 0

    // 2. Tuple element type
    Array tuples = conn.createArrayOf("Tuple(String, Int8)", new Object[]{new Object[]{"a", (byte) 1}});
    ResultSet rs = tuples.getResultSet();
    System.out.println(rs.getMetaData().getColumnTypeName(2)); // String, expected Tuple(String, Int8)
    rs.next();
    rs.getObject(2); // SQLException: Value of class [Ljava.lang.Object; cannot be converted to class java.lang.String

    // 3. geo column, read path
    try (Statement stmt = conn.createStatement();
         ResultSet geo = stmt.executeQuery("SELECT [(1.0, 2.0), (3.0, 4.0)]::Ring")) {
        geo.next();
        geo.getArray(1).getResultSet(); // IndexOutOfBoundsException: Index: 0
    }
}

Root cause

jdbc-v2/src/main/java/com/clickhouse/jdbc/types/ArrayResultSet.java:96 (elementColumn):

return column.getArrayNestedLevel() == 1 ? column.getArrayBaseColumn() : nestedColumns.get(0);

After the Nested special case, the code assumes that every column with a nesting level other than 1 keeps its element in getNestedColumns().get(0). That is true for Array(Array(...)) (level 2 or more). It is not true for level-0 columns:

• ConnectionImpl#createArrayOf (ConnectionImpl.java:647) builds ClickHouseColumn.of("array", typeName) from the element type. For a scalar type the nested list is empty, so get(0) throws. For Tuple / Map, the nested list holds the tuple fields / the map key and value, so get(0) is the first field / the key.
• Geo columns (Ring, Polygon) have level 0 and an empty nested list, so get(0) throws.

types/Array.java:32 already handles level 0 in a different way: it uses the column itself as the element (getArrayNestedLevel() > 0 ? getArrayBaseColumn() : column). That is why getBaseTypeName() is correct and getResultSet() is not. ArrayResultSet#getArray (ArrayResultSet.java:165) also uses elementColumn.

The same expression is in v0.9.9, v0.10.0 and v0.11.0-rc1.

Suggested fix

In ArrayResultSet#elementColumn, resolve a level-0 column explicitly. Do not fall through to getNestedColumns().get(0):

• A geo column → its element type (Ring → Point, Polygon → Ring, and the same for the other geo array types).
• Any other level-0 column (the element column that createArrayOf builds) → the column itself, the same as the Array constructor does.

Keep the current resolution for Nested, for level 1 (Array(T), QBit) and for level 2 or more. A @DataProvider test can cover the rows above (scalar, Nullable, Tuple, Map, empty array, Ring, Polygon), plus a contrast row for a read-path Array(Tuple(...)) that must not change.

Open PR #3215 (for #3190) changes types/Array.java only for nesting level 2 or more. It does not change this behavior.

Configuration

Client Configuration

// default driver settings, no properties

Environment

• Cloud
• Client version: jdbc-v2 0.12.0-rc1-SNAPSHOT, built from main at 5392b642e. The same code is in 0.9.9, 0.10.0 and 0.11.0-rc1.
• Language version: OpenJDK 17.0.20.1
• OS: Linux (Docker)

ClickHouse Server

• ClickHouse Server version: 26.9.1.1629
• ClickHouse Server non-default settings, if any: none
• CREATE TABLE statements for tables involved: none (no table is necessary)
• Sample data for all these tables: none

---

Found by automated analysis (Polyglot AI) while working on #3190. Verified with an integration test through the public JDBC API against a live ClickHouse 26.9.1.1629 server, not only by reading the code.