Pular para o conteúdo principal

​
Pré-requisitos

Para os exemplos deste artigo, você precisará de:
  • uma instância do servidor ClickHouse em execução
  • ter o curl instalado. No Ubuntu ou Debian, execute sudo apt install curl ou consulte esta documentação para ver as instruções de instalação.

​
Visão geral

A interface HTTP permite usar o ClickHouse em qualquer plataforma, com qualquer linguagem de programação, na forma de uma API REST. A interface HTTP é mais limitada do que a interface nativa, mas oferece melhor suporte a linguagens. Por padrão, o clickhouse-server escuta nas seguintes portas:
  • porta 8123 para HTTP
  • a porta 8443 para HTTPS pode ser habilitada
Se você fizer uma solicitação GET / sem parâmetros, será retornado um código de resposta 200 junto com a string “Ok.”:
“Ok.” é o valor padrão definido em http_server_default_response e pode ser alterado, se desejar. Veja também: Observações sobre códigos de resposta HTTP.

​
Interface web

O ClickHouse inclui uma interface web, que pode ser acessada no seguinte endereço:
A interface web oferece suporte à exibição do progresso durante a execução da consulta, ao cancelamento de consultas e à transmissão de resultados. Ela tem um recurso oculto para exibir gráficos e diagramas de pipelines de consulta. Depois de executar uma consulta com sucesso, aparece um botão de download que permite baixar os resultados da consulta em vários formatos, incluindo CSV, TSV, JSON, JSONLines, Parquet, Markdown ou qualquer formato personalizado compatível com o ClickHouse. A funcionalidade de download usa o cache de consultas para recuperar os resultados com eficiência, sem reexecutar a consulta. Ela fará o download do conjunto completo de resultados mesmo que a UI exiba apenas uma das muitas páginas. A interface web foi projetada para profissionais como você. Em scripts de verificação de integridade, use a requisição GET /ping. Este handler sempre retorna “Ok.” (com uma quebra de linha no final). Disponível a partir da versão 18.12.13. Veja também /replicas_status para verificar o atraso da réplica.

​
Consultas por HTTP/HTTPS

Para fazer consultas por HTTP/HTTPS, há três opções:
  • enviar a solicitação como um parâmetro query na URL
  • usar o método POST.
  • enviar o início da consulta no parâmetro query e o restante usando POST
O tamanho da URL é limitado a 1 MiB por padrão, mas isso pode ser alterado com a configuração http_max_uri_size.
Se a solicitação for bem-sucedida, você receberá o código de resposta 200 e o resultado no corpo da resposta. Se ocorrer um erro, você receberá o código de resposta 500 e um texto descritivo do erro no corpo da resposta. As solicitações que usam GET são ‘somente leitura’. Isso significa que, para consultas que modificam dados, você só pode usar o método POST. Você pode enviar a própria consulta tanto no corpo da requisição POST quanto como parâmetro na URL. Vamos ver alguns exemplos. No exemplo abaixo, curl é usado para enviar a consulta SELECT 1. Observe o uso de codificação de URL para o espaço: %20.
command
Response
Neste exemplo, o wget é usado com os parâmetros -nv (não detalhado) e -O- para exibir o resultado no terminal. Nesse caso, não é necessário usar codificação de URL para o espaço:
command
Neste exemplo, enviamos uma requisição HTTP bruta para o netcat:
command
response
Como você pode ver, o comando curl é um tanto inconveniente, já que os espaços precisam ser escapados na URL. Embora o wget faça esse escape automaticamente, não recomendamos usá-lo porque ele não funciona bem com HTTP 1.1 ao usar keep-alive e Transfer-Encoding: chunked.
Se parte da consulta for enviada no parâmetro e outra parte no POST, uma quebra de linha será inserida entre essas duas partes de dados. Por exemplo, isto não funcionará:
Por padrão, os dados são retornados no formato TabSeparated. A cláusula FORMAT é usada na consulta para especificar qualquer outro formato. Por exemplo:
command
Response
Você pode usar o parâmetro de URL default_format ou o cabeçalho X-ClickHouse-Format para especificar um formato padrão diferente de TabSeparated.
Você pode usar o método POST com consultas parametrizadas. Os parâmetros são especificados entre chaves, com o nome e o tipo do parâmetro, como em {name:Type}. Os valores dos parâmetros são enviados com param_name:

