Java-клиент

​

Setup

• Maven Central (веб-страница проекта): https://mvnrepository.com/artifact/com.clickhouse/client-v2
• Ночные сборки (ссылка на репозиторий): https://central.sonatype.com/repository/maven-snapshots/
• Artifactory со старыми ночными сборками (ссылка на репозиторий): https://s01.oss.sonatype.org/content/repositories/snapshots/

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

// https://mvnrepository.com/artifact/com.clickhouse/client-v2
implementation("com.clickhouse:client-v2:0.9.8")

// https://mvnrepository.com/artifact/com.clickhouse/client-v2
implementation 'com.clickhouse:client-v2:0.9.8'

​

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

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

​

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

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

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

Client client = new Client.Builder()
        .useSSLAuthentication(true)
        .setUsername("some_user")
        .setClientCertificate("some_user.crt")
        .setClientKey("some_user.key")

​

Конфигурация

​

Конфигурация клиента

​

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

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

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

​

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

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

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

​

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

 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");

	...
}

​

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

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

​

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

​

ClickHouseFormat

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

​

API вставки

​

insert(String tableName, InputStream data, ClickHouseFormat format)

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

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)

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

// 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

​

InsertResponse

​

API запросов

​

query(String sqlQuery)

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

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)

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

// 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)

List<GenericRecord> queryAll(String sqlQuery)

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

​

QueryResponse

​

Примеры

• Пример кода доступен в репозитории
• Справочник по Spring Service реализации

​

Общий API

​

getTableSchema(String table)

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

​

getTableSchemaFromQuery(String sql)

TableSchema getTableSchemaFromQuery(String sql)

​

TableSchema

​

register(Class<?> clazz, TableSchema schema)

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

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

​

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

• 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 для доступа к данным.

​

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

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

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];
    }
}

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

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
    }
}

​

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

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

​

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

• 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.

​

Общие различия

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

​

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

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

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");
    }
}

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");
}