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

Java-клиент

v0.8+

Клиентская библиотека Java для взаимодействия с сервером БД по его протоколам. Текущая реализация поддерживает только HTTP-интерфейс. Библиотека предоставляет собственный API для отправки запросов на сервер. Также она содержит инструменты для работы с различными форматами бинарных данных (RowBinary* & Native*).

Настройка​

<dependency>
  <groupId>com.clickhouse</groupId>
  <artifactId>client-v2</artifactId>
  <version>0.9.8</version>
</dependency>

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

Объект Client инициализируется с помощью com.clickhouse.client.api.Client.Builder#build(). Каждый клиент имеет собственный контекст, объекты между клиентами не разделяются. Builder предоставляет методы конфигурации для удобной настройки.

Пример:

 Client client = new Client.Builder()
                .addEndpoint("https://clickhouse-cloud-instance:8443/")
                .setUsername(user)
                .setPassword(password)
                .build();

Client реализует интерфейс AutoCloseable, и его следует закрывать, когда он больше не нужен.

Аутентификация​

Аутентификация настраивается для каждого клиента на этапе инициализации. Поддерживаются три метода аутентификации: по паролю, по токену доступа и по клиентскому SSL‑сертификату.

Для аутентификации по паролю необходимо задать имя пользователя и пароль, вызвав методы setUsername(String) и setPassword(String):

 Client client = new Client.Builder()
        .addEndpoint("https://clickhouse-cloud-instance:8443/")
        .setUsername(user)
        .setPassword(password)
        .build();

Для аутентификации по токену доступа необходимо задать его, вызвав метод setAccessToken(String):

 Client client = new Client.Builder()
        .addEndpoint("https://clickhouse-cloud-instance:8443/")
        .setAccessToken(userAccessToken)
        .build();

Аутентификация по SSL-сертификату клиента требует указания имени пользователя, включения SSL-аутентификации, указания клиентского сертификата и клиентского ключа с помощью вызова методов setUsername(String), useSSLAuthentication(boolean), setClientCertificate(String) и setClientKey(String) соответственно:

Client client = new Client.Builder()
        .useSSLAuthentication(true)
        .setUsername("some_user")
        .setClientCertificate("some_user.crt")
        .setClientKey("some_user.key")
Примечание

Аутентификацию 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"]})

Настройка​

Все настройки задаются методами экземпляра (так называемыми методами конфигурации), которые однозначно определяют область действия и контекст каждого значения. Ключевые параметры конфигурации задаются на одном уровне (клиент или операция) и не переопределяют друг друга.

Конфигурация задаётся при создании клиента. См. com.clickhouse.client.api.Client.Builder.

Настройка клиента​

МетодАргументыОписаниеПо умолчаниюКлюч
addEndpoint(String endpoint)endpoint - адрес сервера в формате URLДобавляет endpoint сервера в список доступных серверов. В настоящее время поддерживается только один endpoint.nonenone
addEndpoint(Protocol protocol, String host, int port, boolean secure)protocol - протокол подключения
host - IP-адрес или имя хоста
secure - использовать HTTPS		Добавляет endpoint сервера в список доступных серверов. В настоящее время поддерживается только один endpoint.nonenone
enableConnectionPool(boolean enable)enable - флаг включения/отключенияУстанавливает, включен ли пул соединенийtrueconnection_pool_enabled
setMaxConnections(int maxConnections)maxConnections - число соединенийУстанавливает, сколько соединений клиент может открыть к каждому endpoint-у сервера.10max_open_connections
setConnectionTTL(long timeout, ChronoUnit unit)timeout - значение тайм-аута
unit - единица времени		Устанавливает TTL соединения, по истечении которого соединение будет считаться неактивным-1connection_ttl
setKeepAliveTimeout(long timeout, ChronoUnit unit)timeout - значение тайм-аута
unit - единица времени		Устанавливает тайм-аут Keep-Alive для HTTP-соединения. Установите 0, чтобы отключить Keep-Alive.-http_keep_alive_timeout
setConnectionReuseStrategy(ConnectionReuseStrategy strategy)strategy - LIFO или FIFOВыбирает стратегию повторного использования соединений, которую должен применять пул соединенийFIFOconnection_reuse_strategy
setDefaultDatabase(String database)database - имя базы данныхУстанавливает базу данных по умолчанию.defaultdatabase

Идентификация клиента​

