Le client JS officiel pour se connecter à ClickHouse.
Le client est écrit en TypeScript et fournit le typage de son API publique.
Sans aucune dépendance, il est optimisé pour des performances maximales et testé avec différentes versions et configurations de ClickHouse (nœud unique on-premise, cluster on-premise et ClickHouse Cloud).
Deux versions distinctes du client sont disponibles selon l’environnement :
@clickhouse/client - Node.js uniquement@clickhouse/client-web - navigateurs (Chrome/Firefox), Cloudflare workers
Si vous utilisez TypeScript, assurez-vous d’utiliser au minimum la version 4.5, qui active la syntaxe d’import et d’export inline.
Le code source du client est disponible dans le repository GitHub ClickHouse-JS.
Skills pour AI AgentLe client JS est fourni avec des Skills pour AI Agent qui peuvent aider les agents de développement à utiliser le client. Installez-les avec :npm skills add ClickHouse/clickhouse-js
Prérequis de l’environnement (node.js)
| Version de Node.js | Prise en charge ? |
|---|
| 24.x | ✔ |
| 22.x | ✔ |
| 20.x | ✔ |
| 18.x | Dans la mesure du possible |
Prérequis de l’environnement (web)
npm i @clickhouse/client-web
Compatibilité avec ClickHouse
| Version du client | ClickHouse |
|---|
| 1.12.0 | 24.8+ |
Création d’une instance de client
createClient :
import { createClient } from '@clickhouse/client' // or '@clickhouse/client-web'
const client = createClient({
/* configuration */
})
const { createClient } = require('@clickhouse/client');
const client = createClient({
/* configuration */
})
| Setting | Description | Default Value | See Also | |
|---|
| url?: string | URL d’une instance ClickHouse. | http://localhost:8123 | Documentation sur la configuration de l’URL | |
| pathname?: string | Chemin optionnel à ajouter à l’URL ClickHouse après son analyse par le client. | '' | Documentation sur l’utilisation d’un proxy avec un chemin | |
| request_timeout?: number | Délai d’expiration de la requête, en millisecondes. | 30_000 | - | |
compression?: { **response**?: boolean; **request**?: boolean } | Active la compression. | - | Documentation sur la compression | |
| username?: string | Nom de l’utilisateur au nom duquel les requêtes sont effectuées. | default | - | |
| password?: string | Mot de passe de l’utilisateur. | '' | - | |
| application?: string | Nom de l’application qui utilise le client Node.js. | clickhouse-js | - | |
| database?: string | Nom de la base de données à utiliser. | default | - | |
| clickhouse_settings?: ClickHouseSettings | Paramètres ClickHouse à appliquer à toutes les requêtes. | {} | - | |
log?: { **LoggerClass**?: Logger, **level**?: ClickHouseLogLevel } | Configuration des logs internes du client. | - | Documentation sur le logging | |
| session_id?: string | ID de session ClickHouse facultatif à envoyer avec chaque requête. | - | - | |
keep_alive?: { **enabled**?: boolean } | Activé par défaut dans les versions Node.js et web. | - | - | |
http_headers?: Record<string, string> | En-têtes HTTP supplémentaires pour les requêtes ClickHouse sortantes. | - | Documentation sur le reverse proxy avec authentification | |
| roles?: string | string[] | Noms des rôles ClickHouse à associer aux requêtes sortantes. | - | Utilisation des rôles avec l’interface HTTP |
Paramètres de configuration spécifiques à Node.js
| Paramètre | Description | Valeur par défaut | Voir aussi | |
|---|
| max_open_connections?: number | Nombre maximal de sockets connectés autorisés par hôte. | 10 | - | |
tls?: { **ca_cert**: Buffer, **cert**?: Buffer, **key**?: Buffer } | Configurer les certificats TLS. | - | Documentation TLS | |
keep_alive?: { **enabled**?: boolean, **idle_socket_ttl**?: number } | - | - | Documentation Keep Alive | |
| http_agent?: http.Agent | https.Agent
| Agent HTTP personnalisé pour le client. | - | Documentation sur l’agent HTTP |
set_basic_auth_header?: boolean
| Ajoute l’en-tête Authorization avec des identifiants d’authentification Basic. | true | utilisation de ce paramètre dans la documentation sur l’agent HTTP | |
La configuration de l’URL écrasera toujours les valeurs codées en dur, et un avertissement sera alors consigné.
http[s]://[username:password@]hostname:port[/database][?param1=value1¶m2=value2]. Dans presque tous les cas, le nom d’un paramètre donné reflète son chemin dans l’interface des options de configuration, à quelques exceptions près. Les paramètres suivants sont pris en charge :
| Paramètre | Type |
|---|
pathname | une chaîne arbitraire. |
application_id | une chaîne arbitraire. |
session_id | une chaîne arbitraire. |
request_timeout | nombre non négatif. |
max_open_connections | nombre non négatif, supérieur à zéro. |
compression_request | booléen. Voir ci-dessous (1) |
compression_response | booléen. |
log_level | valeurs autorisées : OFF, TRACE, DEBUG, INFO, WARN, ERROR. |
keep_alive_enabled | booléen. |
clickhouse_setting_* ou ch_* | voir ci-dessous (2) |
http_header_* | voir ci-dessous (3) |
(Node.js uniquement) keep_alive_idle_socket_ttl | nombre non négatif. |
- (1) Pour les booléens, les valeurs valides sont
true/1 et false/0.
- (2) Tout paramètre préfixé par
clickhouse_setting_ ou ch_ verra ce préfixe supprimé, et le reste sera ajouté aux clickhouse_settings du client. Par exemple, ?ch_async_insert=1&ch_wait_for_async_insert=1 sera identique à :
createClient({
clickhouse_settings: {
async_insert: 1,
wait_for_async_insert: 1,
},
})
clickhouse_settings doivent être transmises sous la forme 1/0 dans l’URL.
- (3) Comme pour (2), mais pour la configuration
http_header. Par exemple, ?http_header_x-clickhouse-auth=foobar sera équivalent à :
createClient({
http_headers: {
'x-clickhouse-auth': 'foobar',
},
})
| Paramètre(s) | Description |
|---|
HOST and PORT | En général, le port est 8443 lors de l’utilisation de TLS, ou 8123 sans TLS. |
DATABASE NAME | Par défaut, une base de données nommée default est disponible ; utilisez le nom de la base de données à laquelle vous voulez vous connecter. |
USERNAME and PASSWORD | Par défaut, le nom d’utilisateur est default. Utilisez le nom d’utilisateur adapté à votre cas d’usage. |
curl.
Si vous utilisez ClickHouse autogéré, les détails de connexion sont définis par votre administrateur ClickHouse.
Vue d’ensemble de la connexion
url (y compris
le protocole et le port) et password sont définies via des variables d’environnement, et que l’utilisateur default est utilisé.
Exemple : création d’une instance de client Node.js à l’aide de variables d’environnement pour la configuration.
import { createClient } from '@clickhouse/client'
const client = createClient({
url: process.env.CLICKHOUSE_HOST ?? 'http://localhost:8123',
username: process.env.CLICKHOUSE_USER ?? 'default',
password: process.env.CLICKHOUSE_PASSWORD ?? '',
})
Pool de connexions (Node.js uniquement)
10, mais vous pouvez la modifier à l’aide de l’option de configuration max_open_connections.
Rien ne garantit que la même connexion du pool sera utilisée pour les requêtes suivantes, sauf si l’utilisateur définit max_open_connections: 1. Cela est rarement nécessaire, mais peut être requis lorsque des utilisateurs emploient des tables temporaires.
Voir aussi : configuration Keep-Alive.
Chaque méthode qui envoie une requête ou une instruction (command, exec, insert, select) renvoie query_id dans le résultat. Cet identifiant unique est attribué par le client à chaque requête et peut être utile pour récupérer les données dans system.query_log,
s’il est activé dans la configuration du serveur, ou pour annuler des requêtes longues (voir l’exemple). Si nécessaire, query_id peut être redéfini par l’utilisateur dans les paramètres des méthodes command/query/exec/insert.
Si vous redéfinissez le paramètre query_id, vous devez garantir son unicité pour chaque appel. Un UUID aléatoire est un bon choix.
Paramètres de base pour toutes les méthodes du client
interface BaseQueryParams {
// ClickHouse settings that can be applied on query level.
clickhouse_settings?: ClickHouseSettings
// Parameters for query binding.
query_params?: Record<string, unknown>
// AbortSignal instance to cancel a query in progress.
abort_signal?: AbortSignal
// query_id override; if not specified, a random identifier will be generated automatically.
query_id?: string
// session_id override; if not specified, the session id will be taken from the client configuration.
session_id?: string
// credentials override; if not specified, the client's credentials will be used.
auth?: { username: string, password: string }
// A specific list of roles to use for this query. Overrides the roles set in the client configuration.
role?: string | Array<string>
}
SELECT, ou pour envoyer des DDLs comme CREATE TABLE, et doit donc être attendue. Le jeu de résultats renvoyé est destiné à être exploité dans l’application.
Il existe une méthode dédiée insert pour l’insertion de données, et command pour les DDLs. interface QueryParams extends BaseQueryParams {
// Query to execute that might return some data.
query: string
// Format of the resulting dataset. Default: JSON.
format?: DataFormat
}
interface ClickHouseClient {
query(params: QueryParams): Promise<ResultSet>
}
N’indiquez pas la clause FORMAT dans query ; utilisez plutôt le paramètre format.
Abstractions du jeu de résultats et des lignes
ResultSet fournit plusieurs méthodes pratiques pour traiter les données dans votre application.
L’implémentation Node.js de ResultSet utilise Stream.Readable en interne, tandis que la version web utilise l’API Web ReadableStream.
Vous pouvez consommer le ResultSet en appelant les méthodes text ou json sur ResultSet, puis charger en mémoire l’ensemble des lignes renvoyées par la requête.
Vous devriez commencer à consommer le ResultSet dès que possible, car il maintient le flux de réponse ouvert et garde par conséquent la connexion sous-jacente occupée. Le client ne met pas les données entrantes en mémoire tampon afin d’éviter une utilisation potentiellement excessive de la mémoire par l’application.
Sinon, si l’ensemble est trop volumineux pour tenir entièrement en mémoire, vous pouvez appeler la méthode stream et traiter les données en mode streaming. Chaque chunk de la réponse sera alors transformé en tableaux de lignes relativement petits (la taille de ce tableau dépend de la taille du chunk reçu par le client depuis le server, qui peut varier, ainsi que de la taille de chaque ligne), un chunk à la fois.
Veuillez consulter la liste des formats de données pris en charge afin de déterminer le format le mieux adapté au streaming dans votre cas. Par exemple, si vous souhaitez diffuser des objets JSON en streaming, vous pouvez choisir JSONEachRow, et chaque ligne sera analysée comme un objet JS, ou éventuellement le format plus compact JSONCompactColumns, qui fera de chaque ligne un tableau compact de valeurs. Voir aussi : streaming de fichiers.
Si le ResultSet ou son flux n’est pas entièrement consommé, il sera détruit après la période d’inactivité request_timeout.
interface BaseResultSet<Stream> {
// See "Query ID" section above
query_id: string
// Consume the entire stream and get the contents as a string
// Can be used with any DataFormat
// Should be called only once
text(): Promise<string>
// Consume the entire stream and parse the contents as a JS object
// Can be used only with JSON formats
// Should be called only once
json<T>(): Promise<T>
// Returns a readable stream for responses that can be streamed
// Every iteration over the stream provides an array of Row[] in the selected DataFormat
// Should be called only once
stream(): Stream
}
interface Row {
// Get the content of the row as a plain string
text: string
// Parse the content of the row as a JS object
json<T>(): T
}
JSONEachRow, qui consomme l’intégralité du flux et interprète le contenu comme des objets JS.
Code source.
const resultSet = await client.query({
query: 'SELECT * FROM my_table',
format: 'JSONEachRow',
})
const dataset = await resultSet.json() // or `row.text` to avoid parsing JSON
JSONEachRow avec l’approche classique on('data'). Cette approche est interchangeable avec la syntaxe for await const. Code source.
const rows = await client.query({
query: 'SELECT number FROM system.numbers_mt LIMIT 5',
format: 'JSONEachRow', // or JSONCompactEachRow, JSONStringsEachRow, etc.
})
const stream = rows.stream()
stream.on('data', (rows: Row[]) => {
rows.forEach((row: Row) => {
console.log(row.json()) // or `row.text` to avoid parsing JSON
})
})
await new Promise((resolve, reject) => {
stream.on('end', () => {
console.log('Completed!')
resolve(0)
})
stream.on('error', reject)
})
CSV avec l’approche classique on('data'). Cette approche peut être utilisée à la place de la syntaxe for await const.
Code source
const resultSet = await client.query({
query: 'SELECT number FROM system.numbers_mt LIMIT 5',
format: 'CSV', // or TabSeparated, CustomSeparated, etc.
})
const stream = resultSet.stream()
stream.on('data', (rows: Row[]) => {
rows.forEach((row: Row) => {
console.log(row.text)
})
})
await new Promise((resolve, reject) => {
stream.on('end', () => {
console.log('Completed!')
resolve(0)
})
stream.on('error', reject)
})
JSONEachRow, consommé avec la syntaxe for await const. Cette approche peut être utilisée à la place de l’approche classique on('data').
Code source.
const resultSet = await client.query({
query: 'SELECT number FROM system.numbers LIMIT 10',
format: 'JSONEachRow', // or JSONCompactEachRow, JSONStringsEachRow, etc.
})
for await (const rows of resultSet.stream()) {
rows.forEach(row => {
console.log(row.json())
})
}
La syntaxe for await const demande un peu moins de code que l’approche on('data'), mais elle peut avoir un impact négatif sur les performances.
Pour plus de détails, consultez cette issue dans le dépôt Node.js. ReadableStream d’objets.
const resultSet = await client.query({
query: 'SELECT * FROM system.numbers LIMIT 10',
format: 'JSONEachRow'
})
const reader = resultSet.stream().getReader()
while (true) {
const { done, value: rows } = await reader.read()
if (done) { break }
rows.forEach(row => {
console.log(row.json())
})
}
export interface InsertResult {
query_id: string
executed: boolean
}
interface ClickHouseClient {
insert(params: InsertParams): Promise<InsertResult>
}
{ query_id: '...', executed: false }. Si, dans ce cas, le query_id n’a pas été fourni dans les paramètres de la méthode, il sera une chaîne vide dans le résultat, car renvoyer un UUID aléatoire généré par le client pourrait prêter à confusion, puisque la requête portant ce query_id n’existera pas dans la table system.query_log.
Si l’instruction insert a été envoyée au serveur, l’indicateur executed sera true.
Méthode insert et streaming dans Node.js
Stream.Readable, soit avec un simple Array<T>, selon le format de données spécifié pour la méthode insert. Voir aussi cette section sur le streaming de fichiers.
La méthode insert est destinée à être utilisée avec await ; il est toutefois possible de fournir un flux d’entrée et de n’attendre l’opération insert que plus tard, une fois le flux terminé (ce qui résoudra également la promesse insert). Cela peut s’avérer utile pour des écouteurs d’événements et des cas similaires, mais la gestion des erreurs peut être délicate, avec de nombreux cas limites côté client. À la place, envisagez d’utiliser les async inserts, comme illustré dans cet exemple.
interface InsertParams<T> extends BaseQueryParams {
// Table name to insert the data into
table: string
// A dataset to insert.
values: ReadonlyArray<T> | Stream.Readable
// Format of the dataset to insert.
format?: DataFormat
// Allows to specify which columns the data will be inserted into.
// - An array such as `['a', 'b']` will generate: `INSERT INTO table (a, b) FORMAT DataFormat`
// - An object such as `{ except: ['a', 'b'] }` will generate: `INSERT INTO table (* EXCEPT (a, b)) FORMAT DataFormat`
// By default, the data is inserted into all columns of the table,
// and the generated statement will be: `INSERT INTO table FORMAT DataFormat`.
columns?: NonEmptyArray<string> | { except: NonEmptyArray<string> }
}
Une requête annulée avec abort_signal ne garantit pas qu’aucune insertion de données n’a eu lieu, car le serveur a pu recevoir une partie des données envoyées en streaming avant l’annulation.
await client.insert({
table: 'my_table',
// structure should match the desired format, JSONEachRow in this example
values: [
{ id: 42, name: 'foo' },
{ id: 42, name: 'bar' },
],
format: 'JSONEachRow',
})
await client.insert({
table: 'my_table',
values: fs.createReadStream('./path/to/a/file.csv'),
format: 'CSV',
})
CREATE OR REPLACE TABLE mytable
(id UInt32, message String)
ENGINE MergeTree()
ORDER BY (id)
// Generated statement: INSERT INTO mytable (message) FORMAT JSONEachRow
await client.insert({
table: 'mytable',
values: [{ message: 'foo' }],
format: 'JSONEachRow',
// `id` column value for this row will be zero (default for UInt32)
columns: ['message'],
})
// Generated statement: INSERT INTO mytable (* EXCEPT (message)) FORMAT JSONEachRow
await client.insert({
table: tableName,
values: [{ id: 144 }],
format: 'JSONEachRow',
// `message` column value for this row will be an empty string
columns: {
except: ['message'],
},
})
await client.insert({
table: 'mydb.mytable', // Fully qualified name including the database
values: [{ id: 42, message: 'foo' }],
format: 'JSONEachRow',
})
Limites de la version web
@clickhouse/client-web ne fonctionnent qu’avec les formats Array<T> et JSON*.
L’insertion de flux n’est pas encore prise en charge dans la version web en raison d’une compatibilité insuffisante des navigateurs.
Par conséquent, l’interface InsertParams de la version web diffère légèrement de celle de Node.js,
car values est limité au seul type ReadonlyArray<T> :
interface InsertParams<T> extends BaseQueryParams {
// Table name to insert the data into
table: string
// A dataset to insert.
values: ReadonlyArray<T>
// Format of the dataset to insert.
format?: DataFormat
// Allows to specify which columns the data will be inserted into.
// - An array such as `['a', 'b']` will generate: `INSERT INTO table (a, b) FORMAT DataFormat`
// - An object such as `{ except: ['a', 'b'] }` will generate: `INSERT INTO table (* EXCEPT (a, b)) FORMAT DataFormat`
// By default, the data is inserted into all columns of the table,
// and the generated statement will be: `INSERT INTO table FORMAT DataFormat`.
columns?: NonEmptyArray<string> | { except: NonEmptyArray<string> }
}
CREATE TABLE ou ALTER TABLE.
Elle doit être attendue.
Le flux de réponse est détruit immédiatement, ce qui libère le socket sous-jacent.
interface CommandParams extends BaseQueryParams {
// Statement to execute.
query: string
}
interface CommandResult {
query_id: string
}
interface ClickHouseClient {
command(params: CommandParams): Promise<CommandResult>
}
await client.command({
query: `
CREATE TABLE IF NOT EXISTS my_cloud_table
(id UInt64, name String)
ORDER BY (id)
`,
// Recommended for cluster usage to avoid situations where a query processing error occurred after the response code,
// and HTTP headers were already sent to the client.
// See https://clickhouse.com/docs/interfaces/http/#response-buffering
clickhouse_settings: {
wait_end_of_query: 1,
},
})
await client.command({
query: `
CREATE TABLE IF NOT EXISTS my_table
(id UInt64, name String)
ENGINE MergeTree()
ORDER BY (id)
`,
})
await client.command({
query: `INSERT INTO my_table SELECT '42'`,
})
Une requête annulée avec abort_signal ne garantit pas que l’instruction n’ait pas été exécutée par le serveur.
query/insert
et que son résultat vous intéresse, vous pouvez utiliser exec comme alternative à command.
exec renvoie un flux lisible qui DOIT être consommé ou détruit côté application.
interface ExecParams extends BaseQueryParams {
// Statement to execute.
query: string
}
interface ClickHouseClient {
exec(params: ExecParams): Promise<QueryResult>
}
export interface QueryResult {
stream: Stream.Readable
query_id: string
}
export interface QueryResult {
stream: ReadableStream
query_id: string
}
ping, fournie pour vérifier l’état de la connexion, renvoie true si le serveur est accessible.
Si le serveur est inaccessible, l’erreur sous-jacente est également incluse dans le résultat.
type PingResult =
| { success: true }
| { success: false; error: Error }
/** Parameters for the health-check request - using the built-in `/ping` endpoint.
* This is the default behavior for the Node.js version. */
export type PingParamsWithEndpoint = {
select: false
/** AbortSignal instance to cancel a request in progress. */
abort_signal?: AbortSignal
/** Additional HTTP headers to attach to this particular request. */
http_headers?: Record<string, string>
}
/** Parameters for the health-check request - using a SELECT query.
* This is the default behavior for the Web version, as the `/ping` endpoint does not support CORS.
* Most of the standard `query` method params, e.g., `query_id`, `abort_signal`, `http_headers`, etc. will work,
* except for `query_params`, which does not make sense to allow in this method. */
export type PingParamsWithSelectQuery = { select: true } & Omit<
BaseQueryParams,
'query_params'
>
export type PingParams = PingParamsWithEndpoint | PingParamsWithSelectQuery
interface ClickHouseClient {
ping(params?: PingParams): Promise<PingResult>
}
/ping, tandis que la version Web utilise une simple requête SELECT 1 pour obtenir un résultat similaire, car l’endpoint /ping ne prend pas en charge CORS.
Exemple : (Node.js/Web) Un ping simple vers l’instance du serveur ClickHouse. NB : pour la version Web, les erreurs interceptées seront différentes.
Code source.
const result = await client.ping();
if (!result.success) {
// process result.error
}
ping, ou spécifier des paramètres supplémentaires tels que query_id, vous pouvez l’utiliser comme suit :
const result = await client.ping({ select: true, /* query_id, abort_signal, http_headers, or any other query params */ });
query — voir la définition de type PingParamsWithSelectQuery.
Fermer (Node.js uniquement)
Streaming de fichiers (Node.js uniquement)
query (JSONEachRow, CSV, etc.) et dans le nom du fichier de sortie.
Le client prend en charge les formats de données JSON et texte.
Si vous définissez format sur l’un des formats de la famille JSON (JSONEachRow, JSONCompactEachRow, etc.), le client sérialise et désérialise les données pendant leur transmission.
Les données fournies dans les formats texte « bruts » (CSV, familles TabSeparated et CustomSeparated) sont transmises telles quelles, sans transformation supplémentaire.
Il peut y avoir une confusion entre JSON en tant que format général et le format JSON de ClickHouse.Le client prend en charge le streaming d’objets JSON avec des formats tels que JSONEachRow (voir le tableau ci-dessous pour les autres formats adaptés au streaming ; voir aussi les select_streaming_ exemples dans le dépôt du client).En revanche, des formats comme ClickHouse JSON et quelques autres sont représentés par un seul objet dans la réponse et ne peuvent donc pas être traités en streaming par le client. | Format | Entrée (tableau) | Entrée (objet) | Entrée/Sortie (flux) | Sortie (JSON) | Sortie (texte) |
|---|
| JSON | ❌ | ✔️ | ❌ | ✔️ | ✔️ |
| JSONCompact | ❌ | ✔️ | ❌ | ✔️ | ✔️ |
| JSONObjectEachRow | ❌ | ✔️ | ❌ | ✔️ | ✔️ |
| JSONColumnsWithMetadata | ❌ | ✔️ | ❌ | ✔️ | ✔️ |
| JSONStrings | ❌ | ❌️ | ❌ | ✔️ | ✔️ |
| JSONCompactStrings | ❌ | ❌ | ❌ | ✔️ | ✔️ |
| JSONEachRow | ✔️ | ❌ | ✔️ | ✔️ | ✔️ |
| JSONEachRowWithProgress | ❌️ | ❌ | ✔️ ❗- voir ci-dessous | ✔️ | ✔️ |
| JSONStringsEachRow | ✔️ | ❌ | ✔️ | ✔️ | ✔️ |
| JSONCompactEachRow | ✔️ | ❌ | ✔️ | ✔️ | ✔️ |
| JSONCompactStringsEachRow | ✔️ | ❌ | ✔️ | ✔️ | ✔️ |
| JSONCompactEachRowWithNames | ✔️ | ❌ | ✔️ | ✔️ | ✔️ |
| JSONCompactEachRowWithNamesAndTypes | ✔️ | ❌ | ✔️ | ✔️ | ✔️ |
| JSONCompactStringsEachRowWithNames | ✔️ | ❌ | ✔️ | ✔️ | ✔️ |
| JSONCompactStringsEachRowWithNamesAndTypes | ✔️ | ❌ | ✔️ | ✔️ | ✔️ |
| CSV | ❌ | ❌ | ✔️ | ❌ | ✔️ |
| CSVWithNames | ❌ | ❌ | ✔️ | ❌ | ✔️ |
| CSVWithNamesAndTypes | ❌ | ❌ | ✔️ | ❌ | ✔️ |
| TabSeparated | ❌ | ❌ | ✔️ | ❌ | ✔️ |
| TabSeparatedRaw | ❌ | ❌ | ✔️ | ❌ | ✔️ |
| TabSeparatedWithNames | ❌ | ❌ | ✔️ | ❌ | ✔️ |
| TabSeparatedWithNamesAndTypes | ❌ | ❌ | ✔️ | ❌ | ✔️ |
| CustomSeparated | ❌ | ❌ | ✔️ | ❌ | ✔️ |
| CustomSeparatedWithNames | ❌ | ❌ | ✔️ | ❌ | ✔️ |
| CustomSeparatedWithNamesAndTypes | ❌ | ❌ | ✔️ | ❌ | ✔️ |
| Parquet | ❌ | ❌ | ✔️ | ❌ | ✔️❗- voir ci-dessous |
JSONEachRowWithProgress est un format de sortie uniquement qui prend en charge les informations de progression dans le flux. Voir cet exemple pour plus de détails.
La liste complète des formats d’entrée et de sortie de ClickHouse est disponible
ici.
Types de données ClickHouse pris en charge
Le type JS correspondant s’applique à tous les formats JSON*, sauf à ceux qui représentent tout sous forme de chaîne (par ex. JSONStringEachRow)
| Type | Statut | type JS |
|---|
| UInt8/16/32 | ✔️ | number |
| UInt64/128/256 | ✔️ ❗- voir ci-dessous | string |
| Int8/16/32 | ✔️ | number |
| Int64/128/256 | ✔️ ❗- voir ci-dessous | string |
| Float32/64 | ✔️ | number |
| Decimal | ✔️ ❗- voir ci-dessous | number |
| Boolean | ✔️ | boolean |
| String | ✔️ | string |
| FixedString | ✔️ | string |
| UUID | ✔️ | string |
| Date32/64 | ✔️ | string |
| DateTime32/64 | ✔️ ❗- voir ci-dessous | string |
| Enum | ✔️ | string |
| LowCardinality | ✔️ | string |
| Array(T) | ✔️ | T[] |
| (new) JSON | ✔️ | object |
| Variant(T1, T2…) | ✔️ | T (selon la variante) |
| Dynamic | ✔️ | T (selon la variante) |
| Nested | ✔️ | T[] |
| Tuple(T1, T2, …) | ✔️ | [T1, T2, …] |
| Tuple(n1 T1, n2 T2…) | ✔️ | { n1: T1; n2: T2; …} |
| Nullable(T) | ✔️ | type JS pour T ou null |
| IPv4 | ✔️ | string |
| IPv6 | ✔️ | string |
| Point | ✔️ | [ number, number ] |
| Ring | ✔️ | Array<Point> |
| Polygon | ✔️ | Array<Ring> |
| MultiPolygon | ✔️ | Array<Polygon> |
| Map(K, V) | ✔️ | Record<K, V> |
| Time/Time64 | ✔️ | string |
Points à noter sur les types Date/Date32
Date/Date32 n’acceptent à l’insertion que des chaînes de caractères.
Exemple : insérer une valeur de type Date.
Code source
await client.insert({
table: 'my_table',
values: [ { date: '2022-09-05' } ],
format: 'JSONEachRow',
})
DateTime ou DateTime64, vous pouvez employer aussi bien des chaînes de caractères que des objets Date JS. Les objets Date JS peuvent être passés tels quels à insert avec date_time_input_format défini sur best_effort. Consultez cet exemple pour plus de détails.
Points à noter concernant les types Decimal*
JSON*. Supposons que nous ayons une table définie comme suit :
CREATE TABLE my_table
(
id UInt32,
dec32 Decimal(9, 2),
dec64 Decimal(18, 3),
dec128 Decimal(38, 10),
dec256 Decimal(76, 20)
)
ENGINE MergeTree()
ORDER BY (id)
await client.insert({
table: 'my_table',
values: [{
id: 1,
dec32: '1234567.89',
dec64: '123456789123456.789',
dec128: '1234567891234567891234567891.1234567891',
dec256: '12345678912345678912345678911234567891234567891234567891.12345678911234567891',
}],
format: 'JSONEachRow',
})
JSON*, ClickHouse renvoie par défaut les Decimal sous forme de nombres, ce qui peut entraîner une perte de précision. Pour éviter cela, vous pouvez convertir les Decimal en chaînes de caractères dans la requête :
await client.query({
query: `
SELECT toString(dec32) AS decimal32,
toString(dec64) AS decimal64,
toString(dec128) AS decimal128,
toString(dec256) AS decimal256
FROM my_table
`,
format: 'JSONEachRow',
})
Types intégraux : Int64, Int128, Int256, UInt64, UInt128, UInt256
JSON* afin d’éviter
un dépassement de capacité d’entier, car les valeurs maximales de ces types sont supérieures à Number.MAX_SAFE_INTEGER.
Ce comportement peut toutefois être modifié
avec le paramètre output_format_json_quote_64bit_integers
.
Exemple : Ajustez le format de sortie JSON pour les nombres 64 bits.
const resultSet = await client.query({
query: 'SELECT * from system.numbers LIMIT 1',
format: 'JSONEachRow',
})
expect(await resultSet.json()).toEqual([ { number: '0' } ])
const resultSet = await client.query({
query: 'SELECT * from system.numbers LIMIT 1',
format: 'JSONEachRow',
clickhouse_settings: { output_format_json_quote_64bit_integers: 0 },
})
expect(await resultSet.json()).toEqual([ { number: 0 } ])
const client = createClient({
clickhouse_settings: {}
})
client.query({
clickhouse_settings: {}
})
Assurez-vous que l’utilisateur pour le compte duquel les requêtes sont exécutées dispose des droits suffisants pour modifier les paramètres.
name — Identifiant de substitution.data_type - Type de données de la valeur du paramètre de l’application.
Exemple :: Requête avec des paramètres.
Code source
.
await client.query({
query: 'SELECT plus({val1: Int32}, {val2: Int32})',
format: 'CSV',
query_params: {
val1: 10,
val2: 20,
},
})
GZIP est pris en charge via zlib.
createClient({
compression: {
response: true,
request: true
}
})
response: true indique au serveur ClickHouse de renvoyer un corps de réponse compressé. Valeur par défaut : response: falserequest: true active la compression du corps de la requête du client. Valeur par défaut : request: false
Journalisation (Node.js uniquement)
La journalisation est une fonctionnalité expérimentale susceptible d’évoluer à l’avenir.
stdout via les méthodes console.debug/info, et dans stderr via les méthodes console.warn/error.
Vous pouvez personnaliser la logique de journalisation en fournissant une LoggerClass, et choisir le niveau de journalisation souhaité avec le paramètre level (la valeur par défaut est WARN) :
import type { Logger } from '@clickhouse/client'
// All three LogParams types are exported by the client
interface LogParams {
module: string
message: string
args?: Record<string, unknown>
}
type ErrorLogParams = LogParams & { err: Error }
type WarnLogParams = LogParams & { err?: Error }
class MyLogger implements Logger {
trace({ module, message, args }: LogParams) {
// ...
}
debug({ module, message, args }: LogParams) {
// ...
}
info({ module, message, args }: LogParams) {
// ...
}
warn({ module, message, args }: WarnLogParams) {
// ...
}
error({ module, message, args, err }: ErrorLogParams) {
// ...
}
}
const client = createClient({
log: {
LoggerClass: MyLogger,
level: ClickHouseLogLevel.DEBUG,
}
})
TRACE - informations de bas niveau sur le cycle de vie des sockets Keep-AliveDEBUG - informations sur la réponse (sans les en-têtes d’autorisation ni les informations sur l’hôte)INFO - pratiquement inutilisé ; affiche le niveau de log actuel lors de l’initialisation du clientWARN - erreurs non fatales ; une requête ping ayant échoué est journalisée comme un avertissement, car l’erreur sous-jacente est incluse dans le résultat renvoyéERROR - erreurs fatales provenant des méthodes query/insert/exec/command, par exemple une requête ayant échoué
Vous trouverez l’implémentation par défaut de Logger ici.
Certificats TLS (Node.js uniquement)
certs
et que le fichier d’autorité de certification s’appelle CA.pem :
const client = createClient({
url: 'https://<hostname>:<port>',
username: '<username>',
password: '<password>', // if required
tls: {
ca_cert: fs.readFileSync('certs/CA.pem'),
},
})
const client = createClient({
url: 'https://<hostname>:<port>',
username: '<username>',
tls: {
ca_cert: fs.readFileSync('certs/CA.pem'),
cert: fs.readFileSync(`certs/client.crt`),
key: fs.readFileSync(`certs/client.key`),
},
})
Configuration de Keep-Alive (Node.js uniquement)
Connection: keep-alive sera envoyé. Les sockets inactifs restent dans le pool de connexions pendant 2500 millisecondes par défaut (voir les notes sur l’ajustement de cette option).
keep_alive.idle_socket_ttl doit avoir une valeur sensiblement inférieure à celle configurée sur le serveur/LB. La principale raison est qu’en HTTP/1.1, le serveur peut fermer les sockets sans en avertir le client ; si le serveur ou le load balancer ferme la connexion avant le client, celui-ci peut tenter de réutiliser un socket fermé, ce qui entraîne une erreur socket hang up.
Si vous modifiez keep_alive.idle_socket_ttl, gardez à l’esprit qu’il doit toujours rester aligné sur la configuration Keep-Alive de votre serveur/LB, et qu’il doit être toujours inférieur à cette valeur, afin de garantir que le serveur ne ferme jamais le premier la connexion encore ouverte.
Ajustement de idle_socket_ttl
keep_alive.idle_socket_ttl sur 2500 millisecondes, cette valeur étant considérée comme la plus sûre par défaut ; côté serveur, keep_alive_timeout peut être défini jusqu’à seulement 3 secondes dans les versions de ClickHouse antérieures à 23.11 sans modification de config.xml.
Si les performances vous conviennent et que vous ne rencontrez aucun problème, il est recommandé de ne pas augmenter la valeur du paramètre keep_alive.idle_socket_ttl, car cela peut entraîner des erreurs de type “Socket hang-up” ; de plus, si votre application envoie beaucoup de requêtes et qu’il y a peu d’inactivité entre elles, la valeur par défaut devrait suffire, car les sockets ne resteront pas inactifs assez longtemps et le client les conservera dans le pool.
curl -is --data-binary "SELECT 1" <clickhouse_url>
Connection et Keep-Alive dans la réponse. Par exemple :
Connection: Keep-Alive
Keep-Alive: timeout=10
keep_alive_timeout est de 10 secondes, et vous pouvez essayer d’augmenter keep_alive.idle_socket_ttl à 9000, voire 9500 millisecondes, afin de conserver les sockets inactifs ouverts un peu plus longtemps que par défaut. Surveillez les éventuelles erreurs “Socket hang-up” : elles indiquent que le serveur ferme les connexions avant le client. Réduisez alors la valeur jusqu’à ce que les erreurs disparaissent.
Si vous rencontrez des erreurs socket hang up même avec la dernière version du client, voici les options possibles pour résoudre le problème :
-
Activez les logs avec au minimum le niveau
WARN (par défaut). Cela permet de vérifier s’il existe un flux non consommé ou en suspens dans le code applicatif : la couche de transport l’enregistrera au niveau WARN, car cela peut entraîner la fermeture du socket par le serveur. Vous pouvez activer la journalisation dans la configuration du client comme suit :
const client = createClient({
log: { level: ClickHouseLogLevel.WARN },
})
-
Assurez-vous que la configuration souhaitée est appliquée à la bonne instance du client. Si votre application utilise plusieurs instances du client, vérifiez que celle utilisée pour les requêtes a bien la valeur correcte pour
keep_alive.idle_socket_ttl.
-
Réduisez le paramètre
keep_alive.idle_socket_ttl de 500 millisecondes dans la configuration du client. Dans certaines situations, par exemple en cas de latence réseau élevée entre le client et le serveur, cela peut être utile afin d’écarter le cas où une requête sortante récupérerait un socket que le serveur s’apprête à fermer.
-
Si cette erreur se produit lors de requêtes longues sans aucune donnée entrante ou sortante (par exemple un
INSERT FROM SELECT de longue durée), cela peut être dû à un load balancer ou à d’autres composants réseau qui ferment les connexions persistantes ou les requêtes longues. Vous pouvez essayer de forcer l’arrivée de données pendant ces requêtes en utilisant une combinaison de ces paramètres ClickHouse :
const client = createClient({
// Ici, nous supposons que certaines requêtes auront un temps d'exécution supérieur à 5 minutes
request_timeout: 400_000,
/** Ces paramètres combinés permettent d'éviter les problèmes de timeout du LB dans le cas de requêtes de longue durée sans données entrantes ou sortantes,
* comme `INSERT FROM SELECT` et d'autres similaires, car la connexion pourrait être marquée comme inactive par le LB et fermée brutalement.
* Dans ce cas, nous supposons que le LB a un délai d'expiration de connexion inactive de 120s, nous définissons donc 110s comme valeur « sûre ». */
clickhouse_settings: {
send_progress_in_http_headers: 1,
http_headers_progress_interval_ms: '110000', // UInt64, doit être passé comme une chaîne
},
})
-
La fonctionnalité Keep-Alive peut être entièrement désactivée. Dans ce cas, le client ajoutera également l’en-tête
Connection: close à chaque requête, et l’agent HTTP sous-jacent ne réutilisera pas les connexions. Le paramètre keep_alive.idle_socket_ttl sera ignoré, puisqu’il n’y aura plus de sockets inactifs. Cela entraînera une surcharge supplémentaire, car une nouvelle connexion sera établie pour chaque requête.
const client = createClient({
keep_alive: {
enabled: false,
},
})
-
Écartez les problèmes potentiels liés au reste de la pile réseau, y compris Node.js lui-même, en exécutant un test simple en ligne de commande avec la même instance ClickHouse et le même chemin réseau (c.-à-d. depuis la même machine ou le même segment réseau, par exemple un pod Kubernetes), par exemple avec
curl :
curl -is --user '<user>:<password>' --data-binary "SELECT 1" <clickhouse_url>
curl, il est probable que le problème ne soit pas lié à la configuration du client, mais plutôt à la pile réseau ou à la configuration du serveur.
-
Pour tester la connexion avec les fonctionnalités natives de Node.js, vous pouvez essayer de créer une requête HTTP simple vers le serveur ClickHouse à l’aide de l’API
fetch intégrée :
const response = await fetch('<clickhouse_url>?query=SELECT+1', {
method: 'POST',
headers: {
'Authorization': 'Basic ' + Buffer.from('<user>:<password>').toString('base64'),
}
})
-
Dans certains cas, le code applicatif ou les adaptateurs du framework peuvent ajouter un
ping() préventif avant l’exécution effective de la requête, ce qui peut conduire à une situation où la requête ping() réussit, mais où la requête suivante échoue avec une erreur “socket hang up” en raison du même problème sous-jacent de connexions inactives. Si vous observez ce comportement dans les logs, vérifiez s’il existe une option permettant de désactiver les pings préventifs dans votre framework ou votre code applicatif. Cela devrait également réduire la probabilité d’être soumis à une limitation de débit par l’un des composants réseau intermédiaires.
-
Assurez-vous que l’application elle-même dispose de suffisamment de temps CPU et que le réseau n’est pas bridé par l’hébergeur. Différents moyens de surveillance, comme les métriques de pause du GC, les métriques de latence de la boucle d’événements et d’autres du même type, peuvent également aider à écarter d’éventuels problèmes de manque de ressources.
-
Vérifiez votre code applicatif avec la règle ESLint no-floating-promises activée, ce qui aidera à identifier les promesses non gérées susceptibles d’entraîner des flux et des sockets orphelins.
Utilisateurs en lecture seule
readonly=1, la compression de la réponse ne peut pas être activée, car elle nécessite le paramètre enable_http_compression. La configuration suivante entraînera une erreur :
const client = createClient({
compression: {
response: true, // won't work with a readonly=1 user
},
})
readonly=1.
Proxy avec un chemin d’accès
http://proxy:8123/clickhouse_server, indiquez clickhouse_server comme option de configuration pathname (avec ou sans slash initial) ; sinon, s’il est fourni directement dans l’url, il sera interprété comme l’option database. Plusieurs segments de chemin sont pris en charge, par exemple /my_proxy/db.
const client = createClient({
url: 'http://proxy:8123',
pathname: '/clickhouse_server',
})
Proxy inverse avec authentification
http_headers pour y fournir les en-têtes nécessaires :
const client = createClient({
http_headers: {
'My-Auth-Header': '...',
},
})
Agent HTTP/HTTPS personnalisé (expérimental, Node.js uniquement)
Il s’agit d’une fonctionnalité expérimentale susceptible d’évoluer de manière incompatible avec les versions précédentes dans de futures releases. L’implémentation et les paramètres par défaut fournis par le client devraient suffire pour la plupart des cas d’usage. N’utilisez cette fonctionnalité que si vous êtes certain d’en avoir besoin.
max_open_connections, keep_alive.enabled, tls), lequel gère les connections au ClickHouse server. En outre, si des certificats TLS sont utilisés, l’agent sous-jacent sera configuré avec les certificats nécessaires et les en-têtes d’authentification TLS appropriés seront appliqués.
À partir de la version 1.2.0, il est possible de fournir au client un agent HTTP ou HTTPS personnalisé à la place de l’agent sous-jacent par défaut. Cela peut être utile dans le cas de configurations réseau complexes. Les conditions suivantes s’appliquent lorsqu’un agent personnalisé est fourni :
- Les options
max_open_connections et tls n’auront aucun effet et seront ignorées par le client, car elles font partie de la configuration de l’agent sous-jacent.
keep_alive.enabled réglera uniquement la valeur par défaut de l’en-tête Connection (true -> Connection: keep-alive, false -> Connection: close).- Bien que la gestion des sockets keep-alive inactifs continue de fonctionner (car elle n’est pas liée à l’agent, mais au socket lui-même), il est désormais possible de la désactiver complètement en définissant
keep_alive.idle_socket_ttl sur 0.
Exemples d’utilisation d’un Agent personnalisé
const agent = new http.Agent({ // or https.Agent
keepAlive: true,
keepAliveMsecs: 2500,
maxSockets: 10,
maxFreeSockets: 10,
})
const client = createClient({
http_agent: agent,
})
const agent = new https.Agent({
keepAlive: true,
keepAliveMsecs: 2500,
maxSockets: 10,
maxFreeSockets: 10,
ca: fs.readFileSync('./ca.crt'),
})
const client = createClient({
url: 'https://myserver:8443',
http_agent: agent,
// With a custom HTTPS agent, the client won't use the default HTTPS connection implementation; the headers should be provided manually
http_headers: {
'X-ClickHouse-User': 'username',
'X-ClickHouse-Key': 'password',
},
// Important: authorization header conflicts with the TLS headers; disable it.
set_basic_auth_header: false,
})
const agent = new https.Agent({
keepAlive: true,
keepAliveMsecs: 2500,
maxSockets: 10,
maxFreeSockets: 10,
ca: fs.readFileSync('./ca.crt'),
cert: fs.readFileSync('./client.crt'),
key: fs.readFileSync('./client.key'),
})
const client = createClient({
url: 'https://myserver:8443',
http_agent: agent,
// With a custom HTTPS agent, the client won't use the default HTTPS connection implementation; the headers should be provided manually
http_headers: {
'X-ClickHouse-User': 'username',
'X-ClickHouse-Key': 'password',
'X-ClickHouse-SSL-Certificate-Auth': 'on',
},
// Important: authorization header conflicts with the TLS headers; disable it.
set_basic_auth_header: false,
})
Authorization par défaut à l’aide du paramètre set_basic_auth_header (introduit dans la version 1.2.0), car il entre en conflit avec les en-têtes TLS. Tous les en-têtes TLS doivent alors être fournis manuellement.
Limites connues (Node.js/web)
- Il n’existe pas de mappeurs de données pour les ensembles de résultats ; seuls les types primitifs du langage sont donc utilisés. La prise en charge de certains mappeurs de types de données est prévue avec le format RowBinary.
- Il existe quelques points de vigilance concernant les types de données Decimal* et Date* / DateTime*.
- Lors de l’utilisation de formats de la famille JSON*, les nombres supérieurs à Int32 sont représentés sous forme de chaînes de caractères, car les valeurs maximales des types Int64+ sont supérieures à
Number.MAX_SAFE_INTEGER. Consultez la section Types intégraux pour plus de détails.
- Le streaming pour les requêtes select fonctionne, mais il est désactivé pour les inserts (y compris au niveau du type).
- La compression des requêtes est désactivée et la configuration est ignorée. La compression des réponses fonctionne.
- Aucune prise en charge de la journalisation pour le moment.
- Pour réduire la consommation de mémoire de l’application, envisagez d’utiliser des flux pour les insertions volumineuses (par ex. depuis des fichiers) et les requêtes SELECT, lorsque c’est pertinent. Pour les écouteurs d’événements et cas d’usage similaires, les insertions asynchrones peuvent également être une bonne option, car elles permettent de minimiser, voire d’éviter complètement, le regroupement en lots côté client. Des exemples d’insertions asynchrones sont disponibles dans le dépôt du client, avec
async_insert_ comme préfixe de nom de fichier.
- Le client n’active pas la compression des requêtes ou des réponses par défaut. Toutefois, lors de requêtes SELECT ou d’insertions sur de grands jeux de données, vous pouvez envisager de l’activer via
ClickHouseClientConfigOptions.compression (soit uniquement pour request ou response, soit pour les deux).
- La compression entraîne une baisse significative des performances. L’activer pour
request ou response ralentira respectivement les requêtes SELECT ou les insertions, mais réduira la quantité de trafic réseau transférée par l’application.
Si vous avez des questions ou besoin d’aide, n’hésitez pas à nous contacter sur le Slack de la communauté (canal #clickhouse-js) ou via les issues GitHub. 
