Client Java

​

Configuration

• Maven Central (page du projet) : https://mvnrepository.com/artifact/com.clickhouse/client-v2
• Builds nocturnes (lien vers le dépôt) : https://central.sonatype.com/repository/maven-snapshots/
• Ancien dépôt Artifactory des builds nocturnes (lien vers le dépôt) : 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'

​

Initialisation

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

​

Authentification

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

​

Configuration

​

Configuration du client

​

Identification du client

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

​

Identification des opérations

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

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

​

Paramètres du serveur

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

	...
}

​

En-tête HTTP personnalisé

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

​

Définitions courantes

​

ClickHouseFormat

• raw - l’utilisateur doit transcoder les données brutes
• full - le client peut transcoder lui-même les données et accepte un flux de données brutes
• - - opération non prise en charge par ClickHouse pour ce format

​

API d’insertion

​

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 requête

​

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

​

Exemples

• Le code d’exemple est disponible dans le dépôt
• Implémentation de référence du service Spring

​

API commune

​

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

​

Exemples d’utilisation

• client-v2 - principal ensemble d’exemples.
• demo-service - exemple d’utilisation du client dans une application Spring Boot.
• demo-kotlin-service - exemple d’utilisation du client dans une application Ktor (Kotlin).

​

Lecture des données

• Méthode query() qui renvoie un objet QueryResponse de bas niveau contenant un InputStream avec les données. Généralement combinée à ClickHouseBinaryFormatReader pour les lectures en streaming, elle peut aussi être utilisée avec toute autre implémentation personnalisée de lecteur. QueryResponse donne également accès aux métadonnées du jeu de résultats et aux métriques.
• Méthode queryAll() avec utilisation de GenericRecord pour un accès pratique aux lignes. Dans ce cas, l’intégralité du jeu de résultats est chargée en mémoire.
• Méthode queryRecords() qui renvoie com.clickhouse.client.api.query.Records - un itérateur pour les objets GenericRecord. Cette méthode repose sur une approche en streaming (aucune donnée n’est chargée en mémoire) et utilise GenericRecord pour accéder aux données.

​

Lecture des Arrays

• getList(...) - lit n’importe quel Array(...) comme List<T>. Bon choix par défaut pour une lecture typée flexible. Prend en charge les tableaux imbriqués.
• getByteArray(...), getShortArray(...), getIntArray(...), getLongArray(...), getFloatArray(...), getDoubleArray(...), getBooleanArray(...) - idéal pour les tableaux 1D de valeurs compatibles avec les types primitifs.
• getStringArray(...) - pour Array(String) (et les valeurs d’enum représentées par leur nom).
• getObjectArray(...) - option générique pour tout type d’élément de Array(...), y compris les tableaux imbriqués. À utiliser pour lire des tableaux contenant des valeurs Nullable et des tableaux imbriqués.

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(...) - lit n’importe quel Array(...) en tant que List<T>. Bon choix par défaut pour une lecture à typage flexible. Prend en charge les tableaux imbriqués.
• getByteArray(...), getShortArray(...), getIntArray(...), getLongArray(...), getFloatArray(...), getDoubleArray(...), getBooleanArray(...) - idéal pour les tableaux 1D de valeurs compatibles avec les types primitifs.
• getStringArray(...) - pour Array(String) (et les valeurs d’enum représentées par leur nom).
• getObjectArray(...) - option générique pour tout type d’élément de Array(...), y compris les tableaux imbriqués. À utiliser pour lire des tableaux contenant des valeurs NULL et des tableaux imbriqués.

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

​

Guide de migration

• aucun service loader n’est utilisé pour charger l’implémentation. Le com.clickhouse.client.api.Client sert de classe façade pour toutes sortes d’implémentations à l’avenir.
• moins de sources de configuration : l’une est fournie au builder et l’autre via les paramètres d’opération (QuerySettings, InsertSettings). La version précédente avait une configuration par nœud et chargeait les variables d’environnement dans certains cas.

​

Correspondance des paramètres de configuration

• com.clickhouse.client.config.ClickHouseDefaults - paramètres de configuration à définir dans la plupart des cas d’utilisation, comme USER et PASSWORD.
• com.clickhouse.client.config.ClickHouseClientOption - paramètres de configuration spécifiques au client, comme HEALTH_CHECK_INTERVAL.
• com.clickhouse.client.http.config.ClickHouseHttpOption - paramètres de configuration spécifiques à l’interface HTTP, comme RECEIVE_QUERY_PROGRESS.

​

Différences générales

• Client V2 utilise moins de classes propriétaires afin d’améliorer la portabilité. Par exemple, V2 fonctionne avec n’importe quelle implémentation de java.io.InputStream pour envoyer des données à un serveur.
• Le paramètre async de Client V2 est off par défaut. Cela signifie qu’il n’y a pas de thread supplémentaire et que l’application garde davantage de contrôle sur le client. Ce paramètre doit être off dans la majorité des cas d’utilisation. L’activation de async crée un thread distinct pour chaque requête. Cela n’a de sens que si vous utilisez un executor contrôlé par l’application (voir com.clickhouse.client.api.Client.Builder#setSharedOperationExecutor)

​

Écriture des données

• utilisez n’importe quelle implémentation de java.io.InputStream. La V1 com.clickhouse.data.ClickHouseInputStream est prise en charge, mais n’est PAS recommandée.
• une fois la fin du flux d’entrée détectée, elle est traitée comme telle. Auparavant, il fallait fermer le flux de sortie d’une requête.

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
}

• il n’y a qu’une seule méthode à appeler. Il n’est pas nécessaire de créer un objet de corps de requête supplémentaire.
• le flux du corps de la requête est fermé automatiquement une fois toutes les données copiées.
• une nouvelle API de bas niveau est 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 conçu pour implémenter une logique d’écriture de données personnalisée. Par exemple, pour lire des données depuis une file d’attente.

​

Lecture des données

• Les données sont lues au format RowBinaryWithNamesAndTypes par défaut. À l’heure actuelle, seul ce format est pris en charge lorsqu’une liaison de données est nécessaire.
• Les données peuvent être lues sous forme de collection d’enregistrements à l’aide de la méthode List<GenericRecord> com.clickhouse.client.api.Client#queryAll(java.lang.String). Cette méthode lit les données en mémoire puis libère la connexion. Aucune gestion supplémentaire n’est nécessaire. GenericRecord donne accès aux données et prend en charge certaines conversions.

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