В журнале запросов есть два поля, идентифицирующих приложение, из которого поступил запрос: client_name и http_user_agent. Нативный TCP-протокол использует client_name для идентификации приложения. HTTP-протокол использует http_user_agent для идентификации приложения. Метод setClientName в Client builder устанавливает корректные значения для обоих протоколов. Поле http_user_agent задаётся в соответствии с общим форматом заголовка User-Agent: application-name[/version] [(operating-system; architecture; ...)]. Этот набор значений повторяется для каждого уровня: приложение, клиентская библиотека, HTTP-клиентская библиотека. Значение, заданное методом setClientName, стоит первым в списке.

Например:

client.setClientName("my-app-01/1.0");

приведёт к следующему значению http_user_agent:

my-app-01/1.0 clickhouse-java-v2/0.9.6-SNAPSHOT (Linux; jvm:17.0.17) Apache-HttpClient/5.4.4

Приложение может задать собственный HTTP-заголовок User-Agent для своей идентификации. Однако часть clickhouse-java-v2/0.9.6-SNAPSHOT будет добавлена в конец заголовка.

Идентификация операции​

Журнал запросов содержит ещё два поля query_id и log_comment, которые можно использовать, чтобы идентифицировать операцию и добавить дополнительную информацию в журнал запросов.

query_id — уникальный идентификатор операции. Его можно задать в приложении, вызвав метод setQueryId класса QuerySettings.

QuerySettings querySettings = new QuerySettings();
querySettings.setQueryId("some-query-id");

log_comment — это комментарий, который можно добавить в журнал запросов. Его можно задать в приложении, вызвав метод logComment класса QuerySettings.

QuerySettings querySettings = new QuerySettings();
querySettings.logComment("some-comment");

Настройки сервера​

Настройки на стороне сервера можно задать на уровне клиента один раз при его создании (см. метод serverSetting класса Builder) и на уровне операции (см. serverSetting в классе настроек операции).

 try (Client client = new Client.Builder().addEndpoint(Protocol.HTTP, "localhost", mockServer.port(), false)
        .setUsername("default")
        .setPassword(ClickHouseServerForTest.getPassword())
        .compressClientRequest(true)

        // Client level
        .serverSetting("max_threads", "10")
        .serverSetting("async_insert", "1")
        .serverSetting("roles", Arrays.asList("role1", "role2"))

        .build()) {

	// Operation level
	QuerySettings querySettings = new QuerySettings();
	querySettings.serverSetting("session_timezone", "Europe/Zurich");

	...
}

⚠️ При задании параметров методом setOption (как у Client.Builder, так и у класса настроек операции) имя серверной настройки должно начинаться с префикса clickhouse_setting_. В этом случае может пригодиться метод com.clickhouse.client.api.ClientConfigProperties#serverSetting().

Пользовательский HTTP-заголовок​

Пользовательские HTTP-заголовки можно задать для всех операций (на уровне клиента) или только для отдельной операции (на уровне операции).


QuerySettings settings = new QuerySettings()
    .httpHeader(HttpHeaders.REFERER, clientReferer)
    .setQueryId(qId);

Когда параметры задаются с помощью метода setOption (в Client.Builder или в классе настроек операции), имя пользовательского заголовка должно начинаться с префикса http_header_. В этом случае пригодится метод com.clickhouse.client.api.ClientConfigProperties#httpHeader().

Общие определения​

ClickHouseFormat​

Перечисление поддерживаемых форматов. Включает все форматы, поддерживаемые ClickHouse.

  • raw - пользователь должен самостоятельно преобразовать сырые данные
  • full - клиент может самостоятельно транскодировать данные и принимать поток необработанных данных
  • - - ClickHouse не поддерживает эту операцию для данного формата

Эта версия клиента поддерживает:

