Java Клиент
Java-клиентская библиотека для взаимодействия с сервером БД через его протоколы. Текущая реализация поддерживает только HTTP интерфейс. Библиотека предоставляет собственное API для отправки запросов на сервер. Библиотека также предоставляет инструменты для работы с различными бинарными форматами данных (RowBinary* & Native*).
Настройка
- 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().
У каждого клиента есть свой собственный контекст, и объекты между ними не разделяются.
У Builder есть методы конфигурации для удобной настройки.
Пример:
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) | - endpoint - 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 - временная единица тайм-аута | Устанавливает время жизни соединения после которого соединение будет считаться неактивным |
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 для проверки хоста сервера. |
setSSLTrustStorePassword(String password) | password - секретное значение | Устанавливает пароль для разблокировки хранилища доверенных сертификатов SSL, указанного в setSSLTrustStore(String path) |
setSSLTrustStoreType(String type) | type - имя типа хранилища доверенных сертификатов | Устанавливает тип хранилища доверенных сертификатов, указанного в 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 - строковое значение действительного идентификатора временной зоны Java (см. java.time.ZoneId) | Устанавливает, должна ли указанная временная зона использоваться при декодировании значений полей DateTime и Date. Она переопределит временную зону сервера |
setServerTimeZone(String timeZone) | timeZone - строковое значение действительного идентификатора временной зоны 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) | - headers - карта с HTTP-заголовками и их значениями. | Устанавливает несколько значений HTTP-заголовков одновременно. |
serverSetting(String name, String value) | - name - имя параметра уровня запроса.- value - строковое значение параметра. | Устанавливает, какие настройки передавать серверу вместе с каждым запросом. Индивидуальные операции могут переопределить это. Список настроек |
serverSetting(String name, Collection values) | - name - имя параметра уровня запроса.- values - строковые значения параметра. | Устанавливает, какие настройки передавать серверу вместе с каждым запросом. Индивидуальные операции могут переопределить это. Этот метод полезен для установки настроек с несколькими значениями, например ролей |
columnToMethodMatchingStrategy(ColumnToMethodMatchingStrategy strategy) | - strategy - реализация стратегии соответствия столбца и поля | Устанавливает пользовательскую стратегию для соответствия полей класса DTO и столбцов БД при регистрации DTO. |
useHTTPBasicAuth(boolean useBasicAuth) | - useBasicAuth - флаг, который указывает, следует ли включать опцию | Устанавливает, должно ли использоваться базовое HTTP-аутентификация для аутентификации по имени пользователя и паролю. По умолчанию включен. Использование этого типа аутентификации решает проблемы с паролями, содержащими специальные символы, которые не могут быть переданы через HTTP-заголовки. |
setClientName(String clientName) | - clientName - строка, представляющая имя приложения | Устанавливает дополнительную информацию о вызываемом приложении. Эта строка будет передана серверу как имя клиента. В случае HTTP-протокола она будет передана как заголовок User-Agent. |
useBearerTokenAuth(String bearerToken) | - bearerToken - закодированный токен носителя | Указывает, следует ли использовать аутентификацию носителя и какой токен использовать. Токен будет отправлен как есть, поэтому он должен быть закодирован перед передачей в этот метод. |
Общие определения
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) | Устанавливает ID запроса, который будет назначен операции. По умолчанию: null. |
setDeduplicationToken(String token) | Устанавливает токен дедупликации. Этот токен будет отправлен серверу и может быть использован для идентификации запроса. По умолчанию: null. |
setInputStreamCopyBufferSize(int size) | Размер буфера копирования. Буфер используется во время операций записи для копирования данных из входного потока, предоставленного пользователем, в выходной поток. По умолчанию: 8196. |
serverSetting(String name, String value) | Устанавливает индивидуальные настройки сервера для операции. |
serverSetting(String name, Collection values) | Устанавливает индивидуальные настройки сервера с несколькими значениями для операции. Элементы коллекции должны быть строковыми значениями. |
setDBRoles(Collection dbRoles) | Устанавливает роли БД, которые будут установлены перед выполнением операции. Элементы коллекции должны быть строковыми значениями. |
setOption(String option, Object value) | Устанавливает опцию конфигурации в сыром формате. Это не серверная настройка. |
InsertResponse
Объект ответа, который содержит результат операции вставки. Он доступен только если клиент получил ответ от сервера.
Этот объект должен быть закрыт как можно скорее, чтобы освободить соединение, так как это соединение не может быть повторно использовано, пока все данные предыдущего ответа полностью не будут прочитаны.
| Метод | Описание |
|---|---|
OperationMetrics getMetrics() | Возвращает объект с метриками операции. |
String getQueryId() | Возвращает ID запроса, назначенный для операции приложением (через настройки операции или сервером). |
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) | Устанавливает ID запроса, который будет назначен операции. |
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) | Устанавливает индивидуальные настройки сервера с несколькими значениями для операции. Элементы коллекции должны быть строковыми значениями. |
setDBRoles(Collection dbRoles) | Устанавливает роли БД, которые будут установлены перед выполнением операции. Элементы коллекции должны быть строковыми значениями. |
setOption(String option, Object value) | Устанавливает опцию конфигурации в сыром формате. Это не серверная настройка. |
QueryResponse
Объект ответа, который содержит результат выполнения запроса. Он доступен только если клиент получил ответ от сервера.
Этот объект должен быть закрыт как можно скорее, чтобы освободить соединение, поскольку соединение не может быть повторно использовано, пока все данные предыдущего ответа полностью не будут прочитаны.
| Метод | Описание |
|---|---|
ClickHouseFormat getFormat() | Возвращает формат, в котором данные в ответе закодированы. |
InputStream getInputStream() | Возвращает не сжатый байтовый поток данных в указанном формате. |
OperationMetrics getMetrics() | Возвращает объект с метриками операции. |
String getQueryId() | Возвращает ID запроса, назначенный для операции приложением (через настройки операции или сервером). |
TimeZone getTimeZone() | Возвращает часовой пояс, который должен использоваться для обработки типов Date/DateTime в ответе. |
Examples
- Пример кода доступен в репозитории
- Ссылка на реализацию Spring Service implementation
Common API
getTableSchema(String table)
Извлекает схему таблицы для table.
Подписи
Параметры
table - имя таблицы, для которой должна быть извлечена схема.
database - база данных, в которой определена целевая таблица.
Возвращаемое значение
Возвращает объект TableSchema со списком колонок таблицы.
getTableSchemaFromQuery(String sql)
Извлекает схему из SQL-запроса.
Подписи
Параметры
sql - "SELECT" SQL-запрос, для которого должна быть возвращена схема.
Возвращаемое значение
Возвращает объект 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).
