Cliente de Java

​

Configuración

• Maven Central (página web del proyecto): https://mvnrepository.com/artifact/com.clickhouse/client-v2
• Versiones nocturnas (enlace al repositorio): https://central.sonatype.com/repository/maven-snapshots/
• Artifactory de compilaciones Nightly anteriores (enlace al repositorio): 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'

​

Inicialización

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

​

Autenticación

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

​

Configuración

​

Configuración del cliente

​

Identificación del 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

​

Identificación de operaciones

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

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

​

Configuración del 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");

	...
}

​

Encabezado HTTP personalizado

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

​

Definiciones comunes

​

ClickHouseFormat

• raw - el usuario debe transcodificar los datos sin procesar
• full - el cliente puede transcodificar datos por su cuenta y acepta un flujo de datos sin procesar
• - - operación no admitida por ClickHouse para este formato

​

API de inserción

​

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 consultas

​

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

​

Ejemplos

• El código de ejemplo está disponible en el repositorio
• Servicio de Spring de referencia implementación

​

API común

​

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

​

Ejemplos de uso

• client-v2 - colección principal de ejemplos.
• demo-service - ejemplo de cómo utilizar el cliente en una aplicación Spring Boot.
• demo-kotlin-service - ejemplo de cómo usar el cliente en una aplicación de Ktor (Kotlin).

​

Lectura de datos

• método query() que devuelve un objeto QueryResponse de bajo nivel que contiene un InputStream con datos. Normalmente se combina con ClickHouseBinaryFormatReader para lecturas en streaming, pero puede utilizarse con cualquier otra implementación personalizada de lector. QueryResponse también proporciona acceso a los metadatos del conjunto de resultados y a las métricas.
• método queryAll() y uso de GenericRecord para acceder cómodamente a las filas. En este caso, todo el conjunto de resultados se carga en memoria.
• método queryRecords() que devuelve com.clickhouse.client.api.query.Records: un iterador de objetos GenericRecord. Este método utiliza un enfoque de streaming (no se cargan datos en memoria) y usa GenericRecord para acceder a los datos.

​

Lectura de Arrays

• getList(...) - lee cualquier Array(...) como List<T>. Es una buena opción predeterminada para lecturas flexibles con tipado. Admite arrays anidados.
• getByteArray(...), getShortArray(...), getIntArray(...), getLongArray(...), getFloatArray(...), getDoubleArray(...), getBooleanArray(...) - mejor para arrays 1D de valores compatibles con tipos primitivos.
• getStringArray(...) - para Array(String) (y valores de enum representados por nombres).
• getObjectArray(...) - opción genérica para cualquier tipo de elemento de Array(...), incluidos los arrays anidados. Úselo para leer arrays con valores anulables y arrays anidados.

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(...) - lee cualquier Array(...) como List<T>. Buena opción predeterminada para lecturas flexibles con tipado. Admite arrays anidados.
• getByteArray(...), getShortArray(...), getIntArray(...), getLongArray(...), getFloatArray(...), getDoubleArray(...), getBooleanArray(...) - ideal para arrays unidimensionales de valores compatibles con tipos primitivos.
• getStringArray(...) - para Array(String) (y valores de enum representados por nombres).
• getObjectArray(...) - opción genérica para cualquier tipo de elemento de Array(...), incluidos los arrays anidados. Úsela para leer arrays con valores que admiten NULL y arrays anidados.

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

​

Guía de migración

• no se utiliza ningún cargador de servicios para obtener la implementación. com.clickhouse.client.api.Client es una clase fachada para todo tipo de implementaciones futuras.
• menos fuentes de configuración: una se proporciona al builder y otra se encuentra en la configuración de operación (QuerySettings, InsertSettings). La versión anterior tenía una configuración por nodo y, en algunos casos, cargaba variables de entorno.

​

Coincidencia de parámetros de configuración

• com.clickhouse.client.config.ClickHouseDefaults - parámetros de configuración que suelen establecerse en la mayoría de los casos de uso, como USER y PASSWORD.
• com.clickhouse.client.config.ClickHouseClientOption - parámetros de configuración específicos para el cliente, como HEALTH_CHECK_INTERVAL.
• com.clickhouse.client.http.config.ClickHouseHttpOption - parámetros de configuración específicos de la interfaz HTTP, como RECEIVE_QUERY_PROGRESS.

​

Diferencias generales

• Client V2 utiliza menos clases propietarias para aumentar la portabilidad. Por ejemplo, V2 funciona con cualquier implementación de java.io.InputStream para escribir datos en un servidor.
• La configuración async de Client V2 está off de forma predeterminada. Esto significa que no hay hilos adicionales y que la aplicación tiene un mayor control sobre el cliente. Esta configuración debería estar off en la mayoría de los casos de uso. Al habilitar async, se creará un hilo independiente para cada solicitud. Solo tiene sentido cuando se usa un executor controlado por la aplicación (consulte com.clickhouse.client.api.Client.Builder#setSharedOperationExecutor)

​

Escritura de datos

• usa cualquier implementación de java.io.InputStream. Se admite V1 com.clickhouse.data.ClickHouseInputStream, pero NO se recomienda.
• Una vez detectado el final del flujo de entrada, se actúa en consecuencia. Antes, debe cerrarse el flujo de salida de una solicitud.

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
}

• solo hay que llamar a un único método. No es necesario crear un objeto de solicitud adicional.
• el flujo del cuerpo de la solicitud se cierra automáticamente cuando se copian todos los datos.
• hay una nueva API de bajo nivel disponible: 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 está diseñada para implementar lógica personalizada de escritura de datos. Por ejemplo, leer datos de una cola.

​

Lectura de datos

• Los datos se leen en el formato RowBinaryWithNamesAndTypes de forma predeterminada. Actualmente, solo se admite este formato cuando se requiere el enlace de datos.
• Los datos pueden leerse como una colección de registros mediante el método List<GenericRecord> com.clickhouse.client.api.Client#queryAll(java.lang.String). Este método lee los datos en memoria y libera la conexión. No requiere ninguna gestión adicional. GenericRecord proporciona acceso a los datos e implementa algunas conversiones.

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