ФорматВводВывод
TabSeparatedrawraw
TabSeparatedRawrawraw
TabSeparatedWithNamesrawraw
TabSeparatedWithNamesAndTypesrawraw
TabSeparatedRawWithNamesrawraw
TabSeparatedRawWithNamesAndTypesrawraw
Templaterawraw
TemplateIgnoreSpacesraw-
CSVrawraw
CSVWithNamesrawraw
CSVWithNamesAndTypesrawraw
CustomSeparatedrawraw
CustomSeparatedWithNamesrawraw
CustomSeparatedWithNamesAndTypesrawraw
SQLInsert-raw
Valuesrawraw
Vertical-raw
JSONrawraw
JSONAsStringraw-
JSONAsObjectraw-
JSONStringsrawraw
JSONColumnsrawraw
JSONColumnsWithMetadatarawraw
JSONCompactrawraw
JSONCompactStrings-raw
JSONCompactColumnsrawraw
JSONEachRowrawraw
PrettyJSONEachRow-raw
JSONEachRowWithProgress-raw
JSONStringsEachRowrawraw
JSONStringsEachRowWithProgress-raw
JSONCompactEachRowrawraw
JSONCompactEachRowWithNamesrawraw
JSONCompactEachRowWithNamesAndTypesrawraw
JSONCompactStringsEachRowrawraw
JSONCompactStringsEachRowWithNamesrawraw
JSONCompactStringsEachRowWithNamesAndTypesrawraw
JSONObjectEachRowrawraw
BSONEachRowrawraw
TSKVrawraw
Pretty-raw
PrettyNoEscapes-raw
PrettyMonoBlock-raw
PrettyNoEscapesMonoBlock-raw
PrettyCompact-raw
PrettyCompactNoEscapes-raw
PrettyCompactMonoBlock-raw
PrettyCompactNoEscapesMonoBlock-raw
PrettySpace-raw
PrettySpaceNoEscapes-raw
PrettySpaceMonoBlock-raw
PrettySpaceNoEscapesMonoBlock-raw
Prometheus-raw
Protobufrawraw
ProtobufSinglerawraw
ProtobufListrawraw
Avrorawraw
AvroConfluentraw-
Parquetrawraw
ParquetMetadataraw-
Arrowrawraw
ArrowStreamrawraw
ORCrawraw
Oneraw-
Npyrawraw
RowBinaryfullfull
RowBinaryWithNamesfullfull
RowBinaryWithNamesAndTypesfullfull
RowBinaryWithDefaultsfull-
Nativefullraw
Null-raw
XML-raw
CapnProtorawraw
LineAsStringrawraw
Regexpraw-
RawBLOBrawraw
MsgPackrawraw
MySQLDumpraw-
DWARFraw-
Markdown-raw
Formraw-

API вставки​

insert(String tableName, InputStream data, ClickHouseFormat format)​

Принимает данные в виде потока байтов (InputStream) в указанном формате. Ожидается, что data закодирован в формате format.

Сигнатуры

CompletableFuture<InsertResponse> insert(String tableName, InputStream data, ClickHouseFormat format, InsertSettings settings)
CompletableFuture<InsertResponse> insert(String tableName, InputStream data, ClickHouseFormat format)

Параметры

tableName — имя целевой таблицы.

data — входной поток закодированных данных.

format — формат, в котором закодированы данные.

settings — настройки запроса.

Возвращаемое значение

Future типа InsertResponse — результат операции и дополнительная информация, например, метрики на стороне сервера.

Примеры

try (InputStream dataStream = getDataStream()) {
    try (InsertResponse response = client.insert(TABLE_NAME, dataStream, ClickHouseFormat.JSONEachRow,
            insertSettings).get(3, TimeUnit.SECONDS)) {

        log.info("Insert finished: {} rows written", response.getMetrics().getMetric(ServerMetrics.NUM_ROWS_WRITTEN).getLong());
    } catch (Exception e) {
        log.error("Failed to write JSONEachRow data", e);
        throw new RuntimeException(e);
    }
}

insert(String tableName, List<?> data, InsertSettings settings)​

Отправляет запрос на запись в базу данных. Список объектов преобразуется в эффективный формат и затем отправляется на сервер. Класс элементов списка должен быть предварительно зарегистрирован с помощью метода register(Class, TableSchema).

Сигнатуры

client.insert(String tableName, List<?> data, InsertSettings settings)
client.insert(String tableName, List<?> data)

Параметры

tableName — имя целевой таблицы.

data — коллекция объектов DTO (Data Transfer Object).

settings — настройки запроса.

Возвращаемое значение

Future типа InsertResponse — результат операции и дополнительная информация, например метрики на стороне сервера.

Примеры

// Important step (done once) - register class to pre-compile object serializer according to the table schema.
client.register(ArticleViewEvent.class, client.getTableSchema(TABLE_NAME));

List<ArticleViewEvent> events = loadBatch();

try (InsertResponse response = client.insert(TABLE_NAME, events).get()) {
    // handle response, then it will be closed and connection that served request will be released.
}

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()Возвращает идентификатор запроса, назначенный для операции приложением (через настройки операции или сервером).

API запросов​

query(String sqlQuery)​

