O cliente JS oficial para se conectar ao ClickHouse.
O cliente é escrito em TypeScript e fornece tipos para a API pública do cliente.
Ele não tem nenhuma dependência, é otimizado para desempenho máximo e é testado com várias versões e configurações do ClickHouse (nó único on-premise, cluster on-premise e ClickHouse Cloud).
Há duas versões diferentes do cliente disponíveis para ambientes distintos:
@clickhouse/client - somente Node.js@clickhouse/client-web - navegadores (Chrome/Firefox), Cloudflare Workers
Ao usar TypeScript, certifique-se de usar no mínimo a versão 4.5, que habilita a sintaxe inline de import e export.
O código-fonte do cliente está disponível no repositório do GitHub ClickHouse-JS.
skills para agentes de IAO cliente JS inclui skills para agentes de IA que podem ajudar agentes de codificação a usar o cliente. Instale-as com:npm skills add ClickHouse/clickhouse-js
Requisitos de ambiente (node.js)
| Versão do Node.js | Compatível? |
|---|
| 24.x | ✔ |
| 22.x | ✔ |
| 20.x | ✔ |
| 18.x | Melhor esforço |
Requisitos de ambiente (web)
npm i @clickhouse/client-web
| Versão do cliente | ClickHouse |
|---|
| 1.12.0 | 24.8+ |
Criando uma instância de cliente
createClient:
import { createClient } from '@clickhouse/client' // ou '@clickhouse/client-web'
const client = createClient({
/* configuração */
})
const { createClient } = require('@clickhouse/client');
const client = createClient({
/* configuração */
})
| Configuração | Descrição | Valor padrão | Veja também | |
|---|
| url?: string | A URL de uma instância do ClickHouse. | http://localhost:8123 | Documentação de configuração de URL | |
| pathname?: string | Um caminho opcional para adicionar à URL do ClickHouse após ela ser processada pelo cliente. | '' | Documentação de proxy com caminho | |
| request_timeout?: number | O timeout da requisição em milissegundos. | 30_000 | - | |
compression?: { **response**?: boolean; **request**?: boolean } | Ativa a compressão. | - | Documentação de compressão | |
| username?: string | O nome do usuário em nome de quem as requisições são feitas. | default | - | |
| password?: string | A senha do usuário. | '' | - | |
| application?: string | O nome da aplicação que usa o cliente Node.js. | clickhouse-js | - | |
| database?: string | O nome do banco de dados a ser usado. | default | - | |
| clickhouse_settings?: ClickHouseSettings | Configurações do ClickHouse a serem aplicadas a todas as requisições. | {} | - | |
log?: { **LoggerClass**?: Logger, **level**?: ClickHouseLogLevel } | Configuração dos logs internos do cliente. | - | Documentação de logging | |
| session_id?: string | ID de sessão opcional do ClickHouse para enviar com cada requisição. | - | - | |
keep_alive?: { **enabled**?: boolean } | Ativado por padrão nas versões Node.js e Web. | - | - | |
http_headers?: Record<string, string> | HTTP headers adicionais para as requisições enviadas ao ClickHouse. | - | Documentação de proxy reverso com autenticação | |
| roles?: string | string[] | Nomes de roles do ClickHouse para associar às requisições enviadas. | - | Uso de roles com a interface HTTP |
Parâmetros de configuração específicos do Node.js
| Configuração | Descrição | Valor padrão | Veja também | |
|---|
| max_open_connections?: number | Número máximo de sockets conectados permitidos por host. | 10 | - | |
tls?: { **ca_cert**: Buffer, **cert**?: Buffer, **key**?: Buffer } | Configura certificados TLS. | - | documentação de TLS | |
keep_alive?: { **enabled**?: boolean, **idle_socket_ttl**?: number } | - | - | documentação do Keep Alive | |
| http_agent?: http.Agent | https.Agent
| Agente HTTP personalizado para o cliente. | - | documentação do agente HTTP |
set_basic_auth_header?: boolean
| Define o cabeçalho Authorization com as credenciais de autenticação básica. | true | uso desta configuração na documentação do agente HTTP | |
A configuração de URL sempre sobrescreverá os valores definidos no código, e um aviso será registrado no log nesse caso.
http[s]://[username:password@]hostname:port[/database][?param1=value1¶m2=value2]. Em quase todos os casos, o nome de um determinado parâmetro reflete seu caminho na interface de opções de configuração, com algumas exceções. Há suporte para os seguintes parâmetros:
| Parâmetro | Tipo |
|---|
pathname | uma string arbitrária. |
application_id | uma string arbitrária. |
session_id | uma string arbitrária. |
request_timeout | número não negativo. |
max_open_connections | número não negativo, maior que zero. |
compression_request | booleano. Veja abaixo (1) |
compression_response | booleano. |
log_level | valores permitidos: OFF, TRACE, DEBUG, INFO, WARN, ERROR. |
keep_alive_enabled | booleano. |
clickhouse_setting_* ou ch_* | veja abaixo (2) |
http_header_* | veja abaixo (3) |
(somente Node.js) keep_alive_idle_socket_ttl | número não negativo. |
- (1) Para booleanos, os valores válidos são
true/1 e false/0.
- (2) Qualquer parâmetro com o prefixo
clickhouse_setting_ ou ch_ terá esse prefixo removido, e o restante será adicionado a clickhouse_settings do cliente. Por exemplo, ?ch_async_insert=1&ch_wait_for_async_insert=1 será o mesmo que:
createClient({
clickhouse_settings: {
async_insert: 1,
wait_for_async_insert: 1,
},
})
clickhouse_settings devem ser informados como 1/0 na URL.
- (3) Semelhante a (2), mas para a configuração
http_header. Por exemplo, ?http_header_x-clickhouse-auth=foobar equivale a:
createClient({
http_headers: {
'x-clickhouse-auth': 'foobar',
},
})
Reúna os detalhes da conexão
| Parâmetro(s) | Descrição |
|---|
HOST and PORT | Normalmente, a porta é 8443 ao usar TLS ou 8123 quando não se usa TLS. |
DATABASE NAME | Por padrão, há um banco de dados chamado default; use o nome do banco de dados ao qual você deseja se conectar. |
USERNAME and PASSWORD | Por padrão, o nome de usuário é default. Use o nome de usuário apropriado para o seu caso de uso. |
curl de exemplo.
Se você estiver usando ClickHouse autogerenciado, os detalhes de conexão são definidos pelo administrador do seu ClickHouse.
O cliente implementa uma conexão por meio do protocolo HTTP ou HTTPS. O suporte a RowBinary está previsto; consulte a issue relacionada.
O exemplo a seguir demonstra como configurar uma conexão com o ClickHouse Cloud. Ele pressupõe que os valores de url (incluindo
protocolo e porta) e password sejam especificados por meio de variáveis de ambiente, e que o usuário default seja usado.
Exemplo: Criando uma instância do cliente Node.js usando variáveis de ambiente na configuração.
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 conexões (somente Node.js)
10, mas você pode alterá-lo com a opção de configuração max_open_connections.
Não há garantia de que a mesma conexão do pool será usada em consultas subsequentes, a menos que o usuário defina max_open_connections: 1. Isso raramente é necessário, mas pode ser exigido em casos em que os usuários estejam usando tabelas temporárias.
Veja também: configuração de Keep-Alive.
Todo método que envia uma consulta ou uma instrução (command, exec, insert, select) fornecerá query_id no resultado. Esse identificador exclusivo é atribuído pelo cliente a cada consulta e pode ser útil para obter os dados de system.query_log,
se ele estiver habilitado na configuração do servidor, ou para cancelar consultas de longa duração (veja o exemplo). Se necessário, o query_id pode ser substituído pelo usuário nos parâmetros dos métodos command/query/exec/insert.
Se você estiver substituindo o parâmetro query_id, precisará garantir que ele seja exclusivo em cada chamada. Um UUID aleatório é uma boa escolha.
Parâmetros base para todos os métodos do cliente
interface BaseQueryParams {
// Configurações do ClickHouse que podem ser aplicadas no nível da consulta.
clickhouse_settings?: ClickHouseSettings
// Parâmetros para vinculação de consulta.
query_params?: Record<string, unknown>
// Instância de AbortSignal para cancelar uma consulta em andamento.
abort_signal?: AbortSignal
// Substituição de query_id; se não especificado, um identificador aleatório será gerado automaticamente.
query_id?: string
// Substituição de session_id; se não especificado, o id de sessão será obtido da configuração do cliente.
session_id?: string
// Substituição de credenciais; se não especificado, as credenciais do cliente serão utilizadas.
auth?: { username: string, password: string }
// Uma lista específica de roles a serem usadas para esta consulta. Substitui as roles definidas na configuração do cliente.
role?: string | Array<string>
}
SELECT, ou para enviar DDLs, como CREATE TABLE, e deve ser aguardado. Espera-se que o conjunto de resultados retornado seja consumido pela aplicação.
Há um método dedicado, insert, para inserção de dados, e command, para DDLs. interface QueryParams extends BaseQueryParams {
// Consulta a ser executada que pode retornar dados.
query: string
// Formato do conjunto de dados resultante. Padrão: JSON.
format?: DataFormat
}
interface ClickHouseClient {
query(params: QueryParams): Promise<ResultSet>
}
Não especifique a cláusula FORMAT em query; use o parâmetro format no lugar.
Abstrações de conjunto de resultados e linhas
ResultSet fornece vários métodos práticos para o processamento de dados na sua aplicação.
A implementação de ResultSet no Node.js usa Stream.Readable internamente, enquanto a versão web usa a Web API ReadableStream.
Você pode consumir o ResultSet chamando os métodos text ou json em ResultSet e carregar na memória todo o conjunto de linhas retornado pela consulta.
Você deve começar a consumir o ResultSet o quanto antes, pois ele mantém o fluxo de resposta aberto e, consequentemente, a conexão subjacente ocupada. O cliente não armazena os dados recebidos em buffer para evitar um possível uso excessivo de memória pela aplicação.
Como alternativa, se ele for grande demais para caber na memória de uma só vez, você pode chamar o método stream e processar os dados em modo de streaming. Nesse caso, cada fragmento da resposta será transformado em arrays relativamente pequenos de linhas (o tamanho desse array depende do tamanho de um fragmento específico que o cliente recebe do servidor, já que ele pode variar, e do tamanho de uma linha individual), um fragmento por vez.
Consulte a lista de formatos de dados compatíveis para determinar qual é o melhor formato para streaming no seu caso. Por exemplo, se você quiser processar objetos JSON em streaming, pode escolher JSONEachRow, e cada linha será analisada como um objeto JS ou, talvez, o formato mais compacto JSONCompactColumns, no qual cada linha será um array compacto de valores. Veja também: arquivos em streaming.
Se o ResultSet ou seu fluxo não for consumido por completo, ele será destruído após o período de inatividade de request_timeout.
interface BaseResultSet<Stream> {
// Veja a seção "Query ID" acima
query_id: string
// Consome o stream inteiro e retorna o conteúdo como uma string
// Pode ser usado com qualquer DataFormat
// Deve ser chamado apenas uma vez
text(): Promise<string>
// Consome o stream inteiro e faz o parse do conteúdo como um objeto JS
// Pode ser usado apenas com formatos JSON
// Deve ser chamado apenas uma vez
json<T>(): Promise<T>
// Retorna um stream legível para respostas que suportam streaming
// Cada iteração sobre o stream fornece um array de Row[] no DataFormat selecionado
// Deve ser chamado apenas uma vez
stream(): Stream
}
interface Row {
// Retorna o conteúdo da linha como uma string simples
text: string
// Faz o parse do conteúdo da linha como um objeto JS
json<T>(): T
}
JSONEachRow, consumindo todo o fluxo e interpretando o conteúdo como objetos JS.
Código-fonte.
const resultSet = await client.query({
query: 'SELECT * FROM my_table',
format: 'JSONEachRow',
})
const dataset = await resultSet.json() // ou `row.text` para evitar o parsing do JSON
JSONEachRow, usando a abordagem clássica on('data'). Isso pode ser usado de forma intercambiável com a sintaxe for await const. Código-fonte.
const rows = await client.query({
query: 'SELECT number FROM system.numbers_mt LIMIT 5',
format: 'JSONEachRow', // ou JSONCompactEachRow, JSONStringsEachRow, etc.
})
const stream = rows.stream()
stream.on('data', (rows: Row[]) => {
rows.forEach((row: Row) => {
console.log(row.json()) // ou `row.text` para evitar o parsing do JSON
})
})
await new Promise((resolve, reject) => {
stream.on('end', () => {
console.log('Completed!')
resolve(0)
})
stream.on('error', reject)
})
CSV usando a abordagem clássica com on('data'). Isso pode ser usado de forma intercambiável com a sintaxe for await const.
Código-fonte
const resultSet = await client.query({
query: 'SELECT number FROM system.numbers_mt LIMIT 5',
format: 'CSV', // ou 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, consumidos com a sintaxe for await const. Isso pode ser usado de forma intercambiável com a abordagem clássica on('data').
Código-fonte.
const resultSet = await client.query({
query: 'SELECT number FROM system.numbers LIMIT 10',
format: 'JSONEachRow', // ou JSONCompactEachRow, JSONStringsEachRow, etc.
})
for await (const rows of resultSet.stream()) {
rows.forEach(row => {
console.log(row.json())
})
}
A sintaxe for await const tem um pouco menos de código do que a abordagem on('data'), mas pode ter um impacto negativo no desempenho.
Veja esta issue no repositório do Node.js para mais detalhes. 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())
})
}
export interface InsertResult {
query_id: string
executed: boolean
}
interface ClickHouseClient {
insert(params: InsertParams): Promise<InsertResult>
}
insert, a instrução insert não será enviada ao servidor; em vez disso, o método será resolvido imediatamente com { query_id: '...', executed: false }. Se o query_id não tiver sido fornecido nos parâmetros do método nesse caso, ele será uma string vazia no resultado, já que retornar um UUID aleatório gerado pelo cliente poderia causar confusão, pois a consulta com esse query_id não existirá na tabela system.query_log.
Se a instrução insert tiver sido enviada ao servidor, o sinalizador executed será true.
Método insert e streaming no Node.js
Stream.Readable quanto com um Array<T> simples, dependendo do formato de dados especificado no método insert. Veja também esta seção sobre streaming de arquivos.
O método insert deve ser aguardado com await; no entanto, é possível especificar um stream de entrada e aguardar a operação insert mais tarde, apenas quando o stream for concluído (o que também resolverá a promise de insert). Isso pode ser útil para listeners de eventos e cenários semelhantes, mas o tratamento de erros pode não ser trivial, com vários casos de borda no lado do cliente. Em vez disso, considere usar async inserts, como mostrado neste exemplo.
interface InsertParams<T> extends BaseQueryParams {
// Nome da tabela na qual os dados serão inseridos
table: string
// Um dataset a ser inserido.
values: ReadonlyArray<T> | Stream.Readable
// Formato do dataset a ser inserido.
format?: DataFormat
// Permite especificar em quais colunas os dados serão inseridos.
// - Um array como `['a', 'b']` irá gerar: `INSERT INTO table (a, b) FORMAT DataFormat`
// - Um objeto como `{ except: ['a', 'b'] }` irá gerar: `INSERT INTO table (* EXCEPT (a, b)) FORMAT DataFormat`
// Por padrão, os dados são inseridos em todas as colunas da tabela,
// e a instrução gerada será: `INSERT INTO table FORMAT DataFormat`.
columns?: NonEmptyArray<string> | { except: NonEmptyArray<string> }
}
Uma requisição cancelada com abort_signal não garante que não tenha havido inserção de dados, pois o servidor pode ter recebido parte dos dados enviados em streaming antes do cancelamento.
await client.insert({
table: 'my_table',
// a estrutura deve corresponder ao formato desejado, JSONEachRow neste exemplo
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',
})
INSERT.
Considere uma definição de tabela como a seguinte:
CREATE OR REPLACE TABLE mytable
(id UInt32, message String)
ENGINE MergeTree()
ORDER BY (id)
// Instrução gerada: INSERT INTO mytable (message) FORMAT JSONEachRow
await client.insert({
table: 'mytable',
values: [{ message: 'foo' }],
format: 'JSONEachRow',
// o valor da coluna `id` nesta linha será zero (padrão para UInt32)
columns: ['message'],
})
// Instrução gerada: INSERT INTO mytable (* EXCEPT (message)) FORMAT JSONEachRow
await client.insert({
table: tableName,
values: [{ id: 144 }],
format: 'JSONEachRow',
// O valor da coluna `message` para esta linha será uma string vazia
columns: {
except: ['message'],
},
})
await client.insert({
table: 'mydb.mytable', // Nome totalmente qualificado, incluindo o banco de dados
values: [{ id: 42, message: 'foo' }],
format: 'JSONEachRow',
})
@clickhouse/client-web funcionam apenas com os formatos Array<T> e JSON*.
A inserção via streams ainda não é compatível com a versão web devido à baixa compatibilidade dos navegadores.
Consequentemente, a interface InsertParams da versão web é ligeiramente diferente da versão do Node.js,
pois values se limitam ao tipo ReadonlyArray<T>:
interface InsertParams<T> extends BaseQueryParams {
// Nome da tabela na qual os dados serão inseridos
table: string
// Um dataset a ser inserido.
values: ReadonlyArray<T>
// Formato do dataset a ser inserido.
format?: DataFormat
// Permite especificar em quais colunas os dados serão inseridos.
// - Um array como `['a', 'b']` irá gerar: `INSERT INTO table (a, b) FORMAT DataFormat`
// - Um objeto como `{ except: ['a', 'b'] }` irá gerar: `INSERT INTO table (* EXCEPT (a, b)) FORMAT DataFormat`
// Por padrão, os dados são inseridos em todas as colunas da tabela,
// e a instrução gerada será: `INSERT INTO table FORMAT DataFormat`.
columns?: NonEmptyArray<string> | { except: NonEmptyArray<string> }
}
CREATE TABLE ou ALTER TABLE.
Deve-se aguardar sua conclusão.
O fluxo de resposta é destruído imediatamente, o que significa que o socket subjacente é liberado.
interface CommandParams extends BaseQueryParams {
// Instrução a ser executada.
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)
`,
// Recomendado para uso em cluster para evitar situações em que ocorre um erro no processamento da consulta após o código de resposta,
// e os headers HTTP já foram enviados ao cliente.
// Consulte 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'`,
})
Uma solicitação cancelada com abort_signal não garante que a instrução não tenha sido executada pelo servidor.
query/insert
e quiser o resultado, pode usar exec como alternativa a command.
exec retorna um stream de leitura que DEVE ser consumido ou destruído pela aplicação.
interface ExecParams extends BaseQueryParams {
// Instrução a ser executada.
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, usado para verificar o status da conectividade, retorna true se o servidor puder ser acessado.
Se o servidor estiver inacessível, o erro subjacente também será incluído no resultado.
type PingResult =
| { success: true }
| { success: false; error: Error }
/** Parâmetros para a requisição de verificação de integridade - usando o endpoint `/ping` integrado.
* Este é o comportamento padrão para a versão Node.js. */
export type PingParamsWithEndpoint = {
select: false
/** Instância de AbortSignal para cancelar uma requisição em andamento. */
abort_signal?: AbortSignal
/** HTTP headers adicionais para incluir nesta requisição específica. */
http_headers?: Record<string, string>
}
/** Parâmetros para a requisição de verificação de integridade - usando uma consulta SELECT.
* Este é o comportamento padrão para a versão Web, pois o endpoint `/ping` não suporta CORS.
* A maioria dos parâmetros padrão do método `query`, como `query_id`, `abort_signal`, `http_headers`, etc., funcionará,
* exceto `query_params`, que não faz sentido ser permitido neste método. */
export type PingParamsWithSelectQuery = { select: true } & Omit<
BaseQueryParams,
'query_params'
>
export type PingParams = PingParamsWithEndpoint | PingParamsWithSelectQuery
interface ClickHouseClient {
ping(params?: PingParams): Promise<PingResult>
}
/ping, enquanto a versão Web usa uma consulta SELECT 1 simples para obter um resultado semelhante, já que o endpoint /ping não oferece suporte a CORS.
Exemplo: (Node.js/Web) Um ping simples para a instância do servidor ClickHouse. Observação: para a versão Web, os erros capturados serão diferentes.
Código-fonte.
const result = await client.ping();
if (!result.success) {
// tratar result.error
}
ping ou especificar parâmetros adicionais, como query_id, poderá usá-lo da seguinte forma:
const result = await client.ping({ select: true, /* query_id, abort_signal, http_headers, ou qualquer outro parâmetro de consulta */ });
query — consulte a definição de tipo PingParamsWithSelectQuery.
Fecha todas as conexões abertas e libera recursos. Não tem efeito na versão web.
Streaming de arquivos (apenas Node.js)
query (JSONEachRow, CSV etc.) e o nome do arquivo de saída.
O cliente trata formatos de dados como JSON ou texto.
Se você especificar format como um dos formatos da família JSON (JSONEachRow, JSONCompactEachRow etc.), o cliente serializará e desserializará os dados durante a comunicação via wire.
Os dados fornecidos nos formatos de texto “brutos” (famílias CSV, TabSeparated e CustomSeparated) são enviados via wire sem transformações adicionais.
Pode haver confusão entre JSON como formato geral e o formato JSON do ClickHouse.O cliente oferece suporte a streaming de objetos JSON com formatos como JSONEachRow (consulte a tabela abaixo para ver outros formatos compatíveis com streaming; consulte também os exemplos select_streaming_ no repositório do cliente).Apenas formatos como ClickHouse JSON e alguns outros são representados como um único objeto na resposta e não podem ser transmitidos por streaming pelo cliente. | Formato | Entrada (array) | Entrada (objeto) | Entrada/Saída (Stream) | Saída (JSON) | Saída (texto) |
|---|
| JSON | ❌ | ✔️ | ❌ | ✔️ | ✔️ |
| JSONCompact | ❌ | ✔️ | ❌ | ✔️ | ✔️ |
| JSONObjectEachRow | ❌ | ✔️ | ❌ | ✔️ | ✔️ |
| JSONColumnsWithMetadata | ❌ | ✔️ | ❌ | ✔️ | ✔️ |
| JSONStrings | ❌ | ❌️ | ❌ | ✔️ | ✔️ |
| JSONCompactStrings | ❌ | ❌ | ❌ | ✔️ | ✔️ |
| JSONEachRow | ✔️ | ❌ | ✔️ | ✔️ | ✔️ |
| JSONEachRowWithProgress | ❌️ | ❌ | ✔️ ❗- veja abaixo | ✔️ | ✔️ |
| JSONStringsEachRow | ✔️ | ❌ | ✔️ | ✔️ | ✔️ |
| JSONCompactEachRow | ✔️ | ❌ | ✔️ | ✔️ | ✔️ |
| JSONCompactStringsEachRow | ✔️ | ❌ | ✔️ | ✔️ | ✔️ |
| JSONCompactEachRowWithNames | ✔️ | ❌ | ✔️ | ✔️ | ✔️ |
| JSONCompactEachRowWithNamesAndTypes | ✔️ | ❌ | ✔️ | ✔️ | ✔️ |
| JSONCompactStringsEachRowWithNames | ✔️ | ❌ | ✔️ | ✔️ | ✔️ |
| JSONCompactStringsEachRowWithNamesAndTypes | ✔️ | ❌ | ✔️ | ✔️ | ✔️ |
| CSV | ❌ | ❌ | ✔️ | ❌ | ✔️ |
| CSVWithNames | ❌ | ❌ | ✔️ | ❌ | ✔️ |
| CSVWithNamesAndTypes | ❌ | ❌ | ✔️ | ❌ | ✔️ |
| TabSeparated | ❌ | ❌ | ✔️ | ❌ | ✔️ |
| TabSeparatedRaw | ❌ | ❌ | ✔️ | ❌ | ✔️ |
| TabSeparatedWithNames | ❌ | ❌ | ✔️ | ❌ | ✔️ |
| TabSeparatedWithNamesAndTypes | ❌ | ❌ | ✔️ | ❌ | ✔️ |
| CustomSeparated | ❌ | ❌ | ✔️ | ❌ | ✔️ |
| CustomSeparatedWithNames | ❌ | ❌ | ✔️ | ❌ | ✔️ |
| CustomSeparatedWithNamesAndTypes | ❌ | ❌ | ✔️ | ❌ | ✔️ |
| Parquet | ❌ | ❌ | ✔️ | ❌ | ✔️❗- veja abaixo |
SELECT provavelmente será gravar o fluxo resultante em um arquivo. Veja o exemplo no repositório da biblioteca cliente.
JSONEachRowWithProgress é um formato somente de saída compatível com o envio de informações de progresso no fluxo. Veja este exemplo para mais detalhes.
A lista completa de formatos de entrada e saída do ClickHouse está disponível
aqui.
Tipos de dados do ClickHouse suportados
O tipo JS correspondente se aplica a quaisquer formatos JSON*, exceto aos que representam tudo como string (por exemplo, JSONStringEachRow)
| Tipo | Status | Tipo JS |
|---|
| UInt8/16/32 | ✔️ | number |
| UInt64/128/256 | ✔️ ❗- veja abaixo | string |
| Int8/16/32 | ✔️ | number |
| Int64/128/256 | ✔️ ❗- veja abaixo | string |
| Float32/64 | ✔️ | number |
| Decimal | ✔️ ❗- veja abaixo | number |
| Boolean | ✔️ | boolean |
| String | ✔️ | string |
| FixedString | ✔️ | string |
| UUID | ✔️ | string |
| Date32/64 | ✔️ | string |
| DateTime32/64 | ✔️ ❗- veja abaixo | string |
| Enum | ✔️ | string |
| LowCardinality | ✔️ | string |
| Array(T) | ✔️ | T[] |
| (new) JSON | ✔️ | object |
| Variant(T1, T2…) | ✔️ | T (depende da variante) |
| Dynamic | ✔️ | T (depende da variante) |
| Nested | ✔️ | T[] |
| Tuple(T1, T2, …) | ✔️ | [T1, T2, …] |
| Tuple(n1 T1, n2 T2…) | ✔️ | { n1: T1; n2: T2; …} |
| Nullable(T) | ✔️ | tipo JS para 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 |
Ressalvas sobre os tipos Date/Date32
Date/Date32 só podem ser inseridas como
strings.
Exemplo: Insira um valor do tipo Date.
Código-fonte
await client.insert({
table: 'my_table',
values: [ { date: '2022-09-05' } ],
format: 'JSONEachRow',
})
DateTime ou DateTime64, poderá usar tanto strings quanto objetos Date do JS. Objetos Date do JS podem ser passados para insert sem alterações, com date_time_input_format definido como best_effort. Veja este exemplo para mais detalhes.
Ressalvas sobre os tipos Decimal*
JSON*. Supondo que tenhamos uma tabela 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)
await client.insert({
table: 'my_table',
values: [{
id: 1,
dec32: '1234567.89',
dec64: '123456789123456.789',
dec128: '1234567891234567891234567891.1234567891',
dec256: '12345678912345678912345678911234567891234567891234567891.12345678911234567891',
}],
format: 'JSONEachRow',
})
JSON*, o ClickHouse retorna valores Decimal como números por padrão, o que pode causar perda de precisão. Para evitar isso, você pode converter os valores Decimal em string na 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',
})
Tipos integrais: Int64, Int128, Int256, UInt64, UInt128, UInt256
JSON* para evitar
estouro de inteiros, já que os valores máximos desses tipos são maiores que Number.MAX_SAFE_INTEGER.
Esse comportamento, no entanto, pode ser modificado
com a configuração output_format_json_quote_64bit_integers
.
Exemplo: Ajuste o formato de saída 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 } ])
Configurações do ClickHouse
const client = createClient({
clickhouse_settings: {}
})
client.query({
clickhouse_settings: {}
})
Certifique-se de que o usuário em nome do qual as consultas são feitas tenha permissões suficientes para alterar as configurações.
name — Identificador do placeholder.data_type - Tipo de dado do valor do parâmetro da aplicação.
Exemplo:: Consulta com parâmetros.
Código-fonte
.
await client.query({
query: 'SELECT plus({val1: Int32}, {val2: Int32})',
format: 'CSV',
query_params: {
val1: 10,
val2: 20,
},
})
GZIP é compatível por meio de zlib.
createClient({
compression: {
response: true,
request: true
}
})
response: true instrui o servidor ClickHouse a responder com o corpo da resposta comprimido. Valor padrão: response: falserequest: true ativa a compressão no corpo da requisição do cliente. Valor padrão: request: false
Logging (apenas para Node.js)
O logging é um recurso experimental e está sujeito a alterações futuras.
logger emite registros de log em stdout por meio dos métodos console.debug/info e em stderr por meio dos métodos console.warn/error.
Você pode personalizar a lógica de logging fornecendo uma LoggerClass e escolher o nível de log desejado por meio do parâmetro level (o padrão é WARN):
import type { Logger } from '@clickhouse/client'
// Todos os três tipos de LogParams são exportados pelo cliente
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 - informações de baixo nível sobre o ciclo de vida dos sockets Keep-AliveDEBUG - informações da resposta (sem os headers de autorização nem informações do host)INFO - praticamente não é usado; exibirá o nível de log atual quando o cliente for inicializadoWARN - erros não fatais; uma solicitação ping com falha é registrada como aviso, pois o erro subjacente está incluído no resultado retornadoERROR - erros fatais dos métodos query/insert/exec/command, como uma solicitação com falha
Você pode encontrar a implementação padrão de Logger aqui.
Certificados TLS (somente para Node.js)
certs
e que o nome do arquivo da CA seja CA.pem:
const client = createClient({
url: 'https://<hostname>:<port>',
username: '<username>',
password: '<password>', // se necessário
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`),
},
})
Configuração de Keep-Alive (somente Node.js)
Connection: keep-alive será enviado. Os sockets ociosos permanecerão no connection pool por 2500 milissegundos por padrão (veja as notas sobre como ajustar esta opção).
Espera-se que keep_alive.idle_socket_ttl tenha um valor consideravelmente menor do que a configuração do servidor/LB. O principal motivo é que, como o HTTP/1.1 permite que o servidor feche os sockets sem notificar o cliente, se o servidor ou o balanceador de carga fechar a connection antes de o cliente fazer isso, o cliente poderá tentar reutilizar o socket fechado, resultando em um erro socket hang up.
Se você estiver modificando keep_alive.idle_socket_ttl, tenha em mente que ele deve estar sempre em sincronia com a configuração de Keep-Alive do seu servidor/LB e deve ser sempre menor do que ela, garantindo que o servidor nunca feche primeiro a connection aberta.
Ajustando idle_socket_ttl
keep_alive.idle_socket_ttl como 2500 milissegundos, por ser considerado o padrão mais seguro; no lado do servidor, keep_alive_timeout pode estar definido em apenas 3 segundos em versões do ClickHouse anteriores à versão 23.11 sem modificações no config.xml.
Se você está satisfeito com o desempenho e não enfrenta nenhum problema, é recomendável não aumentar o valor da configuração keep_alive.idle_socket_ttl, pois isso pode levar a erros de “Socket hang-up”; além disso, se sua aplicação envia muitas consultas e não há muito tempo de inatividade entre elas, o valor padrão deve ser suficiente, já que os sockets não ficarão ociosos por tempo suficiente, e o cliente os manterá no pool.
curl -is --data-binary "SELECT 1" <clickhouse_url>
Connection e Keep-Alive na resposta. Por exemplo:
Connection: Keep-Alive
Keep-Alive: timeout=10
keep_alive_timeout é de 10 segundos, e você pode tentar aumentar keep_alive.idle_socket_ttl para 9000 ou até 9500 milissegundos para manter os sockets ociosos abertos por um pouco mais de tempo do que o padrão. Fique atento a possíveis erros de “Socket hang-up”, que indicam que o servidor fecha as conexões antes do cliente, e reduza o valor até que os erros desapareçam.
Se você estiver enfrentando erros socket hang up mesmo usando a versão mais recente do cliente, há as seguintes opções para resolver esse problema:
-
Habilite logs com pelo menos o nível de log
WARN (padrão). Isso permitirá verificar se há algum stream não consumido ou pendente no código da aplicação: a camada de transporte registrará isso no nível WARN, pois isso pode fazer com que o socket seja fechado pelo servidor. Você pode habilitar o logging na configuração do cliente da seguinte forma:
const client = createClient({
log: { level: ClickHouseLogLevel.WARN },
})
-
Certifique-se de que a configuração desejada está sendo aplicada à instância correta do cliente. Se você tiver várias instâncias de cliente na sua aplicação, verifique novamente se aquela que está usando para consultas tem o valor correto de
keep_alive.idle_socket_ttl.
-
Reduza a configuração
keep_alive.idle_socket_ttl em 500 milissegundos na configuração do cliente. Em certas situações, por exemplo, alta latência de rede entre cliente e servidor, isso pode ser benéfico, pois elimina o cenário em que uma requisição de saída obtém um socket que o servidor está prestes a fechar.
-
Se esse erro estiver acontecendo durante consultas de longa duração sem entrada ou saída de dados (por exemplo, um
INSERT FROM SELECT de longa duração), isso pode ser causado por um balanceador de carga ou outros componentes de rede fechando conexões de longa duração ou requisições demoradas. Você pode tentar forçar a entrada de alguns dados durante consultas de longa duração usando uma combinação destas configurações do ClickHouse:
const client = createClient({
// Aqui assumimos que teremos algumas consultas com mais de 5 minutos de tempo de execução
request_timeout: 400_000,
/** Estas configurações em conjunto ajudam a evitar problemas de timeout do LB em consultas de longa duração sem entrada ou saída de dados,
* como `INSERT FROM SELECT` e outras semelhantes, já que a conexão pode ser marcada como idle pelo LB e fechada abruptamente.
* Neste caso, assumimos que o LB tem timeout de conexão idle de 120s, então definimos 110s como um valor "seguro". */
clickhouse_settings: {
send_progress_in_http_headers: 1,
http_headers_progress_interval_ms: '110000', // UInt64, deve ser passado como string
},
})
-
O recurso Keep-Alive pode ser desabilitado totalmente. Nesse caso, o cliente também adicionará o header
Connection: close a cada requisição, e o agente HTTP subjacente não reutilizará as conexões. A configuração keep_alive.idle_socket_ttl será ignorada, pois não haverá sockets em estado idle. Isso resultará em sobrecarga adicional, pois uma nova conexão será estabelecida para cada requisição.
const client = createClient({
keep_alive: {
enabled: false,
},
})
-
Descarte possíveis problemas com o restante da pilha de rede, incluindo o próprio Node.js, executando um teste simples em linha de comando com a mesma instância do ClickHouse e o mesmo caminho de rede (ou seja, a partir da mesma máquina ou segmento de rede, por exemplo, um pod do Kubernetes), por exemplo, usando
curl:
curl -is --user '<user>:<password>' --data-binary "SELECT 1" <clickhouse_url>
curl, é provável que o problema não esteja relacionado à configuração do cliente, mas sim à pilha de rede ou à configuração do servidor.
-
Para testar a conexão com a funcionalidade nativa do Node.js, você pode tentar criar uma requisição HTTP simples para o servidor ClickHouse usando a API
fetch incorporada:
const response = await fetch('<clickhouse_url>?query=SELECT+1', {
method: 'POST',
headers: {
'Authorization': 'Basic ' + Buffer.from('<user>:<password>').toString('base64'),
}
})
-
Em alguns casos, o código da aplicação ou os adaptadores do framework podem adicionar um
ping() preventivo antes da execução real da consulta, o que pode levar a uma situação em que a requisição ping() é bem-sucedida, mas a requisição de consulta subsequente falha com um erro “socket hang up” devido ao mesmo problema subjacente com conexões ociosas. Se você observar esse padrão nos logs, verifique se há uma opção para desabilitar pings preventivos no seu framework ou no código da aplicação. Isso também deve ajudar a reduzir a probabilidade de sofrer limitação de taxa por algum componente intermediário da rede.
-
Certifique-se de que a própria aplicação esteja recebendo tempo de CPU suficiente e de que a rede não esteja sendo limitada pelo provedor de hospedagem. Várias formas de monitoramento, como métricas de pausa do GC, métricas de defasagem do loop de eventos e outras semelhantes, também podem ser úteis para descartar possíveis problemas de falta de recursos.
-
Tente verificar o código da sua aplicação com a regra no-floating-promises do ESLint habilitada, o que ajudará a identificar promises não tratadas que podem levar a streams e sockets pendentes.
Ao usar o cliente com um usuário readonly=1, a compressão da resposta não pode ser habilitada, pois isso exige a configuração enable_http_compression. A configuração a seguir resultará em um erro:
const client = createClient({
compression: {
response: true, // não funciona com um usuário readonly=1
},
})
clickhouse_server como a opção de configuração pathname (com ou sem a barra inicial); caso contrário, se ele for fornecido diretamente em url, será interpretado como a opção database. Vários segmentos são compatíveis, por exemplo, /my_proxy/db.
const client = createClient({
url: 'http://proxy:8123',
pathname: '/clickhouse_server',
})
http_headers para fornecer os cabeçalhos necessários:
const client = createClient({
http_headers: {
'My-Auth-Header': '...',
},
})
Agente HTTP/HTTPS personalizado (experimental, somente para Node.js)
Este é um recurso experimental que pode mudar de maneiras incompatíveis com versões anteriores em lançamentos futuros. A implementação padrão e as configurações fornecidas pelo cliente devem ser suficientes para a maioria dos casos de uso. Use este recurso apenas se tiver certeza de que precisa dele.
max_open_connections, keep_alive.enabled, tls), que gerenciará as conexões com o servidor ClickHouse. Além disso, se certificados TLS forem usados, o agente subjacente será configurado com os certificados necessários, e os cabeçalhos corretos de autenticação TLS serão aplicados.
A partir da versão 1.2.0, é possível fornecer ao cliente um agente HTTP ou HTTPS personalizado, substituindo o agente padrão. Isso pode ser útil em caso de configurações de rede complexas. As seguintes condições se aplicam caso um agente personalizado seja fornecido:
- As opções
max_open_connections e tls não terão nenhum efeito e serão ignoradas pelo cliente, pois fazem parte da configuração do agente subjacente.
keep_alive.enabled regulará apenas o valor padrão do cabeçalho Connection (true -> Connection: keep-alive, false -> Connection: close).- Embora o gerenciamento de sockets keep-alive ociosos continue funcionando (já que não está vinculado ao agente, mas a um socket específico), agora é possível desativá-lo completamente definindo o valor de
keep_alive.idle_socket_ttl como 0.
Exemplos de uso de agente personalizado
const agent = new http.Agent({ // ou 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,
// Com um agente HTTPS personalizado, o cliente não usará a implementação padrão de conexão HTTPS; os cabeçalhos devem ser fornecidos manualmente
http_headers: {
'X-ClickHouse-User': 'username',
'X-ClickHouse-Key': 'password',
},
// Importante: o cabeçalho de autorização entra em conflito com os cabeçalhos TLS; desative-o.
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,
// Com um agente HTTPS personalizado, o cliente não usará a implementação padrão de conexão HTTPS; os cabeçalhos devem ser fornecidos manualmente
http_headers: {
'X-ClickHouse-User': 'username',
'X-ClickHouse-Key': 'password',
'X-ClickHouse-SSL-Certificate-Auth': 'on',
},
// Importante: o cabeçalho de autorização entra em conflito com os cabeçalhos TLS; desative-o.
set_basic_auth_header: false,
})
set_basic_auth_header (introduzida na versão 1.2.0), pois ele entra em conflito com os cabeçalhos TLS. Todos os cabeçalhos TLS devem ser fornecidos manualmente.
Limitações conhecidas (Node.js/web)
Limitações conhecidas (web)
- O streaming para consultas SELECT funciona, mas está desabilitado para inserções (inclusive no nível de tipo).
- A compressão da requisição está desabilitada, e a configuração é ignorada. A compressão da resposta funciona.
- Ainda não há suporte a logging.
- Para reduzir o consumo de memória da aplicação, considere usar streams para inserts grandes (por exemplo, de arquivos) e selects, quando aplicável. Para listeners de eventos e casos de uso semelhantes, async inserts podem ser outra boa opção, permitindo minimizar ou até mesmo evitar completamente o agrupamento em lotes no lado do cliente. Exemplos de async insert estão disponíveis no repositório do cliente, com
async_insert_ como prefixo do nome do arquivo.
- O cliente não habilita a compressão de requisição ou resposta por padrão. No entanto, ao fazer selects ou inserts de grandes volumes de dados, você pode considerar habilitá-la via
ClickHouseClientConfigOptions.compression (seja apenas para request ou response, ou para ambos).
- A compressão tem um impacto significativo no desempenho. Habilitá-la para
request ou response afetará negativamente a velocidade de selects ou inserts, respectivamente, mas reduzirá a quantidade de tráfego de rede transferido pela aplicação.
Se você tiver alguma dúvida ou precisar de ajuda, sinta-se à vontade para falar conosco no Community Slack (canal #clickhouse-js) ou pelo GitHub Issues. 
