You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Yes. client-v2 has the same defect for the spellings enum(...) and ENUM(...): the client always reads them as Enum8, so an ordinal outside -128..127 silently shifts the row. The canonical spelling Enum(...) does not fold: read and write fail with Unsupported data type: Enum. Only type strings written by the application are affected.
Checked on main (f73e372bc) and ClickHouse 26.9.1.1629. The released v0.11.1 has the same code.
Findings
enum(...) / ENUM(...) → always Enum8 (silent wrong data on read).ClickHouseDataType.Enum8 declares the alias "ENUM" (clickhouse-data/src/main/java/com/clickhouse/data/ClickHouseDataType.java:61, since 2023-01), and ClickHouseDataType.of() falls back to the upper-case name (:493). The server types enum('a' = 1000) as Enum16. The reader reads 1 of 2 bytes, and the next column reads the high byte. 2 server rows give 3 client rows, without an error. When the total byte count is odd, the read ends with an EOFException.
Write: for ordinal 1000, the Int8 range check throws. When the written value is small but the column is Enum16 (mixed ordinals), the client writes 1 byte and the server rejects the insert (CANNOT_READ_ALL_DATA).
Enum(...) → ClickHouseDataType.Enum, which has no width (ClickHouseDataType.java:60, case-sensitive). BinaryStreamReader.readValue (client-v2/.../internal/BinaryStreamReader.java:301) and SerializerUtils.serializeData (client-v2/.../internal/SerializerUtils.java:784) have no case for it. Both throw, also for Enum('a' = 1). This is not silent, but a bare Enum does not work in a schema written by hand.
enum16(...) → Unknown data type: enum16. The server accepts it (Enum16('a' = 1000)). Enum8/Enum16 are case-sensitive in ClickHouseDataType and have no alias.
Where it is reachable: only through ClickHouseColumn.of(name, type) in a TableSchema that the application builds, for example for Client.newBinaryFormatReader(response, schema) on RowBinary without a header, RowBinaryFormatWriter, or register(Class, schema). A schema from the server (RowBinaryWithNamesAndTypes / Native header, getTableSchema) always spells Enum8/Enum16, and these read correctly (rows Enum16('a' = 1000) below).
Suggested fix (same rule as the server and ClickHouse/clickhouse-js#1131): in ClickHouseColumn.update() (clickhouse-data/src/main/java/com/clickhouse/data/ClickHouseColumn.java:177-181), for a bare enum name (Enum / enum / ENUM), set the data type from the ordinals: Enum16 if a value is outside -128..127, else Enum8. Explicit Enum8/Enum16 stay as they are. As an option, accept enum8/enum16 without case sensitivity, as the server does. I do not expect a breaking change: each input that changes behavior throws or returns wrong data today.
Open: the parser is in clickhouse-data, which jdbc-v2 and v1 share. I did not test those clients. #3304 and PR #3312 (enum member validation on insert) are a different problem.
Output
server 26.9.1.1629
1) server type name | client-v2 ClickHouseColumn.of(...).getDataType()
Enum('a' = 1) server=Enum8('a' = 1) client=Enum
Enum('a' = 1000) server=Enum16('a' = 1000) client=Enum
enum('a' = 1) server=Enum8('a' = 1) client=Enum8
enum('a' = 1000) server=Enum16('a' = 1000) client=Enum8
ENUM('a' = 1000) server=Enum16('a' = 1000) client=Enum8
Enum8('a' = 1) server=Enum8('a' = 1) client=Enum8
Enum16('a' = 1000) server=Enum16('a' = 1000) client=Enum16
enum16('a' = 1000) server=Enum16('a' = 1000) client=error: Unknown data type: enum16
2) RowBinary read, hand-written schema [e <type>, u UInt8], expect one row [a, 7]
read Enum('a' = 1) x1 -> rows=0 then error: ClientException: Failed to read value for column e <- IllegalArgumentException: Unsupported data type: Enum
read Enum('a' = 1000) x1 -> rows=0 then error: ClientException: Failed to read value for column e <- IllegalArgumentException: Unsupported data type: Enum
read enum('a' = 1) x1 -> rows=1 [a, 7]
read enum('a' = 1000) x1 -> rows=0 then error: ClientException: Reading row 2 (time since last next call 1) <- IOException: Reading column 1 (`u`) in row 2 (time since last next call 1) <- EOFException: End of stream reached before reading all data
read ENUM('a' = 1000) x1 -> rows=0 then error: ClientException: Reading row 2 (time since last next call 0) <- IOException: Reading column 1 (`u`) in row 2 (time since last next call 0) <- EOFException: End of stream reached before reading all data
read Enum8('a' = 1) x1 -> rows=1 [a, 7]
read Enum16('a' = 1000) x1 -> rows=1 [a, 7]
read enum16('a' = 1000) x1 -> rows=0 then error: IllegalArgumentException: Unknown data type: enum16
2b) same read, 2 source rows (expect [a, 7], [a, 7])
read enum('a' = 1000) x2 -> rows=3 [<unknown>, 3], [<unknown>, 232], [<unknown>, 7]
read Enum16('a' = 1000) x2 -> rows=2 [a, 7], [a, 7]
3) RowBinary write into (e Enum16('a' = 1000), u UInt8), expect stored a,7
write Enum('a' = 1000) -> error: UnsupportedOperationException: Unsupported data type: Enum
write enum('a' = 1000) -> error: IllegalArgumentException: int(1000) should be between -128 and 127 inclusive of both values
write Enum16('a' = 1000) -> bytes=[e8 03 07] stored a,7
3b) RowBinary write 'a' into (e Enum16('a' = 1, 'b' = 1000), u UInt8), expect stored a,7
write enum('a' = 1, 'b' = 1000) -> bytes=[01 07] server error: ServerException: Code: 33. DB::Exception: Cannot read all data. Bytes read: 0. Bytes expected: 1: (at row 1) : While executing WaitForAsyncInsert. (CANNOT_READ_ALL_DATA) (version 26.9.1.1629 (official build))
write Enum16('a' = 1, 'b' = 1000) -> bytes=[01 00 07] stored a,7
Reproduction program (java -cp client-v2.jar:<deps> Repro.java, after mvn -pl client-v2 -am install -DskipTests)
@polyglotAI-bot
Thanks! Prepare the fix that do what is suggested in your comment.
Make sure having integration tests especially with dynamic and variant types. Add needed metadata to com.clickhouse.client.api.data_formats.internal.BinaryStreamReader.EnumValue so when we read it from stream we know size of 8 or 16
Activity
chernser commentedon Nov 13, 2026
@polyglotAI-bot please do preliminary investigation.
polyglotAI-bot commentedon Nov 13, 2026
Yes. client-v2 has the same defect for the spellings
enum(...)andENUM(...): the client always reads them asEnum8, so an ordinal outside -128..127 silently shifts the row. The canonical spellingEnum(...)does not fold: read and write fail withUnsupported data type: Enum. Only type strings written by the application are affected.Checked on
main(f73e372bc) and ClickHouse 26.9.1.1629. The releasedv0.11.1has the same code.Findings
enum(...)/ENUM(...)→ alwaysEnum8(silent wrong data on read).ClickHouseDataType.Enum8declares the alias"ENUM"(clickhouse-data/src/main/java/com/clickhouse/data/ClickHouseDataType.java:61, since 2023-01), andClickHouseDataType.of()falls back to the upper-case name (:493). The server typesenum('a' = 1000)asEnum16. The reader reads 1 of 2 bytes, and the next column reads the high byte. 2 server rows give 3 client rows, without an error. When the total byte count is odd, the read ends with anEOFException.Int8range check throws. When the written value is small but the column isEnum16(mixed ordinals), the client writes 1 byte and the server rejects the insert (CANNOT_READ_ALL_DATA).Enum(...)→ClickHouseDataType.Enum, which has no width (ClickHouseDataType.java:60, case-sensitive).BinaryStreamReader.readValue(client-v2/.../internal/BinaryStreamReader.java:301) andSerializerUtils.serializeData(client-v2/.../internal/SerializerUtils.java:784) have no case for it. Both throw, also forEnum('a' = 1). This is not silent, but a bareEnumdoes not work in a schema written by hand.enum16(...)→Unknown data type: enum16. The server accepts it (Enum16('a' = 1000)).Enum8/Enum16are case-sensitive inClickHouseDataTypeand have no alias.Where it is reachable: only through
ClickHouseColumn.of(name, type)in aTableSchemathat the application builds, for example forClient.newBinaryFormatReader(response, schema)onRowBinarywithout a header,RowBinaryFormatWriter, orregister(Class, schema). A schema from the server (RowBinaryWithNamesAndTypes/Nativeheader,getTableSchema) always spellsEnum8/Enum16, and these read correctly (rowsEnum16('a' = 1000)below).Suggested fix (same rule as the server and ClickHouse/clickhouse-js#1131): in
ClickHouseColumn.update()(clickhouse-data/src/main/java/com/clickhouse/data/ClickHouseColumn.java:177-181), for a bare enum name (Enum/enum/ENUM), set the data type from the ordinals:Enum16if a value is outside -128..127, elseEnum8. ExplicitEnum8/Enum16stay as they are. As an option, acceptenum8/enum16without case sensitivity, as the server does. I do not expect a breaking change: each input that changes behavior throws or returns wrong data today.Open: the parser is in
clickhouse-data, which jdbc-v2 and v1 share. I did not test those clients. #3304 and PR #3312 (enum member validation on insert) are a different problem.Output
Reproduction program (
java -cp client-v2.jar:<deps> Repro.java, aftermvn -pl client-v2 -am install -DskipTests)chernser commentedon Nov 13, 2026
@polyglotAI-bot
Thanks! Prepare the fix that do what is suggested in your comment.
Make sure having integration tests especially with dynamic and variant types. Add needed metadata to com.clickhouse.client.api.data_formats.internal.BinaryStreamReader.EnumValue so when we read it from stream we know size of 8 or 16
Resolve a bare Enum through ClickHouseDataType, without a case-insens…