Отправляет sqlQuery как есть. Формат ответа определяется настройками запроса. QueryResponse будет содержать ссылку на поток ответа, который должен быть прочитан ридером, работающим с соответствующим форматом.

Сигнатуры

CompletableFuture<QueryResponse> query(String sqlQuery, QuerySettings settings)
CompletableFuture<QueryResponse> query(String sqlQuery)

Параметры

sqlQuery — одна SQL-команда. Запрос отправляется на сервер как есть.

settings — настройки запроса.

Возвращаемое значение

Future типа QueryResponse — результирующий набор данных и дополнительная информация, например метрики на стороне сервера. Объект Response следует закрыть после чтения набора данных.

Примеры

final String sql = "select * from " + TABLE_NAME + " where title <> '' limit 10";

// Default format is RowBinaryWithNamesAndTypesFormatReader so reader have all information about columns
try (QueryResponse response = client.query(sql).get(3, TimeUnit.SECONDS);) {

    // Create a reader to access the data in a convenient way
    ClickHouseBinaryFormatReader reader = client.newBinaryFormatReader(response);

    while (reader.hasNext()) {
        reader.next(); // Read the next record from stream and parse it

        // get values
        double id = reader.getDouble("id");
        String title = reader.getString("title");
        String url = reader.getString("url");

        // collecting data
    }
} catch (Exception e) {
    log.error("Failed to read data", e);
}

// put business logic outside of the reading block to release http connection asap.

query(String sqlQuery, Map<String, Object> queryParams, QuerySettings settings)​

Отправляет sqlQuery как есть. Также передаёт параметры запроса, чтобы сервер мог скомпилировать SQL-выражение.

Сигнатуры

CompletableFuture<QueryResponse> query(String sqlQuery, Map<String, Object> queryParams, QuerySettings settings)

Параметры

sqlQuery — SQL-выражение с плейсхолдерами {}.

queryParams — map переменных для подстановки значений при формировании SQL-выражения на стороне сервера.

settings — настройки запроса.

Возвращаемое значение

Future типа QueryResponse — результирующий набор данных и дополнительная информация, например метрики на стороне сервера. Объект Response следует закрыть после чтения набора данных.

Примеры


// define parameters. They will be sent to the server along with the request.
Map<String, Object> queryParams = new HashMap<>();
queryParams.put("param1", 2);

try (QueryResponse response =
        client.query("SELECT * FROM " + table + " WHERE col1 >= {param1:UInt32}", queryParams, new QuerySettings()).get()) {

    // Create a reader to access the data in a convenient way
    ClickHouseBinaryFormatReader reader = client.newBinaryFormatReader(response);

    while (reader.hasNext()) {
        reader.next(); // Read the next record from stream and parse it

        // reading data
    }

} catch (Exception e) {
    log.error("Failed to read data", e);
}

queryAll(String sqlQuery)​

Запрашивает данные в формате RowBinaryWithNamesAndTypes. Возвращает результат в виде коллекции. Скорость чтения такая же, как у ридера, но для хранения всего датасета требуется больше памяти.

Сигнатуры

List<GenericRecord> queryAll(String sqlQuery)

Параметры

sqlQuery — SQL-выражение для запроса данных с сервера.

Возвращаемое значение

Полный набор данных, представленный списком объектов GenericRecord, обеспечивающих построчный доступ к данным результата.

Примеры

try {
    log.info("Reading whole table and process record by record");
    final String sql = "select * from " + TABLE_NAME + " where title <> ''";

    // Read whole result set and process it record by record
    client.queryAll(sql).forEach(row -> {
        double id = row.getDouble("id");
        String title = row.getString("title");
        String url = row.getString("url");

        log.info("id: {}, title: {}, url: {}", id, title, url);
    });
} catch (Exception e) {
    log.error("Failed to read data", e);
}

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 в ответе.

Примеры​

Общий API​

getTableSchema(String table)​

Извлекает схему таблицы table.

Сигнатуры

TableSchema getTableSchema(String table)
TableSchema getTableSchema(String table, String database)

Параметры

table — имя таблицы, для которой необходимо получить данные схемы.

database — база данных, в которой определена целевая таблица.

Возвращаемое значение

Возвращает объект TableSchema со списком столбцов таблицы.

getTableSchemaFromQuery(String sql)​

Извлекает schema из SQL-команды.

Сигнатуры

TableSchema getTableSchemaFromQuery(String sql)

Параметры

sql - SQL-оператор "SELECT", схема которого должна быть возвращена.

