ClickHouse JS

El client oficial de JS para conectarse a ClickHouse. El client está escrito en TypeScript y proporciona definiciones de tipos para la API pública del client.

No tiene dependencias, está optimizado para ofrecer el máximo rendimiento y se ha probado con varias versiones y configuraciones de ClickHouse (on-premise en nodo único, on-premise en clúster y ClickHouse Cloud).

Hay dos versiones diferentes del client disponibles para distintos entornos:

• @clickhouse/client - solo para Node.js
• @clickhouse/client-web - navegadores (Chrome/Firefox), Cloudflare Workers

Al usar TypeScript, asegúrate de que sea como mínimo la versión 4.5, que habilita la sintaxis inline de importación y exportación.

El código fuente del client está disponible en el repositorio de GitHub de ClickHouse-JS.

Node.js debe estar disponible en el entorno para poder ejecutar el client. El client es compatible con todas las versiones mantenidas de Node.js.

En cuanto una versión de Node.js se acerca al fin de su vida útil, el client deja de ser compatible con ella, ya que se considera obsoleta e insegura.

Compatibilidad de las versiones actuales de Node.js:

La versión web del client se ha probado oficialmente con las versiones más recientes de los navegadores Chrome y Firefox, y puede usarse como dependencia, por ejemplo, en aplicaciones React/Vue/Angular o en Cloudflare Workers.

Para instalar la versión estable más reciente del client para Node.js, ejecuta:

npm i @clickhouse/client

Instalación de la versión web:

npm i @clickhouse/client-web

Es probable que el client también funcione con versiones anteriores; sin embargo, esta compatibilidad se ofrece sobre la base del mejor esfuerzo y no está garantizada. Si utiliza una versión de ClickHouse anterior a la 23.3, consulte la política de seguridad de ClickHouse y considere actualizar.

Nuestro objetivo es cubrir varios escenarios de uso del client con los examples del repositorio del client.

Puede consultar un resumen general en el README de examples.

Si algo no está claro o falta en los examples o en la documentación siguiente, no dude en contactarnos.

La mayoría de los ejemplos deberían ser compatibles con las versiones del client para Node.js y web, salvo que se indique explícitamente lo contrario.

Puedes crear tantas instancias de client como sea necesario con la fábrica createClient:

import { createClient } from '@clickhouse/client' // or '@clickhouse/client-web'

const client = createClient({
  /* configuration */
})

Si tu entorno no admite módulos ESM, puedes usar la sintaxis CJS en su lugar:

const { createClient } = require('@clickhouse/client');

const client = createClient({
  /* configuration */
})

Una instancia de client puede preconfigurarse durante su creación.

Al crear una instancia de client, se pueden ajustar los siguientes ajustes de conexión:

Es posible configurar la mayoría de los parámetros de la instancia de client mediante una URL. El formato de la URL es http[s]://[username:password@]hostname:port[/database][?param1=value1&param2=value2]. En casi todos los casos, el nombre de un parámetro concreto refleja su ruta en la interfaz de opciones de configuración, con algunas excepciones. Se admiten los siguientes parámetros:

• (1) Para los booleanos, los valores válidos son true/1 y false/0.
• (2) A cualquier parámetro con el prefijo clickhouse_setting_ o ch_ se le eliminará ese prefijo, y el resto se añadirá a clickhouse_settings del client. Por ejemplo, ?ch_async_insert=1&ch_wait_for_async_insert=1 será lo mismo que:

createClient({
  clickhouse_settings: {
    async_insert: 1,
    wait_for_async_insert: 1,
  },
})

Nota: los valores booleanos de clickhouse_settings deben pasarse como 1/0 en la URL.

• (3) Igual que (2), pero para la configuración de http_header. Por ejemplo, ?http_header_x-clickhouse-auth=foobar será equivalente a:

createClient({
  http_headers: {
    'x-clickhouse-auth': 'foobar',
  },
})

Para conectarse a ClickHouse con HTTP(S), necesita esta información:

Los detalles de su servicio de ClickHouse Cloud están disponibles en la consola de ClickHouse Cloud. Seleccione un servicio y haga clic en Connect:

Elija HTTPS. Los detalles de conexión se muestran en un comando curl de ejemplo.

Si usa ClickHouse autogestionado, los detalles de conexión los establece su administrador de ClickHouse.

El client implementa una conexión mediante los protocolos HTTP o HTTPS. La compatibilidad con RowBinary está prevista; consulta el issue relacionado.