​
Consultas INSERT via HTTP/HTTPS

O método POST de transmissão de dados é necessário para consultas INSERT. Nesse caso, você pode escrever o início da consulta no parâmetro da URL e usar o POST para enviar os dados a serem inseridos. Os dados a serem inseridos podem ser, por exemplo, um dump do MySQL separado por tabulações. Dessa forma, a consulta INSERT substitui o LOAD DATA LOCAL INFILE do MySQL.

​
Exemplos

Para criar uma tabela:
Para usar a consulta INSERT, já conhecida, para inserir dados:
Para enviar os dados separadamente da consulta:
É possível especificar qualquer formato de dados. Por exemplo, é possível especificar o formato ‘Values’, o mesmo formato usado ao escrever INSERT INTO t VALUES:
Para inserir dados de um dump com campos separados por tabulação, especifique o formato correspondente:
Para ler o conteúdo da tabela:
Os dados são exibidos em ordem aleatória devido ao processamento paralelo das consultas
Para excluir a tabela:
Para solicitações bem-sucedidas que não retornam uma tabela de dados, retorna-se um corpo de resposta vazio.

​
Compressão

A compressão pode ser usada para reduzir o tráfego de rede ao transmitir grandes volumes de dados ou para criar dumps já comprimidos. Ao transmitir dados, você pode usar o formato de compressão interno do ClickHouse. Os dados comprimidos têm um formato não padrão, e você precisa do programa clickhouse-compressor para trabalhar com eles. Ele é instalado por padrão com o pacote clickhouse-client. Para aumentar a eficiência da inserção de dados, desative a verificação de checksum no lado do servidor com a configuração http_native_compression_disable_checksumming_on_decompress. Se você especificar compress=1 na URL, o servidor comprimirá os dados enviados para você. Se você especificar decompress=1 na URL, o servidor descomprimirá os dados enviados no método POST. Você também pode optar por usar a compressão HTTP. O ClickHouse oferece suporte aos seguintes métodos de compressão:
  • gzip
  • br
  • deflate
  • xz
  • zstd
  • lz4
  • bz2
  • snappy
Para enviar uma solicitação POST comprimida, adicione o cabeçalho de solicitação Content-Encoding: compression_method. Para que o ClickHouse comprima a resposta, adicione o cabeçalho Accept-Encoding: compression_method à solicitação. Você pode configurar o nível de compressão dos dados usando a configuração http_zlib_compression_level para todos os métodos de compressão.
Alguns clientes HTTP podem descomprimir por padrão os dados recebidos do servidor (com gzip e deflate), e você pode receber dados descomprimidos mesmo que use corretamente as configurações de compressão.

​
Exemplos

Para enviar dados compactados ao servidor:
Para receber o arquivo compactado de dados do servidor:
Para receber dados compactados do servidor, use gunzip para descompactá-los:

​
Banco de dados padrão

Você pode usar o parâmetro database na URL ou o cabeçalho X-ClickHouse-Database para especificar o banco de dados padrão.
Por padrão, o banco de dados registrado nas configurações do servidor é usado como banco de dados padrão. Por padrão, esse é o banco de dados chamado default. Como alternativa, você sempre pode especificar o banco de dados usando um ponto antes do nome da tabela.

​
Autenticação

O nome de usuário e a senha podem ser informados de uma destas três formas:
  1. Usando autenticação HTTP básica.
Por exemplo:
  1. Nos parâmetros de URL user e password
Não recomendamos usar esse método, pois o parâmetro pode ser registrado em log por um proxy web e armazenado em cache no navegador
Por exemplo:
  1. Usando os cabeçalhos ‘X-ClickHouse-User’ e ‘X-ClickHouse-Key’
Por exemplo:
Se o nome de usuário não for especificado, será usado o nome default. Se a senha não for especificada, será usada uma senha vazia. Você também pode usar os parâmetros de URL para especificar configurações para processar uma única consulta ou perfis inteiros de configurações. Por exemplo:
Para mais informações, consulte:

​
Uso de sessões do ClickHouse no protocolo HTTP