Возвращаемое значение

Возвращает объект TableSchema со столбцами, соответствующими выражению sql.

TableSchema​

register(Class<?> clazz, TableSchema schema)​

Компилирует слой сериализации и десериализации для Java-класса, который будет использоваться для записи и чтения данных в соответствии со схемой schema. Метод создаёт сериализатор и десериализатор для пары геттер/сеттер и соответствующего столбца. Соответствие столбца определяется путём извлечения его имени из имени метода. Например, getFirstName будет соответствовать столбцу first_name или firstname.

Сигнатуры

void register(Class<?> clazz, TableSchema schema)

Параметры

clazz — класс POJO, используемый для чтения и записи данных.

schema - Схема данных для сопоставления со свойствами POJO.

Примеры

client.register(ArticleViewEvent.class, client.getTableSchema(TABLE_NAME));

Примеры использования​

Полный код примеров хранится в репозитории в каталоге example (folder):

  • client-v2 - основной набор примеров.
  • demo-service - пример использования клиента в приложении Spring Boot.
  • demo-kotlin-service - пример использования клиента в Ktor-приложении на Kotlin.

Чтение данных​

Существует два распространённых способа чтения данных:

  • Метод query() возвращает низкоуровневый объект QueryResponse, содержащий InputStream с данными. Обычно он используется вместе с ClickHouseBinaryFormatReader для потокового чтения, но также может использоваться с любой другой пользовательской реализацией ридера. QueryResponse также предоставляет доступ к метаданным результирующего набора данных и метрикам.
  • метод queryAll() с использованием GenericRecord для удобного построчного доступа к данным. В этом случае весь результирующий набор загружается в память.
  • queryRecords() — метод, возвращающий com.clickhouse.client.api.query.Records, итератор по объектам GenericRecord. Этот метод использует потоковый подход (данные не загружаются в память) и применяет GenericRecord для доступа к данным.

Примечание: потоковый подход требует быстрого чтения; в противном случае может произойти таймаут записи на сервере, так как данные читаются непосредственно из сетевого потока.

Чтение массивов​

Методы ClickHouseBinaryFormatReader

  • getList(...) - считывает любой Array(...) как List<T>. Хороший вариант по умолчанию для гибкого типизированного чтения. Поддерживает вложенные массивы.
  • getByteArray(...), getShortArray(...), getIntArray(...), getLongArray(...), getFloatArray(...), getDoubleArray(...), getBooleanArray(...) - лучше всего подходят для одномерных массивов значений, совместимых с примитивными типами.
  • getStringArray(...) - для Array(String) (и значений перечислений, представленных в виде имён).
  • getObjectArray(...) - универсальный вариант для любого типа элементов Array(...), включая вложенные массивы. Используйте его для чтения массивов с Nullable-значениями и вложенных массивов.

Перегрузки на основе индекса и имени доступны для всех методов. Индексация начинается с 1. Методы, использующие индекс, выполняют прямой доступ к столбцу. Методы, основанные на имени, при каждом вызове выполняют поиск индекса.

try (QueryResponse response = client.query("SELECT * FROM my_table").get()) {
    ClickHouseBinaryFormatReader reader = client.newBinaryFormatReader(response);
    while (reader.next() != null) {

        Object[] uint64 = reader.getObjectArray("uint64_arr"); // Array(UInt64) -> BigInteger[]
        Object[] arr2d = reader.getObjectArray("arr2d");       // Array(Array(Int64)) -> Object[]

        // nested arrays are returned as nested Object[]:
        Object[] firstInner = (Object[]) arr2d[0];
        Long firstValue = (Long) firstInner[0];
    }
}

Методы GenericRecord

  • getList(...) - читает любой Array(...) как List<T>. Оптимальный вариант по умолчанию для гибкого типизированного чтения. Поддерживает вложенные массивы.
  • getByteArray(...), getShortArray(...), getIntArray(...), getLongArray(...), getFloatArray(...), getDoubleArray(...), getBooleanArray(...) - лучше всего подходят для одномерных массивов значений, совместимых с примитивными типами.
  • getStringArray(...) - для Array(String) (и значений перечислений, представленных именами).
  • getObjectArray(...) - универсальный вариант для любого типа элементов Array(...), включая вложенные массивы. Используйте его для чтения массивов с Nullable-значениями и вложенных массивов.

Перегрузки на основе индекса и имени доступны для всех методов. Индексация начинается с 1. Методы, использующие индекс, выполняют прямой доступ к столбцу. Методы, основанные на имени, при каждом вызове выполняют поиск индекса.

