> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
> O cliente JS oficial para conectar ao ClickHouse.
# ClickHouse JS
O cliente JS oficial para se conectar ao ClickHouse.
O cliente é escrito em TypeScript e fornece tipagens para a API pública do cliente.
Ele tem zero dependências, é otimizado para desempenho máximo e foi testado com várias versões e configurações do ClickHouse (single node on-premise, cluster on-premise e ClickHouse Cloud).
Há duas versões diferentes do cliente disponíveis para ambientes distintos:
* `@clickhouse/client` - apenas Node.js
* `@clickhouse/client-web` - navegadores (Chrome/Firefox), Cloudflare workers
Ao usar TypeScript, certifique-se de que a versão seja pelo menos a [4.5](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-5.html), que habilita a [sintaxe inline de import e export](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-5.html#type-modifiers-on-import-names).
O código-fonte do cliente está disponível no [repositório GitHub ClickHouse-JS](https://github.com/ClickHouse/clickhouse-js).
**Skills para agentes de IA**
O cliente JS vem com Skills para agentes de IA que podem ajudar agentes de codificação a trabalhar com o cliente. Instale-as com:
```sh theme={null}
npm skills add ClickHouse/clickhouse-js
```
## Requisitos do ambiente (node.js)
O Node.js deve estar disponível no ambiente para executar o cliente.
O cliente é compatível com todos os [lançamentos do Node.js atualmente mantidos](https://github.com/nodejs/release#readme).
Assim que uma versão do Node.js se aproxima do fim de vida, o cliente deixa de oferecer suporte a ela, por ser considerada desatualizada e insegura.
Versões atuais do Node.js com suporte:
| Versão do Node.js | Compatível? |
| ----------------- | -------------- |
| 24.x | ✔ |
| 22.x | ✔ |
| 20.x | ✔ |
| 18.x | Melhor esforço |
## Requisitos de ambiente (web)
A versão web do cliente é oficialmente testada nas versões mais recentes dos navegadores Chrome/Firefox e pode ser usada como dependência, por exemplo, em aplicações React/Vue/Angular ou em Cloudflare workers.
## Instalação
Para instalar a versão estável mais recente do cliente Node.js, execute:
```sh theme={null}
npm i @clickhouse/client
```
Instalação da versão web:
```sh theme={null}
npm i @clickhouse/client-web
```
## Compatibilidade com ClickHouse
| Versão do cliente | ClickHouse |
| ----------------- | ---------- |
| 1.12.0 | 24.8+ |
É provável que o cliente também funcione com versões mais antigas; no entanto, esse suporte é oferecido em regime de melhor esforço e não é garantido. Se você estiver usando uma versão do ClickHouse anterior à versão 23.3, consulte a [política de segurança do ClickHouse](https://github.com/ClickHouse/ClickHouse/blob/master/SECURITY.md) e considere atualizá-la.
## Exemplos
Nosso objetivo é abranger vários cenários de uso do client com os [exemplos](https://github.com/ClickHouse/clickhouse-js/blob/main/examples) no repositório do client.
A visão geral está disponível no [README dos exemplos](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/README.md#overview).
Se algo não estiver claro ou estiver faltando nos exemplos ou na documentação a seguir, sinta-se à vontade para [entrar em contato conosco](/docs/pt-BR/integrations/language-clients/js/index#contact-us).
### API do cliente
A maioria dos exemplos deve ser compatível com as versões para Node.js e web do cliente, a menos que seja explicitamente indicado o contrário.
#### Criando uma instância de cliente
Você pode criar quantas instâncias de cliente forem necessárias com a função de fábrica `createClient`:
```ts theme={null}
import { createClient } from '@clickhouse/client' // or '@clickhouse/client-web'
const client = createClient({
/* configuration */
})
```
Se o seu ambiente não oferecer suporte a módulos ESM, você pode usar a sintaxe CJS em vez disso:
```ts theme={null}
const { createClient } = require('@clickhouse/client');
const client = createClient({
/* configuration */
})
```
Uma instância de cliente pode ser [pré-configurada](/docs/pt-BR/integrations/language-clients/js/index#configuration) ao ser instanciada.
#### Configuração
Ao criar uma instância do cliente, as seguintes configurações de conexão podem ser ajustadas:
| 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](/docs/pt-BR/integrations/language-clients/js/index#url-configuration) | |
| **pathname**?: string | Um pathname opcional a ser adicionado à URL do ClickHouse depois que ela for processada pelo cliente. | `''` | [documentação de proxy com um pathname](/docs/pt-BR/integrations/language-clients/js/index#proxy-with-a-pathname) | |
| **request\_timeout**?: number | O tempo limite da solicitação, em milissegundos. | `30_000` | - | |
| **compression**?: `{ **response**?: boolean; **request**?: boolean }` | Habilita a compressão. | - | [documentação de compressão](/docs/pt-BR/integrations/language-clients/js/index#compression) | |
| **username**?: string | O nome do usuário em cujo nome as solicitaçõ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 solicitações. | `{}` | - | |
| **log**?: `{ **LoggerClass**?: Logger, **level**?: ClickHouseLogLevel }` | Configuração dos logs internos do cliente. | - | [documentação de logging](/docs/pt-BR/integrations/language-clients/js/index#logging-nodejs-only) | |
| **session\_id**?: string | ID de sessão opcional do ClickHouse a ser enviado com каждой solicitação. | - | - | |
| **keep\_alive**?: `{ **enabled**?: boolean }` | Habilitado por padrão nas versões para Node.js e Web. | - | - | |
| **http\_headers**?: `Record` | Cabeçalhos HTTP adicionais para as solicitações enviadas ao ClickHouse. | - | [documentação de reverse proxy com authentication](/docs/pt-BR/integrations/language-clients/js/index#reverse-proxy-with-authentication) | |
| **roles**?: string | string\[] | Nomes de roles do ClickHouse a serem associados às solicitações enviadas. | - | [Uso de roles com a interface HTTP](/docs/pt-BR/concepts/features/interfaces/http#setting-role-with-query-parameters) |
#### 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 sobre TLS](/docs/pt-BR/integrations/language-clients/js/index#tls-certificates-nodejs-only) | |
| **keep\_alive**?: `{ **enabled**?: boolean, **idle_socket_ttl**?: number }` | - | - | [documentação sobre Keep Alive](/docs/pt-BR/integrations/language-clients/js/index#keep-alive-configuration-nodejs-only) | |
| **http\_agent**?: http.Agent | https.Agent
Experimental | HTTP agent personalizado para o cliente. | - | [documentação do HTTP agent](/docs/pt-BR/integrations/language-clients/js/index#custom-httphttps-agent-experimental-nodejs-only) |
| **set\_basic\_auth\_header**?: boolean
Experimental | Define o cabeçalho `Authorization` com as credenciais de autenticação básica. | `true` | [uso desta configuração na documentação do HTTP agent](/docs/pt-BR/integrations/language-clients/js/index#custom-httphttps-agent-experimental-nodejs-only) | |
### Configuração de URL
A configuração de URL *sempre* substituirá os valores definidos no código, e um aviso será registrado no log nesse caso.
É possível configurar a maioria dos parâmetros da instância do cliente com uma URL. O formato da URL é `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. Os seguintes parâmetros são suportados:
| Parameter | Type |
| ------------------------------------------- | --------------------------------------------------------------------- |
| `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_*` or `ch_*` | veja abaixo (2) |
| `http_header_*` | veja abaixo (3) |
| (Node.js only) `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:
```ts theme={null}
createClient({
clickhouse_settings: {
async_insert: 1,
wait_for_async_insert: 1,
},
})
```
Nota: os valores booleanos de `clickhouse_settings` devem ser passados como `1`/`0` na URL.
* (3) Semelhante ao item (2), mas para a configuração de `http_header`. Por exemplo, `?http_header_x-clickhouse-auth=foobar` será equivalente a:
```ts theme={null}
createClient({
http_headers: {
'x-clickhouse-auth': 'foobar',
},
})
```
### Conexão
#### Reúna os detalhes da conexão
Para se conectar ao ClickHouse via HTTP(S), você precisa das seguintes informações:
| 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. |
Os detalhes do seu serviço do ClickHouse Cloud estão disponíveis no console do ClickHouse Cloud.
Selecione um serviço e clique em **Connect**:
Escolha **HTTPS**. Os detalhes de conexão são exibidos em um comando `curl` de exemplo.
Se você estiver usando ClickHouse autogerenciado, os detalhes de conexão são definidos pelo administrador do seu ClickHouse.
#### Visão geral da conexão
O client estabelece uma conexão via protocolo HTTP ou HTTPS. O suporte a RowBinary está em andamento; veja a [issue relacionada](https://github.com/ClickHouse/clickhouse-js/issues/216).
O exemplo a seguir mostra 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 de Client para Node.js usando variáveis de ambiente na configuração.
```ts theme={null}
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 ?? '',
})
```
O repositório da biblioteca cliente contém vários exemplos que usam variáveis de ambiente, como [criar uma tabela no ClickHouse Cloud](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/schema-and-deployments/create_table_cloud.ts), [usar inserts assíncronos](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/async_insert.ts) e vários outros.
#### Pool de conexões (somente Node.js)
Para evitar a sobrecarga de estabelecer uma conexão a cada requisição, o cliente cria um pool de conexões com o ClickHouse para reutilizá-las, usando um mecanismo de Keep-Alive. Por padrão, o Keep-Alive é habilitado, e o tamanho do pool de conexões é definido como `10`, mas você pode alterá-lo com a [opção de configuração](/docs/pt-BR/integrations/language-clients/js/index#configuration) `max_open_connections`.
Não há garantia de que a mesma conexão do pool será usada nas consultas seguintes, 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](/docs/pt-BR/integrations/language-clients/js/index#keep-alive-configuration-nodejs-only).
### ID da consulta
Todo método que envia uma consulta ou uma instrução (`command`, `exec`, `insert`, `select`) fornecerá `query_id` no resultado. Esse identificador único é atribuído pelo client a cada consulta e pode ser útil para buscar os dados em `system.query_log`,
se ele estiver habilitado na [configuração do servidor](/docs/pt-BR/reference/settings/server-settings/settings), ou para cancelar consultas de longa duração (veja [o exemplo](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/troubleshooting/cancel_query.ts)). 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ê substituir o parâmetro `query_id`, precisará garantir que ele seja único em cada chamada. Um UUID aleatório é uma boa escolha.
### Base parameters for all client methods
Há vários parâmetros que se aplicam a todos os métodos do cliente ([query](/docs/pt-BR/integrations/language-clients/js/index#query-method)/[command](/docs/pt-BR/integrations/language-clients/js/index#command-method)/[insert](/docs/pt-BR/integrations/language-clients/js/index#insert-method)/[exec](/docs/pt-BR/integrations/language-clients/js/index#exec-method)).
```ts theme={null}
interface BaseQueryParams {
// ClickHouse settings that can be applied on query level.
clickhouse_settings?: ClickHouseSettings
// Parameters for query binding.
query_params?: Record
// 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
}
```
### Método de consulta
Ele é usado para a maioria das instruções que podem ter uma resposta, como `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 específico, [insert](/docs/pt-BR/integrations/language-clients/js/index#insert-method), para inserção de dados, e [command](/docs/pt-BR/integrations/language-clients/js/index#command-method), para DDLs.
```ts theme={null}
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
}
```
Veja também: [Base parameters for all client methods](/docs/pt-BR/integrations/language-clients/js/index#base-parameters-for-all-client-methods).
Não especifique a cláusula FORMAT em `query`; use o parâmetro `format`.
#### Abstrações de conjunto de resultados e de 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 em buffer os dados recebidos para evitar um uso de memória potencialmente excessivo 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 isso pode variar, e do tamanho de cada linha), um fragmento por vez.
Consulte a lista de [formatos de dados compatíveis](/docs/pt-BR/integrations/language-clients/js/index#supported-data-formats) para determinar qual é o melhor formato para streaming no seu caso. Por exemplo, se você quiser fazer streaming de objetos JSON, poderá escolher [JSONEachRow](/docs/pt-BR/reference/formats/JSON/JSONEachRow), e cada linha será convertida em um objeto JS, ou talvez o formato mais compacto [JSONCompactColumns](/docs/pt-BR/reference/formats/JSON/JSONCompactColumns), em que cada linha será um array compacto de valores. Veja também: [arquivos em streaming](/docs/pt-BR/integrations/language-clients/js/index#streaming-files-nodejs-only).
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`.
```ts theme={null}
interface BaseResultSet {
// 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
// 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(): Promise
// 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
}
```
**Exemplo:** (Node.js/Web) Uma consulta cujo conjunto de dados resultante está no formato `JSONEachRow`, consumindo todo o stream e interpretando o conteúdo como objetos JS.
[Código-fonte](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/array_json_each_row.ts).
```ts theme={null}
const resultSet = await client.query({
query: 'SELECT * FROM my_table',
format: 'JSONEachRow',
})
const dataset = await resultSet.json() // or `row.text` to avoid parsing JSON
```
**Exemplo:** (somente no Node.js) Resultado de consulta em streaming no formato `JSONEachRow` usando a abordagem clássica `on('data')`. Ela pode ser usada em vez da sintaxe `for await const`. [Código-fonte](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/performance/select_streaming_json_each_row.ts).
```ts theme={null}
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)
})
```
**Exemplo:** (somente no Node.js) Resultado de uma consulta em streaming no formato `CSV` usando a abordagem clássica `on('data')`. Isso pode ser usado de forma intercambiável com a sintaxe `for await const`.
[Código-fonte](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/performance/select_streaming_text_line_by_line.ts)
```ts theme={null}
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)
})
```
**Exemplo:** (apenas Node.js) Resultado de uma consulta em streaming como objetos JS no formato `JSONEachRow`, consumido com a sintaxe `for await const`. Isso pode ser usado no lugar da abordagem clássica `on('data')`.
[Código-fonte](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/performance/select_streaming_json_each_row_for_await.ts).
```ts theme={null}
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())
})
}
```
A sintaxe `for await const` exige um pouco menos de código do que a abordagem `on('data')`, mas pode ter um impacto negativo no desempenho.
Consulte [esta issue no repositório do Node.js](https://github.com/nodejs/node/issues/31979) para mais detalhes.
**Exemplo:** (Apenas Web) Iteração sobre o `ReadableStream` de objetos.
```ts theme={null}
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())
})
}
```
### Método insert
Este é o principal método de inserção de dados.
```ts theme={null}
export interface InsertResult {
query_id: string
executed: boolean
}
interface ClickHouseClient {
insert(params: InsertParams): Promise
}
```
O tipo de retorno é mínimo, pois não esperamos que nenhum dado seja retornado pelo servidor e consumimos o fluxo de resposta imediatamente.
Se um array vazio for fornecido ao método 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 params do método nesse caso, ele será uma string vazia no resultado, já que retornar um UUID aleatório gerado pelo client poderia ser confuso, 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, a flag `executed` será `true`.
#### Método `insert` e streaming no Node.js
Ele pode funcionar tanto com um `Stream.Readable` quanto com um `Array` simples, dependendo do [formato de dados](/docs/pt-BR/integrations/language-clients/js/index#supported-data-formats) especificado para o método `insert`. Veja também esta seção sobre [streaming de arquivos](/docs/pt-BR/integrations/language-clients/js/index#streaming-files-nodejs-only).
O método `insert` deve ser aguardado; no entanto, é possível especificar um stream de entrada e aguardar a operação de `insert` mais tarde, somente quando o stream for concluído (o que também resolverá a promise do `insert`). Isso pode ser útil para listeners de eventos e cenários semelhantes, mas o tratamento de erros pode não ser trivial, com muitos casos-limite no lado do client. Em vez disso, considere usar [inserções assíncronas](/docs/pt-BR/concepts/features/operations/insert/asyncinserts), como mostrado [neste exemplo](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/performance/async_insert_without_waiting.ts).
Se você tiver uma instrução INSERT personalizada que seja difícil de modelar com este método, considere usar o [método `command`](/docs/pt-BR/integrations/language-clients/js/index#command-method).
Você pode ver como ele é usado nos exemplos [INSERT INTO ... VALUES](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/insert_values_and_functions.ts) ou [INSERT INTO ... SELECT](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/insert_from_select.ts).
```ts theme={null}
interface InsertParams extends BaseQueryParams {
// Table name to insert the data into
table: string
// A dataset to insert.
values: ReadonlyArray | 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 | { except: NonEmptyArray }
}
```
Veja também: [Base parameters for all client methods](/docs/pt-BR/integrations/language-clients/js/index#base-parameters-for-all-client-methods).
Uma requisição cancelada com `abort_signal` não garante que nenhum dado tenha sido inserido, pois o servidor pode ter recebido parte dos dados transmitidos em fluxo antes do cancelamento.
**Exemplo:** (Node.js/Web) Insira um array de valores.
[Código-fonte](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/array_json_each_row.ts).
```ts theme={null}
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',
})
```
**Exemplo:** (apenas no Node.js) Insira um stream a partir de um arquivo CSV.
[Código-fonte](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/performance/insert_file_stream_csv.ts). Veja também: [streaming de arquivos](/docs/pt-BR/integrations/language-clients/js/index#streaming-files-nodejs-only).
```ts theme={null}
await client.insert({
table: 'my_table',
values: fs.createReadStream('./path/to/a/file.csv'),
format: 'CSV',
})
```
**Exemplo**: Exclua algumas colunas da instrução INSERT.
Considere a seguinte definição de tabela:
```sql theme={null}
CREATE OR REPLACE TABLE mytable
(id UInt32, message String)
ENGINE MergeTree()
ORDER BY (id)
```
Insira apenas uma coluna específica:
```ts theme={null}
// 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'],
})
```
Exclua algumas colunas:
```ts theme={null}
// 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'],
},
})
```
Veja o [código-fonte](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/insert_exclude_columns.ts) para mais detalhes.
**Exemplo**: Inserir em um banco de dados diferente do informado para a instância do cliente. [Código-fonte](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/insert_into_different_db.ts).
```ts theme={null}
await client.insert({
table: 'mydb.mytable', // Fully qualified name including the database
values: [{ id: 42, message: 'foo' }],
format: 'JSONEachRow',
})
```
#### Limitações da versão web
No momento, os inserts em `@clickhouse/client-web` só funcionam com os formatos `Array` e `JSON*`.
A inserção via streams ainda não tem suporte na versão web devido à baixa compatibilidade dos navegadores.
Consequentemente, a interface `InsertParams` da versão web é um pouco diferente da versão para Node.js,
já que `values` se limita apenas ao tipo `ReadonlyArray`:
```ts theme={null}
interface InsertParams extends BaseQueryParams {
// Table name to insert the data into
table: string
// A dataset to insert.
values: ReadonlyArray
// 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 | { except: NonEmptyArray }
}
```
Isso pode mudar no futuro. Veja também: [Base parameters for all client methods](/docs/pt-BR/integrations/language-clients/js/index#base-parameters-for-all-client-methods).
### Método command
Pode ser usado com instruções que não geram saída, quando a cláusula FORMAT não se aplica ou quando a resposta não é necessária. Um exemplo desse tipo de instrução pode ser `CREATE TABLE` ou `ALTER TABLE`.
Deve ser aguardado.
O fluxo de resposta é encerrado imediatamente, o que significa que o socket subjacente é liberado.
```ts theme={null}
interface CommandParams extends BaseQueryParams {
// Statement to execute.
query: string
}
interface CommandResult {
query_id: string
}
interface ClickHouseClient {
command(params: CommandParams): Promise
}
```
Veja também: [Base parameters for all client methods](/docs/pt-BR/integrations/language-clients/js/index#base-parameters-for-all-client-methods).
**Exemplo:** (Node.js/Web) Criar uma tabela no ClickHouse Cloud.
[Código-fonte](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/schema-and-deployments/create_table_cloud.ts).
```ts theme={null}
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,
},
})
```
**Exemplo:** (Node.js/Web) Crie uma tabela em uma instância do ClickHouse auto-hospedada.
[Código-fonte](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/schema-and-deployments/create_table_single_node.ts).
```ts theme={null}
await client.command({
query: `
CREATE TABLE IF NOT EXISTS my_table
(id UInt64, name String)
ENGINE MergeTree()
ORDER BY (id)
`,
})
```
**Exemplo:** (Node.js/Web) INSERT FROM SELECT
```ts theme={null}
await client.command({
query: `INSERT INTO my_table SELECT '42'`,
})
```
Uma requisição cancelada com `abort_signal` não garante que a instrução não tenha sido executada pelo servidor.
### Método `exec`
Se você tiver uma consulta personalizada que não se enquadre em `query`/`insert`
e quiser o resultado, poderá usar `exec` como alternativa a `command`.
`exec` retorna um fluxo legível que DEVE ser consumido ou encerrado no lado da aplicação.
```ts theme={null}
interface ExecParams extends BaseQueryParams {
// Statement to execute.
query: string
}
interface ClickHouseClient {
exec(params: ExecParams): Promise
}
```
Veja também: [Base parameters for all client methods](/docs/pt-BR/integrations/language-clients/js/index#base-parameters-for-all-client-methods).
O tipo de retorno do stream é diferente nas versões Node.js e Web.
Node.js:
```ts theme={null}
export interface QueryResult {
stream: Stream.Readable
query_id: string
}
```
Web:
```ts theme={null}
export interface QueryResult {
stream: ReadableStream
query_id: string
}
```
### Ping
O método `ping`, usado para verificar o status da conectividade, retorna `true` se o servidor puder ser acessado.
Se o servidor estiver inacessível, o erro correspondente também será incluído no resultado.
```ts theme={null}
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
}
/** 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
}
```
Ping pode ser uma ferramenta útil para verificar se o servidor está disponível quando a aplicação é iniciada, especialmente com o ClickHouse Cloud, em que uma instância pode estar ociosa e voltar a ficar ativa após um ping: nesse caso, talvez você queira tentar novamente algumas vezes, com um intervalo entre as tentativas.
Observe que, por padrão, a versão Node.js usa o endpoint `/ping`, enquanto a versão Web usa uma consulta simples `SELECT 1` 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. Obs.: para a versão Web, os erros capturados serão diferentes.
[Código-fonte](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/ping.ts).
```ts theme={null}
const result = await client.ping();
if (!result.success) {
// process result.error
}
```
**Exemplo:** Se você também quiser verificar as credenciais ao chamar o método `ping` ou especificar parâmetros adicionais, como `query_id`, poderá usá-lo da seguinte forma:
```ts theme={null}
const result = await client.ping({ select: true, /* query_id, abort_signal, http_headers, or any other query params */ });
```
O método ping aceitará a maioria dos parâmetros padrão do método `query` — consulte a definição de tipo `PingParamsWithSelectQuery`.
### Close (somente Node.js)
Fecha todas as conexões abertas e libera os recursos. No-op na versão web.
```ts theme={null}
await client.close()
```
## Streaming de arquivos (somente Node.js)
Há vários exemplos de streaming de arquivos com formatos de dados populares (NDJSON, CSV, Parquet) no repositório da biblioteca cliente.
* [Streaming a partir de um arquivo NDJSON](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/performance/insert_file_stream_ndjson.ts)
* [Streaming a partir de um arquivo CSV](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/performance/insert_file_stream_csv.ts)
* [Streaming a partir de um arquivo Parquet](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/performance/insert_file_stream_parquet.ts)
* [Streaming para um arquivo Parquet](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/performance/select_parquet_as_file.ts)
O streaming de outros formatos para um arquivo deve ser semelhante ao de Parquet,
a única diferença estará no formato usado na chamada `query` (`JSONEachRow`, `CSV` etc.) e no nome do arquivo de saída.
## Formatos de dados compatíveis
O cliente lida com 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 pelo wire.
Os dados fornecidos nos formatos de texto "brutos" (famílias `CSV`, `TabSeparated` e `CustomSeparated`) são enviados pelo wire sem transformações adicionais.
Pode haver confusão entre JSON como formato geral e o [formato JSON do ClickHouse](/docs/pt-BR/reference/formats/JSON/JSON).
O cliente oferece suporte ao streaming de objetos JSON com formatos como [JSONEachRow](/docs/pt-BR/reference/formats/JSON/JSONEachRow) (consulte a visão geral da tabela para outros formatos adequados para streaming; veja também os `select_streaming_` [examples no repositório da biblioteca cliente](https://github.com/ClickHouse/clickhouse-js/tree/main/examples/node)).
A única questão é que formatos como [ClickHouse JSON](/docs/pt-BR/reference/formats/JSON/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 |
Para o Parquet, o principal caso de uso das instruções SELECT provavelmente será gravar o fluxo resultante em um arquivo. Veja [o exemplo](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/performance/select_parquet_as_file.ts) no repositório da biblioteca cliente.
`JSONEachRowWithProgress` é um formato somente de saída que oferece suporte ao reporte de progresso no fluxo. Veja [este exemplo](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/performance/select_json_each_row_with_progress.ts) para mais detalhes.
A lista completa dos formatos de entrada e saída do ClickHouse está disponível
[aqui](/docs/pt-BR/reference/formats/index).
## Tipos de dados do ClickHouse suportados
O tipo JS correspondente é relevante para todos os formatos `JSON*`, exceto aqueles 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\[] |
| (novo) 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\ |
| Polygon | ✔️ | Array\ |
| MultiPolygon | ✔️ | Array\ |
| Map(K, V) | ✔️ | Record\ |
| Time/Time64 | ✔️ | string |
A lista completa dos formatos compatíveis do ClickHouse está disponível
[aqui](/docs/pt-BR/reference/data-types/index).
Veja também:
* [Exemplos de uso de Dynamic/Variant/JSON](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/dynamic_variant_json.ts)
* [Exemplos de uso de Time/Time64](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/time_time64.ts)
### Observações sobre os tipos Date/Date32
Como o cliente insere valores sem conversão adicional de tipo, colunas do tipo `Date`/`Date32` só podem ser inseridas como
strings.
**Exemplo:** Insira um valor do tipo `Date`.
[Código-fonte](https://github.com/ClickHouse/clickhouse-js/blob/ba387d7f4ce375a60982ac2d99cb47391cf76cec/__tests__/integration/date_time.test.ts)
```ts theme={null}
await client.insert({
table: 'my_table',
values: [ { date: '2022-09-05' } ],
format: 'JSONEachRow',
})
```
No entanto, se você estiver usando colunas `DateTime` ou `DateTime64`, poderá usar tanto strings quanto objetos `Date` do JS. Objetos `Date` do JS podem ser passados diretamente para `insert`, com `date_time_input_format` definido como `best_effort`. Consulte este [exemplo](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/insert_js_dates.ts) para mais detalhes.
### Ressalvas sobre os tipos Decimal\*
É possível inserir valores Decimal usando formatos da família `JSON*`. Supondo que temos uma tabela definida como:
```sql theme={null}
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 inserir valores sem perda de precisão usando a representação textual:
```ts theme={null}
await client.insert({
table: 'my_table',
values: [{
id: 1,
dec32: '1234567.89',
dec64: '123456789123456.789',
dec128: '1234567891234567891234567891.1234567891',
dec256: '12345678912345678912345678911234567891234567891234567891.12345678911234567891',
}],
format: 'JSONEachRow',
})
```
No entanto, ao consultar os dados nos formatos `JSON*`, o ClickHouse retornará valores Decimal como *números* por padrão, o que pode levar à perda de precisão. Para evitar isso, você pode converter valores Decimal para string na consulta:
```ts theme={null}
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',
})
```
Consulte [este exemplo](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/insert_decimals.ts) para mais detalhes.
### Tipos integrais: Int64, Int128, Int256, UInt64, UInt128, UInt256
Embora o servidor possa aceitá-los como números, eles são retornados como strings nos formatos de saída da família `JSON*` para evitar
overflow de inteiro, já que os valores máximos desses tipos são maiores que `Number.MAX_SAFE_INTEGER`.
Esse comportamento, no entanto, pode ser alterado
com a [configuração `output_format_json_quote_64bit_integers`](/docs/pt-BR/reference/settings/formats#output_format_json_quote_64bit_integers)
.
**Exemplo:** Ajuste o formato de saída JSON para números de 64 bits.
```ts theme={null}
const resultSet = await client.query({
query: 'SELECT * from system.numbers LIMIT 1',
format: 'JSONEachRow',
})
expect(await resultSet.json()).toEqual([ { number: '0' } ])
```
```ts theme={null}
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
O cliente pode ajustar o comportamento do ClickHouse por meio do mecanismo de
[configurações](/docs/pt-BR/reference/settings/session-settings).
As configurações podem ser definidas no nível da instância do cliente para que sejam aplicadas a todas as requisições enviadas ao
ClickHouse:
```ts theme={null}
const client = createClient({
clickhouse_settings: {}
})
```
Ou uma configuração pode ser aplicada em nível de requisição:
```ts theme={null}
client.query({
clickhouse_settings: {}
})
```
Um arquivo de declaração de tipos com todas as configurações do ClickHouse compatíveis pode ser encontrado
[aqui](https://github.com/ClickHouse/clickhouse-js/blob/main/packages/client-common/src/settings.ts).
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.
## Tópicos avançados
### Consultas com parâmetros
Você pode criar uma consulta com parâmetros e passar valores para ela a partir da aplicação cliente. Isso permite evitar a formatação
da consulta no lado do cliente com valores dinâmicos específicos.
Formate uma consulta normalmente e, em seguida, coloque entre chaves os valores que deseja passar dos parâmetros da aplicação para a consulta, no
seguinte formato:
```text theme={null}
{: }
```
onde:
* `name` — Identificador do placeholder.
* `data_type` - [Tipo de dado](/docs/pt-BR/reference/data-types/index) do valor do parâmetro da aplicação.
**Exemplo:**: Consulta com parâmetros.
[Código-fonte](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/coding/query_with_parameter_binding.ts)
.
```ts theme={null}
await client.query({
query: 'SELECT plus({val1: Int32}, {val2: Int32})',
format: 'CSV',
query_params: {
val1: 10,
val2: 20,
},
})
```
Consulte [https://clickhouse.com/docs/interfaces/cli#cli-queries-with-parameters-syntax](https://clickhouse.com/docs/interfaces/cli#cli-queries-with-parameters-syntax) para mais detalhes.
### Compressão
NB: no momento, a compressão de requisições não está disponível na versão web. A compressão de respostas funciona normalmente. A versão do Node.js oferece suporte a ambas.
Aplicações de dados que operam com grandes volumes de dados trafegando pelo wire podem se beneficiar da ativação da compressão. Atualmente, há suporte apenas a `GZIP`, por meio de [zlib](https://nodejs.org/docs/latest-v14.x/api/zlib.html).
```typescript theme={null}
createClient({
compression: {
response: true,
request: true
}
})
```
Os parâmetros de configuração são:
* `response: true` instrui o servidor ClickHouse a responder com o corpo da resposta comprimido. Valor padrão: `response: false`
* `request: true` habilita a compressão no corpo da requisição do cliente. Valor padrão: `request: false`
### Logging (somente Node.js)
O logging é uma funcionalidade experimental e pode mudar no futuro.
A implementação padrão do 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`):
```typescript theme={null}
import type { Logger } from '@clickhouse/client'
// All three LogParams types are exported by the client
interface LogParams {
module: string
message: string
args?: Record
}
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,
}
})
```
Atualmente, o cliente registrará os seguintes eventos:
* `TRACE` - informações de baixo nível sobre o ciclo de vida dos sockets Keep-Alive
* `DEBUG` - informações da resposta (sem os cabeçalhos de autorização e as informações de host)
* `INFO` - praticamente não é usado; exibirá o nível de log atual quando o cliente for inicializado
* `WARN` - erros não fatais; uma solicitação `ping` com falha é registrada como aviso, pois o erro subjacente está incluído no resultado retornado
* `ERROR` - 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](https://github.com/ClickHouse/clickhouse-js/blob/main/packages/client-common/src/logger.ts).
### Certificados TLS (somente Node.js)
O Node.js client oferece suporte opcional a TLS básico (somente autoridade certificadora)
e mútuo (autoridade certificadora e certificados do cliente).
Exemplo de configuração de TLS básico, supondo que você tenha seus certificados na pasta `certs`
e que o nome do arquivo da CA seja `CA.pem`:
```ts theme={null}
const client = createClient({
url: 'https://:',
username: '',
password: '', // if required
tls: {
ca_cert: fs.readFileSync('certs/CA.pem'),
},
})
```
Exemplo de configuração de TLS mútuo com certificados de cliente:
```ts theme={null}
const client = createClient({
url: 'https://:',
username: '',
tls: {
ca_cert: fs.readFileSync('certs/CA.pem'),
cert: fs.readFileSync(`certs/client.crt`),
key: fs.readFileSync(`certs/client.key`),
},
})
```
Consulte exemplos completos de TLS [básico](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/security/basic_tls.ts) e [mútuo](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/security/mutual_tls.ts) no repositório.
### Configuração de Keep-Alive (somente Node.js)
O cliente habilita o Keep-Alive no agente HTTP subjacente por padrão, o que significa que os sockets conectados serão reutilizados em solicitações subsequentes, e o cabeçalho `Connection: keep-alive` será enviado. Os sockets ociosos permanecerão no pool de conexões por 2500 milissegundos por padrão (consulte as [notas sobre como ajustar essa opção](/docs/pt-BR/integrations/language-clients/js/index#adjusting-idle_socket_ttl)).
O ideal é 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 conexão *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 sincronizado 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 conexão aberta.
#### Ajustando `idle_socket_ttl`
O cliente define `keep_alive.idle_socket_ttl` como 2500 milissegundos, pois esse pode ser considerado o padrão mais seguro; no lado do servidor, `keep_alive_timeout` pode ser definido para [valores tão baixos quanto 3 segundos em versões do ClickHouse anteriores à 23.11](https://github.com/ClickHouse/ClickHouse/commit/1685cdcb89fe110b45497c7ff27ce73cc03e82d1) 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 possíveis erros de "Socket hang-up"; além disso, se a sua aplicação envia muitas consultas e não há muito intervalo entre elas, o valor padrão deve ser suficiente, pois os sockets não ficarão ociosos por tempo suficiente, e o cliente os manterá no pool.
Você pode encontrar o valor correto do timeout de Keep-Alive nos cabeçalhos de resposta do servidor executando o seguinte comando:
```sh theme={null}
curl -is --data-binary "SELECT 1"
```
Verifique os valores dos cabeçalhos `Connection` e `Keep-Alive` na resposta. Por exemplo:
```text theme={null}
Connection: Keep-Alive
Keep-Alive: timeout=10
```
Nesse caso, `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.
#### Solução de problemas
Se você estiver enfrentando erros de `socket hang up` mesmo usando a versão mais recente do client, há as seguintes opções para resolver esse problema:
* Ative os logs com pelo menos o nível `WARN` (padrão). Isso permitirá verificar se há um 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 ativar o logging na configuração do client da seguinte forma:
```ts theme={null}
const client = createClient({
log: { level: ClickHouseLogLevel.WARN },
})
```
* Certifique-se de que a configuração desejada esteja aplicada à instância correta do client. Se você tiver várias instâncias de client na aplicação, confira se a que está usando para as queries tem o valor correto de `keep_alive.idle_socket_ttl`.
* Reduza a configuração `keep_alive.idle_socket_ttl` do client em 500 milissegundos. Em certas situações, por exemplo, alta latência de rede entre client e servidor, isso pode ser benéfico, pois evita o caso 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 queries longas, 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 que fecham conexões de longa duração ou requisições demoradas. Você pode tentar forçar a entrada de alguns dados durante queries longas usando uma combinação destas ClickHouse settings:
```ts theme={null}
const client = createClient({
// Aqui assumimos que teremos algumas queries com mais de 5 minutos de tempo de execução
request_timeout: 400_000,
/** Essas configurações em conjunto ajudam a evitar problemas de timeout do LB no caso de queries longas sem entrada ou saída de dados,
* como `INSERT FROM SELECT` e semelhantes, pois a conexão pode ser marcada como ociosa pelo LB e fechada abruptamente.
* Neste caso, assumimos que o LB tem timeout de conexão ociosa 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
},
})
```
No entanto, tenha em mente que o tamanho total dos headers recebidos tem limite de 16 KB nas versões recentes do Node.js; após uma certa quantidade de headers de progresso recebidos, em torno de 70 a 80 nos nossos testes, será gerada uma exceção.
Também é possível usar uma abordagem totalmente diferente, evitando completamente o tempo de espera na transmissão; isso pode ser feito aproveitando a "funcionalidade" da interface HTTP de que mutações não são canceladas quando a conexão é perdida. Veja [este exemplo (parte 2)](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/long_running_queries_timeouts.ts) para mais detalhes.
* O recurso Keep-Alive pode ser desativado por completo. Nesse caso, o client também adicionará o header `Connection: close` a cada requisição, e o HTTP agent subjacente não reutilizará as conexões. A configuração `keep_alive.idle_socket_ttl` será ignorada, pois não haverá sockets ociosos. Isso resultará em sobrecarga adicional, já que uma nova conexão será estabelecida para cada requisição.
```ts theme={null}
const client = createClient({
keep_alive: {
enabled: false,
},
})
```
* Descarte possíveis problemas com o restante da stack de rede, incluindo o próprio Node.js, executando um teste simples de linha de comando com a mesma instância do ClickHouse e o mesmo caminho de rede (isto é, a partir da mesma máquina ou segmento de rede, por exemplo, um pod do Kubernetes), por exemplo, usando `curl`:
```sh theme={null}
curl -is --user ':' --data-binary "SELECT 1"
```
Talvez seja interessante executá-lo em loop por vários minutos. Se você vir erros semelhantes no `curl`, é provável que o problema não esteja relacionado à configuração do client, mas sim à stack de rede ou à configuração do servidor.
* Para testar a conexão com funcionalidade nativa do Node.js, você pode tentar criar uma requisição HTTP simples para o servidor ClickHouse usando a API `fetch` integrada:
```ts theme={null}
const response = await fetch('?query=SELECT+1', {
method: 'POST',
headers: {
'Authorization': 'Basic ' + Buffer.from(':').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 solicitação `ping()` é bem-sucedida, mas a solicitação de consulta seguinte falha com um erro "socket hang up" devido ao mesmo problema subjacente com conexões ociosas. Se você identificar esse padrão nos logs, verifique se há alguma opção para desativar pings preventivos no seu framework ou no código da aplicação. Isso também deve ajudar a reduzir a probabilidade de ter a taxa limitada por qualquer 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. Diferentes formas de monitoramento, como métricas de pausa de GC, métricas de defasagem do loop de eventos e outras semelhantes, também podem ser úteis para descartar possíveis problemas de escassez de recursos.
* Tente verificar o código da sua aplicação com a regra ESLint [no-floating-promises](https://typescript-eslint.io/rules/no-floating-promises/) habilitada, o que ajudará a identificar promises não tratadas que podem levar a streams e sockets pendentes.
### Usuários somente leitura
Ao usar o client com um [usuário readonly=1](/docs/pt-BR/concepts/features/configuration/settings/permissions-for-queries#readonly), a compressão da resposta não pode ser habilitada, pois requer a configuração `enable_http_compression`. A configuração a seguir resultará em um erro:
```ts theme={null}
const client = createClient({
compression: {
response: true, // won't work with a readonly=1 user
},
})
```
Veja o [exemplo](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/security/read_only_user.ts), que mostra mais detalhes sobre as limitações de usuários com readonly=1.
### Proxy com pathname
Se a sua instância do ClickHouse estiver atrás de um proxy e houver um pathname na URL, como, por exemplo, [http://proxy:8123/clickhouse\_server](http://proxy:8123/clickhouse\_server), especifique `clickhouse_server` na opção de configuração `pathname` (com ou sem barra inicial); caso contrário, se ele for informado diretamente em `url`, será interpretado como a opção `database`. Há suporte para vários segmentos, por exemplo, `/my_proxy/db`.
```ts theme={null}
const client = createClient({
url: 'http://proxy:8123',
pathname: '/clickhouse_server',
})
```
### Proxy reverso com autenticação
Se você tiver um proxy reverso com autenticação à frente da sua implantação do ClickHouse, poderá usar a configuração `http_headers` para fornecer os cabeçalhos necessários:
```ts theme={null}
const client = createClient({
http_headers: {
'My-Auth-Header': '...',
},
})
```
### Agente HTTP/HTTPS personalizado (experimental, somente Node.js)
Este é um recurso experimental que pode sofrer mudanças 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.
Por padrão, o cliente configurará o agente HTTP ou HTTPS subjacente usando as definições fornecidas na configuração do cliente (como `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 um agente HTTP ou HTTPS personalizado ao cliente, substituindo o agente subjacente padrão. Isso pode ser útil em caso de configurações de rede complexas. As seguintes condições se aplicam se um agente personalizado for 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 um agente personalizado
Usando um agente HTTP ou HTTPS personalizado sem certificados:
```ts theme={null}
const agent = new http.Agent({ // or https.Agent
keepAlive: true,
keepAliveMsecs: 2500,
maxSockets: 10,
maxFreeSockets: 10,
})
const client = createClient({
http_agent: agent,
})
```
Usando um HTTPS Agent personalizado com TLS básico e certificado da CA:
```ts theme={null}
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,
})
```
Usando um agente HTTPS personalizado com TLS mútuo:
```ts theme={null}
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,
})
```
Com certificados *e* um agente *HTTPS* personalizado, provavelmente é necessário desativar o cabeçalho de autorização padrão por meio da configuração `set_basic_auth_header` (introduzida na versão 1.2.0), pois ele conflita com os cabeçalhos TLS. Todos os cabeçalhos TLS devem ser fornecidos manualmente.
## Limitações conhecidas (Node.js/web)
* Não há mapeadores de dados para os conjuntos de resultados, por isso apenas tipos primitivos da linguagem são usados. Está prevista a adição de mapeadores para determinados tipos de dados com [suporte ao formato RowBinary](https://github.com/ClickHouse/clickhouse-js/issues/216).
* Existem algumas [ressalvas sobre os tipos de dados Decimal\* e Date\* / DateTime\*](/docs/pt-BR/integrations/language-clients/js/index#datedate32-types-caveats).
* Ao usar formatos da família JSON\*, números maiores que Int32 são representados como strings, já que os valores máximos dos tipos Int64+ são maiores que `Number.MAX_SAFE_INTEGER`. Consulte a seção [Tipos integrais](/docs/pt-BR/integrations/language-clients/js/index#integral-types-int64-int128-int256-uint64-uint128-uint256) para mais detalhes.
## Limitações conhecidas (web)
* O streaming para consultas SELECT funciona, mas está desabilitado para inserções (também no nível do tipo).
* A compressão das requisições está desabilitada, e a configuração é ignorada. A compressão das respostas funciona.
* Ainda não há suporte a logging.
## Dicas para otimizar o desempenho
* Para reduzir o consumo de memória da aplicação, considere usar streams para inserts grandes (por exemplo, a partir de arquivos) e instrução SELECT, quando aplicável. Para listeners de eventos e casos de uso semelhantes, [async inserts](/docs/pt-BR/concepts/features/operations/insert/asyncinserts) podem ser outra boa opção, permitindo minimizar ou até mesmo evitar completamente o batching no client side. Exemplos de async insert estão disponíveis no [repositório da biblioteca cliente](https://github.com/ClickHouse/clickhouse-js/tree/main/examples/node), com `async_insert_` como prefixo do nome do arquivo.
* O client não habilita a compressão de request nem de response por padrão. No entanto, ao selecionar ou inserir datasets grandes, 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 das instruções SELECT ou dos inserts, respectivamente, mas reduzirá a quantidade de tráfego de rede transferida pela aplicação.
## Fale conosco
Se você tiver alguma dúvida ou precisar de ajuda, fique à vontade para entrar em contato conosco no [Slack da comunidade](https://clickhouse.com/slack) (canal `#clickhouse-js`) ou via [issues no GitHub](https://github.com/ClickHouse/clickhouse-js/issues).
