Обзор Java-клиентов

• Клиент 0.8+
• JDBC 0.8+
• Драйвер R2DBC

ClickHouse client

Java client — это библиотека, реализующая собственный API, который абстрагирует детали сетевого взаимодействия с сервером ClickHouse. В настоящее время поддерживается только HTTP‑интерфейс. Библиотека предоставляет утилиты для работы с различными форматами ClickHouse и другими связанными функциями.

Java Client был разработан ещё в 2015 году. Его кодовая база со временем стала очень сложной для сопровождения, API — запутанным, а дальнейшая оптимизация — затруднительной. Поэтому в 2024 году мы переработали его в новый компонент client-v2. У него понятный API, более лёгкая кодовая база, дополнительные улучшения производительности и лучшая поддержка форматов ClickHouse (в основном RowBinary и Native). В ближайшем будущем JDBC будет использовать этот клиент.

Поддерживаемые типы данных

Тип данных	Поддержка в Client V2	Поддержка в Client V1
Int8	✔	✔
Int16	✔	✔
Int32	✔	✔
Int64	✔	✔
Int128	✔	✔
Int256	✔	✔
UInt8	✔	✔
UInt16	✔	✔
UInt32	✔	✔
UInt64	✔	✔
UInt128	✔	✔
UInt256	✔	✔
Float32	✔	✔
Float64	✔	✔
Decimal	✔	✔
Decimal32	✔	✔
Decimal64	✔	✔
Decimal128	✔	✔
Decimal256	✔	✔
Bool	✔	✔
String	✔	✔
FixedString	✔	✔
Nullable	✔	✔
Date	✔	✔
Date32	✔	✔
DateTime	✔	✔
DateTime32	✔	✔
DateTime64	✔	✔
Interval	✗	✗
Enum	✔	✔
Enum8	✔	✔
Enum16	✔	✔
Array	✔	✔
Map	✔	✔
Nested	✔	✔
Tuple	✔	✔
UUID	✔	✔
IPv4	✔	✔
IPv6	✔	✔
Object	✗	✔
Point	✔	✔
Nothing	✔	✔
MultiPolygon	✔	✔
Ring	✔	✔
Polygon	✔	✔
SimpleAggregateFunction	✔	✔
AggregateFunction	✗	✔
Variant	✔	✗
Dynamic	✔	✗
JSON	✔	✗

Типы данных ClickHouse

Примечание

• AggregatedFunction — ⚠️ не поддерживает SELECT * FROM table ...
• Decimal — используйте SET output_format_decimal_trailing_zeros=1 в версии 21.9+ для единообразия вывода
• Enum — может трактоваться и как строка, и как целое число
• UInt64 — соответствует типу long в client-v1

Возможности

Таблица возможностей клиентов:

Name	Client V2	Client V1	Comments
Http Connection	✔	✔
Http Compression (LZ4)	✔	✔
Server Response Compression - LZ4	✔	✔
Client Request Compression - LZ4	✔	✔
HTTPS	✔	✔
Client SSL Cert (mTLS)	✔	✔
Http Proxy	✔	✔
POJO SerDe	✔	✗
Connection Pool	✔	✔	При использовании Apache HTTP Client
Named Parameters	✔	✔
Retry on failure	✔	✔
Failover	✗	✔
Load-balancing	✗	✔
Server auto-discovery	✗	✔
Log Comment	✔	✔
Session Roles	✔	✔
SSL Client Authentication	✔	✔
Session timezone	✔	✔

JDBC-драйвер наследует те же возможности, что и базовая реализация клиента. Другие возможности JDBC перечислены на этой странице.

Совместимость

• Все проекты в этом репозитории тестируются со всеми активными LTS-версиями ClickHouse.
• Политика поддержки
• Мы рекомендуем регулярно обновлять клиент, чтобы не пропускать исправления уязвимостей и новые улучшения.
• Если у вас возникла проблема с миграцией на API v2 — создайте issue, и мы вам ответим!

Логирование

Наш Java‑клиент использует SLF4J для логирования. Вы можете использовать любой совместимый с SLF4J фреймворк для логирования, например Logback или Log4j. Если вы используете Maven, добавьте следующую зависимость в файл pom.xml:

<dependencies>
    <!-- SLF4J API -->
    <dependency>
        <groupId>org.slf4j</groupId>
        <artifactId>slf4j-api</artifactId>
        <version>2.0.16</version> <!-- Используйте последнюю версию -->
    </dependency>

    <!-- Logback Core -->
    <dependency>
        <groupId>ch.qos.logback</groupId>
        <artifactId>logback-core</artifactId>
        <version>1.5.16</version> <!-- Используйте последнюю версию -->
    </dependency>

    <!-- Logback Classic (связывает SLF4J с Logback) -->
    <dependency>
        <groupId>ch.qos.logback</groupId>
        <artifactId>logback-classic</artifactId>
        <version>1.5.16</version> <!-- Используйте последнюю версию -->
    </dependency>
</dependencies>

Настройка логирования

Настройка будет зависеть от того, какой фреймворк для логирования вы используете. Например, если вы используете Logback, вы можете настроить логирование в файле logback.xml:

<configuration>
    <!-- Аппендер для консоли -->
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>[%d{yyyy-MM-dd HH:mm:ss}] [%level] [%thread] %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <!-- Аппендер для файла -->
    <appender name="FILE" class="ch.qos.logback.core.FileAppender">
        <file>logs/app.log</file>
        <append>true</append>
        <encoder>
            <pattern>[%d{yyyy-MM-dd HH:mm:ss}] [%level] [%thread] %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <!-- Корневой логгер -->
    <root level="info">
        <appender-ref ref="STDOUT" />
        <appender-ref ref="FILE" />
    </root>

    <!-- Настраиваемые уровни логирования для отдельных пакетов -->
    <logger name="com.clickhouse" level="info" />
</configuration>

Журнал изменений