try (QueryResponse response = client.query("SELECT * FROM my_table").get()) {
    List<GenericRecord> rows = client.queryAll(
        "SELECT int_arr, arr2d_nullable FROM test_arrays ORDER BY id");

    for (GenericRecord row : rows) {
        Object[] intArr = row.getObjectArray("int_arr");                 // Array(Int32) -> Integer[]
        Object[] arr2d = row.getObjectArray("arr2d_nullable");           // Array(Array(Nullable(Int32)))

        Object[] inner = (Object[]) arr2d[0];
        Object maybeNull = inner[1]; // may be null
    }
}

Руководство по миграции​

Старый клиент (V1) использовал com.clickhouse.client.ClickHouseClient#builder в качестве точки входа. Новый клиент (V2) применяет аналогичный подход с com.clickhouse.client.api.Client.Builder. Основные отличия:

  • для получения реализации service loader не используется. com.clickhouse.client.api.Client — это класс-фасад для любых будущих реализаций.
  • меньше источников конфигурации: один передаётся в builder, а второй — через настройки операций (QuerySettings, InsertSettings). В предыдущей версии конфигурация задавалась отдельно для каждого узла, и в некоторых случаях загружались переменные окружения.

Соответствие параметров конфигурации​

В V1 есть 3 класса перечислений, связанных с конфигурацией:

  • com.clickhouse.client.config.ClickHouseDefaults - параметры конфигурации, которые обычно задаются в большинстве сценариев использования. Например, USER и PASSWORD.
  • com.clickhouse.client.config.ClickHouseClientOption — параметры конфигурации, специфичные для клиента. Например, HEALTH_CHECK_INTERVAL.
  • com.clickhouse.client.http.config.ClickHouseHttpOption — параметры конфигурации, специфичные для HTTP-интерфейса. Например, RECEIVE_QUERY_PROGRESS.

