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

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

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

Устаревание

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

Настройка​

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

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

Формат 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, для чего требуется эта зависимость:

Вы можете выбрать использование 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_discoveryfalseДолжен ли клиент обнаруживать дополнительные узлы из системных таблиц и/или clickhouse-keeper/zookeeper.
node_discovery_interval0Интервал обнаружения узлов в миллисекундах, нулевое или отрицательное значение означает одноразовое обнаружение.
node_discovery_limit100Максимальное количество узлов, которые могут быть обнаружены за раз; нулевое или отрицательное значение означает отсутствие ограничения.

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

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

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

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

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

    Перезапуск и повторная попытка​

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

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

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

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

    Поддержка Java Client​

    JDBC Драйвер​