ClickHouse/clickhouse-java v0.11.0-rc1 on GitHub

Release Migration Guide

Breaking changes

[client-v2, jdbc-v2] The socket buffer options socket_rcvbuf and
socket_sndbuf have no default value anymore. Now the options are applied only when the application sets them
(Client.Builder#setSocketRcvbuf,
Client.Builder#setSocketSndbuf, or the properties of the same name). This is done to let OS TCP Stack auto-tune
values. Do not set them until absolutely needed. (#3121)
[client-v2, jdbc-v2] Server error 159 (TIMEOUT_EXCEEDED) is not retried by default anymore. It has its own
retry cause, ClientFaultCause.ServerTimeoutExceeded, which ServerRetryable does not include and which is not in
the default client_retry_on_failures list. Add ServerTimeoutExceeded to the list to retry this error.
(#3072)
[r2dbc] Pre 1.0.0 artifact is not supported anymore because R2DBC API reached stable 1.0.0 version.
[jdbc-v2] DatabaseMetaData#getTables now returns null in REMARKS (table comment) and TYPE_SCHEM by
default, because metadata is read with SHOW statements (see the jdbc_metadata_use_show_statements entry in New
Features). Set jdbc_metadata_use_show_statements=false to get the table comments.
(#2907)
[client-v2,jdbc-v2] Added ZSTD compression support for Block compression stream and used by default not to
compress client requests. Previously only LZ4 was supported in this case. Note: Added ZSTD library and native
libraries to -all JDBC package because it is now required to work with server.
(#3105).

Important Changes

[client-v2] com.clickhouse.client.api.observability.SpanSupport now uses QUERY and INSERT operation
constants (QUERY <database> and INSERT <database>.<table> span names). db.operation.name attribute is set to
INSERT for insert operations and left unset for queries because SQL statements are not parsed on the client.
[client-v2] com.clickhouse.client.api.metrics.OperationMetrics now has a single constructor,
OperationMetrics(ClientStatisticsHolder, OperationType); the constructor without an operation type was removed.
Metrics are created by the client, which always knows the kind of the operation it runs, and the constructor takes
an internal type (com.clickhouse.client.api.internal.ClientStatisticsHolder), so application code is not expected
to call it. (#2974)

New Features

Data Types

[client-v2, jdbc-v2] Added support for the MultiPoint geo data type (ClickHouse 26.8+). Previously the type
was unknown to the client, so reading or writing a MultiPoint column failed with Unknown data type: MultiPoint,
and a MultiPoint value inside a Geometry column failed with an out-of-range variant discriminator. MultiPoint is
Array(Point) on the wire, exactly like Ring and LineString, so it is read and written as double[][] through
generic records, binary readers, POJO binding, and SQL parameter formatting, and is read from Dynamic columns. In
the JDBC driver (jdbc-v2) MultiPoint maps to java.sql.Types.ARRAY, is returned as double[][] from getObject
and as a java.sql.Array from getArray, and is reported by ResultSetMetaData and DatabaseMetaData. ClickHouse
26.8 also adds MultiPoint to the Geometry
variant; the server appends it after the existing six variants instead of ordering it by type name, so the client now
keeps that order and decodes a MultiPoint held in a Geometry column. Because MultiPoint shares its Java
representation (double[][]) with Ring and LineString, it is not selectable through the shape-based Geometry
write path — a 2D value keeps resolving to Ring as before, and writing MultiPoint requires a concrete MultiPoint
column. (#3048)
[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. 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, and reported as such by ResultSetMetaData and DatabaseMetaData.
Previously reading or writing a BFloat16 column failed with an
unsupported-data-type error. (#2279)
[client-v2, jdbc-v2] Added support for the experimental QBit(element_type, dimension[, stride]) vector data type
(ClickHouse 25.10+; the allow_experimental_qbit_type server setting is required to create a column). The type-name
parser accepts two or three parameters (the optional third is the stride) and recognizes the documented element types
Int8, BFloat16, Float32, and Float64; an element type outside that set is parsed with a warning rather than
rejected, so a newer server-side element type keeps parsing. A QBit value is transmitted over RowBinary exactly like
Array(element_type), so it is read and written as a Java array of the element type (float[] for
BFloat16/Float32, double[] for Float64) through generic records, binary readers, and POJO binding, via a
dedicated QBit read/serialize path. A QBit held inside a Dynamic/Variant/JSON column is also decoded (its
binary type encoding is read back to the concrete QBit(...) type). In the
JDBC driver (jdbc-v2) QBit maps to java.sql.Types.ARRAY and is returned as a java.sql.Array from
getObject/getArray. Previously QBit was an unimplemented type constant and reading or writing such a column
failed. A plain top-level QBit column with a Float32, Float64, or BFloat16 element type is also read through
the Native output format: there the server transmits it using its internal bit-plane-transposed
Tuple(FixedString(...)) layout, and the client reverses that transposition to reconstruct the same
float[]/double[] vector as RowBinary. A QBit that is strided (QBit(element_type, dimension, stride)),
wrapped in Nullable/LowCardinality, nested inside another type (e.g. Array/Tuple/Map(String, QBit(...))),
or carrying any other element type is not yet decoded over Native and fails fast with a clear error directing you
to a RowBinary format such as RowBinaryWithNamesAndTypes.
(#2610)

Observability

[client-v2, jdbc-v2] Added a Micrometer implementation of the metrics SPI.
Client.Builder.setMetricsRecorder(new MicrometerMetricsRecorder(meterRegistry)) reports the metrics of every client
operation to a Micrometer MeterRegistry: a timer db.client.operation.duration per completed operation, a timer
clickhouse.client.operation.serialization.duration when the client measured the serialization step, a counter
clickhouse.client.operation.count per completed operation, and a counter clickhouse.client.operation.retries per
retried attempt. Previously the client could bind only its connection-pool gauges to Micrometer, so exporting the
metrics of the operations themselves was left to the application. Meter names, units, descriptions and tag keys are
the standard ones of the SPI - the recorder derives them through MetricsSupport, so they are the names of
MetricName and the keys of MetricAttribute and mean the same as for every other recorder. A successful operation
carries no error.type tag and a failed one does, so the outcomes are separate time series of the same meter and a
failure the server reported also carries db.response.status_code; a duration the client did not measure is not
recorded, so no operation is reported with a made-up duration. The seconds of the SPI are handed to the registry as
nanoseconds, because a Micrometer timer keeps its own time unit, so a backend publishes the duration in the unit it
expects. The no-argument constructor reports to Metrics.globalRegistry, which is what the jdbc-v2
jdbc_metrics_recorder property needs, so a JDBC connection exports its metrics to Micrometer by naming the class -
jdbc_metrics_recorder=com.clickhouse.client.api.observability.micrometer.MicrometerMetricsRecorder - without
application code. micrometer-core stays an optional dependency of client-v2 and is not shaded into the all
artifacts, so a client that does not use this recorder needs no Micrometer on the classpath.
(#2975)
[client-v2, jdbc-v2] Added a metrics SPI that lets an application export the metrics of client operations to any
metrics backend. Client.Builder.setMetricsRecorder(MetricsRecorder) registers a backend-agnostic recorder from the
com.clickhouse.client.api.observability package, and the jdbc-v2 property jdbc_metrics_recorder names the recorder
class a connection registers with its own client. Previously the client collected operation metrics but only returned
them to the caller, so exporting them was left to the application. Each completed operation reports exactly one
success or one failure event, and each retried attempt reports a retry event, which gives the operation duration, the
serialization duration, the number of operations by outcome and the number of retries. The SPI follows the pattern of
the span SPI: an implementation extends the DefaultMetricsRecorder base class and overrides only what it cares
about, so it keeps working when the client starts reporting an event it does not know about, and the reusable
MetricsSupport class derives the standard values from the same structures, so its logic is opt-in and overridable.
Metric names, units and attribute keys follow the OpenTelemetry semantic conventions for database clients where a
convention exists and are placed under clickhouse. where it does not; they are defined by the MetricName and
MetricAttribute enums, durations are reported in seconds, and a duration the client did not measure is reported as
MetricsSupport.DURATION_UNKNOWN instead of a made-up value. The metric attributes are deliberately a smaller set
than the span attributes, because an attribute of a metric becomes a time series: the statement text, the query id and
the statement parameters stay on spans. Nothing is recorded and no metrics-related work is done when no recorder is
registered. (#2975)
[client-v2] Added an OpenTelemetry implementation of the observability SPI.
Client.Builder.setSpanRecorder(new OpenTelemetrySpanRecorder(openTelemetry))
reports every client operation and every transport request as an OpenTelemetry CLIENT span: an operation span is
started as a child of the current OpenTelemetry context, so it joins the application's own trace, and each request
span - including one per retry - is a child of its operation span. Span names and attribute keys are the standard ones
of the SPI (the recorder derives them through SpanSupport), every value is recorded with the OpenTelemetry attribute
type that matches it, and a failure sets the span status to ERROR and is recorded as an OpenTelemetry exception
event next to the error.type and db.response.status_code attributes. The recorder reports to a supplied
OpenTelemetry instance, to a Tracer given to new OpenTelemetrySpanRecorder(Tracer), or to
GlobalOpenTelemetry - read when a span is started - when constructed without arguments. Previously an application
that wanted OpenTelemetry spans had to write that mapping itself. The OpenTelemetry API is a compile-only dependency
of
client-v2: the recorder is used only by an application that already provides opentelemetry-api at runtime, so
nothing is added to the classpath of a client that does not use it.
(#2974)
[client-v2] Added an observability SPI that lets an application observe client operations as spans.
Client.Builder.setSpanRecorder(SpanRecorder) registers a backend-agnostic recorder from the new
com.clickhouse.client.api.observability package: each operation (a query, a command or an insert - including the
ping and getTableSchema calls, which run a query) starts one operation span, and every transport request made for
it - including each retry - starts a child request span. SpanRecorder and Span are plain interfaces; an
implementation extends the
DefaultSpanRecorder base class and overrides only what it cares about, so it keeps working when the client starts a
kind of span it does not know about. The registered recorder is called first and receives everything the client knows
about the operation (its QuerySettings/InsertSettings, the statement, the target table, the batch size, the
endpoint, the metrics of the completed operation and the failure), so it is free to record whatever it needs and in
whatever form; the reusable SpanSupport class derives the standard span names and attribute values from those same
structures and is called by a recorder implementation that wants them, so its logic is opt-in and overridable. Span
names and attribute keys follow the OpenTelemetry semantic conventions for database and HTTP client spans; the keys
are defined by the SpanAttribute enum and the values are derived by
SpanSupport, so all recorders that use it report the same information (statement text, target database and table,
query id, statement parameters, batch size, the first configured endpoint on the operation span and the per-attempt
server address and port on the request spans, HTTP status, returned rows, and the error type and ClickHouse error code
on failure). The outcome of a completed operation is reported per operation kind - recordQuerySuccess
for a read and recordInsertSuccess for an insert - because the metrics that describe a read are not the ones that
describe a write: a query reports db.response.returned_rows, clickhouse.response.read_rows and
clickhouse.response.read_bytes, an insert reports clickhouse.response.written_rows and
clickhouse.response.written_bytes. The same distinction is available on the metrics themselves through the new
OperationMetrics#getOperationType(), which returns the new com.clickhouse.client.api.metrics.OperationType - the
kind of the call the application made, so a command that writes is reported as a query. An operation span is started
on the calling thread, so it joins the caller's ambient trace even when the operation runs on the client's executor,
and it is ended exactly once for every operation that starts. Previously the client exposed no hook for tracing, so an
application could not attribute a query or a retried request to its own trace. When no recorder is registered nothing
is recorded and no span-related work is done, so the default path is unchanged. An OpenTelemetry implementation of the
SPI is available as OpenTelemetrySpanRecorder. (#2974)

Improvements

[migration-helpers] Added migration-helpers module containing ConfigurationMigrationHelper and
ConfigPropertyCache to convert configuration properties and connection URLs from v1 (0.7.1) format to v2 (0.9.8+)
format (automatically prefixing ClickHouse server settings with clickhouse_setting_, custom headers with
http_header_, and mapping renamed property keys).
[client-v2, jdbc-v2] Added TLS cipher suite selection. Client.Builder.setSSLCipherSuites(String...) (client-v2)
and the comma-separated ssl_cipher_suites connection property (client-v2 and jdbc-v2) restrict the cipher suites
enabled on secure connections; when unset, the transport defaults are used. Cipher-suite selection is independent of
the trust configuration and ssl_mode. (#2882)
[client-v2, jdbc-v2] Added support for un-flattened Nested(...) columns (tables created with
flatten_nested = 0). Previously the RowBinary writer threw UnsupportedOperationException: Unsupported data type: Nested when inserting such a column. client-v2 now serializes a Nested(f1 T1, ..., fN TN)
column the same way it is read — identically to Array(Tuple(T1, ..., TN)) (a var-uint row count followed by one
tuple per nested row) — so it can be written through the insert path / RowBinaryFormatWriter. In
jdbc-v2 an un-flattened Nested(...) column is exposed as a JDBC ARRAY whose element type is
Tuple(f1 T1, ..., fN TN): it can be inserted through Connection#createArrayOf/setArray or setObject
and read back through getArray/getObject, and java.sql.Array#getResultSet() iterates the nested rows as
(INDEX, VALUE) pairs where each VALUE is the tuple. (#2477)
[client-v2, jdbc-v2] Added logging on previously-silent error and diagnostic paths (no functional or public-API
change). (#2969)
[jdbc-v2] DatabaseMetaData#getSchemas, #getTables and #getColumns now read metadata with SHOW DATABASES,
SHOW TABLES and DESCRIBE TABLE instead of the system.databases, system.tables and system.columns tables. The
server does not show some tables in the system tables by default (for example, tables of DataLakeCatalog
databases), so tools that use DatabaseMetaData did not find them. The new driver property
jdbc_metadata_use_show_statements (default true) selects the implementation; set it to false to use the system
tables. With the SHOW statements, getTables() returns null in REMARKS (table comment) and TYPE_SCHEM;
getColumns() sends one DESCRIBE TABLE query for each table that matches and skips a table that was dropped
meanwhile, that the user cannot describe, or whose data lake metadata cannot be read. All other columns and values are
the same. (#2907)

Bug Fixes

[jdbc-v2] Fixed an INSERT ... VALUES statement whose values list holds a literal, an expression (e.g. ? + 1)
or, with the JAVACC parser, a JDBC escape sequence or a query parameter, being written with the RowBinary writer
when beta.row_binary_for_simple_insert is enabled. The writer takes one bound value per column, so the bound values
were shifted to other columns: the statement failed with a misleading error, or stored wrong data with no error. The
parsers did not report such values: the JAVACC parser discarded the result of its values-list check, and the
ANTLR4 parsers reported only function calls. Now the writer is used only for a values list of ? placeholders, and
other statements use the standard PreparedStatement path.
(#3083)
[client-v2,jdbc-v2] - Replaced slow HTTP LZ4 compression with compressing stream from
lz4-java library. Client uses Apache Compress to handle HTTP compression (because it has convenient factory for many
compressions methods. However, Apache Compress uses slow LZ4 implementation what causes very slow inserts. Now
lz4-java used for insert. Query still slow but will be fix in future releases (need refactoring and custom
implementation to solve it). Using ZSTD for queries should solve the issue.
(#2273).
[client-v2] Fixed writing a String value into a UUID column (also as an Array/Tuple element or a Map
key) failing with ClassCastException. The string is now parsed with UUID.fromString; a string it cannot parse is
rejected on the client with an IllegalArgumentException. (#3132)
[client-v2] Fixed reading a Nullable column in the Native format failing with Failed to read block ... End of stream reached before reading all data, or returning values of the wrong rows. The reader consumed a null
marker before every value, which is the RowBinary layout. Native is columnar: it stores a null map of one byte per
row before the values of the whole column, and a null row still has a placeholder value. The markers were therefore
taken from the value bytes and the column was read out of alignment. The null map is now read as a block.
(#3137)
[client-v2] Fixed geo columns (Point, Ring, LineString, MultiPoint, Polygon, MultiLineString,
MultiPolygon) being misread from the Native format. The reader decoded a geo column row by row with the RowBinary
decoders, while Native writes it column-major: a Point block came back with its coordinates scrambled across rows
and no error, and every other geo type desynchronized the block and failed with
Non-empty typeName is required. A geo column is now decoded from the Native layout - the two Float64
sub-columns of a point, and cumulative offsets plus the flattened elements for the array levels - and returns the same
values as RowBinaryWithNamesAndTypes, which is unchanged.
(#3088)
[client-v2, jdbc-v2] Fixed a column type with a JSON element that is followed by a parameterized type, for
example Tuple(JSON, FixedString(3)), being parsed wrongly. JSON is valid with and without a parameter list, and
the parser looked for the opening bracket of that list anywhere after the keyword, so it took the brackets of the next
element for the parameters of the JSON element. Everything up to those brackets was consumed, which dropped the
elements between them, or failed with Unknown data type: <parameter> when the following type had more than one
parameter, for example Tuple(JSON, Decimal(10, 2)). Reading such a column, and Client#getTableSchema of a table
that has one, failed or returned an incomplete type. A parameter list is now recognized only when it immediately
follows the JSON keyword. (#3098)
[jdbc-v1] Fixed WITH RECURSIVE <name> AS (...) failing to parse. The JavaCC grammar did not know the
RECURSIVE keyword, so it was taken for the name of the first common table expression and the statement was rejected.
The query itself still ran, because the driver falls back to sending the original SQL, but every
createStatement / prepareStatement call logged a WARN parse failure and the statement was classified as unknown.
RECURSIVE is now accepted after WITH and stays usable as an ordinary identifier (column, alias, table or CTE
name). (#3122)
[jdbc-v2] Fixed WITH RECURSIVE <name> AS (...) failing to parse. Neither SQL grammar knew the RECURSIVE
keyword, so it was taken for the name of the first common table expression and the statement was rejected. The query
itself still ran, because the driver falls back to sending the original SQL, but every createStatement /
prepareStatement call logged a parse failure (WARN with the JavaCC backend) and the statement was classified as
unknown. RECURSIVE is now accepted after WITH by both the JavaCC and the ANTLR4 grammars, and stays usable as an
ordinary identifier (column, alias, table or CTE name). (#3122)
[jdbc-v2] Fixed ArrayResultSet#next() leaving the cursor before-first for empty arrays or on the last row for
non-empty arrays after exhaustion. The cursor now moves to the after-last state when next() returns false.
[jdbc-v2] Added the non-reserved keywords AGGREGATE, BOUNDED, EXTEND, HANDLER, IDLE, PROTOCOL,
RECENT, TIMEOUT and UNORDERED (ClickHouse 26.8+; IDLE, TIMEOUT and RECENT come from the multi-word
keywords IDLE TIMEOUT and RECENT SAMPLES) to the list of keywords allowed in identifier positions. The server
accepts all of them as a column or table alias, so a query using one of them as an identifier must parse.
(#3113)
[client-v2] Fixed a query with statement parameters sent in the request body
(client.http.use_form_request_for_query=true) failing with LZ4 decompression failed ... (LZ4_DECODER_FAILED)
when client request compression and HTTP compression were both enabled. The multipart body is always sent
uncompressed, but the request still declared Content-Encoding: lz4; ClickHouse 26.8+ honours that header for
multipart requests and tried to decompress a plain body. The header is now omitted for multipart requests, like the
decompress query parameter already was. Response compression (Accept-Encoding,
enable_http_compression) is unchanged. (#3075)
[client-v1] Fixed the DateTime64 case of testReadWriteSimpleTypes failing against ClickHouse 26.8. From 26.8
an unquoted number written to a DateTime64 column in the Values/Quoted and JSON paths is a Unix timestamp in
seconds instead of the raw scaled value - the server setting input_format_read_datetime_number_as_raw_value
changed its default from 1 to 0 - so the insert into ... values(1) of the test stored 1970-01-01 00:00:01
instead of the expected 1970-01-01 00:00:00.001. The test now writes a quoted date-time literal for DateTime64, as
it already does for FixedString and UUID, so the written value means the same on every server version and the
sub-second round-trip stays covered. No client code is affected: both clients quote a date-time value in a text
statement or send it in RowBinary. (#3114)
[jdbc-v2, client-v2] Fixes issue with FORMAT in query unable to override format set by client when used with
ClickHouse 26.8+. Default format is RowBinaryWithNamesAndTypes set at client level. For JDBC, recommend using
format=JSONEachRow to query JSON. Setting format= (empty or null) omits the format request header so explicit
query FORMAT clauses take effect; note that on JDBC any statement without a FORMAT clause will fail because the
server falls back to default_format (TabSeparated). DatabaseMetaData is unaffected: every statement it runs
internally pins RowBinaryWithNamesAndTypes in its own settings, so metadata keeps working regardless of the
connection's format property. (#3086)
[jdbc-v2] Fixed Connection#prepareStatement and PreparedStatement#addBatch throwing
StringIndexOutOfBoundsException for an INSERT ... VALUES (...) statement containing a JDBC escape sequence
({d '...'}, {ts '...'}, ...) or a ClickHouse query parameter whose name starts with d/t (e.g. {d:Int32}).
The default JAVACC parser records the values list positions as offsets into the SQL it rebuilds from the token
stream, where such sequences are rewritten or dropped, while the driver slices the original SQL with them — so the
slice was taken at the wrong offsets or past the end of the statement. The positions are now checked against the
original SQL and discarded when they do not address its values list, in which case the driver falls back to its
generic parameter substitution path. Such a statement is now prepared without error; the escape sequence itself is
still sent to the server unchanged. The ANTLR4 parser backends were not affected.
(#3017)
[jdbc-v2] Fixed a ? inside a // line comment or inside a heredoc (dollar quoted string, e.g. $$...$$ or
$tag$...$tag$) being counted as a PreparedStatement parameter. Such a statement expected a value the application
could not supply, so executeQuery() failed with Parameter at position 'N' is not set for a query the server
executes fine. The placeholder scan now skips both token kinds, like the server lexer does; a $ that does not open a
heredoc is still treated as an ordinary character (it is a valid identifier character).
(#3009)
[jdbc-v2] Fixed INSERT INTO [TABLE] FUNCTION f(...) VALUES (?) failing with
Code: 60 ... does not exist. (UNKNOWN_TABLE) when the beta.row_binary_for_simple_insert feature was enabled.
Neither SQL parser reported a table-function insert target as a function, so the statement was routed to the
RowBinary writer, which looked the function name (or a placeholder such as unknown) up as a table. Both parsers
now report such a statement as using a function, so it stays on the regular SQL path; additionally the JavaCC grammar
no longer mis-parses INSERT INTO TABLE FUNCTION f(...) by consuming
FUNCTION as the table name. Inserts into a plain table are unaffected and still use the RowBinary
writer. (#3015)
[jdbc-v2] Fixed Connection#prepareStatement throwing a NullPointerException for an
INSERT ... VALUES (...) statement whose values list the default JavaCC parser cannot parse — most commonly one
containing a heredoc string ($$...$$), which the grammar has no token for, but also any other unparsable token
inside the list. The parser's error recovery left the values list's start position recorded without its matching end
position, which was then unboxed unguarded. Both positions are now dropped together, so the driver falls back to its
generic parameter-substitution path and such statements are prepared and executed successfully. The ANTLR4
parser backends were not affected. (#3013)
[client-v2] Fixed reading a JSON or named Tuple value nested in a Dynamic column when a typed path or
element name requires quoting (it contains a space, a comma or a bracket). Names read from the binary type encoding
were appended to the reconstructed type name unquoted, so e.g. JSON(`a b` Int64) inside a Dynamic column
produced a malformed type name and the whole query failed with IllegalArgumentException: Unknown data type: b Int64.
Such names are now back-quoted (with inner back-quotes escaped) exactly as the server renders them, and JSON skip
paths and path regexps are emitted with their SKIP / SKIP REGEXP markers. Names that need no quoting are rendered
as before. Top-level JSON columns and JSON nested in Map/Tuple/Array were not affected — their type comes
from the RowBinaryWithNamesAndTypes header, which the server already quotes.
(#3001)
[client-v2] Fixed reading a Variant, Nested, Decimal or Enum value held in a Dynamic column. The
concrete type rebuilt from the binary type encoding did not match what the server encoded: Variant was wrapped twice
(so the discriminator selected the wrong element), Nested read only the element names and left the element type
encodings in the stream, and Decimal/Enum lost their precision and scale / their constants whenever the value sat
inside another type, so a decimal read back unscaled (1.2500 as 12500) and every enum value read back as
<unknown>. The constant width of an enum is now taken from the type tag rather than from the number of constants,
which also fixes reading an Enum16 with fewer than 128 constants and negative Enum8 constants.
(#3003)
[client-v2] Fixed a Nullable(T) column bound to a primitive POJO field silently corrupting a row on the POJO
read path. The compiled setter went straight to a primitive read method without consuming the Nullable
null-marker byte, which is on the wire for every value of a nullable column regardless of the value, so the stream
stayed shifted by one byte per row and the nullable column and every column after it decoded from the wrong offset
without any error being raised. The generated setter now consumes the marker; a value that is actually NULL cannot
be held by a primitive field and is reported with a NullValueException. Boxed POJO fields are unaffected.
(#2993)
[client-v2] Fixed the Native format reader (NativeFormatReader) misreading Array columns in multi-row
results whose rows have different lengths. Native encodes an array column as cumulative row offsets followed by the
flattened elements, but the reader used the first row's offset as the element count for every row — truncating later
rows and desyncing the columns that follow the array in the same block. Each row's length is now derived from the
difference between consecutive offsets, and empty array rows (len == 0) no longer read a phantom element. Results
with uniform array lengths were unaffected. (#2955)
[jdbc-v2] Fixed SQLException#getSQLState() returning the generic data-exception state 22000
when ClickHouse reports an unknown table. The driver now returns 42S02 (base table or view not found) while
preserving the ClickHouse error code and original exception.
(#3104)
[client-v2] Fixed truncated LZ4 stream errors reporting literal {0} and {1} placeholders instead of the number
of bytes read and expected. (#3108)
[jdbc-v2] Fixed DatabaseMetaData#getTables reporting TABLE_TYPE = TABLE for a table with the BigQuery
engine (present in system.table_engines since ClickHouse 26.8). The engine was missing from the
engine-to-table-type mapping, so it fell back to the default TABLE, and getTables(..., types = {"REMOTE TABLE"})
returned no row for such a table. BigQuery is now mapped to REMOTE TABLE, like the other external-storage engines.
(#3049)
[jdbc-v2] Fixed PreparedStatement.getMetaData() losing the result-set schema for a statement whose SQL contains
a comment. The DESCRIBE query used to resolve the metadata was built by re-scanning the SQL with a regex that knew
only quoted tokens, so a ? inside a -- / # / /* */ comment was rewritten to NULL and an odd ' inside a
comment mis-paired the quote alternative, leaving a real placeholder unreplaced — the
DESCRIBE then failed and the driver silently returned untyped metadata. The metadata query is now built from the
placeholder positions the statement parser already computed, so it always matches the SQL that a parameterized
execution produces. (#3011)
[client-v2] Fixed reading a UInt64 column into a primitive POJO field (e.g. long) always failing with
ClassCastException: BinaryStreamReader cannot be cast to java.math.BigInteger. The compiled setter for that
combination never emitted a read call, so it cast the reader itself instead of a value and consumed nothing from the
stream, which made every primitive field bound to a UInt64 column unusable. The value is now read and converted to
the target primitive with the matching Number accessor, which narrows a value that does not fit the same way a Java
narrowing conversion does (a long holds every UInt64 value bit-for-bit and can be read back with
Long.toUnsignedString(long); a boolean is true for any non-zero value). Boxed fields (BigInteger, Long) are
unaffected. (#2996)
[jdbc-v2] Fixed ResultSetMetaData.getPrecision() and getScale() returning 0 for columns wrapped in
SimpleAggregateFunction(func, T). The wrapper is transparent on the read path (values are read as plain T), but
both accessors described the wrapper itself, which carries no precision or scale — so a
SimpleAggregateFunction(sum, Decimal(18, 4)) column looked like a scale-0 value and
SimpleAggregateFunction(any, DateTime64(3, tz)) looked like second precision. They now describe the nested type.
AggregateFunction columns are unchanged, since their values are aggregation states rather than values of the nested
type. (#3042)
[clickhouse-jdbc] Fixed Connection#prepareStatement throwing a NullPointerException for an
INSERT ... VALUES (...) statement whose values list the JavaCC parser cannot parse — most commonly one containing a
heredoc string ($$...$$), which the grammar has no token for, but also any other unparsable token inside the list.
The parser's error recovery left the values list's start position recorded without its matching end position, which
was then unboxed unguarded. Both positions are now dropped together, so the driver falls back to its generic
parameter-substitution path instead of failing, and a statement such as
insert into t values ($$a@b$$, ?) is prepared and executed successfully.
(#3033)
[jdbc-v2] Fixed the ANTLR4 lexer not nesting /* */ block comments. ClickHouse (and the JavaCC parser backend)
raise the nesting level on an inner /* and close the comment only at the matching */, while the ANTLR4 lexer ended
the comment at the first */ and lexed the rest of it as SQL. With the ANTLR4 / ANTLR4_PARAMS_PARSER backends
this made statements the server accepts (e.g. SELECT 1 /* ) /* ) */ ) */, 2) report syntax errors, and made
ANTLR4_PARAMS_PARSER count a ? inside the nested part of a comment as a bind parameter. Comments that do not nest
are unaffected; an unterminated block comment is now skipped to the end of the statement instead of being lexed as
stray tokens. (#3021)
[client-v2] Fixed reading a SimpleAggregateFunction(func, T) value held in a Dynamic column. The binary type
encoding of such a value (0x2E <function_name> <parameters> <arguments> <argument_type_encodings>) was not consumed
at all, so the read failed with IndexOutOfBoundsException, and the unconsumed encoding bytes would otherwise have
been interpreted as row data and desynchronized the rest of the RowBinary stream. The concrete type is now
reconstructed from the encoding and the value is read as its argument type T, so it reads exactly like the same
value in a plain SimpleAggregateFunction column. (#3005)
[jdbc-v2] Fixed PreparedStatement#executeBatch sending a syntactically broken INSERT when an ANTLR4 parser
backend is selected (jdbc_sql_parser=ANTLR4 / ANTLR4_PARAMS_PARSER) and the values list contains a value
expression the bundled grammar cannot parse - a JDBC escape sequence ({d '...'}), or valid ClickHouse syntax the
grammar does not cover such as a hex string literal (hex(x'AB')). Such a statement is still given a parse tree,
completed by error recovery, and the values list positions and the value group count were read from it: the values
list was reported to stop at the closing parenthesis of a nested function call, so the batch template lost its own
closing parenthesis, and a two-group values list could be reported as a single group. Both are now discarded when the
statement could not be parsed without errors, so the driver uses its generic parameter substitution path instead -
and, with the beta RowBinary writer enabled, such a statement is no longer routed to it. The default JAVACC
backend is not affected by this. (#3019)
[jdbc-v2] Fixed the ANTLR4 lexer rejecting // line comments, which the ClickHouse server and the driver's JavaCC
grammar both accept. Because / is also the division operator, // comment was lexed as two operator tokens, so a
statement containing a // comment was reported as a syntax error by the ANTLR4-based parser backends (ANTLR4,
ANTLR4_PARAMS_PARSER), and an INSERT preceded by such a comment was misclassified as a statement with a result
set. // is now skipped like --, # and #!; a single / and // inside a string literal or a quoted identifier
are unaffected. Placeholder counting inside // comments for the backends that scan the raw SQL separately (JAVACC,
ANTLR4) is fixed by
#3009. (#3023)
[jdbc-v2] Fixed ? parameter placeholders being lost when jdbc_sql_parser=ANTLR4_PARAMS_PARSER is selected and
the bundled grammar cannot match part of the statement - a JDBC escape sequence ({d '...'}), or valid ClickHouse
syntax the grammar does not cover such as a hex string literal (hex(x'AB')). That backend read the placeholders only
from the parse tree, and the tokens error recovery skips are not part of it, so a placeholder inside such an
expression was dropped: getParameterMetaData().getParameterCount() was too low, setXxx for a dropped placeholder
failed, and the remaining values were substituted at the wrong offsets. The placeholders are now re-derived from the
original SQL when the statement could not be parsed without errors, as the other two backends always do.
(#3025)
[client-v2, jdbc-v2] Fixed Client.getTableSchema(...), Client.getTableSchemaFromQuery(...) and ping()
failing against ClickHouse 26.8+, where the X-ClickHouse-Format header the client sends wins over a FORMAT
clause in the query. These internal queries now set their format in the settings instead of a FORMAT clause.
(#3068)
[jdbc-v2] Fixed an INSERT whose values list holds a function call the bundled ANTLR4 grammar cannot match -
such as hex(x'AB'), valid ClickHouse the grammar has no hex string literal for - being reported to hold no function
call when an ANTLR4 parser backend is selected (jdbc_sql_parser=ANTLR4 / ANTLR4_PARAMS_PARSER). Function calls
in a values list are reported by a callback on the parse tree, and such a statement is still given a parse tree,
completed by error recovery, which skips the tokens the parser recovered on - the function call among them. With the
beta
RowBinary writer enabled (beta.row_binary_for_simple_insert=true) the statement was then routed to it, where a
literal function-call column cannot be written; it now takes the generic parameter substitution path, as it already
did for a function call the grammar matches. Since such a parse tree cannot tell, any insert that could not be parsed
without errors is now assumed to hold a function call in its values list, so none of them is written with the
RowBinary writer. The default JAVACC backend is not affected by this.
(#3027)
[clickhouse-client] Fixed JPMS/module-path service loading for ClickHouseRequestManager by loading client
services from the com.clickhouse.client module, which declares the required uses directives. This avoids
ServiceConfigurationError failures from com.clickhouse.data when applications run on the module path.
(#2669)
[client-v2] Fixed Client.cancelTransportRequest(queryId) being silently dropped when it landed between two
attempts of a retried operation (query, POJO insert and stream insert): the operation issued the next attempt anyway
and could complete successfully. The request of an attempt now stays registered until the whole operation is over, and
the cancellation is checked before every attempt, so a cancelled operation stops instead of sending another request.
(#2989)
[client-v1] Fixed BlockingPipedOutputStream.close() not being idempotent under concurrency: the check of the
closed flag and the closing handshake were not atomic, so two threads closing the same stream (e.g. a writer thread
and a try-with-resources block) could both put the end-of-stream marker into the queue, and the second one failed with
Close stream timed out after <n> ms once the reader had stopped consuming. Exactly one caller now performs the
handshake and runs the post-close action; a concurrent or repeated close() returns immediately. A
close() which fails while flushing the remaining data also marks the stream closed and runs the post-close action,
so the stream cannot stay half-closed. (#3055)
[client-v1] Fixed NonBlockingPipedOutputStream.close() not being idempotent under concurrency. Two threads could both
flush and mutate the same pending buffer before the reader consumed it, silently replacing the payload with an empty
buffer and running the post-close action twice. Exactly one caller now flushes the pending data, enqueues the
end-of-stream marker, and runs the post-close action; concurrent or repeated close() calls return immediately.
(#3057)
[jdbc-v2] Fixed JDBC escape processing rewriting text inside string literals and quoted identifiers. Because
PreparedStatement inlines bound parameters into the statement text, a bound value containing {fn (or {d '...'}
/ {ts '...'}) was re-read as SQL syntax: the {fn was removed together with the next } found anywhere in the
statement — usually the closing brace of an unrelated Map/Tuple literal in another value or row — corrupting the
inserted data or failing with a server-side SYNTAX_ERROR. Escape sequences are now recognized only outside of quoted
text, and a {fn ...} escape is unwrapped at its matching closing brace, so nested braces (e.g. a {name:Type} query
parameter or a nested escape) stay balanced. (#2995)
[jdbc-v2] Fixed prepared statements losing parameter markers after an empty -- comment line or after
SELECT * EXCEPT (...), which caused parameter binding to fail with ArrayIndexOutOfBoundsException for the affected
SQL parser backends. (#3052)
[client-v2] Fixed LZ4 input streams not closing their underlying HTTP response stream. Closing an LZ4 stream
returned by QueryResponse.getInputStream() now releases the wrapped transport stream, including after a partial
read. (#2985)
[jdbc-v2] Fixed the default JavaCC SQL parser aborting on a heredoc string ($$body$$, $tag$body$tag$)
whose body contains a character that is not a valid SQL token on its own, such as !, &, | or ~. The lexer had
no heredoc token, so such a body raised a lexer error that left the statement classified as
UNKNOWN — an INSERT was reported as a result-set-bearing statement with no table name and no values-list positions,
which disables the batch values template and the table-name based paths. A heredoc is now lexed as a single string
literal. (#3029)
[client-v2, jdbc-v2] Reduced noisy and potentially sensitive logging; SQL that fails to parse is no longer logged
at WARN (it could contain credentials/PII). (#2970)
[client-v2] Fixed BigDecimal values written into a Dynamic column being silently truncated when the value's
scale exceeded the inferred width's maximum scale, and throwing an overflow error when the value carried an integer
part (e.g. 19.99). The Dynamic type inference now sizes the Decimal width to hold both the integer digits and
the value's scale, keeps the scale as wide as the width allows without stealing room from the integer part, and writes
the actual column scale into the Dynamic type tag. Values that already round-tripped losslessly are unchanged.
(#2966)
[client-v2] Fixed the RowBinary writer throwing
UnsupportedOperationException: Unsupported data type: SimpleAggregateFunction when inserting into a
SimpleAggregateFunction(func, T) column (the reader already supported these columns). The value is now serialized
identically to its underlying type T, writing the Nullable null-marker byte when the underlying type is nullable
(e.g. SimpleAggregateFunction(anyLast, Nullable(String))), mirroring the read path.
(#2477)
[client-v2] Fixed the Dynamic type tag for a SimpleAggregateFunction type being written as a bare
0x2E byte. The binary type encoding also carries the function name, its parameters and its argument types, so the
server read the function name out of the value bytes that followed and failed with
ATTEMPT_TO_READ_AFTER_EOF. Since the client never infers a SimpleAggregateFunction from a Java value and the
reader cannot read one back out of a Dynamic column, this now fails fast with a clear
ClientException instead of producing a corrupt RowBinary stream (the same treatment QBit already gets).
(#3007)
[client-v2, jdbc-v2] Fixed several logging-layer defects. In client-v2, HttpAPIClientHelper.shouldRetry
threw a ClassCastException when a retryable ServerException was wrapped as the cause of another exception (the
branch matched on the cause but the cast used the outer exception); the retry decision is now taken from whichever
exception is the ServerException. Also in client-v2, a failure to build the HTTP client version string is now
logged at WARN with the throwable attached instead of a bare INFO message that discarded the cause. In jdbc-v2,
a failure to close the response after a query error now logs the close failure itself instead of the
already-propagated outer exception. (#2968)
[client-v2] Fixed scalar String query parameters containing a tab (0x09), newline (0x0a) or backslash being
mishandled through the server's param_<name> interface. A {name:String}
parameter value is parsed by the server with deserializeTextEscaped, which treated a raw tab or newline as a field
delimiter (failing the query with BAD_QUERY_PARAMETER: ... isn't parsed completely)
and a raw backslash as the start of an escape sequence (silently corrupting the value, e.g. C:\temp
became C:<tab>emp). Client.query(sql, params, ...) now escapes the backslash, tab and newline in a scalar String
parameter so any value round-trips; every other character the server reads verbatim — including the single quote and
carriage return — is left unchanged, so Identifier values and pre-formatted Array/Map literals passed as a
String still round-trip. The JDBC driver (jdbc-v2), which inlines parameters as SQL literals and already escaped
the backslash and single quote, is unchanged and covered by a new regression test.
(#2781)
[client-v2] Fixed a null query-parameter value being sent as the literal string "null", so
Client.query(sql, params, ...) binding a Java null to a scalar placeholder such as
{x:Nullable(Decimal128(8))} was rejected by the server with BAD_QUERY_PARAMETER
(Value null cannot be parsed as Nullable(...)). A top-level scalar null is now sent as the ClickHouse
\N NULL sentinel so it binds SQL NULL; a null nested inside an Array/Map parameter value continues to render
as the SQL NULL keyword. (#2977)
[client-v2] Fixed binary array decoding for nullable element types so Array(Nullable(Float64)) and similar
columns now return boxed arrays such as Double[] instead of Object[]. This keeps null-supporting arrays aligned
with their element type while preserving the existing Object[] fallback for Variant/Dynamic/Geometry arrays.
(#2846)
[client-v2] Fixed Float32/Float64 columns throwing ClassCastException when a value of a non-matching boxed
numeric type was supplied through the Object-typed insert surface — for example a
Double (the natural type of Java literal like 1.5) for a Float32 column, or a Float for a
Float64 column. The RowBinary serializer now narrows any Number (and, like the Int* columns, a String/
Boolean) through Number#floatValue()/Number#doubleValue(), so the float columns accept the same value types the
integer columns already did. (#2930)
[client-v2] Fixed a NullPointerException when serializing a null value into a non-nullable
Enum8/Enum16 column. SerializerUtils.serializeEnumData had no null guard, so a null in a non-nullable enum
column reached value.getClass() and failed the RowBinary insert path with a confusing NPE instead of a clear error.
It now throws IllegalArgumentException naming the column, consistent with the existing IllegalArgumentException
for other unsupported enum values. Nullable enum columns are unaffected.
(#2931)
[client-v2] Fixed silent data corruption when serializing a Java null into a non-nullable
Array(...) column via RowBinaryFormatWriter. RowBinaryFormatSerializer.writeValuePreamble
special-cased Array, emitting a stray marker byte on top of the array length; the server read the extra byte as a
phantom extra row (single-column inserts) or as a column shift that failed the insert with CANNOT_READ_ALL_DATA
(multi-column inserts). A non-nullable Array cannot represent a null, so it now throws IllegalArgumentException
naming the column — consistent with every other non-nullable type — in both the RowBinary and
RowBinaryWithDefaults paths. Empty arrays ([]) still serialize correctly, and Dynamic columns, which can hold a
null as the implicit Nothing type, are unaffected. (#2938)
[client-v2] Fixed POJO insert error classification so transport write failures such as java.net.SocketException:
Broken pipe (Write failed) are now surfaced as transfer/network errors instead of being wrapped as
DataSerializationException. This only changes the exception type reported for request-body transport failures during
Client.insert (...); actual POJO reflection/serialization failures are still reported as DataSerializationException.
(#2729)
[client-v2] Fixed binary varint decoding for length and count fields so overflowing or overlong values fail with
an IOException instead of being decoded into corrupted or negative int values.
(#2902)
[client-v2] Fixed container query parameters being sent unquoted, so Client.query(sql, params, settings) binding
a List<LocalDate> (or an array/Map) to a placeholder like {ids:Array(Date)} was rejected by the server with
CANNOT_PARSE_INPUT_ASSERTION_FAILED. Parameter values are now formatted by
DataTypeConverter#convertParameterToString(Object) before being sent: pass the raw Java value and the client renders
it into the text the server's param_<name> interface expects — a Collection, array (object or primitive), or Map
becomes ClickHouse Array (['2026-05-13']) / Map ({'k':'v'}) text with String/temporal leaves single-quoted
and numeric/boolean leaves left unquoted, while a scalar is passed through unquoted as before. No manual
pre-formatting of container parameters is needed. (#2897)
[client-v2] Fixed DateTime/DateTime64 columns declared with a synthetic fixed-offset timezone name
(Fixed/UTC±HH:MM:SS, e.g. Fixed/UTC+05:30:00) being silently read in UTC instead of the declared offset. The
RowBinary reader now recovers the offset from the column's declared type.
(#2876)
[jdbc-v2] Fixed the ANTLR4 SQL parser backends (jdbc_sql_parser=ANTLR4 and ANTLR4_PARAMS_PARSER) lexing the
body of a heredoc string ($$body$$, $tag$body$tag$) as ordinary SQL. The lexer had no heredoc token, so every $
was dropped as an unrecognized character and the body was parsed as identifiers, operators and statement separators: a
body that still looked like valid SQL was silently mis-parsed (wrong table name and VALUES-list positions), and a body
containing ; — as well as the empty heredoc $$$$ — was reported as a parse error, which classifies an INSERT as a
result-set-bearing statement with no values-list positions. A heredoc is now lexed as a single string literal and
accepted as a literal value (INSERT ... VALUES lists, column expressions, settings), and a $ inside an identifier
(a$b, or an unterminated tag such as
$foo$bar) is part of the identifier, as the server reads it.
(#3031)
[jdbc-v2] Fixed the beta RowBinary writer (DriverProperties.BETA_ROW_BINARY_WRITER) throwing
NoSuchColumnException for INSERT statements whose column names are backtick-quoted, in particular the canonical
Nested sub-column wire form `directory`.`id`. The SQL parser now unescapes each backtick-quoted INSERT
column-name component before the by-name server-schema lookup, matching how the table and database identifiers are
already handled. (#2896)

Documentation

[examples] - New demo-spring-service added to demonstrate usage of observability SPI.

Dependencies

[client-v1,client-v2] Upgraded org.apache.httpcomponents.client5:httpclient5 from 5.4.4 to 5.6.4 in client-v2 and
clickhouse-http-client to pick up the fixes of the newer 5.x releases, including known vulnerabilities.
(#3078)
[client-v2] Upgraded org.bouncycastle:bcprov-jdk18on from 1.84 to 1.85 in client-v2 (#3141).

ClickHouse/clickhouse-java v0.11.0-rc1 Release v0.11.0-rc1 (2026-10-02) on GitHub

Breaking changes

Important Changes

New Features

Data Types

Observability

Improvements

Bug Fixes

Documentation

Dependencies

ClickHouse/clickhouse-java v0.11.0-rc1
Release v0.11.0-rc1 (2026-10-02)

on GitHub