El siguiente ejemplo muestra cómo configurar una conexión a ClickHouse Cloud. Se da por hecho que los valores de url (incluidos el protocolo y el puerto) y password se especifican mediante variables de entorno, y que se usa el usuario default.

Ejemplo: Crear una instancia de Client de Node.js usando variables de entorno para la configuración.

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 ?? '',
})

El repositorio del client contiene varios ejemplos que usan variables de entorno, como crear una tabla en ClickHouse Cloud, usar inserciones asíncronas, entre muchos otros.

Para evitar la sobrecarga de establecer una conexión en cada solicitud, el client crea un pool de conexiones a ClickHouse para reutilizarlas mediante un mecanismo Keep-Alive. De forma predeterminada, Keep-Alive está habilitado y el tamaño del pool de conexiones se establece en 10, pero puede cambiarlo con la opción de configuración max_open_connections.

No se garantiza que se use la misma conexión del pool en las consultas posteriores, a menos que el usuario establezca max_open_connections: 1. Esto rara vez es necesario, pero puede ser obligatorio en casos en los que se utilicen tablas temporales.

Véase también: configuración de Keep-Alive.

Cada método que envía una consulta o una sentencia (command, exec, insert, select) proporcionará query_id en el resultado. El client asigna este identificador único a cada consulta y puede ser útil para obtener los datos de system.query_log, si está habilitado en la configuración del servidor, o para cancelar consultas de larga duración (consulte el ejemplo). Si es necesario, el usuario puede sobrescribir query_id en los parámetros de los métodos command/query/exec/insert.

Existen varios parámetros que pueden aplicarse a todos los métodos del client (query/command/insert/exec).

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

Se utiliza para la mayoría de las sentencias que pueden devolver una respuesta, como SELECT, o para enviar DDL como CREATE TABLE, y debe usarse con await. Se espera que el conjunto de resultados devuelto se consuma en la aplicación.

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

Véase también: Parámetros base para todos los métodos del client.

ResultSet proporciona varios métodos prácticos para procesar datos en su aplicación.

La implementación de ResultSet en Node.js usa Stream.Readable internamente, mientras que la versión web usa la API web ReadableStream.

Puede consumir el ResultSet llamando a los métodos text o json de ResultSet y cargar en memoria el conjunto completo de filas devuelto por la consulta.

Debe empezar a consumir el ResultSet lo antes posible, ya que mantiene abierto el flujo de respuesta y, en consecuencia, mantiene ocupada la conexión subyacente. El client no almacena en búfer los datos entrantes para evitar un posible uso excesivo de memoria por parte de la aplicación.

Como alternativa, si es demasiado grande para caber en memoria de una sola vez, puede llamar al método stream y procesar los datos en modo streaming. En ese caso, cada uno de los fragmentos de la respuesta se transformará en arrays de filas relativamente pequeños (el tamaño de este array depende del tamaño del fragmento concreto que el client recibe del servidor, ya que puede variar, y del tamaño de cada fila), un fragmento cada vez.

Consulte la lista de formatos de datos compatibles para determinar cuál es el mejor formato para el streaming en su caso. Por ejemplo, si quiere transmitir objetos JSON, puede elegir JSONEachRow, y cada fila se interpretará como un objeto de JS o, quizá, un formato JSONCompactColumns más compacto, que hará que cada fila sea un array compacto de valores. Véase también: archivos en streaming.

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
}

Ejemplo: (Node.js/Web) Una consulta con un conjunto de resultados en formato JSONEachRow, que consume todo el flujo y analiza el contenido como objetos de JS. Código fuente.

const resultSet = await client.query({
  query: 'SELECT * FROM my_table',
  format: 'JSONEachRow',
})
const dataset = await resultSet.json() // or `row.text` to avoid parsing JSON

Ejemplo: (solo para Node.js) Resultado de una consulta en streaming en formato JSONEachRow mediante el enfoque clásico on('data'). Puede usarse indistintamente con la sintaxis for await const. Código fuente.

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

Ejemplo: (solo para Node.js) Resultado de una consulta en streaming en formato CSV con el enfoque clásico on('data'). Esto puede usarse indistintamente con la sintaxis for await const. Código fuente

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

Ejemplo: (solo para Node.js) Resultado de consulta en streaming como objetos de JS en formato JSONEachRow, consumidos con la sintaxis for await const. Esto puede usarse indistintamente con el enfoque clásico on('data'). Código fuente.

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

