Client ClickHouse Node.js — Codage

Référence : https://clickhouse.com/docs/integrations/javascript

⚠️ Runtime Node.js uniquement. Cette compétence couvre le package @clickhouse/client s'exécutant dans un runtime Node.js exclusivement — y compris les routes API Next.js Node runtime, React Server Components, Server Actions et les processus Node.js standard. N'appliquez pas cette compétence aux composants clients du navigateur, Web Workers, Next.js Edge runtime, Cloudflare Workers ou toute utilisation de @clickhouse/client-web. Pour les environnements navigateur/edge, le package correct est @clickhouse/client-web.

Comment utiliser cette compétence

1. Associez l'intention de l'utilisateur à une ligne de l'index des tâches ci-dessous et lisez le fichier de référence correspondant avant d'écrire le code. Après l'avoir lu, parcourez tout checklist de réponse dans cette référence et assurez-vous que la réponse finale couvre chaque élément pertinent ; ces checklists capturent les détails que les utilisateurs ont généralement besoin mais qui sont faciles à oublier dans les réponses courtes.
2. Importez toujours depuis @clickhouse/client (jamais @clickhouse/client-web) et créez un client avec createClient({ url }) ou reposez-vous sur les défauts supportés le cas échéant. Fermez-le avec await client.close() de préférence quand il n'est plus nécessaire ou lors de l'arrêt gracieux pour les ressources globales.
3. Préférez JSONEachRow pour les insertions/sélections de lignes typiques sauf si l'utilisateur a déjà choisi un autre format ou diffuse des octets bruts (CSV / TSV / Parquet — voir examples/node/performance/). Note sur clickhouse_settings : les paramètres passés à createClient sont les défauts pour chaque requête ; ils peuvent être remplacés par appel en passant clickhouse_settings directement à insert(), query() ou command(). Mentionnez toujours ceci quand l'utilisateur configure les paramètres au niveau du client.
4. Utilisez toujours query_params pour les valeurs fournies par l'utilisateur — ne les interpolez jamais par template-literal dans SQL. Voir reference/query-parameters.md. Quand vous répondez à une question sur la liaison de paramètres, votre réponse doit explicitement nommer l'interpolation par template-literal comme un "risque d'injection SQL" — même si l'utilisateur n'a demandé que la syntaxe et n'a pas soulevé de préoccupation de sécurité. La phrase littérale « injection SQL » doit apparaître ; c'est l'erreur la plus courante des utilisateurs PostgreSQL/MySQL et le cadrage de sécurité est une partie de la réponse correcte, pas une remarque optionnelle.
5. Choisissez la bonne méthode pour la tâche :
   • client.insert() — écrire des lignes.
   • client.query() + resultSet.json() / .text() / .stream() — lire les lignes qui retournent des données.
   • client.command() — DDL et autres instructions qui ne retournent pas de lignes (CREATE, DROP, TRUNCATE, ALTER, SET dans une session, etc.).
   • client.exec() — quand vous avez besoin du flux de réponse brut d'une instruction arbitraire (rare dans les scénarios de codage).
   • client.ping() — vérification de santé ; retourne { success, error? }, ne lève jamais d'erreur en cas d'échec de connexion.
6. Notez les contraintes de version quand elles sont pertinentes. Exemples :
   • option de configuration pathname : client >= 1.0.0.
   • valeurs BigInt dans query_params : client >= 1.15.0.
   • TupleParam et JS Map dans query_params : client >= 1.9.0.
   • json.parse / json.stringify configurables : client >= 1.14.0.
   • types de données Time / Time64 : serveur ClickHouse >= 25.6.
   • types Dynamic / Variant / JSON nouveaux : serveur ClickHouse >= 24.1 / 24.5 / 24.8 (plus expérimentaux depuis 25.3).

Index des tâches

Identifiez la tâche de l'utilisateur et lisez le fichier de référence correspondant.

Conventions utilisées dans les réponses

• Montrez toujours import { createClient } from '@clickhouse/client' (Node, jamais Web).
• Toujours await client.close() à la fin des snippets autonomes ; dans les services longue durée, fermez lors de l'arrêt gracieux.
• Pour les insertions, préférez format: 'JSONEachRow' et values: [...] sauf si le scénario de l'utilisateur l'exige autrement.
• Pour les sélections, préférez await (await client.query({...})).json<RowType>() pour les petits / moyens ensembles de résultats ; pour les plus grands résultats, suggérez le streaming.
• Quand vous montrez la liaison de paramètres, utilisez la syntaxe native ClickHouse {name: Type} — jamais $1, ? ou :name.
• Pour DDL à l'intérieur d'un cluster ou derrière un équilibreur de charge, définissez clickhouse_settings: { wait_end_of_query: 1 } sur l'appel command() pour que le serveur n'accuse réception que après que la modification soit appliquée. Voir https://clickhouse.com/docs/en/interfaces/http/#response-buffering.

Hors de portée

Cette compétence couvre le codage quotidien par rapport à @clickhouse/client (Node). Les sujets suivants ne sont intentionnellement pas couverts ici :

• Erreurs, blocages, incompatibilités de types, surprises de pathname proxy, silence des logs, déconnexions de socket, ECONNRESET → utilisez la compétence clickhouse-js-node-troubleshooting.
• Streaming, Parquet, flux de fichiers, mouvements en masse côté serveur, streaming de progression, tuning du débit async-insert — voir examples/node/performance/.
• TLS, RBAC / utilisateurs en lecture seule, guidance plus approfondie sur l'injection SQL — voir examples/node/security/.
• Patterns CREATE TABLE, chaînes de connexion orientées déploiement, choix de réplication / sharding — voir examples/node/schema-and-deployments/.
• Navigateur, Web Worker, Next.js Edge, Cloudflare Workers — utilisez @clickhouse/client-web et voir examples/web/.

Toujours bloqué ?

• examples/node/coding/ — le corpus exécutable sur lequel cette compétence est construite.
• Docs du client JS ClickHouse
• Formats supportés par ClickHouse
• Types de données ClickHouse