Você também pode usar sessões do ClickHouse no protocolo HTTP. Para isso, é necessário adicionar o parâmetro GET session_id à requisição. Você pode usar qualquer string como ID da sessão. Por padrão, a sessão é encerrada após 60 segundos de inatividade. Para alterar esse timeout (em segundos), modifique a configuração default_session_timeout na configuração do servidor ou adicione o parâmetro GET session_timeout à requisição. Para verificar o status da sessão, use o parâmetro session_check=1. Apenas uma consulta por vez pode ser executada em uma única sessão. Você pode receber informações sobre o progresso de uma consulta nos cabeçalhos de resposta X-ClickHouse-Progress. Para isso, habilite send_progress_in_http_headers. Abaixo está um exemplo da sequência de cabeçalhos:
Os possíveis campos de cabeçalho são: As requisições em execução não param automaticamente se a conexão HTTP for perdida. A análise e a formatação dos dados são realizadas no lado do servidor, e o uso da rede pode ser ineficiente. Existem os seguintes parâmetros opcionais: A interface HTTP permite passar dados externos (tabelas temporárias externas) para consulta. Para mais informações, consulte “Dados externos para processamento de consultas”.

​
Bufferização de resposta

A bufferização de resposta pode ser habilitada no lado do servidor. Os seguintes parâmetros de URL são fornecidos para essa finalidade:
  • buffer_size
  • wait_end_of_query
As seguintes configurações podem ser usadas: buffer_size determina o número de bytes do resultado a serem armazenados em buffer na memória do servidor. Se o corpo do resultado for maior que esse limite, o buffer será gravado no canal HTTP, e os dados restantes serão enviados diretamente para o canal HTTP. Para garantir que toda a resposta seja armazenada em buffer, defina wait_end_of_query=1. Nesse caso, os dados que não forem armazenados na memória serão armazenados em buffer em um arquivo temporário do servidor. Por exemplo:
Use bufferização para evitar situações em que ocorra um erro no processamento da consulta depois que o código de resposta e os cabeçalhos HTTP forem enviados ao cliente. Nessa situação, uma mensagem de erro é gravada no final do corpo da resposta e, no lado do cliente, o erro só pode ser detectado na etapa de parsing.

​
Definindo uma role com parâmetros de consulta

Este recurso foi adicionado ao ClickHouse 24.4. Em cenários específicos, pode ser necessário definir primeiro a role concedida antes de executar a própria instrução. No entanto, não é possível enviar SET ROLE e a instrução juntos, pois múltiplas instruções não são permitidas:
O comando acima resulta em um erro:
Para contornar essa limitação, use o parâmetro de consulta role:
Isso equivale a executar SET ROLE my_role antes da instrução. Além disso, é possível especificar vários parâmetros de consulta role:
Neste caso, ?role=my_role&role=my_other_role equivale a executar SET ROLE my_role, my_other_role antes da instrução.

​
Ressalvas sobre códigos de resposta HTTP

Devido às limitações do protocolo HTTP, um código de resposta HTTP 200 não garante que uma consulta tenha sido bem-sucedida. Veja um exemplo:
O motivo desse comportamento é a própria natureza do protocolo HTTP. O cabeçalho HTTP é enviado primeiro com o código HTTP 200, seguido pelo corpo HTTP, e então o erro é injetado no corpo como texto simples. Esse comportamento é independente do formato usado, seja Native, TSV ou JSON; a mensagem de erro sempre aparecerá no meio do fluxo de resposta. Você pode mitigar esse problema habilitando wait_end_of_query=1 (Buffering de resposta). Nesse caso, o envio do cabeçalho HTTP é adiado até que toda a consulta seja concluída. No entanto, isso não resolve completamente o problema, porque o resultado ainda precisa caber em http_response_buffer_size, e outras configurações, como send_progress_in_http_headers, podem interferir no atraso do cabeçalho.
A única forma de capturar todos os erros é analisar o corpo HTTP antes de fazer o parsing usando o formato necessário.
Essas exceções no ClickHouse têm um formato consistente, como mostrado abaixo, independentemente do formato usado (por exemplo, Native, TSV, JSON etc.) quando http_write_exception_in_output_format=0 (padrão). Isso facilita o parsing e a extração de mensagens de erro no lado do cliente.
Onde <TAG> é uma tag aleatória de 16 bytes, a mesma tag enviada no header de resposta X-ClickHouse-Exception-Tag. A <error message> é a mensagem real da exceção (o comprimento exato pode ser encontrado em <message_length>). Todo o bloco de exceção descrito acima pode ter até 16 KiB. Aqui está um exemplo no formato JSON
Veja um exemplo semelhante, mas no formato CSV