Ejemplo: (solo web) Iteración sobre el ReadableStream de objetos.

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

Este es el método principal para insertar datos.

export interface InsertResult {
  query_id: string
  executed: boolean
}

interface ClickHouseClient {
  insert(params: InsertParams): Promise<InsertResult>
}

El tipo de retorno es mínimo, ya que no esperamos que el servidor devuelva ningún dato y vaciamos inmediatamente el flujo de respuesta.

Si se proporciona un array vacío al método insert, la sentencia insert no se enviará al servidor; en su lugar, el método se resolverá de inmediato con { query_id: '...', executed: false }. Si en este caso no se proporcionó query_id en los params del método, en el resultado será una cadena vacía, ya que devolver un UUID aleatorio generado por el client podría resultar confuso, porque la consulta con ese query_id no existirá en la tabla system.query_log.

Si la sentencia insert se envió al servidor, el indicador executed será true.

Puede funcionar tanto con un Stream.Readable como con un Array<T> simple, según el formato de datos especificado para el método insert. Consulte también esta sección sobre el streaming de archivos.

Se debe esperar al método insert; sin embargo, es posible especificar un flujo de entrada y esperar a la operación insert más tarde, únicamente cuando el flujo se haya completado (lo que también resolverá la promesa de insert). Esto puede ser útil para listeners de eventos y casos similares, pero el manejo de errores puede no ser sencillo, ya que hay muchos casos límite del lado del client. En su lugar, considere usar async inserts, como se muestra en este ejemplo.

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

Véase también: Parámetros base para todos los métodos del client.

Ejemplo: (Node.js/Web) Insertar un array de valores. Código fuente.

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',
})

Ejemplo: (solo para Node.js) Inserta un flujo desde un archivo CSV. Código fuente. Véase también: streaming de archivos.

await client.insert({
  table: 'my_table',
  values: fs.createReadStream('./path/to/a/file.csv'),
  format: 'CSV',
})

Ejemplo: Excluya ciertas columnas de la sentencia INSERT.

Dada una definición de tabla como la siguiente:

CREATE OR REPLACE TABLE mytable
(id UInt32, message String)
ENGINE MergeTree()
ORDER BY (id)

Insertar solo una columna específica:

// 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'],
})

Excluir ciertas columnas:

// 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'],
  },
})

Consulta el código fuente para obtener más detalles.

Ejemplo: Insertar en una base de datos distinta de la proporcionada a la instancia del client. Código fuente.

await client.insert({
  table: 'mydb.mytable', // Fully qualified name including the database
  values: [{ id: 42, message: 'foo' }],
  format: 'JSONEachRow',
})

Actualmente, las inserciones en @clickhouse/client-web solo funcionan con los formatos Array<T> y JSON*. La inserción de streams todavía no es compatible con la versión web debido a la limitada compatibilidad de los navegadores.

En consecuencia, la interfaz InsertParams para la versión web es ligeramente distinta de la versión de Node.js, ya que values está limitado exclusivamente al tipo 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> }
}

Esto puede cambiar en el futuro. Véase también: Parámetros base para todos los métodos del client.

Se puede usar para sentencias que no generan ninguna salida, cuando la cláusula FORMAT no es aplicable o cuando no te interesa en absoluto la respuesta. Un ejemplo de este tipo de sentencia puede ser CREATE TABLE o ALTER TABLE.

Se debe esperar su finalización.

El flujo de respuesta se destruye de inmediato, lo que significa que el socket subyacente se libera.

interface CommandParams extends BaseQueryParams {
  // Statement to execute.
  query: string
}

interface CommandResult {
  query_id: string
}

interface ClickHouseClient {
  command(params: CommandParams): Promise<CommandResult>
}

Véase también: Parámetros base para todos los métodos del client.

Ejemplo: (Node.js/Web) Crear una tabla en ClickHouse Cloud. Código fuente.

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

Ejemplo: (Node.js/Web) Crear una tabla en una instancia autohospedada de ClickHouse. Código fuente.

await client.command({
  query: `
    CREATE TABLE IF NOT EXISTS my_table
    (id UInt64, name String)
    ENGINE MergeTree()
    ORDER BY (id)
  `,
})

Ejemplo: (Node.js/Web) INSERT FROM SELECT