Они были разработаны для группировки параметров и обеспечения чёткого разделения. Однако в ряде случаев это приводило к путанице (например, есть ли разница между com.clickhouse.client.config.ClickHouseDefaults#ASYNC и com.clickhouse.client.config.ClickHouseClientOption#ASYNC). Новый клиент V2 использует com.clickhouse.client.api.Client.Builder в качестве единого словаря всех возможных параметров конфигурации клиента. В классе com.clickhouse.client.api.ClientConfigProperties перечислены все имена параметров конфигурации.

В таблице ниже показано, какие старые настройки поддерживаются в новом клиенте и каково их новое значение.

Обозначения: ✔ = поддерживается, ✗ = удалено

Конфигурация V1Метод Builder в V2Комментарии
ClickHouseDefaults#HOSTClient.Builder#addEndpoint
ClickHouseDefaults#PROTOCOL✗В V2 поддерживается только HTTP
ClickHouseDefaults#DATABASE
ClickHouseClientOption#DATABASE		Client.Builder#setDefaultDatabase
ClickHouseDefaults#USERClient.Builder#setUsername
ClickHouseDefaults#PASSWORDClient.Builder#setPassword
ClickHouseClientOption#CONNECTION_TIMEOUTClient.Builder#setConnectTimeout
ClickHouseClientOption#CONNECTION_TTLClient.Builder#setConnectionTTL
ClickHouseHttpOption#MAX_OPEN_CONNECTIONSClient.Builder#setMaxConnections
ClickHouseHttpOption#KEEP_ALIVE
ClickHouseHttpOption#KEEP_ALIVE_TIMEOUT		Client.Builder#setKeepAliveTimeout
ClickHouseHttpOption#CONNECTION_REUSE_STRATEGYClient.Builder#setConnectionReuseStrategy
ClickHouseHttpOption#USE_BASIC_AUTHENTICATIONClient.Builder#useHTTPBasicAuth

General Differences​

  • Client V2 использует меньше проприетарных классов, что повышает переносимость. Например, V2 работает с любой реализацией java.io.InputStream для записи данных на сервер.
  • В Client V2 настройка async по умолчанию имеет значение off. Это означает, что дополнительные потоки не создаются, а приложение получает больше контроля над клиентом. Для большинства сценариев использования этот параметр должен оставаться в состоянии off. При включении async для каждого запроса будет создаваться отдельный поток. Это имеет смысл только при использовании executor, управляемого приложением (см. com.clickhouse.client.api.Client.Builder#setSharedOperationExecutor)

Запись данных​

  • используйте любую реализацию java.io.InputStream. V1 com.clickhouse.data.ClickHouseInputStream поддерживается, но НЕ рекомендуется.
  • как только обнаруживается конец входного потока, он обрабатывается должным образом. Ранее требовалось закрывать выходной поток запроса.

V1 Вставка данных в формате TSV.

InputStream inData = getInData();
ClickHouseRequest.Mutation request = client.read(server)
        .write()
        .table(tableName)
        .format(ClickHouseFormat.TSV);
ClickHouseConfig config = request.getConfig();
CompletableFuture<ClickHouseResponse> future;
try (ClickHousePipedOutputStream requestBody = ClickHouseDataStreamFactory.getInstance()
        .createPipedOutputStream(config)) {
    // start the worker thread which transfer data from the input into ClickHouse
    future = request.data(requestBody.getInputStream()).execute();

    // Copy data from inData stream to requestBody stream

    // We need to close the stream before getting a response
    requestBody.close();

    try (ClickHouseResponse response = future.get()) {
        ClickHouseResponseSummary summary = response.getSummary();
        Assert.assertEquals(summary.getWrittenRows(), numRows, "Num of written rows");
    }
}

V2 Вставка данных в формате TSV.

InputStream inData = getInData();
InsertSettings settings = new InsertSettings().setInputStreamCopyBufferSize(8198 * 2); // set copy buffer size
try (InsertResponse response = client.insert(tableName, inData, ClickHouseFormat.TSV, settings).get(30, TimeUnit.SECONDS)) {

  // Insert is complete at this point

} catch (Exception e) {
 // Handle exception
}
  • достаточно вызвать один метод. Нет необходимости создавать дополнительный объект запроса.
  • Поток тела запроса автоматически закрывается после копирования всех данных.
  • Теперь доступен новый низкоуровневый API com.clickhouse.client.api.Client#insert(java.lang.String, java.util.List<java.lang.String>, com.clickhouse.client.api.DataStreamWriter, com.clickhouse.data.ClickHouseFormat, com.clickhouse.client.api.insert.InsertSettings). com.clickhouse.client.api.DataStreamWriter предназначен для реализации пользовательской логики записи данных. Например, для чтения данных из очереди.

Чтение данных​

  • По умолчанию данные читаются в формате RowBinaryWithNamesAndTypes. В настоящее время, когда требуется привязка данных, поддерживается только этот формат.
  • Данные можно считывать как коллекцию записей с помощью метода List<GenericRecord> com.clickhouse.client.api.Client#queryAll(java.lang.String). Метод загружает данные в память и освобождает соединение, поэтому дополнительная обработка не требуется. GenericRecord предоставляет доступ к данным и выполняет некоторые преобразования типов.
Collection<GenericRecord> records = client.queryAll("SELECT * FROM table");
for (GenericRecord record : records) {
    int rowId = record.getInteger("rowID");
    String name = record.getString("name");
    LocalDateTime ts = record.getLocalDateTime("ts");
}

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

Устаревшая библиотека

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

Настройка​

<!-- https://mvnrepository.com/artifact/com.clickhouse/clickhouse-http-client -->
<dependency>
    <groupId>com.clickhouse</groupId>
    <artifactId>clickhouse-http-client</artifactId>
    <version>0.7.2</version>
</dependency>

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

<!-- https://mvnrepository.com/artifact/org.apache.httpcomponents.client5/httpclient5 -->
<dependency>
    <groupId>org.apache.httpcomponents.client5</groupId>
    <artifactId>httpclient5</artifactId>
    <version>5.3.1</version>
</dependency>

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

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

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

ClickHouseNode server = ClickHouseNode.of("http://localhost:8123/default?compress=0");

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

ClickHouseNodes servers = ClickHouseNodes.of(
    "jdbc:ch:http://server1.domain,server2.domain,server3.domain/my_db"
    + "?load_balancing_policy=random&health_check_interval=5000&failover=2");

API запросов​

try (ClickHouseClient client = ClickHouseClient.newInstance(ClickHouseProtocol.HTTP);
     ClickHouseResponse response = client.read(servers)
        .format(ClickHouseFormat.RowBinaryWithNamesAndTypes)
        .query("select * from numbers limit :limit")
        .params(1000)
        .executeAndWait()) {
            ClickHouseResponseSummary summary = response.getSummary();
            long totalRows = summary.getTotalRowsToRead();
}

API потоковых запросов​

try (ClickHouseClient client = ClickHouseClient.newInstance(ClickHouseProtocol.HTTP);
     ClickHouseResponse response = client.read(servers)
        .format(ClickHouseFormat.RowBinaryWithNamesAndTypes)
        .query("select * from numbers limit :limit")
        .params(1000)
        .executeAndWait()) {
            for (ClickHouseRecord r : response.records()) {
            int num = r.getValue(0).asInteger();
            // type conversion
            String str = r.getValue(0).asString();
            LocalDate date = r.getValue(0).asDate();
        }
}

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

API вставки​


try (ClickHouseClient client = ClickHouseClient.newInstance(ClickHouseProtocol.HTTP);
     ClickHouseResponse response = client.read(servers).write()
        .format(ClickHouseFormat.RowBinaryWithNamesAndTypes)
        .query("insert into my_table select c2, c3 from input('c1 UInt8, c2 String, c3 Int32')")
        .data(myInputStream) // `myInputStream` is source of data in RowBinary format
        .executeAndWait()) {
            ClickHouseResponseSummary summary = response.getSummary();
            summary.getWrittenRows();
}

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

Кодирование в формате RowBinary

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

Пример приведён в коде.

Возможности​

Сжатие​

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

<!-- https://mvnrepository.com/artifact/org.lz4/lz4-java -->
<dependency>
    <groupId>org.lz4</groupId>
    <artifactId>lz4-java</artifactId>
    <version>1.8.0</version>
</dependency>

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

Сжатие также можно отключить несколькими способами.

  1. Отключите сжатие, указав compress=0 в URL-адресе подключения: http://localhost:8123/default?compress=0
  2. Отключите через конфигурацию клиента:
ClickHouseClient client = ClickHouseClient.builder()
   .config(new ClickHouseConfig(Map.of(ClickHouseClientOption.COMPRESS, false)))
   .nodeSelector(ClickHouseNodeSelector.of(ClickHouseProtocol.HTTP))
   .build();

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

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

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

CompletableFuture<List<ClickHouseResponseSummary>> future = ClickHouseClient.send(servers.apply(servers.getNodeSelector()),
    "create database if not exists my_base",
    "use my_base",
    "create table if not exists test_table(s String) engine=Memory",
    "insert into test_table values('1')('2')('3')",
    "select * from test_table limit 1",
    "truncate table test_table",
    "drop table if exists test_table");
List<ClickHouseResponseSummary> results = future.get();

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

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

try (ClickHouseClient client = ClickHouseClient.newInstance(ClickHouseProtocol.HTTP);
     ClickHouseResponse response = client.read(servers)
        .format(ClickHouseFormat.RowBinaryWithNamesAndTypes)
        .query("select * from my_table where name=:name limit :limit")
        .params("Ben", 1000)
        .executeAndWait()) {
            //...
        }
}
Параметры

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

try (ClickHouseClient client = ClickHouseClient.newInstance(ClickHouseProtocol.HTTP);
     ClickHouseResponse response = client.read(servers)
        .format(ClickHouseFormat.RowBinaryWithNamesAndTypes)
        .query("select * from my_table where name=:name")
        .params(Map.of("name","'Ben'"))
        .executeAndWait()) {
            //...
        }
}

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

try (ClickHouseClient client = ClickHouseClient.newInstance(ClickHouseProtocol.HTTP);
     ClickHouseResponse response = client.read(servers)
        .format(ClickHouseFormat.RowBinaryWithNamesAndTypes)
        .query("select * from my_table where name=:name")
        .params(Map.of("name", ClickHouseValues.convertToSqlExpression("Ben's")))
        .executeAndWait()) {
            //...
        }
}

В приведённом выше примере ClickHouseValues.convertToSqlExpression экранирует внутреннюю одинарную кавычку и обернёт значение переменной в корректные одинарные кавычки.

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

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

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

properties.setProperty("auto_discovery", "true");

Или в URL-адресе подключения:

jdbc:ch://my-server/system?auto_discovery=true

При включённом автообнаружении нет необходимости указывать все узлы ClickHouse в URL подключения. Узлы, указанные в URL, будут рассматриваться как начальные (seed) узлы, и 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-клиента​

    options.put("custom_http_headers", "X-ClickHouse-Quota=test, X-ClickHouse-Test=test");

    JDBC-драйвер​

    properties.setProperty("custom_http_headers", "X-ClickHouse-Quota=test, X-ClickHouse-Test=test");