​
Consultas com parâmetros

Você pode criar uma consulta com parâmetros e informar os valores deles por meio dos parâmetros correspondentes da solicitação HTTP. Para mais informações, consulte Consultas com parâmetros para CLI.

​
Exemplo

​
Tabulações em parâmetros de URL

Os parâmetros de consulta são interpretados a partir do formato “escaped”. Isso traz alguns benefícios, como a possibilidade de interpretar valores nulos sem ambiguidade como \N. Isso significa que o caractere de tabulação deve ser codificado como \t (ou \ seguido de uma tabulação). Por exemplo, o trecho a seguir contém uma tabulação real entre abc e 123, e a string de entrada é dividida em dois valores:
No entanto, se você tentar codificar um caractere de tabulação real usando %09 em um parâmetro de URL, ele não será interpretado corretamente:
Se estiver usando parâmetros de URL, você precisará codificar \t como %5C%09. Por exemplo:

​
Interface HTTP predefinida

O ClickHouse suporta consultas específicas por meio da interface HTTP. Por exemplo, você pode gravar dados em uma tabela da seguinte forma:
O ClickHouse também oferece suporte a uma Interface HTTP predefinida, o que pode facilitar a integração com ferramentas de terceiros, como o Prometheus exporter. Vamos ver um exemplo. Antes de mais nada, adicione esta seção ao arquivo de configuração do servidor. http_handlers é configurado para conter várias rule. O ClickHouse faz a correspondência entre as requisições HTTP recebidas e o tipo predefinido em rule, e a primeira regra correspondente executa o handler. Em seguida, o ClickHouse executa a consulta predefinida correspondente se a correspondência for bem-sucedida.
config.xml
Agora você pode fazer uma solicitação diretamente à URL para obter dados no formato Prometheus:
As opções de configuração de http_handlers funcionam da seguinte forma. rule pode configurar os seguintes parâmetros:
  • method
  • headers
  • url
  • full_url
  • handler
Cada um deles é explicado abaixo:
  • method é responsável por corresponder à parte do método da requisição HTTP. method está totalmente em conformidade com a definição de [method] (https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) no protocolo HTTP. É uma configuração opcional. Se não estiver definido no arquivo de configuração, não fará correspondência com a parte do método da requisição HTTP.
  • url é responsável por corresponder à parte da URL (path e query string) da requisição HTTP. Se url tiver o prefixo regex:, serão esperadas expressões regulares RE2. É uma configuração opcional. Se não estiver definido no arquivo de configuração, não fará correspondência com a parte da URL da requisição HTTP.
  • full_url é igual a url, mas inclui a URL completa, isto é, schema://host:port/path?query_string. Observe que o ClickHouse não oferece suporte a “virtual hosts”, portanto host é um endereço IP (e não o valor do cabeçalho Host).
  • empty_query_string - garante que não haja query string (?query_string) na requisição
  • headers são responsáveis por corresponder à parte dos cabeçalhos da requisição HTTP. É compatível com expressões regulares RE2. É uma configuração opcional . Se não estiver definido no arquivo de configuração, não fará correspondência com a parte dos cabeçalhos da requisição HTTP.
  • handler contém a parte principal do processamento. Ele pode ter o seguinte type: E os seguintes parâmetros:
    • query — use com o tipo predefined_query_handler; executa a consulta quando o handler é chamado.
    • query_param_name — use com o tipo dynamic_query_handler; extrai e executa o valor correspondente a query_param_name nos parâmetros da requisição HTTP.
    • status — use com o tipo static, código de status da resposta.
    • content_type — use com qualquer tipo, content-type da resposta.
    • http_response_headers — use com qualquer tipo, map dos cabeçalhos da resposta. Também pode ser usado para definir o tipo de conteúdo.
    • response_content — use com o tipo static, conteúdo da resposta enviado ao cliente; ao usar o prefixo ‘file://’ ou ‘config://’, o conteúdo é obtido do arquivo ou da configuração e enviado ao cliente.
    • user - usuário com o qual executar a consulta (o usuário padrão é default). Observação, você não precisa especificar a senha desse usuário.
