ClickHouse Java Ecosystem

The clickhouse-java repository provides two primary ways to interact with the ClickHouse Database via the HTTP Protocol:

1. Java Client: The core component providing a native API for ClickHouse interaction.
2. JDBC Driver: An implementation of the JDBC specification that uses the Java Client API internally.

There are two versions of these components available to allow for a smooth migration path:

• V2 (Recommended): The modern implementation (client-v2 and jdbc-v2).
• V1 (Legacy): The older version, which is scheduled for deprecation in 2025.

Key features supported by both versions include HTTP connection, LZ4 compression, HTTPS, mTLS, Named Parameters, and Session Roles. Note that V2 adds Java Object SerDe support, while V1 supports Failover, Load-balancing, and Server auto-discovery.

The client-v2 and jdbc-v2 artifacts support the JSONEachRow data format. This allows for parsing ClickHouse results where each row is a JSON object. The implementation provides specialized readers and a Service Provider Interface (SPI) for JSON parsing, supporting different underlying engines like Jackson or Gson.

Key components include:

• ClickHouseFormatReader (and its implementations: ClickHouseBinaryFormatReader, ClickHouseTextFormatReader)
• JSONEachRowFormatReader
• JsonParser SPI for custom parsing logic.

The jdbc-v2 driver allows you to consume FORMAT JSONEachRow responses using specific JSON parser factories. The driver selects a factory based on the jdbc_json_parser_factory driver property.

Selection Mechanism

• Method: The driver picks the factory by its fully-qualified class name (FQN).
• Instantiation: The driver loads the class reflectively and instantiates it via a public no-arg constructor.
• Scope: Selection is connection-level. The factory is instantiated once during connection creation and reused for all JSONEachRow responses on that connection.
• No Enums: There is no enum-style selector; you must provide the exact class name.

Supported Default Factories

• com.clickhouse.client.api.data_formats.JacksonJsonParserFactory
• com.clickhouse.client.api.data_formats.GsonJsonParserFactory

Before approving or proposing changes, identify the public API surface and check for alterations to existing user behavior. High-risk changes include modifications to:

• Public Surface: Classes, interfaces, enums, methods, constructors, and fields.
• Signatures: Argument types, return types, generics, nullability, and thrown exceptions.
• Configuration: Properties, headers, query parameters, connection settings, and defaults.
• Behavior: Retry logic, timeouts, parsing, serialization, and error handling.
• Drivers: JDBC and R2DBC semantics, compatibility, and type mappings.

The clickhouse-java repository provides two main versions of the native Java client:

1. Client V1: The legacy client. It includes features like failover, load-balancing, and server auto-discovery, which are not present in V2. However, it has a more complex API and is harder to maintain.
2. Client V2 (client-v2): The refactored, modern client. It features a cleaner API, better performance, and improved support for ClickHouse formats (specifically RowBinary and Native). It also introduces POJO SerDe support, which is not available in V1.

Key Differences:

• V2 Advantages: Lighter codebase, better performance, POJO SerDe, and support for newer types like Variant, Dynamic, and JSON.
• V1 Advantages: Supports Failover, Load-balancing, and Server auto-discovery.

Ensure changes do not alter externally visible input/output types or formatted output. Pay close attention to:

• Types: Overload resolution, return value types, wrapper types, collection element types, and ordering guarantees.
• Conversions: Numeric precision, null handling, timezone behavior, and string-to-type/type-to-string conversions.
• Formatting: toString() output, SQL rendering, escaping, whitespace, casing, and delimiters.
• Data/Protocols: Date/time, number, enum, and boolean string formatting; HTTP headers; URLs; and serialized payloads.
• Driver Metadata: JDBC metadata strings and textual protocol representations.

By default, String and FixedString columns are eagerly decoded into Java String objects. To access the raw bytes instead, enable binary_string_support via Client.Builder#binaryStringSupport(boolean) or the binary_string_support property.

When enabled, untyped reads (e.g., GenericRecord.getObject(...)) of top-level String or FixedString columns return a StringValue. This is a zero-copy holder that allows you to:

• Get raw bytes via toByteArray() or asByteBuffer().
• Lazily decode to a string via asString().

Note: This only affects top-level columns. Strings nested inside containers (like Array or Map) are still read as standard String objects. This setting can be overridden per-request using QuerySettings#setOption(ClientConfigProperties.BINARY_STRING_SUPPORT.getKey(), true).

The clickhouse-client is an abstract module and cannot be used in isolation. To interact with a ClickHouse server, you must use it in conjunction with a specific implementation module.

Available implementations include:

• clickhouse-http-client (HTTP-based)
• clickhouse-grpc-client (gRPC-based)
• clickhouse-cli-client (CLI-based)