Java Client (0.8+)
Библиотека Java-клиента для взаимодействия с сервером БД через его протоколы. Текущая реализация поддерживает только HTTP интерфейс. Библиотека предоставляет собственный API для отправки запросов на сервер. Также библиотека предоставляет инструменты для работы с различными бинарными форматами данных (RowBinary* & Native*).
Если вам нужна предыдущая версия документации java клиента, пожалуйста, смотрите здесь.
Настройка
- Maven Central (веб-страница проекта): https://mvnrepository.com/artifact/com.clickhouse/client-v2
- Ночные сборки (ссылка на репозиторий): https://s01.oss.sonatype.org/content/repositories/snapshots/com/clickhouse/
- Maven
- Gradle (Kotlin)
- Gradle
Инициализация
Объект Client инициализируется с помощью com.clickhouse.client.api.Client.Builder#build(). Каждый клиент имеет свой собственный контекст и объекты не разделяются между ними.
Строитель имеет методы конфигурации для удобной настройки.
Пример:
Client является AutoCloseable и должен быть закрыт, когда не нужен больше.
Аутентификация
Аутентификация настраивается для каждого клиента на этапе инициализации. Поддерживаются три метода аутентификации: по паролю, по токену доступа, с использованием клиентского сертификата SSL.
Аутентификация по паролю требует установки имени пользователя и пароля с помощью вызовов setUsername(String) и setPassword(String):
Аутентификация по токену доступа требует установки токена доступа с помощью вызова setAccessToken(String):
Аутентификация с использованием клиентского сертификата SSL требует установки имени пользователя, включения SSL-аутентификации, установки клиентского сертификата и ключа клиента с помощью вызовов setUsername(String), useSSLAuthentication(boolean), setClientCertificate(String) и setClientKey(String) соответственно:
Аутентификация SSL может быть трудной для устранения проблем в производственной среде, так как многие ошибки из библиотек SSL предоставляют недостаточно информации. Например, если клиентский сертификат и ключ не совпадают, сервер немедленно завершит соединение (в случае HTTP это будет на стадии инициации соединения, когда ни один HTTP-запрос не отправляется, и, соответственно, ответ не отправляется).
Пожалуйста, используйте инструменты, такие как openssl, для проверки сертификатов и ключей:
- проверьте целостность ключа:
openssl rsa -in [key-file.key] -check -noout - проверьте, что клиентский сертификат имеет совпадающее CN для пользователя:
- получите CN из сертификата пользователя -
openssl x509 -noout -subject -in [user.cert] - проверьте, что то же значение установлено в базе данных
select name, auth_type, auth_params from system.users where auth_type = 'ssl_certificate'(запрос выведетauth_paramsс чем-то вроде{"common_names":["some_user"]})
- получите CN из сертификата пользователя -
Конфигурация
Все настройки определяются экземплярными методами (также известными как методы конфигурации), что делает область видимости и контекст каждого значения ясными. Основные параметры конфигурации определяются в одной области (клиент или операция) и не переопределяют друг друга.
Конфигурация определяется во время создания клиента. См. com.clickhouse.client.api.Client.Builder.
Конфигурация клиента
| Метод конфигурации | Аргументы | Описание |
|---|---|---|
addEndpoint(String endpoint) | - enpoint - URL отформатированного адреса сервера. | Добавляет конечную точку сервера в список доступных серверов. В настоящее время поддерживается только одна конечная точка. |
addEndpoint(Protocol protocol, String host, int port, boolean secure) | - protocol - протокол соединения com.clickhouse.client.api.enums.Protocol#HTTP.- host - IP или имя хоста сервера.- secure - если связь должна использовать защищенную версию протокола (HTTPS) | Добавляет конечную точку сервера в список доступных серверов. В настоящее время поддерживается только одна конечная точка. |
setOption(String key, String value) | - key - строковой ключ опции конфигурации клиента.- value - строковое значение опции | Устанавливает сырой значение параметров клиента. Полезно при чтении конфигурации из файлов свойств. |
setUsername(String username) | - username - имя пользователя для аутентификации | Устанавливает имя пользователя для метода аутентификации, выбранного дальнейшей конфигурацией |
setPassword(String password) | - password - секретное значение для аутентификации паролем | Устанавливает секрет для аутентификации паролем и фактически выбирает метод аутентификации |
setAccessToken(String accessToken) | - accessToken - строковое представление токена доступа | Устанавливает токен доступа для аутентификации с установленным соответствующим методом аутентификации |
useSSLAuthentication(boolean useSSLAuthentication) | - useSSLAuthentication - флаг, указывающий, следует ли использовать аутентификацию SSL | Устанавливает клиентский сертификат SSL в качестве метода аутентификации |
enableConnectionPool(boolean enable) | - enable - флаг, указывающий, следует ли включать эту опцию | Устанавливает, включен ли пул подключений |
setConnectTimeout(long timeout, ChronoUnit unit) | - timeout - тайм-аут в некоторых единицах времени.- unit - единица времени тайм-аута | Устанавливает тайм-аут инициации соединения для любого исходящего соединения. Это влияет на время ожидания получения соединения сокета. |
setConnectionRequestTimeout(long timeout, ChronoUnit unit) | - timeout - тайм-аут в некоторых единицах времени.- unit - единица времени тайм-аута | Устанавливает тайм-аут запроса соединения. Это вступает в силу только для получения соединения из пула. |
setMaxConnections(int maxConnections) | - maxConnections - количество соединений | Устанавливает, сколько соединений может открыть клиент для каждой конечной точки сервера. |
setConnectionTTL(long timeout, ChronoUnit unit) | - timeout - тайм-аут в некоторых единицах времени.- unit - единица времени тайм-аута | Устанавливает время жизни соединения (TTL), после которого соединение будет считаться неактивным |
setKeepAliveTimeout(long timeout, ChronoUnit unit) | - timeout - тайм-аут в некоторых единицах времени.- unit - единица времени тайм-аута | Устанавливает тайм-аут поддержания активного состояния HTTP соединения. Эта опция может быть использована для отключения Keep-Alive, установив тайм-аут в ноль - 0 |
setConnectionReuseStrategy(ConnectionReuseStrategy strategy) | - strategy - константа com.clickhouse.client.api.ConnectionReuseStrategy | Выбирает, какую стратегию должен использовать пул соединений: LIFO, если соединение должно использоваться снова сразу после его возврата в пул, или FIFO, чтобы использовать соединение в порядке их появления (возвращенные соединения не используются немедленно). |
setSocketTimeout(long timeout, ChronoUnit unit) | - timeout - тайм-аут в некоторых единицах времени.- unit - единица времени тайм-аута | Устанавливает тайм-аут сокета, который влияет на операции чтения и записи |
setSocketRcvbuf(long size) | - size - размер в байтах | Устанавливает буфер получения TCP-сокета. Этот буфер находится вне памяти JVM. |
setSocketSndbuf(long size) | - size - размер в байтах | Устанавливает буфер отправки TCP-сокета. Этот буфер находится вне памяти JVM. |
setSocketKeepAlive(boolean value) | - value - флаг, указывающий, следует ли включать эту опцию. | Устанавливает опцию SO_KEEPALIVE для каждого TCP-сокета, созданного клиентом. TCP Keep Alive включает механизм, который будет проверять работоспособность соединения и поможет обнаружить неожиданно завершенные соединения. |
setSocketTcpNodelay(boolean value) | - value - флаг, указывающий, следует ли включать эту опцию. | Устанавливает опцию SO_NODELAY для каждого TCP-сокета, созданного клиентом. Эта опция TCP заставит сокет отправлять данные как можно скорее. |
setSocketLinger(int secondsToWait) | - secondsToWait - количество секунд. | Устанавливает время ожидания для каждого TCP-сокета, созданного клиентом. |
compressServerResponse(boolean enabled) | - enabled - флаг, указывающий, следует ли включать эту опцию | Устанавливает, должен ли сервер сжимать свои ответы. |
compressClientRequest(boolean enabled) | - enabled - флаг, указывающий, следует ли включать эту опцию | Устанавливает, должен ли клиент сжимать свои запросы. |
useHttpCompression(boolean enabled) | - enabled - флаг, указывающий, следует ли включать эту опцию | Устанавливает, следует ли использовать HTTP-сжатие для взаимодействия клиент/сервер, если соответствующие опции включены |
setLZ4UncompressedBufferSize(int size) | - size - размер в байтах | Устанавливает размер буфера, который будет получать несжатую часть потока данных. Если размер буфера недооценен, то будет создан новый, и соответствующее предупреждение будет записано в журнале. |
setDefaultDatabase(String database) | - database - имя базы данных | Устанавливает базу данных по умолчанию. |
addProxy(ProxyType type, String host, int port) | - type - тип прокси.- host - имя хоста прокси или IP-адрес.- port - порт прокси | Устанавливает прокси для использования при взаимодействии с сервером. Установка прокси требуется, если прокси требует аутентификации. |
setProxyCredentials(String user, String pass) | - user - имя пользователя прокси.- pass - пароль | Устанавливает учетные данные пользователя для аутентификации с прокси. |
setExecutionTimeout(long timeout, ChronoUnit timeUnit) | - timeout - тайм-аут в некоторых единицах времени.- timeUnit - единица времени тайм-аута | Устанавливает максимальный тайм-аут выполнения для запросов |
setHttpCookiesEnabled(boolean enabled) | enabled - флаг, указывающий, следует ли включать эту опцию | Устанавливает, должны ли HTTP куки храниться и отправляться обратно на сервер. |
setSSLTrustStore(String path) | path - путь к файлу на локальной (клиентской) стороне системы | Устанавливает, должен ли клиент использовать SSL truststore для валидации хоста сервера. |
setSSLTrustStorePassword(String password) | password - секретное значение | Устанавливает пароль, используемый для разблокировки SSL truststore, указанный в setSSLTrustStore(String path) |
setSSLTrustStoreType(String type) | type - имя типа truststore | Устанавливает тип truststore, указанный в setSSLTrustStore(String path). |
setRootCertificate(String path) | path - путь к файлу на локальной (клиентской) стороне системы | Устанавливает, должен ли клиент использовать указанный корневой (CA) сертификат для валидации хоста сервера. |
setClientCertificate(String path) | path - путь к файлу на локальной (клиентской) стороне системы | Устанавливает путь к клиентскому сертификату, который будет использоваться при инициации SSL-соединения и для аутентификации SSL |
setClientKey(String path) | path - путь к файлу на локальной (клиентской) стороне системы | Устанавливает личный ключ клиента, который будет использоваться для шифрования SSL-соединения с сервером. |
useServerTimeZone(boolean useServerTimeZone) | useServerTimeZone - флаг, указывающий, следует ли включать эту опцию | Устанавливает, должен ли клиент использовать серверный часовой пояс при декодировании значений столбцов DateTime и Date. Если включено, серверный часовой пояс должен быть установлен с помощью setServerTimeZone(String timeZone) |
useTimeZone(String timeZone) | timeZone - строковое значение действительного ID часового пояса java (см. java.time.ZoneId) | Устанавливает, должен ли использоваться указанный часовой пояс при декодировании значений столбцов DateTime и Date. Переопределит часовой пояс сервера |
setServerTimeZone(String timeZone) | timeZone - строковое значение действительного ID часового пояса java (см. java.time.ZoneId) | Устанавливает часовой пояс сервера. В качестве значения по умолчанию будет использоваться UTC. |
useAsyncRequests(boolean async) | async - флаг, указывающий, следует ли включать эту опцию. | Устанавливает, должен ли клиент выполнять запрос в отдельном потоке. Отключено по умолчанию, так как приложение лучше знает, как организовать многопоточные задачи, и выполнение задач в отдельном потоке не помогает с производительностью. |
setSharedOperationExecutor(ExecutorService executorService) | executorService - экземпляр сервиса исполнителя. | Устанавливает сервис исполнителя для операций. |
setClientNetworkBufferSize(int size) | - size - размер в байтах | Устанавливает размер буфера в памяти приложения, который используется для копирования данных между сокетом и приложением. Больший размер уменьшает количество системных вызовов к стеку TCP, но влияет на то, сколько памяти расходуется на каждое соединение. Этот буфер также подлежит сборке мусора, так как соединения краткоживущие. Также имейте в виду, что выделение большого непрерывного блока памяти может быть проблемой. По умолчанию это 300,000 байт. |
retryOnFailures(ClientFaultCause ...causes) | - causes - константа перечисления com.clickhouse.client.api.ClientFaultCause | Устанавливает типы неисправностей, подлежащие восстановлению/повторному вызову. |
setMaxRetries(int maxRetries) | - maxRetries - количество попыток | Устанавливает максимальное количество повторных попыток для ошибок, определенных retryOnFailures(ClientFaultCause ...causes) |
allowBinaryReaderToReuseBuffers(boolean reuse) | - reuse - флаг, указывающий, следует ли включать эту опцию | Большинство наборов данных содержат числовые данные, закодированные в виде небольших последовательностей байтов. По умолчанию считыватель выделит необходимый буфер, прочитает данные в него, а затем преобразует в целевой класс Number. Это может вызвать значительное давление на сборку мусора из-за большого количества небольших объектов, которые выделяются и освобождаются. Если эта опция включена, считыватель будет использовать заранее выделенные буферы для трансформации чисел. Это безопасно, поскольку каждый считыватель имеет свой собственный набор буферов, и считыватели используются одним потоком. |
httpHeader(String key, String value) | - key - ключ HTTP заголовка.- value - строковое значение заголовка. | Устанавливает значение для одного HTTP заголовка. Предыдущее значение будет переопределено. |
httpHeader(String key, Collection values) | - key - ключ HTTP заголовка.- values - список строковых значений. | Устанавливает значения для одного HTTP заголовка. Предыдущее значение будет переопределено. |
httpHeaders(Map headers) | - header - карта с HTTP заголовками и их значениями. | Устанавливает несколько значений HTTP заголовков за один раз. |
serverSetting(String name, String value) | - name - имя параметра уровня запроса.- value - строковое значение параметра. | Устанавливает настройки, которые следует передать серверу вместе с каждым запросом. Отдельные операции могут переопределить их. Список настроек |
serverSetting(String name, Collection values) | - name - имя параметра уровня запроса.- values - строковые значения параметра. | Устанавливает настройки, которые следует передать серверу вместе с каждым запросом. Отдельные операции могут переопределить их. Список настроек. Этот метод полезен для установки настроек с несколькими значениями, например roles |
columnToMethodMatchingStrategy(ColumnToMethodMatchingStrategy strategy) | - strategy - реализация стратегии соответствия столбцов и методов | Устанавливает пользовательскую стратегию, которая будет использоваться для соответствия полей DTO классов и столбцов БД при регистрации DTO. |
useHTTPBasicAuth(boolean useBasicAuth) | - useBasicAuth - флаг, указывающий, следует ли включать эту опцию | Устанавливает, следует ли использовать базовую HTTP аутентификацию для аутентификации по имени пользователя и паролю. По умолчанию включено. Использование этого типа аутентификации решает проблемы с паролями, содержащими специальные символы, которые не могут быть перенесены через HTTP заголовки. |
setClientName(String clientName) | - clientName - строка, представляющая имя приложения | Устанавливает дополнительную информацию о вызываемом приложении. Эта строка будет передана серверу в качестве имени клиента. В случае протокола HTTP это будет передано как заголовок User-Agent. |
useBearerTokenAuth(String bearerToken) | - bearerToken - закодированный токен доступа | Указывает, следует ли использовать аутентификацию Bearer и какой токен использовать. Токен будет отправлен как есть, поэтому он должен быть закодирован перед передачей в этот метод. |
Общие Определения
ClickHouseFormat
Перечисление поддерживаемых форматов. Включает все форматы, которые поддерживает ClickHouse.
raw- пользователь должен перекодировать сырьевые данныеfull- клиент может перекодировать данные сам и принимает необработанный поток данных-- операция, не поддерживаемая ClickHouse для этого формата
Эта версия клиента поддерживает:
API вставки
insert(String tableName, InputStream data, ClickHouseFormat format)
Принимает данные в виде InputStream байтов в указанном формате. Ожидается, что data закодированы в format.
Подписи
Параметры
tableName - имя целевой таблицы.
data - входной поток закодированных данных.
format - формат, в котором данные закодированы.
settings - настройки запроса.
Возвращаемое значение
Future типа InsertResponse - результат операции и дополнительная информация, такая как метрики на стороне сервера.
Примеры
insert(String tableName, List<?> data, InsertSettings settings)
Отправляет запрос на запись в базу данных. Список объектов преобразуется в эффективный формат и затем отправляется на сервер. Класс элементов списка должен быть зарегистрирован заранее с помощью метода register(Class, TableSchema).
Подписи
Параметры
tableName - имя целевой таблицы.
data - коллекция объектов DTO (Data Transfer Object).
settings - настройки запроса.
Возвращаемое значение
Future типа InsertResponse - результат операции и дополнительная информация, такая как метрики на стороне сервера.
Примеры
InsertSettings
Настройки конфигурации для операций вставки.
Методы конфигурации
| Метод | Описание |
|---|---|
setQueryId(String queryId) | Устанавливает идентификатор запроса, который будет присвоен операции. По умолчанию: null. |
setDeduplicationToken(String token) | Устанавливает токен дедупликации. Этот токен будет отправлен на сервер и может использоваться для идентификации запроса. По умолчанию: null. |
setInputStreamCopyBufferSize(int size) | Размер буфера копирования. Буфер используется во время операций записи для копирования данных из предоставленного пользователем входного потока в выходной поток. По умолчанию: 8196. |
serverSetting(String name, String value) | Устанавливает индивидуальные серверные настройки для операции. |
serverSetting(String name, Collection values) | Устанавливает индивидуальные серверные настройки с несколькими значениями для операции. Элементы коллекции должны быть значениями типа String. |
setDBRoles(Collection dbRoles) | Устанавливает роли базы данных, которые будут установлены перед выполнением операции. Элементы коллекции должны быть значениями типа String. |
setOption(String option, Object value) | Устанавливает параметр конфигурации в необработанном формате. Это не серверная настройка. |
InsertResponse
Объект ответа, который содержит результат операции вставки. Он доступен только в том случае, если клиент получил ответ от сервера.
Этот объект должен быть закрыт как можно скорее, чтобы освободить соединение, так как соединение не может быть повторно использовано, пока все данные предыдущего ответа не будут полностью прочитаны.
| Метод | Описание |
|---|---|
OperationMetrics getMetrics() | Возвращает объект с метриками операции. |
String getQueryId() | Возвращает идентификатор запроса, присвоенный операции приложением (через настройки операции или сервером). |
Query API
query(String sqlQuery)
Отправляет sqlQuery как есть. Формат ответа устанавливается настройками запроса. QueryResponse будет содержать ссылку на поток ответа, который должен быть использован читателем для поддерживаемого формата.
Подписи
Параметры
sqlQuery - одно SQL выражение. Запрос отправляется на сервер как есть.
settings - настройки запроса.
Возвращаемое значение
Future типа QueryResponse - набор результатов и дополнительная информация, такая как метрики на стороне сервера. Объект ответа должен быть закрыт после потребления набора данных.
Примеры
query(String sqlQuery, Map<String, Object> queryParams, QuerySettings settings)
Отправляет sqlQuery как есть. Кроме того, будут отправлены параметры запроса, чтобы сервер мог скомпилировать SQL выражение.
Подписи
Параметры
sqlQuery - SQL выражение с заполнителями {}.
queryParams - карта переменных для завершения SQL выражения на сервере.
settings - настройки запроса.
Возвращаемое значение
Future типа QueryResponse - набор результатов и дополнительная информация, такая как метрики на стороне сервера. Объект ответа должен быть закрыт после потребления набора данных.
Примеры
queryAll(String sqlQuery)
Запрашивает данные в формате RowBinaryWithNamesAndTypes. Возвращает результат в виде коллекции. Производительность чтения такая же, как при использовании читателя, но требуется больше памяти для хранения всего набора данных.
Подписи
Параметры
sqlQuery - SQL выражение для запроса данных с сервера.
Возвращаемое значение
Полный набор данных, представленный списком объектов GenericRecord, которые обеспечивают доступ в строковом формате для результатирующих данных.
Примеры
QuerySettings
Настройки конфигурации для операций запросов.
Методы конфигурации
| Метод | Описание |
|---|---|
setQueryId(String queryId) | Устанавливает идентификатор запроса, который будет присвоен операции. |
setFormat(ClickHouseFormat format) | Устанавливает формат ответа. См. RowBinaryWithNamesAndTypes для полного списка. |
setMaxExecutionTime(Integer maxExecutionTime) | Устанавливает время выполнения операции на сервере. Не повлияет на время ожидания чтения. |
waitEndOfQuery(Boolean waitEndOfQuery) | Запрашивает сервер, чтобы он ждал завершения запроса перед отправкой ответа. |
setUseServerTimeZone(Boolean useServerTimeZone) | Часовой пояс сервера (см. конфигурацию клиента) будет использоваться для разбора типов даты/времени в результате операции. По умолчанию false. |
setUseTimeZone(String timeZone) | Запрашивает у сервера использовать timeZone для преобразования времени. См. session_timezone. |
serverSetting(String name, String value) | Устанавливает индивидуальные серверные настройки для операции. |
serverSetting(String name, Collection values) | Устанавливает индивидуальные серверные настройки с несколькими значениями для операции. Элементы коллекции должны быть значениями типа String. |
setDBRoles(Collection dbRoles) | Устанавливает роли базы данных, которые будут установлены перед выполнением операции. Элементы коллекции должны быть значениями типа String. |
setOption(String option, Object value) | Устанавливает параметр конфигурации в необработанном формате. Это не серверная настройка. |
QueryResponse
Объект ответа, который содержит результат выполнения запроса. Он доступен только в том случае, если клиент получил ответ от сервера.
Этот объект должен быть закрыт как можно скорее, чтобы освободить соединение, так как соединение не может быть повторно использовано, пока все данные предыдущего ответа не будут полностью прочитаны.
| Метод | Описание |
|---|---|
ClickHouseFormat getFormat() | Возвращает формат, в котором данные в ответе закодированы. |
InputStream getInputStream() | Возвращает непакетированный поток байтов данных в указанном формате. |
OperationMetrics getMetrics() | Возвращает объект с метриками операции. |
String getQueryId() | Возвращает идентификатор запроса, присвоенный для операции приложением (через настройки операции или сервером). |
TimeZone getTimeZone() | Возвращает часовой пояс, который должен использоваться для обработки типов Date/DateTime в ответе. |
Examples
- Пример кода доступен в репозитории
- Ссылка на реализацию Spring Service пример
Common API
getTableSchema(String table)
Получает схему таблицы для table.
Подписи
Параметры
table - имя таблицы, для которой должны быть получены данные схемы.
database - база данных, где определена целевая таблица.
Возвращаемое значение
Возвращает объект TableSchema со списком колонок таблицы.
getTableSchemaFromQuery(String sql)
Получает схему из SQL-запроса.
Подписи
Параметры
sql - SQL-запрос "SELECT", для которого должна быть возвращена схема.
Возвращаемое значение
Возвращает объект TableSchema с колонками, соответствующими SQL выражению.
TableSchema
register(Class<?> clazz, TableSchema schema)
Компилирует уровень сериализации и десериализации для Java класса, который будет использоваться для записи/чтения данных с schema. Метод создаст сериализатор и десериализатор для пары геттер/сеттер и соответствующей колонны.
Совпадение колонки определяется путем извлечения ее имени из имени метода. Например, getFirstName будет соответствовать колонке first_name или firstname.
Подписи
Параметры
clazz - класс, представляющий POJO, используемый для чтения/записи данных.
schema - схема данных, которая будет использоваться для сопоставления с свойствами POJO.
Примеры
Usage Examples
Полные примеры кода хранятся в репозитории в папке 'example` folder:
- client-v2 - основной набор примеров.
- demo-service - пример того, как использовать клиент в приложении Spring Boot.
- demo-kotlin-service - пример того, как использовать клиент в приложении Ktor (Kotlin).