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

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

Устаревание

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

Настройка

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 запросов

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 клиента

JDBC драйвер