Перейти к основному содержимому
Перейти к основному содержимому

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

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

Возможности​

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

НазваниеClient V2Client V1Комментарии
HTTP-подключение✔✔
HTTP-сжатие (LZ4)✔✔
Сжатие, управляемое приложением✔✗
Сжатие ответов сервера — LZ4✔✔
Сжатие запросов клиента — LZ4✔✔
HTTPS✔✔
Клиентский SSL-сертификат (mTLS)✔✔
HTTP-прокси✔✔
POJO SerDe✔✗
Пул соединений✔✔При использовании Apache HTTP Client
Именованные параметры✔✔
Повтор при сбое✔✔
Переключение при сбое (failover)✗✔
Балансировка нагрузки✗✔
Автообнаружение серверов✗✔
Комментарий в логе✔✔
Роли сессии✔✔
Аутентификация клиента по SSL✔✔
Настройка SNI✔✗
Часовой пояс сессии✔✔

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> <!-- Use the latest version -->
    </dependency>

    <!-- Logback Core -->
    <dependency>
        <groupId>ch.qos.logback</groupId>
        <artifactId>logback-core</artifactId>
        <version>1.5.16</version> <!-- Use the latest version -->
    </dependency>

    <!-- Logback Classic (bridges SLF4J to Logback) -->
    <dependency>
        <groupId>ch.qos.logback</groupId>
        <artifactId>logback-classic</artifactId>
        <version>1.5.16</version> <!-- Use the latest version -->
    </dependency>
</dependencies>

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

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

<configuration>
    <!-- Console Appender -->
    <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>

    <!-- File 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 Logger -->
    <root level="info">
        <appender-ref ref="STDOUT" />
        <appender-ref ref="FILE" />
    </root>

    <!-- Custom Log Levels for Specific Packages -->
    <logger name="com.clickhouse" level="info" />
</configuration>

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