Cliente Java

​

Setup

• Maven Central (página do projeto na web): https://mvnrepository.com/artifact/com.clickhouse/client-v2
• Builds noturnas (link do repositório): https://central.sonatype.com/repository/maven-snapshots/
• Artifactory das compilações Nightly antigas (link do repositório): 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'

​

Inicialização

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

​

Autenticação

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

​

Configuração

​

Configuração do Cliente

​

Identificação do Cliente

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

​

Identificação de Operação

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

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

​

Configurações do Servidor

 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 Header Personalizado

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

​

Definições Comuns

​

ClickHouseFormat

• raw - o usuário deve transcodificar os dados brutos
• full - o cliente pode transcodificar os dados por conta própria e aceita um fluxo de dados brutos
• - - operação não suportada pelo ClickHouse para este formato

​

API de Insert

​

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 de Consulta

​

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

​

Exemplos

• O código de exemplo está disponível no repositório
• Referência de implementação do Spring Service

​

API Comum

​

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

​

Exemplos de uso

• client-v2 - coleção principal de exemplos.
• demo-service - exemplo de uso do cliente em uma aplicação Spring Boot.
• demo-kotlin-service - exemplo de como usar o cliente em um aplicativo Ktor (Kotlin).

​

Lendo Dados

• método query() que retorna um objeto QueryResponse de baixo nível, que contém um InputStream com os dados. Geralmente combinado com ClickHouseBinaryFormatReader para leituras em streaming, mas pode ser usado com qualquer outra implementação personalizada de leitor. QueryResponse também fornece acesso aos metadados do conjunto de resultados e às métricas.
• método queryAll() e uso de GenericRecord para acesso prático às linhas. Nesse caso, todo o conjunto de resultados é carregado na memória.
• método queryRecords() que retorna com.clickhouse.client.api.query.Records — um iterador de objetos GenericRecord. Esse método usa uma abordagem de streaming (nenhum dado é carregado na memória) e utiliza GenericRecord para acessar os dados.

​

Lendo Arrays

• getList(...) - lê qualquer Array(...) como List<T>. Boa opção padrão para leituras tipadas flexíveis. Suporta arrays aninhados.
• getByteArray(...), getShortArray(...), getIntArray(...), getLongArray(...), getFloatArray(...), getDoubleArray(...), getBooleanArray(...) - mais indicados para arrays unidimensionais de valores compatíveis com tipos primitivos.
• getStringArray(...) - para Array(String) (e valores de enum representados por nomes).
• getObjectArray(...) - opção genérica para qualquer tipo de elemento de Array(...), incluindo arrays aninhados. Use-a para ler arrays com valores Nullable e arrays aninhados.

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(...) - lê qualquer Array(...) como List<T>. Boa opção padrão para leituras tipadas flexíveis. Suporta arrays aninhados.
• getByteArray(...), getShortArray(...), getIntArray(...), getLongArray(...), getFloatArray(...), getDoubleArray(...), getBooleanArray(...) - mais indicados para arrays unidimensionais de valores compatíveis com tipos primitivos.
• getStringArray(...) - para Array(String) (e valores de enum representados por nomes).
• getObjectArray(...) - opção genérica para qualquer tipo de elemento de Array(...), incluindo arrays aninhados. Use-a para ler arrays com valores Nullable e arrays aninhados.

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

​

Guia de Migração

• nenhum carregador de serviço é usado para recuperar a implementação. A com.clickhouse.client.api.Client é uma classe de fachada para todos os tipos de implementação que vierem a existir.
• menos fontes de configuração: uma é fornecida ao builder e a outra fica nas configurações da operação (QuerySettings, InsertSettings). A versão anterior tinha configuração por nó e, em alguns casos, carregava variáveis de ambiente.

​

Correspondência de Parâmetros de Configuração

• com.clickhouse.client.config.ClickHouseDefaults - parâmetros de configuração que devem ser definidos na maioria dos casos de uso, como USER e PASSWORD.
• com.clickhouse.client.config.ClickHouseClientOption - parâmetros de configuração específicos do cliente, como HEALTH_CHECK_INTERVAL.
• com.clickhouse.client.http.config.ClickHouseHttpOption - parâmetros de configuração específicos da interface HTTP, como RECEIVE_QUERY_PROGRESS.

​

Diferenças Gerais

• O Client V2 usa menos classes proprietárias para aumentar a portabilidade. Por exemplo, o V2 funciona com qualquer implementação de java.io.InputStream para gravar dados em um servidor.
• A configuração async do Client V2 vem como off por padrão. Isso significa que não há threads extras e que a aplicação tem mais controle sobre o cliente. Essa configuração deve permanecer off na maioria dos casos de uso. Ao habilitar async, uma thread separada será criada para cada solicitação. Isso só faz sentido ao usar um executor controlado pela aplicação (veja com.clickhouse.client.api.Client.Builder#setSharedOperationExecutor)

​

Gravação de dados

• use qualquer implementação de java.io.InputStream. A versão V1 com.clickhouse.data.ClickHouseInputStream é compatível, mas NÃO é recomendada.
• Uma vez detectado o fim do fluxo de entrada, ele é tratado adequadamente. Antes disso, o fluxo de saída de uma requisição deve ser fechado.

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
}

• há apenas um método para chamar. Não é necessário criar um objeto de requisição adicional.
• o stream do corpo da requisição é fechado automaticamente quando todos os dados são copiados.
• há uma nova API de baixo nível disponível 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 foi projetado para implementar uma lógica personalizada de gravação de dados. Por exemplo, lendo dados de uma fila.

​

Lendo Dados

• Os dados são lidos no formato RowBinaryWithNamesAndTypes por padrão. No momento, apenas esse formato é compatível quando o binding de dados é necessário.
• Os dados podem ser lidos como uma coleção de registros usando o método List<GenericRecord> com.clickhouse.client.api.Client#queryAll(java.lang.String). Ele lê os dados para a memória e libera a conexão. Não é necessário nenhum tratamento adicional. GenericRecord fornece acesso aos dados e implementa algumas conversões.

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