Pular para o conteúdo principal
Esta página apresenta os pontos de integração para ajudar você a definir o escopo do trabalho de ingestão e consumo. Para validação e publicação, continue com Testando sua integração e Documentando sua integração.

​
Ingestão

Há duas formas de enviar dados ao ClickHouse. Escolha com base em o seu produto controlar o plano de ingestão ou delegá-lo.

​
Caminho A: ClickPipes (gerenciado, somente no ClickHouse Cloud)

Se você prefere não criar e operar a infraestrutura de ingestão, o ClickPipes é o serviço gerenciado que extrai dados das fontes do seu cliente para o serviço ClickHouse Cloud dele. O ClickPipes cuida do escalonamento, da paralelização, das novas tentativas e dos relatórios de atraso. As fontes compatíveis atualmente incluem:
  • Streaming: Apache Kafka (incluindo MSK, Confluent Cloud, Redpanda, Azure Event Hubs, WarpStream), Amazon Kinesis
  • Armazenamento de objetos: Amazon S3 (e armazenamentos compatíveis com S3), Google Cloud Storage, Azure Blob Storage
  • CDC: PostgreSQL, MySQL, MongoDB, BigQuery

​
Caminho B: ingestão autogerida por meio de um cliente oficial de linguagem

Se você é responsável pelo pipeline, use um dos clientes oficiais de linguagem. Eles cuidam da serialização, do processamento em lotes, do TLS, da compressão e do pool de conexões. Você fornece primitivos de runtime; o cliente cuida do formato wire.
  • Clientes oficiais: Python, Go, Java, JavaScript, Rust, C#, C++
  • Ambos os protocolos wire: HTTP (todos os clientes) e TCP nativo (apenas clientes Go e C++)
  • Autenticação: nome de usuário e senha via TLS por padrão; mTLS e autenticação SSL com certificado de cliente são compatíveis com todos os principais clientes
  • O formato dos dados normalmente é um detalhe de implementação. Os clientes convertem tipos de runtime para ClickHouse Native ou RowBinary format. Se você já produz Arrow, Parquet, JSONEachRow ou outro format, a maioria dos clientes expõe uma API de bytes brutos para dados pré-serializados
  • Para maior vazão, processe em lotes de 10 mil a 100 mil linhas e tenha como meta aproximadamente uma inserção por segundo como limite superior para inserções síncronas. Se o processamento em lotes no lado do cliente for impraticável, use inserções assíncronas para transferir esse processamento para o servidor
Veja também: Inserções em massa.

​
Consumo

Tanto HTTP quanto TCP nativo transportam queries. O protocolo nativo é binário e tem menor sobrecarga. HTTP funciona por meio de balanceadores de carga e proxies. Ambos têm suporte de primeira classe; escolha com base na infraestrutura, não em lacunas de recursos.
  • Código da aplicação: use os mesmos clientes oficiais de linguagem usados na ingestão
  • Ferramentas de BI e SQL: o ClickHouse oferece um driver JDBC v2 oficial (Java) e um driver ODBC. Tableau, Looker, Power BI, Metabase, Apache Superset e Grafana se integram por meio desses drivers ou de conectores dedicados mantidos pela ClickHouse e por parceiros
  • Formato de resultado: os clientes normalmente controlam a serialização. Você pode solicitar Arrow, Parquet ou outros formatos colunares via wire, se o seu produto precisar deles

​
Dimensionamento do conjunto de resultados

A maioria das consultas analíticas retorna conjuntos de resultados pequenos (agregações, resumos, top-N), e o wire raramente é o gargalo. As tabelas do ClickHouse podem armazenar bilhões de linhas, e um SELECT * sem limite em uma tabela de fatos grande pode movimentar terabytes. Modele a requisição na sua aplicação: use LIMIT, paginação, leituras em streaming e listas explícitas de colunas. Se você cria análises voltadas para o usuário, trate conjuntos de resultados não limitados como um problema de UX, não de transporte. O ClickHouse tem um sistema de tipos rico: arrays, tuplas, maps, JSON, nested, LowCardinality e muito mais. Os clientes oficiais mapeiam esses tipos para tipos idiomáticos da linguagem. Se o seu produto expõe dados do ClickHouse aos usuários finais, planeje cedo uma estratégia de mapeamento de tipos.

​
Próximos passos

Escolha um caminho e crie um protótipo usando uma avaliação do ClickHouse Cloud e, depois, registre sua integração no portal de parceiros.

​
Convenção da string user-agent

Os clientes HTTP devem definir uma string User-Agent que identifique sua integração. O ClickHouse analisa isso no servidor para acompanhar a adoção, gerar telemetria de uso e orientar o roadmap. Formato: 
<app_name>/<app_version> <client_name>/<client_version> (<comment>; <key1>: <value1>; <key2>: <value2>)
Exemplos:
  • clickhouse-java/0.8.0
  • my-analytics-app/3.1.2 clickhouse-js/1.2.0 (env: staging; region: us-east-1; lv: node/20.10)
Regras:
  • Sem espaços no nome nem na versão do cliente
  • Se você incluir um comentário, ele deve vir primeiro
  • Chaves de metadados padrão: lv (versão da linguagem ou do framework), os, arch
  • Clientes TCP e do protocolo nativo informam o nome e a versão do cliente por meio de campos do protocolo, não de User-Agent
Se você usar JDBC, consulte identificação do cliente para ver como o driver define User-Agent e campos relacionados.

​
Acesso ao sandbox e ao teste gratuito

ClickHouse Cloud oferece um teste gratuito para desenvolvimento e validação de integrações. Se você for um parceiro House Mate, poderá solicitar créditos adicionais de desenvolvimento por meio do portal de parceiros.
Última modificação em 10 de junho de 2026