await client.command({
  query: `INSERT INTO my_table SELECT '42'`,
})

Si tienes una consulta personalizada que no se ajusta a query/insert y te interesa el resultado, puedes usar exec como alternativa a command.

exec devuelve un stream de lectura que DEBE consumirse o destruirse del lado de la aplicación.

interface ExecParams extends BaseQueryParams {
  // Statement to execute.
  query: string
}

interface ClickHouseClient {
  exec(params: ExecParams): Promise<QueryResult>
}

Véase también: Parámetros base para todos los métodos del client.

El tipo de retorno de Stream es diferente en las versiones para Node.js y Web.

Node.js:

export interface QueryResult {
  stream: Stream.Readable
  query_id: string
}

Web:

export interface QueryResult {
  stream: ReadableStream
  query_id: string
}

El método ping, que se proporciona para comprobar el estado de la conectividad, devuelve true si se puede establecer conexión con el servidor.

Si no se puede establecer conexión con el servidor, el error subyacente también se incluye en el resultado.

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 puede ser útil para comprobar si el servidor está disponible cuando se inicia la aplicación, especialmente con ClickHouse Cloud, donde una instancia puede estar inactiva y reactivarse después de un ping; en ese caso, quizá te convenga reintentarlo unas cuantas veces, con una pausa entre intentos.

Ten en cuenta que, de forma predeterminada, la versión de Node.js usa el endpoint /ping, mientras que la versión web usa una consulta simple SELECT 1 para lograr un resultado similar, ya que el endpoint /ping no admite CORS.

Ejemplo: (Node.js/Web) Un ping sencillo a la instancia del servidor ClickHouse. Nota: en la versión web, los errores capturados serán diferentes. Código fuente.

const result = await client.ping();
if (!result.success) {
  // process result.error
}

Ejemplo: Si además quieres comprobar las credenciales al llamar al método ping o especificar parámetros adicionales como query_id, puedes usarlo así:

const result = await client.ping({ select: true, /* query_id, abort_signal, http_headers, or any other query params */ });

El método ping admite la mayoría de los parámetros estándar del método query; consulta la definición de tipo PingParamsWithSelectQuery.

Cierra todas las conexiones abiertas y libera recursos. No-op en la versión web.

await client.close()

Hay varios ejemplos de streaming de archivos con formatos de datos populares (NDJSON, CSV, Parquet) en el repositorio del Client.

• Streaming desde un archivo NDJSON
• Streaming desde un archivo CSV
• Streaming desde un archivo Parquet
• Streaming a un archivo Parquet

El streaming de otros formatos a un archivo debería ser similar al de Parquet; la única diferencia estará en el format usado en la llamada query (JSONEachRow, CSV, etc.) y en el nombre del archivo de salida.

El Client maneja formatos de datos como JSON o texto.

Si especifica format como uno de la familia de formatos JSON (JSONEachRow, JSONCompactEachRow, etc.), el Client serializará y deserializará los datos durante la comunicación por la red.

Los datos proporcionados en formatos de texto "sin procesar" (familias CSV, TabSeparated y CustomSeparated) se envían por la red sin transformaciones adicionales.

Para Parquet, el principal caso de uso de las consultas SELECT probablemente sea escribir el flujo resultante en un archivo. Consulte el ejemplo en el repositorio del Client.

JSONEachRowWithProgress es un formato solo de salida que admite informes de progreso en el flujo. Consulte este ejemplo para obtener más información.

La lista completa de formatos de entrada y salida de ClickHouse está disponible aquí.

La lista completa de formatos compatibles de ClickHouse está disponible aquí.

Véase también:

• Ejemplos de trabajo con Dynamic/Variant/JSON
• Ejemplos de trabajo con Time/Time64

Dado que el Client inserta valores sin conversión de tipos adicional, las columnas de tipo Date/Date32 solo se pueden insertar como cadenas.

Ejemplo: Insertar un valor de tipo Date. Código fuente

await client.insert({
  table: 'my_table',
  values: [ { date: '2022-09-05' } ],
  format: 'JSONEachRow',
})

Sin embargo, si usas columnas DateTime o DateTime64, puedes usar tanto cadenas como objetos Date de JS. Los objetos Date de JS se pueden pasar a insert tal cual, con date_time_input_format configurado en best_effort. Consulta este ejemplo para obtener más información.

Es posible insertar valores Decimal mediante formatos de la familia JSON*. Supongamos que tenemos una tabla definida como:

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)

