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

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

Клиент ClickHouse​

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

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

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

Тип данныхПоддержка Клиента V2Поддержка Клиента 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 в клиенте v1

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

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

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

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

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

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

Логирование​

Наш 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>

Changelog