Клиент (0.7.x и ранее)

Java клиентская библиотека для общения с сервером БД через его протоколы. Текущая реализация поддерживает только HTTP интерфейс. Библиотека предоставляет собственный API для отправки запросов на сервер.

Устаревание

Эта библиотека скоро будет устаревать. Используйте последний Java Client для новых проектов

Настройка

Maven

Gradle (Kotlin)

Gradle

Начиная с версии 0.5.0, драйвер использует новую клиентскую http библиотеку, которая должна быть добавлена в зависимости.

Maven

Gradle (Kotlin)

Gradle

Инициализация

Формат URL подключения: protocol://host[:port][/database][?param[=value][&param[=value]][#tag[,tag]], например:

• http://localhost:8443?ssl=true&sslmode=NONE
• https://(https://explorer@play.clickhouse.com:443

Подключение к одному узлу:

Подключение к кластеру с несколькими узлами:

Запрос API

Streaming Запрос API

Смотрите полный пример кода в репозитории.

Вставка API

Смотрите полный пример кода в репозитории.

Кодирование RowBinary

Формат RowBinary описан на его странице.

Есть пример кода.

Особенности

Сжатие

Клиент по умолчанию будет использовать сжатие LZ4, для этого требуется данная зависимость:

Maven

Gradle (Kotlin)

Gradle

Вы можете выбрать использование gzip вместо этого, установив compress_algorithm=gzip в URL подключения.

Кроме того, вы можете отключить сжатие несколькими способами.

1. Отключите, установив compress=0 в URL подключения: http://localhost:8123/default?compress=0
2. Отключите через конфигурацию клиента:

Смотрите документацию по сжатию, чтобы узнать больше о различных параметрах сжатия.

Несколько запросов

Выполняйте несколько запросов в рабочем потоке один за другим в рамках одной сессии:

Именованные параметры

Вы можете передавать параметры по имени, а не полагаться исключительно на их позицию в списке параметров. Эта возможность доступна с использованием функции params.

Параметры

Все сигнатуры params, которые включают тип String (String, String[], Map<String, String>), предполагают, что передаваемые ключи являются допустимыми строками SQL ClickHouse. Например:

Если вы предпочитаете не парсить объекты String в SQL ClickHouse вручную, вы можете использовать вспомогательную функцию ClickHouseValues.convertToSqlExpression, расположенную в com.clickhouse.data:

В приведенном выше примере ClickHouseValues.convertToSqlExpression экранирует внутреннюю одинарную кавычку и обрамляет переменную допустимыми одинарными кавычками.

Другие типы, такие как Integer, UUID, Array и Enum, будут автоматически преобразованы внутри params.

Обнаружение узлов

Java клиент предоставляет возможность автоматически обнаруживать узлы ClickHouse. Автообнаружение отключено по умолчанию. Чтобы вручную включить его, установите auto_discovery в true:

Или в URL подключения:

Если автообнаружение включено, нет необходимости указывать все узлы ClickHouse в URL подключения. Узлы, указанные в URL, будут рассматриваться как начальные точки, и Java клиент автоматически обнаружит дополнительные узлы из системных таблиц и/или clickhouse-keeper или zookeeper.

Следующие параметры отвечают за конфигурацию автообнаружения:

Свойство	По умолчанию	Описание
auto_discovery	false	Должен ли клиент обнаруживать дополнительные узлы из системных таблиц и/или clickhouse-keeper/zookeeper.
node_discovery_interval	0	Интервал обнаружения узлов в миллисекундах, нулевое или отрицательное значение означает одноразовое обнаружение.
node_discovery_limit	100	Максимальное количество узлов, которые могут быть обнаружены одновременно; нулевое или отрицательное значение означает отсутствие ограничений.

Балансировка нагрузки

Java клиент выбирает узел ClickHouse для отправки запросов в соответствии с политикой балансировки нагрузки. В общем, политика балансировки нагрузки отвечает за следующие вещи:

1. Получение узла из управляемого списка узлов.
2. Управление статусом узла.
3. Опционально планировать фоновый процесс для обнаружения узлов (если автообнаружение включено) и проводить проверку работоспособности.

Вот список параметров для конфигурации балансировки нагрузки:

Свойство	По умолчанию	Описание
load_balancing_policy	""	Политика балансировки нагрузки может быть одной из: firstAlive - запрос отправляется первому здоровому узлу из управляемого списка узлов random - запрос отправляется на случайный узел из управляемого списка узлов roundRobin - запрос отправляется по очереди каждому узлу из управляемого списка узлов. полное имя класса, реализующего ClickHouseLoadBalancingPolicy - пользовательская политика балансировки нагрузки Если не указано, запрос отправляется первому узлу из управляемого списка узлов.
load_balancing_tags	""	Теги балансировки нагрузки для фильтрации узлов. Запросы отправляются только на узлы, имеющие указанные теги.
health_check_interval	0	Интервал проверки работоспособности в миллисекундах, нулевое или отрицательное значение означает одноразовую проверку.
health_check_method	ClickHouseHealthCheckMethod.SELECT_ONE	Метод проверки работоспособности. Может быть одним из: ClickHouseHealthCheckMethod.SELECT_ONE - проверка с помощью запроса select 1 ClickHouseHealthCheckMethod.PING - специфическая для протокола проверка, которая, как правило, быстрее
node_check_interval	0	Интервал проверки узлов в миллисекундах, отрицательное число рассматривается как ноль. Статус узла проверяется, если прошло указанное количество времени с момента последней проверки. Разница между параметрами health_check_interval и node_check_interval заключается в том, что параметр health_check_interval планирует фоновую задачу, которая проверяет статус списка узлов (всех или неисправных), но параметр node_check_interval указывает, сколько времени прошло с момента последней проверки конкретного узла.
check_all_nodes	false	Следует ли выполнять проверку работоспособности всех узлов или только неисправных.

Откат и повторное выполнение

Java клиент предоставляет параметры конфигурации для настройки поведения отката и повторных попыток для неудачных запросов:

Свойство	По умолчанию	Описание
failover	0	Максимальное количество раз, которое может произойти откат для запроса. Нулевое или отрицательное значение означает отсутствие отката. Откат отправляет неудавшийся запрос на другой узел (в соответствии с политикой балансировки нагрузки) для восстановления после сбоя.
retry	0	Максимальное количество раз, сколько повторов может произойти для запроса. Нулевое или отрицательное значение означает отсутствие повторов. Повтор отправляет запрос на тот же узел и только если сервер ClickHouse возвращает код ошибки NETWORK_ERROR.
repeat_on_session_lock	true	Следует ли повторять выполнение, когда сессия заблокирована до таймаута (в соответствии с session_timeout или connect_timeout). Неудавшийся запрос повторяется, если сервер ClickHouse возвращает код ошибки SESSION_IS_LOCKED.

Добавление пользовательских http заголовков

Java клиент поддерживает HTTP/S транспортный уровень на случай, если мы хотим добавить пользовательские HTTP заголовки к запросу. Мы должны использовать свойство custom_http_headers, и заголовки должны разделяться ,. Ключ/значение заголовка должны быть разделены с помощью =.

Поддержка Java Client

JDBC Драйвер