Podemos insertar valores sin pérdida de precisión usando la representación textual:

await client.insert({
  table: 'my_table',
  values: [{
    id: 1,
    dec32:  '1234567.89',
    dec64:  '123456789123456.789',
    dec128: '1234567891234567891234567891.1234567891',
    dec256: '12345678912345678912345678911234567891234567891234567891.12345678911234567891',
  }],
  format: 'JSONEachRow',
})

Sin embargo, al consultar los datos en formatos JSON*, ClickHouse devolverá los Decimal como números de forma predeterminada, lo que podría causar una pérdida de precisión. Para evitarlo, puedes convertir los Decimal en cadenas en la consulta:

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',
})

Consulta este ejemplo para obtener más información.

Aunque el server puede aceptarlo como un número, en los formatos de salida de la familia JSON* se devuelve como una cadena para evitar el desbordamiento de enteros, ya que los valores máximos de estos tipos son mayores que Number.MAX_SAFE_INTEGER.

Sin embargo, este comportamiento se puede modificar con el ajuste output_format_json_quote_64bit_integers .

Ejemplo: Ajusta el formato de salida JSON para números de 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 } ])

El Client puede ajustar el comportamiento de ClickHouse mediante el mecanismo de ajustes. Los ajustes pueden establecerse en la instancia del Client para que se apliquen a cada solicitud enviada a ClickHouse:

const client = createClient({
  clickhouse_settings: {}
})

O bien, se puede configurar un ajuste a nivel de solicitud:

client.query({
  clickhouse_settings: {}
})

Puede encontrar un archivo de declaración de tipos con todos los ajustes de ClickHouse compatibles aquí.

Puede crear una consulta con parámetros y pasarles valores desde la aplicación cliente. Esto permite evitar dar formato a la consulta con valores dinámicos específicos en el lado del cliente.

Dé formato a una consulta como de costumbre y, a continuación, coloque entre llaves los valores que desee pasar desde los parámetros de la aplicación a la consulta con el siguiente formato:

{<name>: <data_type>}

donde:

• name — Identificador provisional.
• data_type - Tipo de dato del valor del parámetro de la aplicación.

Ejemplo:: Consulta con parámetros. Código fuente .

await client.query({
  query: 'SELECT plus({val1: Int32}, {val2: Int32})',
  format: 'CSV',
  query_params: {
    val1: 10,
    val2: 20,
  },
})

Consulte https://clickhouse.com/docs/interfaces/client#cli-queries-with-parameters-syntax para más detalles.

Nota: la compresión de solicitudes no está disponible actualmente en la versión web. La compresión de respuestas funciona con normalidad. La versión de Node.js admite ambas.

Las aplicaciones de datos que trabajan con grandes conjuntos de datos en tránsito pueden beneficiarse de habilitar la compresión. Actualmente, solo se admite GZIP mediante zlib.

createClient({
  compression: {
    response: true,
    request: true
  }
})

Los parámetros de configuración son:

• response: true indica a ClickHouse server que devuelva el cuerpo de la respuesta comprimido. Valor predeterminado: response: false
• request: true habilita la compresión en el cuerpo de la solicitud del Client. Valor predeterminado: request: false

La implementación predeterminada del logger emite registros en stdout mediante los métodos console.debug/info y en stderr mediante los métodos console.warn/error. Puede personalizar la lógica de registro proporcionando una LoggerClass y elegir el nivel de registro deseado mediante el parámetro level (el valor predeterminado es 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,
  }
})

Actualmente, el Client registrará los siguientes eventos:

• TRACE - información de bajo nivel sobre el ciclo de vida de los sockets Keep-Alive
• DEBUG - información de la respuesta (sin encabezados de autorización ni información del host)
• INFO - prácticamente no se usa; mostrará el nivel de registro actual cuando se inicialice el Client
• WARN - errores no fatales; una solicitud ping fallida se registra como advertencia, ya que el error subyacente se incluye en el resultado devuelto
• ERROR - errores fatales de los métodos query/insert/exec/command, como una solicitud fallida

Puede encontrar la implementación predeterminada de Logger aquí.

El Client de Node.js admite de forma opcional tanto TLS básico (solo autoridad de certificación) como TLS mutuo (autoridad de certificación y certificados de cliente).

Ejemplo de configuración de TLS básico, suponiendo que tiene los certificados en la carpeta certs y que el nombre del archivo de la CA es CA.pem:

