Bibliothèque client Java permettant de communiquer avec un serveur de base de données via ses protocoles. L’implémentation actuelle ne prend en charge que l’[interface HTTP](/fr/concepts/features/interfaces/http). La bibliothèque fournit sa propre API pour envoyer des requêtes à un serveur, ainsi que des outils pour travailler avec différents formats de données binaires (RowBinary\* & Native\*). Configuration * Maven Central (page du projet) : [https://mvnrepository.com/artifact/com.clickhouse/client-v2](https://mvnrepository.com/artifact/com.clickhouse/client-v2) * Builds nocturnes (lien vers le dépôt) : [https://central.sonatype.com/repository/maven-snapshots/](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/](https://s01.oss.sonatype.org/content/repositories/snapshots/)
```xml theme={null} com.clickhouse client-v2 0.9.8 ``` ```kotlin theme={null} // https://mvnrepository.com/artifact/com.clickhouse/client-v2 implementation("com.clickhouse:client-v2:0.9.8") ``` ```groovy theme={null} // https://mvnrepository.com/artifact/com.clickhouse/client-v2 implementation 'com.clickhouse:client-v2:0.9.8' ```
Initialisation L’objet Client est initialisé par `com.clickhouse.client.api.Client.Builder#build()`. Chaque client possède son propre contexte et aucun objet n’est partagé entre eux. Le Builder dispose de méthodes de configuration pour en simplifier la mise en œuvre. Exemple : ```java showLineNumbers theme={null} Client client = new Client.Builder() .addEndpoint("https://clickhouse-cloud-instance:8443/") .setUsername(user) .setPassword(password) .build(); ``` `Client` est `AutoCloseable` et doit être fermé lorsqu’il n’est plus nécessaire. Authentification L’authentification est configurée par client lors de la phase d’initialisation. Trois méthodes d’authentification sont prises en charge : par mot de passe, par jeton d’accès ou par certificat client SSL. L’authentification par mot de passe nécessite de renseigner le nom d’utilisateur et le mot de passe en appelant `setUsername(String)` et `setPassword(String)` : ```java showLineNumbers theme={null} Client client = new Client.Builder() .addEndpoint("https://clickhouse-cloud-instance:8443/") .setUsername(user) .setPassword(password) .build(); ``` L’authentification par jeton d’accès nécessite de configurer le jeton d’accès en appelant `setAccessToken(String)` : ```java showLineNumbers theme={null} Client client = new Client.Builder() .addEndpoint("https://clickhouse-cloud-instance:8443/") .setAccessToken(userAccessToken) .build(); ``` L’authentification par certificat client SSL nécessite de définir le nom d’utilisateur, d’activer l’authentification SSL, de configurer un certificat client et une clé client en appelant respectivement `setUsername(String)`, `useSSLAuthentication(boolean)`, `setClientCertificate(String)` et `setClientKey(String)` : ```java showLineNumbers theme={null} Client client = new Client.Builder() .useSSLAuthentication(true) .setUsername("some_user") .setClientCertificate("some_user.crt") .setClientKey("some_user.key") ``` L’authentification SSL peut être difficile à dépanner en production, car de nombreuses erreurs provenant des bibliothèques SSL ne fournissent pas assez d’informations. Par exemple, si le certificat client et la clé ne correspondent pas, le serveur interrompra immédiatement la connexion (dans le cas de HTTP, cela se produira à l’étape d’établissement de la connexion, lorsqu’aucune requête HTTP n’est envoyée, donc aucune réponse n’est renvoyée). Veuillez utiliser des outils comme [openssl](https://docs.openssl.org/master/man1/openssl/) pour vérifier les certificats et les clés : * vérifier l’intégrité de la clé : `openssl rsa -in [key-file.key] -check -noout` * vérifier que le certificat client a un CN correspondant pour un utilisateur : * obtenir le CN à partir d’un certificat utilisateur - `openssl x509 -noout -subject -in [user.cert]` * vérifier que la même valeur est définie dans la base de données `select name, auth_type, auth_params from system.users where auth_type = 'ssl_certificate'` (la requête affichera `auth_params` avec quelque chose comme ` {"common_names":["some_user"]}`) Configuration Tous les paramètres sont définis par des méthodes d’instance (aussi appelées méthodes de configuration) qui rendent explicites la portée et le contexte de chaque valeur. Les principaux paramètres de configuration sont définis dans une seule portée (client ou opération) et ne se substituent pas mutuellement. La configuration est définie lors de la création du client. Voir `com.clickhouse.client.api.Client.Builder`. Configuration du client | Méthode | Arguments | Description | Par défaut | Clé | | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------- | --------------------------- | | `addEndpoint(String endpoint)` | `endpoint` - adresse du serveur au format URL | Ajoute un endpoint à la liste des serveurs disponibles. Actuellement, un seul endpoint est pris en charge. | `none` | `none` | | `addEndpoint(Protocol protocol, String host, int port, boolean secure)` | `protocol` - protocole de connexion
`host` - IP ou nom d’hôte
`secure` - utiliser HTTPS | Ajoute un endpoint à la liste des serveurs disponibles. Actuellement, un seul endpoint est pris en charge. | `none` | `none` | | `enableConnectionPool(boolean enable)` | `enable` - indicateur pour activer/désactiver | Définit si un pool de connexions est activé | `true` | `connection_pool_enabled` | | `setMaxConnections(int maxConnections)` | `maxConnections` - nombre de connexions | Définit le nombre de connexions qu’un client peut ouvrir vers chaque endpoint de serveur. | `10` | `max_open_connections` | | `setConnectionTTL(long timeout, ChronoUnit unit)` | `timeout` - valeur du délai d’expiration
`unit` - unité de temps | Définit le TTL de la connexion, au-delà duquel elle est considérée comme inactive | `-1` | `connection_ttl` | | `setKeepAliveTimeout(long timeout, ChronoUnit unit)` | `timeout` - valeur du délai d’expiration
`unit` - unité de temps | Définit le délai d’expiration Keep-Alive de la connexion HTTP. Définissez `0` pour désactiver Keep-Alive. | - | `http_keep_alive_timeout` | | `setConnectionReuseStrategy(ConnectionReuseStrategy strategy)` | `strategy` - `LIFO` ou `FIFO` | Sélectionne la stratégie à utiliser pour le pool de connexions | `FIFO` | `connection_reuse_strategy` | | `setDefaultDatabase(String database)` | `database` - nom d’une base de données | Définit la base de données par défaut. | `default` | `database` | | Méthode | Arguments | Description | Par défaut | Clé | | ---------------------------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | --------------------- | | `setUsername(String username)` | `username` - nom d’utilisateur pour l’authentification | Définit le nom d’utilisateur pour une méthode d’authentification sélectionnée par une configuration ultérieure | `default` | `user` | | `setPassword(String password)` | `password` - valeur secrète | Définit un secret pour l’authentification par mot de passe et sélectionne effectivement cette méthode d’authentification | - | `password` | | `setAccessToken(String accessToken)` | `accessToken` - chaîne du jeton d’accès | Définit un jeton d’accès pour s’authentifier avec la méthode d’authentification correspondante | - | `access_token` | | `useSSLAuthentication(boolean useSSLAuthentication)` | `useSSLAuthentication` - indicateur pour activer l’authentification SSL | Définit le certificat client SSL comme méthode d’authentification | - | `ssl_authentication` | | `useHTTPBasicAuth(boolean useBasicAuth)` | `useBasicAuth` - indicateur pour activer/désactiver | Définit si l’authentification HTTP Basic doit être utilisée pour l’authentification par nom d’utilisateur et mot de passe. Résout les problèmes liés aux mots de passe contenant des caractères spéciaux. | `true` | `http_use_basic_auth` | | `useBearerTokenAuth(String bearerToken)` | `bearerToken` - jeton Bearer encodé | Indique s’il faut utiliser l’authentification Bearer et quel jeton employer. Le jeton sera envoyé tel quel. | - | `bearer_token` | | Méthode | Arguments | Description | Par défaut | Clé | | ------------------------------------------------------------ | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ---------------------------- | | `setConnectTimeout(long timeout, ChronoUnit unit)` | `timeout` - valeur du délai d’attente
`unit` - unité de temps | Définit le délai d’établissement pour toute connexion sortante. | - | `connection_timeout` | | `setConnectionRequestTimeout(long timeout, ChronoUnit unit)` | `timeout` - valeur du délai d’attente
`unit` - unité de temps | Définit le délai d’attente pour demander une connexion. Cela s’applique uniquement lors de l’obtention d’une connexion depuis un pool. | `10000` | `connection_request_timeout` | | `setSocketTimeout(long timeout, ChronoUnit unit)` | `timeout` - valeur du délai d’attente
`unit` - unité de temps | Définit le délai d’attente du socket, qui s’applique aux opérations de lecture et d’écriture | `0` | `socket_timeout` | | `setExecutionTimeout(long timeout, ChronoUnit timeUnit)` | `timeout` - valeur du délai d’attente
`timeUnit` - unité de temps | Définit le temps d’exécution maximal des requêtes | `0` | `max_execution_time` | | `retryOnFailures(ClientFaultCause ...causes)` | `causes` - constante d’énumération de `ClientFaultCause` | Définit les types de défaillances récupérables pouvant faire l’objet d’une nouvelle tentative. | `NoHttpResponse` `ConnectTimeout` `ConnectionRequestTimeout` | `client_retry_on_failures` | | `setMaxRetries(int maxRetries)` | `maxRetries` - nombre de nouvelles tentatives | Définit le nombre maximal de nouvelles tentatives pour les échecs définis par `retryOnFailures` | `3` | `retry` | | Méthode | Arguments | Description | Par défaut | Clé | | ------------------------------------ | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | -------------------- | | `setSocketRcvbuf(long size)` | `size` - taille en octets | Définit le tampon de réception du socket TCP. Ce tampon se situe en dehors de la mémoire de la JVM. | `8196` | `socket_rcvbuf` | | `setSocketSndbuf(long size)` | `size` - taille en octets | Définit le tampon d’envoi du socket TCP. Ce tampon se situe en dehors de la mémoire de la JVM. | `8196` | `socket_sndbuf` | | `setSocketKeepAlive(boolean value)` | `value` - indicateur d’activation/désactivation | Définit l’option `SO_KEEPALIVE` pour chaque socket TCP. Le mécanisme TCP Keep Alive permet de vérifier que la connexion est toujours active. | - | `socket_keepalive` | | `setSocketTcpNodelay(boolean value)` | `value` - indicateur d’activation/désactivation | Définit l’option `SO_NODELAY` pour chaque socket TCP. Cette option TCP force le socket à envoyer les données dès que possible. | - | `socket_tcp_nodelay` | | `setSocketLinger(int secondsToWait)` | `secondsToWait` - nombre de secondes | Définit le délai d’attente de fermeture pour chaque socket TCP créé par le client. | - | `socket_linger` | | Méthode | Arguments | Description | Par défaut | Clé | | ----------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------------------------------------------ | | `compressServerResponse(boolean enabled)` | `enabled` - indicateur pour activer/désactiver | Définit si le serveur doit compresser ses réponses. | `true` | `compress` | | `compressClientRequest(boolean enabled)` | `enabled` - indicateur pour activer/désactiver | Définit si le client doit compresser ses requêtes. | `false` | `decompress` | | `useHttpCompression(boolean enabled)` | `enabled` - indicateur pour activer/désactiver | Définit si la compression HTTP doit être utilisée pour les communications entre le client et le serveur si les options correspondantes sont activées | - | - | | `appCompressedData(boolean enabled)` | `enabled` - indicateur pour activer/désactiver | Indique au client que la compression sera gérée par l’application. | `false` | `app_compressed_data` | | `setLZ4UncompressedBufferSize(int size)` | `size` - taille en octets | Définit la taille d’un tampon qui recevra la partie non compressée d’un flux de données. | `65536` | `compression.lz4.uncompressed_buffer_size` | | `disableNativeCompression` | `disable` - indicateur pour désactiver | Désactive la compression native. Si défini sur `true`, la compression native sera désactivée. | `false` | `disable_native_compression` | | Méthode | Arguments | Description | Par défaut | Clé | | ------------------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------- | -------------------- | | `setSSLTrustStore(String path)` | `path` - chemin de fichier sur le système local | Indique si le client doit utiliser le truststore SSL pour valider l’hôte du serveur. | - | `trust_store` | | `setSSLTrustStorePassword(String password)` | `password` - valeur secrète | Définit le mot de passe à utiliser pour déverrouiller le truststore SSL spécifié par `setSSLTrustStore` | - | `key_store_password` | | `setSSLTrustStoreType(String type)` | `type` - nom du type de truststore | Définit le type du truststore spécifié par `setSSLTrustStore`. | - | `key_store_type` | | `setRootCertificate(String path)` | `path` - chemin de fichier sur le système local | Indique si le client doit utiliser le certificat racine (CA) spécifié pour valider l’hôte du serveur. | - | `sslrootcert` | | `setClientCertificate(String path)` | `path` - chemin de fichier sur le système local | Définit le chemin du certificat client à utiliser lors de l’établissement d’une connexion SSL et pour l’authentification SSL. | - | `sslcert` | | `setClientKey(String path)` | `path` - chemin de fichier sur le système local | Définit la clé privée du client à utiliser pour chiffrer la communication SSL avec un serveur. | - | `ssl_key` | | `sslSocketSNI(String sni)` | `sni` - chaîne contenant le nom du serveur | Définit le nom du serveur à utiliser pour le SNI (Server Name Indication) dans une connexion SSL/TLS. | - | `ssl_socket_sni` | | Méthode | Arguments | Description | Par défaut | Clé | | ------------------------------------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | ---------- | ---------------------------------------- | | `addProxy(ProxyType type, String host, int port)` | `type` - type de proxy
`host` - nom d’hôte ou IP du proxy
`port` - port du proxy | Définit le proxy à utiliser pour communiquer avec un serveur. | - | `proxy_type`, `proxy_host`, `proxy_port` | | `setProxyCredentials(String user, String pass)` | `user` - nom d’utilisateur du proxy
`pass` - mot de passe | Définit les identifiants utilisateur à utiliser pour s’authentifier auprès d’un proxy. | - | `proxy_user`, `proxy_password` | | Méthode | Arguments | Description | Par défaut | Clé | | ------------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ---------------------------------------- | | `setHttpCookiesEnabled(boolean enabled)` | `enabled` - indicateur d’activation/désactivation | Indique si les cookies HTTP doivent être mémorisés puis renvoyés au serveur. | - | - | | `httpHeader(String key, String value)` | `key` - clé d’en-tête HTTP
`value` - valeur de chaîne | Définit la valeur d’un en-tête HTTP unique. La valeur précédente est remplacée. | `none` | `none` | | `httpHeader(String key, Collection values)` | `key` - clé d’en-tête HTTP
`values` - liste de valeurs de chaîne | Définit les valeurs d’un en-tête HTTP unique. La valeur précédente est remplacée. | `none` | `none` | | `httpHeaders(Map headers)` | `headers` - map contenant les en-têtes HTTP | Définit plusieurs valeurs d’en-tête HTTP à la fois. | `none` | `none` | | `useHttpFormDataForQuery(boolean enable)` | `enable` - indicateur d’activation/désactivation | Indique si les paramètres de requête doivent être envoyés sous forme de données de formulaire HTTP dans le corps de la requête plutôt que dans l’URL. Fonctionne uniquement avec la compression côté serveur. Si la compression côté client est activée, elle sera désactivée pour les requêtes avec paramètres, car chaque paramètre est envoyé en contenu multipart. | `false` | `client.http.use_form_request_for_query` | | Méthode | Arguments | Description | Par défaut | Clé | | ----------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------------------------ | | `serverSetting(String name, String value)` | `name` - nom du paramètre
`value` - valeur du paramètre | Définit les paramètres à transmettre au serveur avec chaque requête. Les paramètres spécifiques à chaque opération peuvent les remplacer. [Liste des paramètres](/fr/concepts/features/configuration/settings/settings-query-level) | `none` | `none` | | `serverSetting(String name, Collection values)` | `name` - nom du paramètre
`values` - valeurs du paramètre | Définit les paramètres à transmettre au serveur avec plusieurs valeurs, par exemple les [rôles](/fr/concepts/features/interfaces/http#setting-role-with-query-parameters) | `none` | `none` | | `setOption("custom_settings_prefix", value)` | `value` - chaîne de préfixe | Définit le préfixe des paramètres personnalisés transmis au serveur. Il doit être cohérent avec la configuration du serveur. Voir [ClickHouse Docs](/fr/concepts/features/configuration/settings/settings-query-level#custom_settings). | `custom_` | `custom_settings_prefix` | | Méthode | Arguments | Description | Par défaut | Clé | | ---------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | ---------------------- | | `useServerTimeZone(boolean useServerTimeZone)` | `useServerTimeZone` - indicateur pour activer/désactiver | Détermine si le client doit utiliser le fuseau horaire du serveur lors du décodage des valeurs des colonnes DateTime et Date. | `true` | `use_server_time_zone` | | `useTimeZone(String timeZone)` | `timeZone` - identifiant de fuseau horaire Java valide | Détermine si le fuseau horaire spécifié doit être utilisé lors du décodage des valeurs des colonnes DateTime et Date. Remplace le fuseau horaire du serveur. | - | `use_time_zone` | | `setServerTimeZone(String timeZone)` | `timeZone` - identifiant de fuseau horaire Java valide | Définit le fuseau horaire côté serveur. Le fuseau horaire UTC est utilisé par défaut. | `UTC` | `server_time_zone` | | Méthode | Arguments | Description | Par défaut | Clé | | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ---------------------------- | | `setOption(String key, String value)` | `key` - clé d’option de configuration
`value` - valeur de l’option | Définit la valeur brute des options du client. Utile lors de la lecture de la configuration à partir de fichiers de propriétés. | - | - | | `useAsyncRequests(boolean async)` | `async` - indicateur d’activation/désactivation | Définit si le client doit exécuter la requête dans un thread distinct. Désactivé par défaut, car l’application sait mieux comment organiser les tâches multithread. | `false` | `async` | | `setSharedOperationExecutor(ExecutorService executorService)` | `executorService` - instance d’ExecutorService | Définit l’ExecutorService pour les tâches d’opération. | `none` | `none` | | `setQueryIdGenerator(Supplier supplier)` | `supplier` - un `Supplier` qui génère des ID de requête | Définit un générateur d’ID de requête personnalisé utilisé lorsqu’aucun ID de requête n’est spécifié dans les paramètres d’opération (`InsertSettings`, `QuerySettings`). | - | - | | `setClientNetworkBufferSize(int size)` | `size` - taille en octets | Définit la taille d’un tampon dans l’espace mémoire de l’application, utilisé pour copier les données entre le socket et l’application. | `300000` | `client_network_buffer_size` | | `allowBinaryReaderToReuseBuffers(boolean reuse)` | `reuse` - indicateur d’activation/désactivation | Si cette option est activée, le lecteur utilisera des tampons préalloués pour transcoder les nombres. Réduit la pression sur le GC pour les données numériques. | - | - | | `columnToMethodMatchingStrategy(ColumnToMethodMatchingStrategy strategy)` | `strategy` - implémentation de la stratégie de correspondance | Définit une stratégie personnalisée pour faire correspondre les champs de classe DTO et les colonnes de la DB lors de l’enregistrement du DTO. | `none` | `none` | | `setClientName(String clientName)` | `clientName` - chaîne contenant le nom de l’application | Définit des informations supplémentaires sur l’application appelante. Elles seront transmises dans l’en-tête `User-Agent`. | - | `client_name` | | `registerClientMetrics(Object registry, String name)` | `registry` - instance de registre Micrometer
`name` - nom du groupe de métriques | Enregistre des capteurs auprès d’une instance de registre Micrometer ([https://micrometer.io/](https://micrometer.io/)). | - | - | | `setServerVersion(String version)` | `version` - chaîne de version du serveur | Définit la version du serveur pour éviter la détection de version. | - | `server_version` | | `typeHintMapping(Map typeHintMapping)` | `typeHintMapping` - map des type hints | Définit la correspondance des type hints pour les types ClickHouse. Par exemple, pour que les arrays multidimensionnels soient représentés comme des conteneurs Java. | - | `type_hint_mapping` |
Identification du client Le journal de requêtes contient deux champs permettant d’identifier l’application à l’origine d’une requête : `client_name` et `http_user_agent`. Le protocole TCP natif utilise `client_name` pour identifier l’application. Le protocole HTTP utilise `http_user_agent` pour identifier l’application. Le builder client dispose de la méthode `setClientName` pour définir les valeurs correctes pour les deux protocoles. Le champ `http_user_agent` est défini selon le format standard de l’en-tête `User-Agent` : `application-name[/version] [(operating-system; architecture; ...)]`. Cet ensemble de valeurs est répété pour chaque couche : application, bibliothèque client, bibliothèque client HTTP. Ce qui est défini par la méthode `setClientName` apparaît en premier dans la liste. Par exemple : ```java showLineNumbers theme={null} client.setClientName("my-app-01/1.0"); ``` donnera la valeur `http_user_agent` suivante : ``` my-app-01/1.0 clickhouse-java-v2/0.9.6-SNAPSHOT (Linux; jvm:17.0.17) Apache-HttpClient/5.4.4 ``` L’application peut définir son propre en-tête HTTP `User-Agent` pour s’identifier. Toutefois, la partie `clickhouse-java-v2/0.9.6-SNAPSHOT` sera ajoutée à la fin de l’en-tête. Identification des opérations Le journal de requêtes dispose de deux autres champs `query_id` et `log_comment` qui peuvent être utilisés pour identifier une opération et ajouter des informations supplémentaires au journal de requêtes. `query_id` est un identifiant unique d’une opération. Il peut être défini par l’application en appelant la méthode `setQueryId` de la classe `QuerySettings`. ```java showLineNumbers theme={null} QuerySettings querySettings = new QuerySettings(); querySettings.setQueryId("some-query-id"); ``` `log_comment` est un commentaire pouvant être ajouté au journal des requêtes. Il peut être défini par l’application en appelant la méthode `logComment` de la classe `QuerySettings`. ```java showLineNumbers theme={null} QuerySettings querySettings = new QuerySettings(); querySettings.logComment("some-comment"); ``` Paramètres du serveur Les paramètres côté serveur peuvent être définis au niveau du client une seule fois lors de sa création (voir la méthode `serverSetting` du `Builder`) et au niveau de l’opération (voir `serverSetting` pour la classe de paramètres d’opération). ```java showLineNumbers theme={null} 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"); ... } ``` ⚠️ Lorsque des options sont définies via la méthode `setOption` (que ce soit via `Client.Builder` ou la classe de paramètres d’opération), le nom des paramètres serveur doit être préfixé de `clickhouse_setting_`. La méthode `com.clickhouse.client.api.ClientConfigProperties#serverSetting()` peut s’avérer utile dans ce cas. En-tête HTTP personnalisé Des en-têtes HTTP personnalisés peuvent être définis pour toutes les opérations (au niveau du client) ou pour une seule (au niveau de l’opération). ```java showLineNumbers theme={null} QuerySettings settings = new QuerySettings() .httpHeader(HttpHeaders.REFERER, clientReferer) .setQueryId(qId); ``` Lorsque les options sont définies via la méthode `setOption` (que ce soit via `Client.Builder` ou la classe de paramètres d’opération), le nom du header personnalisé doit être préfixé de `http_header_`. La méthode `com.clickhouse.client.api.ClientConfigProperties#httpHeader()` peut s’avérer utile dans ce cas. Définitions courantes ClickHouseFormat Enum des [formats pris en charge](/fr/reference/formats/index). Il inclut tous les formats supportés par ClickHouse. * `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 Cette version du client prend en charge : | Format | Entrée | Sortie | | ------------------------------------------------------------------------------------------------------------------- | :----: | :----: | | [TabSeparated](/fr/reference/formats/TabSeparated/TabSeparated) | brut | brut | | [TabSeparatedRaw](/fr/reference/formats/TabSeparated/TabSeparatedRaw) | brut | brut | | [TabSeparatedWithNames](/fr/reference/formats/TabSeparated/TabSeparatedWithNames) | brut | brut | | [TabSeparatedWithNamesAndTypes](/fr/reference/formats/TabSeparated/TabSeparatedWithNamesAndTypes) | brut | brut | | [TabSeparatedRawWithNames](/fr/reference/formats/TabSeparated/TabSeparatedRawWithNames) | brut | brut | | [TabSeparatedRawWithNamesAndTypes](/fr/reference/formats/TabSeparated/TabSeparatedRawWithNamesAndTypes) | brut | brut | | [Template](/fr/reference/formats/Template/Template) | brut | brut | | [TemplateIgnoreSpaces](/fr/reference/formats/Template/TemplateIgnoreSpaces) | brut | - | | [CSV](/fr/reference/formats/CSV/CSV) | brut | brut | | [CSVWithNames](/fr/reference/formats/CSV/CSVWithNames) | brut | brut | | [CSVWithNamesAndTypes](/fr/reference/formats/CSV/CSVWithNamesAndTypes) | brut | brut | | [CustomSeparated](/fr/reference/formats/CustomSeparated/CustomSeparated) | brut | brut | | [CustomSeparatedWithNames](/fr/reference/formats/CustomSeparated/CustomSeparatedWithNames) | brut | brut | | [CustomSeparatedWithNamesAndTypes](/fr/reference/formats/CustomSeparated/CustomSeparatedWithNamesAndTypes) | brut | brut | | [SQLInsert](/fr/reference/formats/SQLInsert) | - | brut | | [Values](/fr/reference/formats/Values) | brut | brut | | [Vertical](/fr/reference/formats/Vertical) | - | brut | | [JSON](/fr/reference/formats/JSON/JSON) | brut | brut | | [JSONAsString](/fr/reference/formats/JSON/JSONAsString) | brut | - | | [JSONAsObject](/fr/reference/formats/JSON/JSONAsObject) | brut | - | | [JSONStrings](/fr/reference/formats/JSON/JSONStrings) | brut | brut | | [JSONColumns](/fr/reference/formats/JSON/JSONColumns) | brut | brut | | [JSONColumnsWithMetadata](/fr/reference/formats/JSON/JSONColumnsWithMetadata) | brut | brut | | [JSONCompact](/fr/reference/formats/JSON/JSONCompact) | brut | brut | | [JSONCompactStrings](/fr/reference/formats/JSON/JSONCompactStrings) | - | brut | | [JSONCompactColumns](/fr/reference/formats/JSON/JSONCompactColumns) | brut | brut | | [JSONEachRow](/fr/reference/formats/JSON/JSONEachRow) | brut | brut | | [PrettyJSONEachRow](/fr/reference/formats/JSON/PrettyJSONEachRow) | - | brut | | [JSONEachRowWithProgress](/fr/reference/formats/JSON/JSONEachRowWithProgress) | - | brut | | [JSONStringsEachRow](/fr/reference/formats/JSON/JSONStringsEachRow) | brut | brut | | [JSONStringsEachRowWithProgress](/fr/reference/formats/JSON/JSONStringsEachRowWithProgress) | - | raw | | [JSONCompactEachRow](/fr/reference/formats/JSON/JSONCompactEachRow) | raw | raw | | [JSONCompactEachRowWithNames](/fr/reference/formats/JSON/JSONCompactEachRowWithNames) | raw | raw | | [JSONCompactEachRowWithNamesAndTypes](/fr/reference/formats/JSON/JSONCompactEachRowWithNamesAndTypes) | raw | raw | | [JSONCompactStringsEachRow](/fr/reference/formats/JSON/JSONCompactStringsEachRow) | raw | raw | | [JSONCompactStringsEachRowWithNames](/fr/reference/formats/JSON/JSONCompactStringsEachRowWithNames) | raw | raw | | [JSONCompactStringsEachRowWithNamesAndTypes](/fr/reference/formats/JSON/JSONCompactStringsEachRowWithNamesAndTypes) | raw | raw | | [JSONObjectEachRow](/fr/reference/formats/JSON/JSONObjectEachRow) | raw | raw | | [BSONEachRow](/fr/reference/formats/BSONEachRow) | raw | raw | | [TSKV](/fr/reference/formats/TabSeparated/TSKV) | raw | raw | | [Pretty](/fr/reference/formats/Pretty/Pretty) | - | raw | | [PrettyNoEscapes](/fr/reference/formats/Pretty/PrettyNoEscapes) | - | raw | | [PrettyMonoBlock](/fr/reference/formats/Pretty/PrettyMonoBlock) | - | raw | | [PrettyNoEscapesMonoBlock](/fr/reference/formats/Pretty/PrettyNoEscapesMonoBlock) | - | raw | | [PrettyCompact](/fr/reference/formats/Pretty/PrettyCompact) | - | raw | | [PrettyCompactNoEscapes](/fr/reference/formats/Pretty/PrettyCompactNoEscapes) | - | raw | | [PrettyCompactMonoBlock](/fr/reference/formats/Pretty/PrettyCompactMonoBlock) | - | raw | | [PrettyCompactNoEscapesMonoBlock](/fr/reference/formats/Pretty/PrettyCompactNoEscapesMonoBlock) | - | raw | | [PrettySpace](/fr/reference/formats/Pretty/PrettySpace) | - | raw | | [PrettySpaceNoEscapes](/fr/reference/formats/Pretty/PrettySpaceNoEscapes) | - | raw | | [PrettySpaceMonoBlock](/fr/reference/formats/Pretty/PrettySpaceMonoBlock) | - | raw | | [PrettySpaceNoEscapesMonoBlock](/fr/reference/formats/Pretty/PrettySpaceNoEscapesMonoBlock) | - | raw | | [Prometheus](/fr/reference/formats/Prometheus) | - | raw | | [Protobuf](/fr/reference/formats/Protobuf/Protobuf) | raw | raw | | [ProtobufSingle](/fr/reference/formats/Protobuf/ProtobufSingle) | raw | raw | | [ProtobufList](/fr/reference/formats/Protobuf/ProtobufList) | raw | raw | | [Avro](/fr/reference/formats/Avro/Avro) | raw | raw | | [AvroConfluent](/fr/reference/formats/Avro/AvroConfluent) | raw | - | | [Parquet](/fr/reference/formats/Parquet/Parquet) | raw | raw | | [ParquetMetadata](/fr/reference/formats/Parquet/ParquetMetadata) | raw | - | | [Arrow](/fr/reference/formats/Arrow/Arrow) | raw | raw | | [ArrowStream](/fr/reference/formats/Arrow/ArrowStream) | raw | raw | | [ORC](/fr/reference/formats/ORC) | raw | raw | | [One](/fr/reference/formats/One) | raw | - | | [Npy](/fr/reference/formats/Npy) | raw | raw | | [RowBinary](/fr/reference/formats/RowBinary/RowBinary) | full | full | | [RowBinaryWithNames](/fr/reference/formats/RowBinary/RowBinaryWithNamesAndTypes) | full | full | | [RowBinaryWithNamesAndTypes](/fr/reference/formats/RowBinary/RowBinaryWithNamesAndTypes) | full | full | | [RowBinaryWithDefaults](/fr/reference/formats/RowBinary/RowBinaryWithDefaults) | full | - | | [Native](/fr/reference/formats/Native) | full | raw | | [Null](/fr/reference/formats/Null) | - | raw | | [XML](/fr/reference/formats/XML) | - | raw | | [CapnProto](/fr/reference/formats/CapnProto) | raw | raw | | [LineAsString](/fr/reference/formats/LineAsString/LineAsString) | raw | raw | | [Regexp](/fr/reference/formats/Regexp) | raw | - | | [RawBLOB](/fr/reference/formats/RawBLOB) | raw | raw | | [MsgPack](/fr/reference/formats/MsgPack) | raw | raw | | [MySQLDump](/fr/reference/formats/MySQLDump) | raw | - | | [DWARF](/fr/reference/formats/DWARF) | raw | - | | [Markdown](/fr/reference/formats/Markdown) | - | raw | | [Form](/fr/reference/formats/Form) | raw | - | API d’insertion insert(String tableName, InputStream data, ClickHouseFormat format) Accepte des données sous forme d’`InputStream` d’octets dans le format spécifié. `data` doit être encodé dans le `format`. **Signatures** ```java theme={null} CompletableFuture insert(String tableName, InputStream data, ClickHouseFormat format, InsertSettings settings) CompletableFuture insert(String tableName, InputStream data, ClickHouseFormat format) ``` **Paramètres** `tableName` - un nom de table cible. `data` - un flux d’entrée de données encodées. `format` - le format dans lequel les données sont encodées. `settings` - paramètres de la requête. **Valeur de retour** Future du type `InsertResponse` — résultat de l’opération et informations supplémentaires telles que les métriques côté serveur. **Exemples** ```java showLineNumbers theme={null} 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) Envoie une requête d’écriture vers la base de données. La liste des objets est convertie dans un format efficace, puis envoyée au serveur. La classe des éléments de la liste doit être enregistrée au préalable à l’aide de la méthode `register(Class, TableSchema)`. **Signatures** ```java theme={null} client.insert(String tableName, List data, InsertSettings settings) client.insert(String tableName, List data) ``` **Paramètres** `tableName` - nom de la table cible. `data` - objets DTO (Data Transfer Object) de la collection. `settings` - paramètres de la requête. **Valeur de retour** Future du type `InsertResponse` — le résultat de l’opération et des informations supplémentaires telles que les métriques côté serveur. **Exemples** ```java showLineNumbers theme={null} // 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 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 Options de configuration pour les opérations d’insertion. **Méthodes de configuration** | Méthode | Description | | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `setQueryId(String queryId)` | Définit l’ID de la requête qui sera attribué à l’opération. Par défaut : `null`. | | `setDeduplicationToken(String token)` | Définit le jeton de déduplication. Ce jeton est envoyé au serveur et peut être utilisé pour identifier la requête. Par défaut : `null`. | | `setInputStreamCopyBufferSize(int size)` | Taille du tampon de copie. Le tampon est utilisé lors des opérations d’écriture pour copier les données d’un flux d’entrée fourni par l’utilisateur vers un flux de sortie. Par défaut : `8196`. | | `serverSetting(String name, String value)` | Définit individuellement les paramètres du serveur pour une opération. | | `serverSetting(String name, Collection values)` | Définit des paramètres serveur individuels avec plusieurs valeurs pour une opération. Les éléments de la collection doivent être des valeurs `String`. | | `setDBRoles(Collection dbRoles)` | Définit les rôles DB à définir avant l’exécution d’une opération. Les éléments de la collection doivent être des valeurs `String`. | | `setOption(String option, Object value)` | Définit une option de configuration au format brut. Il ne s’agit pas d’un paramètre du serveur. | InsertResponse Objet de réponse contenant le résultat de l’opération d’insertion. Il n’est disponible que si le client a reçu une réponse du serveur. Cet objet doit être fermé dès que possible pour libérer la connexion, car celle-ci ne peut pas être réutilisée tant que toutes les données de la réponse précédente n’ont pas été entièrement lues. | Méthode | Description | | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `OperationMetrics getMetrics()` | Renvoie un objet contenant les métriques de l’opération. | | `String getQueryId()` | Renvoie l’ID de requête attribué à l’opération par l’application (via les paramètres de l’opération) ou par le serveur. | API de requête query(String sqlQuery) Envoie `sqlQuery` tel quel. Le format de réponse est défini par les paramètres de la requête. `QueryResponse` contiendra une référence au flux de réponse qui doit être consommé par un lecteur pour le format pris en charge. **Signatures** ```java theme={null} CompletableFuture query(String sqlQuery, QuerySettings settings) CompletableFuture query(String sqlQuery) ``` **Paramètres** `sqlQuery` - une instruction SQL unique. La requête est envoyée telle quelle au serveur. `settings` - paramètres de la requête. **Valeur de retour** Future du type `QueryResponse` — un jeu de données résultant ainsi que des informations supplémentaires telles que les métriques côté serveur. L’objet Response doit être fermé après consommation du jeu de données. **Exemples** ```java theme={null} 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 queryParams, QuerySettings settings) Envoie `sqlQuery` tel quel. Envoie également les paramètres de requête afin que le serveur puisse compiler l’expression SQL. **Signatures** ```java theme={null} CompletableFuture query(String sqlQuery, Map queryParams, QuerySettings settings) ``` **Paramètres** `sqlQuery` - expression SQL avec des espaces réservés `{}`. `queryParams` - map de variables permettant de compléter l’expression SQL sur le serveur. `settings` - paramètres de la requête. **Valeur de retour** Future du type `QueryResponse` — un jeu de données résultant ainsi que des informations supplémentaires telles que les métriques côté serveur. L’objet Response doit être fermé après consommation du jeu de données. **Exemples** ```java showLineNumbers theme={null} // define parameters. They will be sent to the server along with the request. Map 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) Interroge des données au format `RowBinaryWithNamesAndTypes`. Renvoie le résultat sous forme de collection. Les performances de lecture sont identiques à celles du lecteur, mais davantage de mémoire est nécessaire pour conserver l’intégralité du jeu de données. **Signatures** ```java theme={null} List queryAll(String sqlQuery) ``` **Paramètres** `sqlQuery` - expression SQL pour interroger des données depuis un serveur. **Valeur de retour** Jeu de données complet représenté par une liste d’objets `GenericRecord` offrant un accès ligne par ligne aux données de résultat. **Exemples** ```java showLineNumbers theme={null} 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 Options de configuration pour les opérations de requête. **Méthodes de configuration** | Méthode | Description | | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `setQueryId(String queryId)` | Définit l’ID de requête qui sera attribué à l’opération. | | `setFormat(ClickHouseFormat format)` | Définit le format de la réponse. Voir `RowBinaryWithNamesAndTypes` pour la liste complète. | | `setMaxExecutionTime(Integer maxExecutionTime)` | Définit le temps d’exécution de l’opération sur le serveur. N’affecte pas le délai d’expiration de lecture. | | `waitEndOfQuery(Boolean waitEndOfQuery)` | Demande au serveur d’attendre la fin de la requête avant d’envoyer une réponse. | | `setUseServerTimeZone(Boolean useServerTimeZone)` | Le fuseau horaire du serveur (voir la config du client) sera utilisé pour interpréter les types date/heure dans le résultat d’une opération. Par défaut : `false`. | | `setUseTimeZone(String timeZone)` | Demande au serveur d’utiliser `timeZone` pour la conversion de l’heure. Voir [session\_timezone](/fr/reference/settings/session-settings#session_timezone). | | `serverSetting(String name, String value)` | Définit des paramètres serveur spécifiques pour une opération. | | `serverSetting(String name, Collection values)` | Définit un paramètre du serveur avec plusieurs valeurs pour une opération. Les éléments de la collection doivent être des valeurs `String`. | | `setDBRoles(Collection dbRoles)` | Définit les rôles DB à appliquer avant d’exécuter une opération. Les éléments de la collection doivent être des valeurs `String`. | | `setOption(String option, Object value)` | Définit une option de configuration au format brut. Il ne s’agit pas d’un paramètre serveur. | QueryResponse Objet de réponse contenant le résultat de l’exécution de la requête. Il n’est disponible que si le client a reçu une réponse du serveur. Cet objet doit être fermé dès que possible afin de libérer la connexion, car celle-ci ne peut pas être réutilisée tant que toutes les données de la réponse précédente n’ont pas été lues intégralement. | Méthode | Description | | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `ClickHouseFormat getFormat()` | Renvoie un format dans lequel les données de la réponse sont encodées. | | `InputStream getInputStream()` | Renvoie un flux d’octets non compressé de données au format spécifié. | | `OperationMetrics getMetrics()` | Renvoie un objet contenant les métriques de l’opération. | | `String getQueryId()` | Renvoie l’ID de requête attribué à l’opération par l’application (via les paramètres de l’opération ou par le serveur). | | `TimeZone getTimeZone()` | Renvoie le fuseau horaire à utiliser pour traiter les types Date/DateTime dans la réponse. | Exemples * Le code d’exemple est disponible dans le [dépôt](https://github.com/ClickHouse/clickhouse-java/tree/main/examples/client-v2) * [Implémentation de référence](https://github.com/ClickHouse/clickhouse-java/tree/main/examples/demo-service) du service Spring API commune getTableSchema(String table) Récupère le schéma de la table `table`. **Signatures** ```java theme={null} TableSchema getTableSchema(String table) TableSchema getTableSchema(String table, String database) ``` **Paramètres** `table` - nom de la table pour laquelle les données de schéma doivent être récupérées. `database` - base de données dans laquelle la table cible est définie. **Valeur de retour** Renvoie un objet `TableSchema` contenant la liste des colonnes de la table. getTableSchemaFromQuery(String sql) Récupère le schéma à partir d’une instruction SQL. **Signatures** ```java theme={null} TableSchema getTableSchemaFromQuery(String sql) ``` **Paramètres** `sql` - Instruction SQL “SELECT” dont le schéma doit être renvoyé. **Valeur de retour** Renvoie un objet `TableSchema` dont les colonnes correspondent à l’expression `sql`. TableSchema register(Class clazz, TableSchema schema) Compile la couche de sérialisation et de désérialisation pour la classe Java à utiliser pour l’écriture et la lecture de données avec `schema`. La méthode crée un sérialiseur et un désérialiseur pour la paire getter/setter et la colonne correspondante. La correspondance de colonne est déterminée en extrayant son nom à partir du nom de la méthode. Par exemple, `getFirstName` correspondra à la colonne `first_name` ou `firstname`. **Signatures** ```java theme={null} void register(Class clazz, TableSchema schema) ``` **Paramètres** `clazz` - Classe représentant le POJO utilisé pour lire/écrire des données. `schema` - Schéma de données à utiliser pour la mise en correspondance avec les propriétés POJO. **Exemples** ```java showLineNumbers theme={null} client.register(ArticleViewEvent.class, client.getTableSchema(TABLE_NAME)); ``` Exemples d’utilisation Le code des exemples complets est stocké dans un [dossier](https://github.com/ClickHouse/clickhouse-java/tree/main/examples) ‘example\` du dépôt : * [client-v2](https://github.com/ClickHouse/clickhouse-java/tree/main/examples/client-v2) - principal ensemble d’exemples. * [demo-service](https://github.com/ClickHouse/clickhouse-java/tree/main/examples/demo-service) - exemple d’utilisation du client dans une application Spring Boot. * [demo-kotlin-service](https://github.com/ClickHouse/clickhouse-java/tree/main/examples/demo-kotlin-service) - exemple d’utilisation du client dans une application Ktor (Kotlin). Lecture des données Il existe deux façons courantes de lire les 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. **Note :** l’approche en streaming nécessite une lecture rapide, faute de quoi elle peut provoquer un timeout d’écriture sur le serveur, car les données sont lues directement depuis le flux réseau. Lecture des Arrays **Méthodes de `ClickHouseBinaryFormatReader`** * `getList(...)` - lit n’importe quel `Array(...)` comme `List`. 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. Des surcharges par index et par nom sont disponibles pour toutes les méthodes. L’index est basé sur 1. Les surcharges par index accèdent directement à une colonne. Les méthodes par nom nécessitent une recherche par index à chaque appel. ```java theme={null} 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]; } } ``` **Méthodes de `GenericRecord`** * `getList(...)` - lit n’importe quel `Array(...)` en tant que `List`. 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. Des surcharges par index et par nom sont disponibles pour toutes les méthodes. L’index est basé sur 1. Les surcharges par index accèdent directement à une colonne. Les méthodes par nom nécessitent une recherche par index à chaque appel. ```java theme={null} try (QueryResponse response = client.query("SELECT * FROM my_table").get()) { List 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 L’ancien client (V1) utilisait `com.clickhouse.client.ClickHouseClient#builder` comme point de départ. Le nouveau client (V2) suit un pattern similaire avec `com.clickhouse.client.api.Client.Builder`. Les principales différences sont : * 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 Il existe 3 classes enum liées à la configuration dans V1 : * `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`. Ils ont été conçus pour regrouper les paramètres et assurer une séparation claire. Cependant, dans certains cas, cela a pu prêter à confusion (y a-t-il une différence entre `com.clickhouse.client.config.ClickHouseDefaults#ASYNC` et `com.clickhouse.client.config.ClickHouseClientOption#ASYNC` ?). Le nouveau client V2 utilise `com.clickhouse.client.api.Client.Builder` comme dictionnaire unique de toutes les options de configuration possibles du client. La classe `com.clickhouse.client.api.ClientConfigProperties` recense tous les noms de paramètres de configuration. Le tableau ci-dessous indique quelles options de l’ancienne version sont prises en charge par le nouveau client et leur nouvelle signification. **Légende :** ✔ = pris en charge, ✗ = supprimé | Configuration V1 | Méthode Builder V2 | Commentaires | | -------------------------------------------------------------------------------- | ------------------------------------------- | ------------------------------------ | | `ClickHouseDefaults#HOST` | `Client.Builder#addEndpoint` | | | `ClickHouseDefaults#PROTOCOL` | ✗ | Seul HTTP est pris en charge avec V2 | | `ClickHouseDefaults#DATABASE`
`ClickHouseClientOption#DATABASE` | `Client.Builder#setDefaultDatabase` | | | `ClickHouseDefaults#USER` | `Client.Builder#setUsername` | | | `ClickHouseDefaults#PASSWORD` | `Client.Builder#setPassword` | | | `ClickHouseClientOption#CONNECTION_TIMEOUT` | `Client.Builder#setConnectTimeout` | | | `ClickHouseClientOption#CONNECTION_TTL` | `Client.Builder#setConnectionTTL` | | | `ClickHouseHttpOption#MAX_OPEN_CONNECTIONS` | `Client.Builder#setMaxConnections` | | | `ClickHouseHttpOption#KEEP_ALIVE`
`ClickHouseHttpOption#KEEP_ALIVE_TIMEOUT` | `Client.Builder#setKeepAliveTimeout` | | | `ClickHouseHttpOption#CONNECTION_REUSE_STRATEGY` | `Client.Builder#setConnectionReuseStrategy` | | | `ClickHouseHttpOption#USE_BASIC_AUTHENTICATION` | `Client.Builder#useHTTPBasicAuth` | | | Configuration V1 | Méthode Builder V2 | Commentaires | | ------------------------------------------------------ | ----------------------------------------- | ------------------------------------------------------------------- | | `ClickHouseDefaults#SSL_CERTIFICATE_TYPE` | ✗ | | | `ClickHouseDefaults#SSL_KEY_ALGORITHM` | ✗ | | | `ClickHouseDefaults#SSL_PROTOCOL` | ✗ | | | `ClickHouseClientOption#SSL` | ✗ | Voir `Client.Builder#addEndpoint` | | `ClickHouseClientOption#SSL_MODE` | ✗ | | | `ClickHouseClientOption#SSL_ROOT_CERTIFICATE` | `Client.Builder#setRootCertificate` | L’authentification SSL doit être activée via `useSSLAuthentication` | | `ClickHouseClientOption#SSL_CERTIFICATE` | `Client.Builder#setClientCertificate` | | | `ClickHouseClientOption#SSL_KEY` | `Client.Builder#setClientKey` | | | `ClickHouseClientOption#KEY_STORE_TYPE` | `Client.Builder#setSSLTrustStoreType` | | | `ClickHouseClientOption#TRUST_STORE` | `Client.Builder#setSSLTrustStore` | | | `ClickHouseClientOption#KEY_STORE_PASSWORD` | `Client.Builder#setSSLTrustStorePassword` | | | `ClickHouseClientOption#SSL_SOCKET_SNI` | `Client.Builder#sslSocketSNI` | | | `ClickHouseClientOption#CUSTOM_SOCKET_FACTORY` | ✗ | | | `ClickHouseClientOption#CUSTOM_SOCKET_FACTORY_OPTIONS` | ✗ | Voir `Client.Builder#sslSocketSNI` pour définir le SNI | | Configuration V1 | Méthode du builder V2 | Commentaires | | ------------------------------------------- | -------------------------------------- | ------------ | | `ClickHouseClientOption#SOCKET_TIMEOUT` | `Client.Builder#setSocketTimeout` | | | `ClickHouseClientOption#SOCKET_REUSEADDR` | `Client.Builder#setSocketReuseAddress` | | | `ClickHouseClientOption#SOCKET_KEEPALIVE` | `Client.Builder#setSocketKeepAlive` | | | `ClickHouseClientOption#SOCKET_LINGER` | `Client.Builder#setSocketLinger` | | | `ClickHouseClientOption#SOCKET_IP_TOS` | ✗ | | | `ClickHouseClientOption#SOCKET_TCP_NODELAY` | `Client.Builder#setSocketTcpNodelay` | | | `ClickHouseClientOption#SOCKET_RCVBUF` | `Client.Builder#setSocketRcvbuf` | | | `ClickHouseClientOption#SOCKET_SNDBUF` | `Client.Builder#setSocketSndbuf` | | | Configuration V1 | Méthode du builder | Commentaires | | --------------------------------------------- | --------------------------------------- | -------------------------------------------------------------------------- | | `ClickHouseClientOption#COMPRESS` | `Client.Builder#compressServerResponse` | Voir aussi `useHttpCompression` | | `ClickHouseClientOption#DECOMPRESS` | `Client.Builder#compressClientRequest` | Voir aussi `useHttpCompression` | | `ClickHouseClientOption#COMPRESS_ALGORITHM` | ✗ | `LZ4` pour les protocoles autres que HTTP. HTTP utilise `Accept-Encoding` | | `ClickHouseClientOption#DECOMPRESS_ALGORITHM` | ✗ | `LZ4` pour les protocoles autres que HTTP. HTTP utilise `Content-Encoding` | | `ClickHouseClientOption#COMPRESS_LEVEL` | ✗ | | | `ClickHouseClientOption#DECOMPRESS_LEVEL` | ✗ | | | Configuration V1 | Méthode du builder V2 | Commentaires | | --------------------------------------- | ------------------------------------ | ------------ | | `ClickHouseClientOption#PROXY_TYPE` | `Client.Builder#addProxy` | | | `ClickHouseClientOption#PROXY_HOST` | `Client.Builder#addProxy` | | | `ClickHouseClientOption#PROXY_PORT` | `Client.Builder#addProxy` | | | `ClickHouseClientOption#PROXY_USERNAME` | `Client.Builder#setProxyCredentials` | | | `ClickHouseClientOption#PROXY_PASSWORD` | `Client.Builder#setProxyCredentials` | | | Configuration V1 | Méthode Builder | Commentaires | | ----------------------------------------------- | ------------------------------------ | ---------------------------- | | `ClickHouseClientOption#MAX_EXECUTION_TIME` | `Client.Builder#setExecutionTimeout` | | | `ClickHouseClientOption#RETRY` | `Client.Builder#setMaxRetries` | Voir aussi `retryOnFailures` | | `ClickHouseHttpOption#AHC_RETRY_ON_FAILURE` | `Client.Builder#retryOnFailures` | | | `ClickHouseClientOption#FAILOVER` | ✗ | | | `ClickHouseClientOption#REPEAT_ON_SESSION_LOCK` | ✗ | | | `ClickHouseClientOption#SESSION_ID` | ✗ | | | `ClickHouseClientOption#SESSION_CHECK` | ✗ | | | `ClickHouseClientOption#SESSION_TIMEOUT` | ✗ | | | Configuration V1 | Méthode du builder | Commentaires | | ------------------------------------------------------------------------------------ | ---------------------------------- | ------------ | | `ClickHouseDefaults#SERVER_TIME_ZONE`
`ClickHouseClientOption#SERVER_TIME_ZONE` | `Client.Builder#setServerTimeZone` | | | `ClickHouseClientOption#USE_SERVER_TIME_ZONE` | `Client.Builder#useServerTimeZone` | | | `ClickHouseClientOption#USE_SERVER_TIME_ZONE_FOR_DATES` | | | | `ClickHouseClientOption#USE_TIME_ZONE` | `Client.Builder#useTimeZone` | | | Configuration V1 | Méthode du builder V2 | Commentaires | | ----------------------------------------------- | ------------------------------------------- | ------------ | | `ClickHouseClientOption#BUFFER_SIZE` | `Client.Builder#setClientNetworkBufferSize` | | | `ClickHouseClientOption#BUFFER_QUEUE_VARIATION` | ✗ | | | `ClickHouseClientOption#READ_BUFFER_SIZE` | ✗ | | | `ClickHouseClientOption#WRITE_BUFFER_SIZE` | ✗ | | | `ClickHouseClientOption#REQUEST_CHUNK_SIZE` | ✗ | | | `ClickHouseClientOption#REQUEST_BUFFERING` | ✗ | | | `ClickHouseClientOption#RESPONSE_BUFFERING` | ✗ | | | `ClickHouseClientOption#MAX_BUFFER_SIZE` | ✗ | | | `ClickHouseClientOption#MAX_QUEUED_BUFFERS` | ✗ | | | `ClickHouseClientOption#MAX_QUEUED_REQUESTS` | ✗ | | | `ClickHouseClientOption#REUSE_VALUE_WRAPPER` | ✗ | | | Configuration V1 | Méthode du Builder V2 | Commentaires | | -------------------------------------------------------------- | --------------------------------- | --------------------------------- | | `ClickHouseDefaults#ASYNC`
`ClickHouseClientOption#ASYNC` | `Client.Builder#useAsyncRequests` | | | `ClickHouseDefaults#MAX_SCHEDULER_THREADS` | ✗ | voir `setSharedOperationExecutor` | | `ClickHouseDefaults#MAX_THREADS` | ✗ | voir `setSharedOperationExecutor` | | `ClickHouseDefaults#THREAD_KEEPALIVE_TIMEOUT` | voir `setSharedOperationExecutor` | | | `ClickHouseClientOption#MAX_THREADS_PER_CLIENT` | ✗ | | | `ClickHouseClientOption#MAX_CORE_THREAD_TTL` | ✗ | | | Configuration V1 | Méthode builder V2 | Commentaires | | ---------------------------------------------------- | ------------------------------ | ---------------------------------------------------------- | | `ClickHouseHttpOption#CUSTOM_HEADERS` | `Client.Builder#httpHeaders` | | | `ClickHouseHttpOption#CUSTOM_PARAMS` | ✗ | Voir `Client.Builder#serverSetting` | | `ClickHouseClientOption#CLIENT_NAME` | `Client.Builder#setClientName` | | | `ClickHouseHttpOption#CONNECTION_PROVIDER` | ✗ | | | `ClickHouseHttpOption#DEFAULT_RESPONSE` | ✗ | | | `ClickHouseHttpOption#SEND_HTTP_CLIENT_ID` | ✗ | | | `ClickHouseHttpOption#AHC_VALIDATE_AFTER_INACTIVITY` | ✗ | Toujours activé lors de l’utilisation d’Apache Http Client | | Configuration V1 | Méthode de builder V2 | Commentaires | | ---------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------- | | `ClickHouseDefaults#FORMAT`
`ClickHouseClientOption#FORMAT` | ✗ | Déplacé vers les paramètres d’opération (`QuerySettings` et `InsertSettings`) | | `ClickHouseClientOption#QUERY_ID` | ✗ | Voir `QuerySettings` et `InsertSettings` | | `ClickHouseClientOption#LOG_LEADING_COMMENT` | ✗ | Voir `QuerySettings#logComment` et `InsertSettings#logComment` | | `ClickHouseClientOption#MAX_RESULT_ROWS` | ✗ | Paramètre côté serveur | | `ClickHouseClientOption#RESULT_OVERFLOW_MODE` | ✗ | Paramètre côté serveur | | `ClickHouseHttpOption#RECEIVE_QUERY_PROGRESS` | ✗ | Paramètre côté serveur | | `ClickHouseHttpOption#WAIT_END_OF_QUERY` | ✗ | Paramètre côté serveur | | `ClickHouseHttpOption#REMEMBER_LAST_SET_ROLES` | `Client#setDBRoles` | Désormais une configuration d’exécution. Voir aussi `QuerySettings#setDBRoles` et `InsertSettings#setDBRoles` | | Configuration V1 | Méthode du builder V2 | Commentaires | | ------------------------------------------------ | --------------------- | ------------ | | `ClickHouseClientOption#AUTO_DISCOVERY` | ✗ | | | `ClickHouseClientOption#LOAD_BALANCING_POLICY` | ✗ | | | `ClickHouseClientOption#LOAD_BALANCING_TAGS` | ✗ | | | `ClickHouseClientOption#HEALTH_CHECK_INTERVAL` | ✗ | | | `ClickHouseClientOption#HEALTH_CHECK_METHOD` | ✗ | | | `ClickHouseClientOption#NODE_DISCOVERY_INTERVAL` | ✗ | | | `ClickHouseClientOption#NODE_DISCOVERY_LIMIT` | ✗ | | | `ClickHouseClientOption#NODE_CHECK_INTERVAL` | ✗ | | | `ClickHouseClientOption#NODE_GROUP_SIZE` | ✗ | | | `ClickHouseClientOption#CHECK_ALL_NODES` | ✗ | | | Configuration V1 | Méthode Builder V2 | Commentaires | | -------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------ | | `ClickHouseDefaults#AUTO_SESSION` | ✗ | La prise en charge des sessions sera revue | | `ClickHouseDefaults#BUFFERING` | ✗ | | | `ClickHouseDefaults#MAX_REQUESTS` | ✗ | | | `ClickHouseDefaults#ROUNDING_MODE` | | | | `ClickHouseDefaults#SERVER_VERSION`
`ClickHouseClientOption#SERVER_VERSION` | `Client.Builder#setServerVersion` | | | `ClickHouseDefaults#SRV_RESOLVE` | ✗ | | | `ClickHouseClientOption#CUSTOM_SETTINGS` | | | | `ClickHouseClientOption#PRODUCT_NAME` | ✗ | Utiliser le nom du client | | `ClickHouseClientOption#RENAME_RESPONSE_COLUMN` | ✗ | | | `ClickHouseClientOption#SERVER_REVISION` | ✗ | | | `ClickHouseClientOption#TRANSACTION_TIMEOUT` | ✗ | | | `ClickHouseClientOption#WIDEN_UNSIGNED_TYPES` | ✗ | | | `ClickHouseClientOption#USE_BINARY_STRING` | ✗ | | | `ClickHouseClientOption#USE_BLOCKING_QUEUE` | ✗ | | | `ClickHouseClientOption#USE_COMPILATION` | ✗ | | | `ClickHouseClientOption#USE_OBJECTS_IN_ARRAYS` | ✗ | | | `ClickHouseClientOption#MAX_MAPPER_CACHE` | ✗ | | | `ClickHouseClientOption#MEASURE_REQUEST_TIME` | ✗ | | 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. **V1 Insérer des données au format TSV.** ```java theme={null} InputStream inData = getInData(); ClickHouseRequest.Mutation request = client.read(server) .write() .table(tableName) .format(ClickHouseFormat.TSV); ClickHouseConfig config = request.getConfig(); CompletableFuture 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 Insertion de données au format TSV.** ```java theme={null} 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, 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 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. ```java theme={null} Collection 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"); } ```