Os métodos de configuração para diferentes types são discutidos a seguir.

​
predefined_query_handler

predefined_query_handler oferece suporte à definição de valores de Settings e query_params. Você pode configurar query para o tipo predefined_query_handler. O valor de query é uma consulta predefinida de predefined_query_handler, executada pelo ClickHouse quando uma requisição HTTP corresponde a ela, e o resultado da consulta é retornado. Essa configuração é obrigatória. O exemplo a seguir define os valores das configurações max_threads e max_final_threads e, em seguida, consulta a tabela de sistema para verificar se essas configurações foram definidas com sucesso.
Para manter os handlers padrão, como query, play e ping, adicione a regra <defaults/>.
Por exemplo:

​
Parâmetro virtual _request_body

Além dos parâmetros de URL, cabeçalhos e parâmetros de consulta, predefined_query_handler oferece suporte a um parâmetro virtual especial, _request_body. Ele contém o corpo bruto da requisição HTTP como uma string. Isso permite criar APIs REST flexíveis que podem aceitar formatos de dados arbitrários e processá-los nas suas consultas. Por exemplo, você pode usar _request_body para implementar um endpoint REST que aceita dados JSON em uma requisição POST e os insere em uma tabela:
Em seguida, você pode enviar dados para este endpoint:
Em um predefined_query_handler, apenas uma consulta é compatível.

​
dynamic_query_handler

Em dynamic_query_handler, a consulta é escrita como um parâmetro da requisição HTTP. A diferença é que, em predefined_query_handler, a consulta é escrita no arquivo de configuração. query_param_name pode ser configurado em dynamic_query_handler. O ClickHouse extrai e executa o valor correspondente a query_param_name na URL da requisição HTTP. O valor padrão de query_param_name é /query. Essa é uma configuração opcional. Se não houver definição no arquivo de configuração, o parâmetro não será passado. Para testar essa funcionalidade, o exemplo a seguir define os valores de max_threads e max_final_threads e consulta se as configurações foram definidas com sucesso. Exemplo:

​
static

static pode retornar content_type, status e response_content. response_content pode retornar o conteúdo especificado. Por exemplo, para retornar a mensagem “Say Hi!”:
http_response_headers pode ser usado para definir o tipo de conteúdo em vez de content_type.
Encontre o conteúdo da configuração enviada ao cliente.
Para encontrar o conteúdo do arquivo enviado ao cliente:

​
redirect

redirect fará um redirecionamento 302 para location Por exemplo, veja como adicionar automaticamente set user ao play do ClickHouse:

​
Cabeçalhos de resposta HTTP

O ClickHouse permite configurar cabeçalhos de resposta HTTP personalizados que podem ser aplicados a qualquer tipo de handler configurável. Esses cabeçalhos podem ser definidos usando a configuração http_response_headers, que aceita pares chave-valor que representam nomes de cabeçalhos e seus respectivos valores. Esse recurso é especialmente útil para implementar cabeçalhos de segurança personalizados, políticas de CORS ou quaisquer outros requisitos de cabeçalhos HTTP em toda a interface HTTP do ClickHouse. Por exemplo, você pode configurar cabeçalhos para:
  • Endpoints de consulta regulares
  • UI da Web
  • Verificação de integridade.
Também é possível especificar common_http_response_headers. Eles serão aplicados a todos os handlers HTTP definidos na configuração. Os cabeçalhos serão incluídos na resposta HTTP de cada handler configurado. No exemplo abaixo, toda resposta do servidor conterá dois cabeçalhos personalizados: X-My-Common-Header e X-My-Custom-Header.

​
Resposta JSON/XML válida em caso de exceção durante HTTP streaming

Durante a execução da consulta por HTTP, pode ocorrer uma exceção quando parte dos dados já tiver sido enviada. Normalmente, a exceção é enviada ao cliente em texto simples. Mesmo que tenha sido usado um formato de dados específico para a saída, ela pode acabar se tornando inválida em relação ao formato especificado. Para evitar isso, você pode usar a configuração http_write_exception_in_output_format (desabilitada por padrão), que faz com que o ClickHouse grave a exceção no formato especificado (atualmente compatível com os formatos XML e JSON*). Exemplos:
Última modificação em 3 de julho de 2026