const client = createClient({
  url: 'https://<hostname>:<port>',
  username: '<username>',
  password: '<password>', // if required
  tls: {
    ca_cert: fs.readFileSync('certs/CA.pem'),
  },
})

Ejemplo de configuración de TLS mutuo con certificados de cliente:

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`),
  },
})

Consulta en el repositorio los ejemplos completos de TLS básico y mutuo.

El Client habilita Keep-Alive en el agente HTTP subyacente de forma predeterminada, lo que significa que los sockets conectados se reutilizarán en solicitudes posteriores y que se enviará el encabezado Connection: keep-alive. Los sockets inactivos permanecerán en el pool de conexiones durante 2500 milisegundos de forma predeterminada (consulta las notas sobre cómo ajustar esta opción).

keep_alive.idle_socket_ttl debería tener un valor bastante menor que el de la configuración del servidor/LB. La razón principal es que, como HTTP/1.1 permite que el servidor cierre los sockets sin notificar al Client, si el servidor o el balanceador de carga cierra la conexión antes de que lo haga el Client, este podría intentar reutilizar el socket cerrado, lo que provocaría un error socket hang up.

Si estás modificando keep_alive.idle_socket_ttl, ten en cuenta que siempre debe estar sincronizado con la configuración de Keep-Alive de tu servidor/LB y que debe ser siempre menor que esta, para garantizar que el servidor nunca cierre primero la conexión abierta.

El Client establece keep_alive.idle_socket_ttl en 2500 milisegundos, ya que puede considerarse el valor predeterminado más seguro; del lado del servidor, keep_alive_timeout puede configurarse en un valor tan bajo como 3 segundos en versiones de ClickHouse anteriores a la 23.11 sin modificar config.xml.

Puedes encontrar el valor correcto del tiempo de espera de Keep-Alive en los encabezados de respuesta del servidor ejecutando el siguiente comando:

curl -is --data-binary "SELECT 1" <clickhouse_url>

Comprueba los valores de los encabezados Connection y Keep-Alive en la respuesta. Por ejemplo:

Connection: Keep-Alive
Keep-Alive: timeout=10

En este caso, keep_alive_timeout es de 10 segundos, y podrías intentar aumentar keep_alive.idle_socket_ttl a 9000 o incluso 9500 milisegundos para mantener los sockets inactivos abiertos un poco más de lo habitual. Presta atención a posibles errores de "Socket hang-up", ya que indicarían que el servidor cierra las conexiones antes de que lo haga el Client; reduce el valor hasta que los errores desaparezcan.

Si experimentas errores socket hang up incluso al usar la versión más reciente del Client, tienes las siguientes opciones para resolver este problema:

• Habilita los logs con un log level de al menos WARN (predeterminado). Esto te permitirá comprobar si hay algún stream sin consumir o colgando en el código de la aplicación: la capa de transporte lo registrará en el nivel WARN, ya que esto podría hacer que el servidor cierre el socket. Puedes habilitar el registro en la configuración del Client de la siguiente manera:

  const client = createClient({
    log: { level: ClickHouseLogLevel.WARN },
  })

• Asegúrate de que la configuración deseada se aplique a la instancia de Client correcta. Si tienes varias instancias de Client en tu aplicación, verifica de nuevo que la que usas para las consulta tenga el valor correcto de keep_alive.idle_socket_ttl.

• Reduce el ajuste keep_alive.idle_socket_ttl en la configuración del Client en 500 milisegundos. En determinadas situaciones, por ejemplo, cuando hay una latencia de red alta entre el Client y el servidor, esto puede resultar beneficioso, ya que evita el caso en el que una request saliente obtenga un socket que el servidor esté a punto de cerrar.

• Si este error se produce durante consulta de larga ejecución sin entrada ni salida de datos (por ejemplo, un INSERT FROM SELECT de larga ejecución), podría deberse a que un balanceador de carga u otros componentes de red cierran conexiones de larga duración o requests que tardan mucho en completarse. Puedes intentar forzar la entrada de algunos datos durante las consulta de larga ejecución usando una combinación de estos ajuste de ClickHouse:

  const client = createClient({
    // Aquí asumimos que tendremos algunas queries con más de 5 minutos de tiempo de ejecución
    request_timeout: 400_000,
    /** Estos ajustes en combinación permiten evitar problemas de timeout del LB en caso de queries de larga ejecución sin entrada ni salida de datos,
     *  como `INSERT FROM SELECT` y otras similares, ya que el balanceador de carga podría marcar la conexión como inactiva y cerrarla abruptamente.
     *  En este caso, asumimos que el LB tiene un timeout de conexión inactiva de 120 s, por lo que configuramos 110 s como un valor "seguro". */
    clickhouse_settings: {
      send_progress_in_http_headers: 1,
      http_headers_progress_interval_ms: '110000', // UInt64, debe pasarse como una cadena
    },
  })

  Ten en cuenta, sin embargo, que el tamaño total de los encabezados recibidos tiene un límite de 16 KB en las versiones recientes de Node.js; tras recibir cierta cantidad de encabezados de progreso, que en nuestras pruebas fue de alrededor de 70-80, se generará una excepción.

  También es posible usar un enfoque completamente distinto, evitando por completo el tiempo de espera en tránsito; esto puede lograrse aprovechando la “feature” de la HTTP interface por la que las mutations no se cancelan cuando se pierde la conexión. Consulta este Example (parte 2) para obtener más detalles.

• La funcionalidad Keep-Alive puede deshabilitarse por completo. En ese caso, el Client también añadirá el encabezado Connection: close a cada request, y el HTTP agent subyacente no reutilizará las conexiones. Se ignorará el ajuste keep_alive.idle_socket_ttl, ya que no habrá sockets inactivos. Esto generará una sobrecarga adicional, ya que se establecerá una nueva conexión para cada request.

  const client = createClient({
    keep_alive: {
      enabled: false,
    },
  })

• Descarta posibles problemas con el resto de la stack de red, incluido Node.js, ejecutando una prueba sencilla desde la línea de comandos con la misma instancia de ClickHouse y la misma ruta de red (es decir, desde la misma máquina o segmento de red, por ejemplo, un pod de Kubernetes), por ejemplo, usando curl:

  curl -is --user '<user>:<password>' --data-binary "SELECT 1" <clickhouse_url>

  Puede que te convenga ejecutarlo en un bucle durante varios minutos. Si ves errores similares en curl, es probable que el problema no esté relacionado con la configuración del Client, sino con la stack de red o con la configuración del servidor.

• Para probar la conexión con la funcionalidad nativa de Node.js, puedes intentar crear una request HTTP simple al servidor ClickHouse usando la API integrada fetch:

  const response = await fetch('<clickhouse_url>?query=SELECT+1', {
    method: 'POST',
    headers: {
      'Authorization': 'Basic ' + Buffer.from('<user>:<password>').toString('base64'),
    }
  })

• En algunos casos, el código de la aplicación o los adaptadores del framework pueden añadir un ping() preventivo antes de la ejecución real de la consulta, lo que puede provocar una situación en la que la solicitud ping() se complete correctamente, pero la solicitud de consulta posterior falle con un error "socket hang up" debido al mismo problema subyacente con las conexiones inactivas. Si observa ese patrón en los logs, compruebe si existe alguna opción para deshabilitar los pings preventivos en su framework o en el código de la aplicación. Esto también debería ayudar a reducir la probabilidad de que alguno de los componentes de red intermedios aplique limitación de tasa.

• Asegúrese de que la propia aplicación esté recibiendo suficiente tiempo de CPU y de que la red no esté siendo limitada por el proveedor de hosting. Distintos mecanismos de monitorización, como las métricas de pausas de GC, las métricas de retraso del bucle de eventos y otras similares, también pueden ser útiles para descartar posibles problemas de falta de recursos.

• Pruebe a revisar el código de su aplicación con la regla ESLint no-floating-promises habilitada, lo que ayudará a identificar promesas no gestionadas que podrían dar lugar a streams y sockets colgantes.

Al usar el Client con un usuario con readonly=1, no se puede habilitar la compresión de la respuesta, ya que requiere la configuración enable_http_compression. La siguiente configuración dará como resultado un error:

const client = createClient({
  compression: {
    response: true, // won't work with a readonly=1 user
  },
})

Consulta el ejemplo para ver más detalles sobre las limitaciones de los usuarios con readonly=1.

Si tu instancia de ClickHouse está detrás de un proxy y la URL incluye una ruta, como por ejemplo http://proxy:8123/clickhouse_server, especifica clickhouse_server como opción de configuración pathname (con o sin una barra inicial); de lo contrario, si se proporciona directamente en la url, se interpretará como la opción database. Se admiten varios segmentos, por ejemplo, /my_proxy/db.

const client = createClient({
  url: 'http://proxy:8123',
  pathname: '/clickhouse_server',
})

Si tiene un proxy inverso con autenticación delante de su implementación de ClickHouse, puede usar la configuración http_headers para proporcionar los encabezados necesarios:

const client = createClient({
  http_headers: {
    'My-Auth-Header': '...',
  },
})

De forma predeterminada, el Client configurará el agente HTTP o HTTPS subyacente mediante los ajustes proporcionados en la configuración del Client (como max_open_connections, keep_alive.enabled, tls), que se encargará de gestionar las conexiones al servidor de ClickHouse. Además, si se usan certificados TLS, el agente subyacente se configurará con los certificados necesarios y se aplicarán los encabezados correctos de autenticación TLS.

A partir de la versión 1.2.0, es posible proporcionar un agente HTTP o HTTPS personalizado al Client, en sustitución del agente subyacente predeterminado. Esto puede resultar útil en configuraciones de red complejas. Si se proporciona un agente personalizado, se aplican las siguientes condiciones:

• Las opciones max_open_connections y tls no tendrán efecto y el Client las ignorará, ya que forman parte de la configuración del agente subyacente.
• keep_alive.enabled solo regulará el valor predeterminado del encabezado Connection (true -> Connection: keep-alive, false -> Connection: close).
• Aunque la gestión de sockets keep-alive inactivos seguirá funcionando (ya que no está vinculada al agente, sino al propio socket), ahora es posible desactivarla por completo estableciendo el valor de keep_alive.idle_socket_ttl en 0.

Uso de un agente HTTP o HTTPS personalizado sin certificados:

const agent = new http.Agent({ // or https.Agent
  keepAlive: true,
  keepAliveMsecs: 2500,
  maxSockets: 10,
  maxFreeSockets: 10,
})
const client = createClient({
  http_agent: agent,
})

Uso de un agente HTTPS personalizado con TLS básico y un certificado de CA:

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

Uso de un agente HTTPS personalizado con TLS mutuo:

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

Con certificados y un agente HTTPS personalizado, probablemente sea necesario deshabilitar el encabezado de autorización predeterminado mediante la opción set_basic_auth_header (introducida en la versión 1.2.0), ya que entra en conflicto con los encabezados TLS. Todos los encabezados TLS deben proporcionarse manualmente.

• No hay mapeadores de datos para los conjuntos de resultados, por lo que solo se usan primitivos del lenguaje. Está previsto añadir mapeadores para determinados tipos de datos con soporte para RowBinary format.
• Existen algunas consideraciones sobre los tipos de datos Decimal* y Date* / DateTime*.
• Al usar formatos de la familia JSON*, los números mayores que Int32 se representan como cadenas, ya que los valores máximos de los tipos Int64+ son mayores que Number.MAX_SAFE_INTEGER. Consulta la sección Tipos integrales para obtener más detalles.

• El streaming de las consultas SELECT funciona, pero está deshabilitado para las inserciones (también a nivel de tipo).
• La compresión de solicitudes está deshabilitada y la configuración se ignora. La compresión de respuestas funciona.
• Todavía no hay soporte para registro.

• Para reducir el consumo de memoria de la aplicación, considere usar streams para inserciones grandes (p. ej., desde archivos) y consultas cuando corresponda. Para listeners de eventos y casos de uso similares, los async inserts pueden ser otra buena opción, ya que permiten minimizar, o incluso evitar por completo, el batching del lado del Client. Hay ejemplos de async insert disponibles en el repositorio del Client, con async_insert_ como prefijo del nombre de archivo.
• El Client no habilita la compresión de solicitudes ni de respuestas de forma predeterminada. Sin embargo, al consultar o insertar grandes volúmenes de datos, podría considerar habilitarla mediante ClickHouseClientConfigOptions.compression (ya sea solo para request o response, o para ambos).
• La compresión tiene un costo significativo en el rendimiento. Habilitarla para request o response afectará negativamente a la velocidad de las consultas o las inserciones, respectivamente, pero reducirá la cantidad de tráfico de red transferido por la aplicación.

Si tienes alguna pregunta o necesitas ayuda, no dudes en ponerte en contacto con nosotros en el Slack de la comunidad (canal #clickhouse-js) o a través de issues de GitHub.