O que é ClickHouse: características e instalação passo a passo (guia 2026)

Guia prático de ClickHouse para makers: o que é, por que é tão rápido, suas características chave e como instalá-lo em 5 minutos com curl ou Docker.

Índice

O que é ClickHouse (sem marketing)
- Por que é tão rápido: as quatro razões reais
Características principais que deveria conhecer
A minha opinião: quando ClickHouse é a decisão certa e quando não é
Instalação de ClickHouse passo a passo
As suas primeiras consultas: de zero a dados reais
Erros que vai cometer (eu cometi-os)
Conclusão
Perguntas frequentes

O que é ClickHouse (sem marketing)

ClickHouse é um banco de dados analítico colunar de código aberto, escrito em C++, desenhado para executar consultas de agregação sobre volumes grandes de dados a velocidades que parecem um erro de medição.

A palavra-chave é analítico. Em jargão de bancos de dados, isto significa OLAP (Online Analytical Processing), em oposição a OLTP (Online Transaction Processing), que é o que fazem PostgreSQL ou MySQL.

A diferença importa mais do que parece:

OLTP (Postgres, MySQL, SQLite) está otimizado para ler e escrever linhas individuais muito rápido. "Dá-me o usuário 4821". "Atualiza o estado deste pedido". Milhares de operações pequenas por segundo, com transações e consistência forte.

OLAP (ClickHouse, DuckDB, BigQuery) está otimizado para ler muitas linhas mas poucas colunas. "Dá-me a soma de receitas por país nos últimos 90 dias". Não lhe importa uma linha concreta; importa-lhe varrer milhões de linhas e reduzi-las a um número.

Se quiser o contexto completo desta categoria —história, casos de uso e o mapa de fornecedores— desenvolvo-o em o que são os bancos de dados OLAP.

A chave técnica que o permite é o armazenamento colunar. Um banco de dados por linhas guarda os dados assim no disco:

[id:1, país:ES, ingresos:42, timestamp:...][id:2, país:MX, ingresos:17, timestamp:...]

Se quiser somar a coluna ingresos, tem que ler tudo, incluindo o país e o timestamp que não te importam. ClickHouse guarda cada coluna no seu próprio ficheiro:

ingresos: [42, 17, 88, 12, ...]
país:     [ES, MX, ES, AR, ...]

Para somar ingresos só lê esse ficheiro. Se a sua tabela tem 40 colunas e a sua consulta usa 2, está a ler 5% dos dados. Aí começa a magia, e tudo o resto a amplifica.

Por que é tão rápido: as quatro razões reais

1. Compressão brutal. Quando guarda valores do mesmo tipo juntos e além disso ordenados, os padrões repetem-se e os algoritmos de compressão tornam-se muito eficientes. A documentação de ClickHouse mostra rácios de compressão que vão de 2x em texto livre até mais de 1.000x em colunas de baixa cardinalidade bem ordenadas. Menos bytes no disco = menos I/O = consultas mais rápidas.

2. Índice primário esparso. ClickHouse não cria um índice B-tree com uma entrada por linha. Cria um índice esparso: uma entrada a cada 8.192 linhas (um "grânulo"). Isto significa uns poucos megabytes de índice por terabyte de dados, que cabem em RAM sem se despentear. A contrapartida é que ClickHouse nunca procura uma linha exata, mas o bloco onde está. Para analítica é exatamente o trade-off correto.

3. Motor vetorizado e paralelo. As operações executam-se sobre blocos de colunas usando instruções SIMD, não linha a linha. E paralelizam-se agressivamente sobre todos os cores disponíveis. Num portátil de 8 cores já notas a diferença; num servidor de 64 é outra liga.

4. Separação de leituras e escritas. Os inserts criam "parts" novas que se fundem em segundo plano (arquitetura tipo LSM). Inserir não bloqueia consultas, e consultar não bloqueia inserts.

Características principais que deveria conhecer

Estas são as que realmente mudam como desenham o seu projeto, não a lista completa do datasheet.

Um só binário, zero dependências

Isto soa a detalhe menor e é provavelmente o mais importante para um projeto pequeno. ClickHouse distribui-se como um único executável que contém servidor, cliente e modo local. Não há JVM, não há ZooKeeper obrigatório, não há orquestrador. Descarrega um ficheiro, executa-o, tem um banco de dados analítico.

Compare com levantar Apache Druid, que precisa de seis tipos de processo distintos. Para um maker a trabalhar só, esta diferença é a que decide se o projeto avança ou morre no docker-compose.yml.

`clickhouse-local`: SQL sobre ficheiros sem servidor

Pode consultar CSV, Parquet ou JSON diretamente desde o disco ou desde um URL, sem importar nada nem levantar servidor:

./clickhouse local --query "
  SELECT country, count() AS visitas
  FROM file('logs.csv', CSVWithNames)
  GROUP BY country
  ORDER BY visitas DESC
  LIMIT 10
"

Isto substitui scripts de pandas para exploração rápida e é notavelmente mais rápido em ficheiros grandes.

Vistas materializadas incrementais

Esta é a característica que mais me mudou a forma de construir. Uma vista materializada em ClickHouse não é uma cache que se refresca: é um trigger de inserção. Cada vez que insere na tabela origem, a agregação calcula-se sobre esse bloco e escreve-se na tabela destino.

O resultado é que move o custo do momento da consulta para o momento da inserção. O seu dashboard consulta uma tabela de 4.000 linhas pré-agregadas em vez de 400 milhões de linhas cruas. Cubro-o em profundidade no guia avançado, mas fique com a ideia.

Suporte SQL completo com JOINs de verdade

Durante anos a crítica padrão ao ClickHouse era "os JOINs são maus". Isso já não se sustenta. Suporta todos os tipos de JOIN padrão, tem um otimizador que reordena joins usando estatísticas de colunas, e adiciona tipos que não existem em SQL padrão como ASOF JOIN (unir pelo valor temporal mais próximo, não exato), que é ouro puro para séries temporais e dados financeiros.

Além disso estende SQL com centenas de funções analíticas: uniqExact, quantileTDigest, windowFunnel, sequenceMatch. Coisas que em Postgres seriam uma CTE de 60 linhas aqui são uma função.

Compatibilidade com mais de 70 formatos e data lakes

Lê e escreve Parquet, Iceberg, Delta Lake, Avro, Protobuf, JSON em todas as suas variantes. Pode consultar diretamente ficheiros em S3 sem os ingerir. Isto significa que não o encerra: se amanhã quiser migrar, os seus dados saem em Parquet com uma sentença.

JSON sem explosão de esquema

Pode ingerir dados semi-estruturados com um tipo JSON nativo que internamente os armazena de forma colunar. Ingerir eventos com formas variáveis sem desenhar o esquema perfeito de antemão, e continua a ter desempenho de banco de dados colunar.

A minha opinião: quando ClickHouse é a decisão certa e quando não é

Aqui é onde a maioria dos tutoriais te falha, porque estão escritos por gente que te quer vender algo.

ClickHouse é uma ótima ideia se:

Tem uma tabela de eventos que cresce sem parar —analítica de produto, logs, métricas, clicks, telemetria de IoT— e as suas consultas são agregações sobre intervalos temporais. Este é o caso canónico e onde vai parecer magia.

Está a construir analítica voltada ao usuário: um dashboard dentro do seu produto que muitos clientes consultam simultaneamente. ClickHouse lida com concorrência alta com latências de milissegundos, que é justo onde warehouses como Snowflake se tornam caros.

A sua fatura de BigQuery ou Snowflake lhe dá ansiedade. Um servidor dedicado de 30-60 €/mês com ClickHouse aguenta cargas que num warehouse por consumo custam uma ordem de magnitude mais. Para um projeto bootstrapped isto não é uma otimização, é a diferença entre viável e inviável.

ClickHouse é má ideia se:

Precisa de atualizações e apagamentos frequentes por linha. ClickHouse melhorou muito aqui (mutações leves, ReplacingMergeTree, deletes leves), mas continua a ser um motor pensado para escrever uma vez e ler muitas. Se a sua carga de trabalho é um CRUD, use Postgres.

Precisa de transações ACID multi-tabela. O suporte transacional é limitado e não é o objetivo do projeto. Não coloque aqui o estado dos seus pedidos.

Tem menos de uns poucos milhões de linhas. Com 500.000 linhas Postgres com um índice decente já te dá respostas em milissegundos. Adicionar ClickHouse é complexidade operativa sem benefício. A resposta correta para um dataset pequeno é não mudar de banco de dados.

A sua equipa é zero pessoas e já tem três serviços para manter. É um serviço mais para monitorizar, fazer backup e atualizar. Vale a pena quando a dor de desempenho é real, não quando é antecipada.

A minha regra prática: se um GROUP BY sobre a sua maior tabela demora mais de 5 segundos em Postgres e essa consulta é central para o seu produto, é altura de olhar para ClickHouse. Antes disso, não.

Um matiz adicional: o padrão que melhor me tem funcionado não é substituir Postgres, mas pô-los juntos. Postgres continua a ser a fonte da verdade transacional —usuários, pedidos, configuração— e ClickHouse recebe uma cópia da tabela de eventos via CDC ou um job de replicação. Cada um faz o que sabe fazer.

Instalação de ClickHouse passo a passo

Vamos ao prático. Três caminhos segundo o que precisa.

Opção 1: instalação rápida com curl (macOS, Linux, FreeBSD)

A forma mais direta. Descarregue o binário adequado para o seu sistema:

curl https://clickhouse.com/ | sh

Em Linux e macOS isto instala além disso clickhousectl (com alias chctl) em ~/.local/bin, a CLI oficial para gerir várias versões locais, arrancar servidores em segundo plano e ligar com ClickHouse Cloud.

Se só quiser o binário sem a CLI de gestão:

curl https://clickhouse.com/ | CLICKHOUSE_ONLY=1 sh

Nota para utilizadores de macOS: se o Gatekeeper se queixa de que não pode verificar o desenvolvedor do binário, vá a Ajustes do Sistema → Privacidade e Segurança e autorize a execução. É o comportamento normal de macOS com binários não assinados.

Arranque o servidor:

./clickhouse server

E noutro terminal, o cliente:

./clickhouse client

Deveria ver algo assim:

ClickHouse client version 24.5.1.117 (official build).
Connecting to localhost:9000 as user default.
Connected to ClickHouse server version 24.5.1.

local-host :)

Os dados guardam-se no diretório atual e sobrevivem a reinícios do servidor.

Opção 2: Docker (recomendado se já usa contentores)

A minha opção por padrão quando o projeto já tem um docker-compose.yml, porque evita sujar o sistema e torna o ambiente reproduzível.

docker run -d \
  --name clickhouse \
  -p 8123:8123 \
  -p 9000:9000 \
  -v clickhouse_data:/var/lib/clickhouse \
  --ulimit nofile=262144:262144 \
  clickhouse/clickhouse-server

Os dois portos importam e confundem toda o mundo no início:

8123 é a interface HTTP. A usam a maioria dos clientes web, ferramentas de BI e curl.
9000 é o protocolo nativo TCP. Mais rápido e compacto; é o que usa clickhouse-client e os drivers nativos.

A flag --ulimit nofile não é opcional na prática: ClickHouse abre muitos descritores de ficheiro e sem subir o limite verá erros estranhos sob carga.

Como docker-compose.yml:

services:
  clickhouse:
    image: clickhouse/clickhouse-server
    container_name: clickhouse
    ports:
      - "8123:8123"
      - "9000:9000"
    volumes:
      - clickhouse_data:/var/lib/clickhouse
      - ./config.d:/etc/clickhouse-server/config.d
    ulimits:
      nofile:
        soft: 262144
        hard: 262144
    environment:
      CLICKHOUSE_USER: creacosas
      CLICKHOUSE_PASSWORD: cambia_esto
      CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1

volumes:
  clickhouse_data:

Ligue ao cliente dentro do contentor:

docker exec -it clickhouse clickhouse-client --user creacosas --password cambia_esto

Opção 3: sem instalar nada

Se só quer experimentar a sintaxe e ver a velocidade, o playground oficial tem datasets reais carregados e executa consultas desde o navegador. Zero fricção.

As suas primeiras consultas: de zero a dados reais

Vamos criar algo parecido a um caso real: uma tabela de eventos de um site.

Criar a base de dados e a tabela

CREATE DATABASE creacosas;

USE creacosas;

CREATE TABLE eventos
(
    fecha       Date,
    timestamp   DateTime,
    usuario_id  UInt32,
    evento      LowCardinality(String),
    pais        LowCardinality(String),
    url         String,
    duracion_ms UInt32
)
ENGINE = MergeTree
PARTITION BY toYYYYMM(fecha)
ORDER BY (evento, fecha, usuario_id);

Há aqui três decisões que merecem explicação porque são as decisões de ClickHouse:

ENGINE = MergeTree é o motor de tabela por defeito e o que vai usar 90% do tempo. Toda a família MergeTree (ReplacingMergeTree, SummingMergeTree, AggregatingMergeTree) partilha a mesma base com comportamentos adicionados na fusão de partes.

ORDER BY é a decisão mais importante de todo o seu esquema. Define a ordem física dos dados no disco e, por defeito, também a chave primária. A regra: coloque primeiro as colunas pelas quais filtra mais e que têm menor cardinalidade. Aqui filtramos quase sempre por tipo de evento e por data, então vão à frente. Enganar-se aqui é a causa número um de "ClickHouse está-me lento".

LowCardinality(String) é um tipo que aplica codificação por dicionário. Se uma coluna tem menos de ~10.000 valores distintos (países, tipos de evento, nomes de plano), envolvê-la em LowCardinality reduz o armazenamento e acelera os filtros de forma notável. É uma vitória grátis que quase ninguém usa no início.

Inserir dados de teste

Vamos gerar 10 milhões de linhas sintéticas para ter algo com que brincar:

INSERT INTO eventos
SELECT
    toDate('2026-01-01') + (number % 220)                       AS fecha,
    toDateTime(fecha) + (number % 86400)                        AS timestamp,
    (number % 50000) + 1                                        AS usuario_id,
    ['pageview','click','signup','purchase'][(intHash32(number) % 4) + 1]      AS evento,
    ['ES','MX','AR','CO','CL','US'][(intHash32(number + 7) % 6) + 1]           AS pais,
    concat('/pagina/', toString(number % 500))                  AS url,
    (number % 5000) + 100                                       AS duracion_ms
FROM numbers(10000000);

A função numbers() gera linhas no momento: é a forma padrão de criar datasets de teste em ClickHouse sem descarregar nada. Uso intHash32() em vez de number % N diretamente para as colunas categóricas, porque se duas colunas usam módulos com fatores comuns (4 e 6, por exemplo) acabam correlacionadas e os resultados saem artificialmente uniformes.

Consultar

SELECT
    pais,
    evento,
    count()                         AS total,
    round(avg(duracion_ms))         AS duracion_media,
    uniqExact(usuario_id)           AS usuarios_unicos
FROM eventos
WHERE fecha >= '2026-03-01'
  AND evento = 'purchase'
GROUP BY pais, evento
ORDER BY total DESC;

Repare na última linha da saída do cliente. Diz-lhe quantas linhas processou, quantos bytes leu e a que velocidade:

6 rows in set. Elapsed: 0.021 sec. Processed 1.14 million rows, 8.32 MB (54.28 million rows/s., 396.19 MB/s.)

Esse número —"processed 1.14 million rows" de um total de 10 milhões— é o que importa. ClickHouse só leu 11% da tabela porque o ORDER BY (evento, fecha, ...) lhe permitiu saltar tudo o resto. Otimizar ClickHouse consiste quase sempre em reduzir esse número.

Um truque: ver o tamanho real no disco

SELECT
    table,
    formatReadableSize(sum(data_compressed_bytes))   AS comprimido,
    formatReadableSize(sum(data_uncompressed_bytes)) AS sin_comprimir,
    round(sum(data_uncompressed_bytes) / sum(data_compressed_bytes), 2) AS ratio
FROM system.columns
WHERE database = 'creacosas'
GROUP BY table;

As tabelas do sistema (system.columns, system.parts, system.query_log) são uma das melhores coisas de ClickHouse: toda a introspeção do motor é SQL consultável.

Erros que vai cometer (eu cometi-os)

Inserir linha a linha. ClickHouse detesta os inserts pequenos. Cada INSERT cria uma "part" nova no disco que depois há que fundir. Mil inserts de uma linha geram mil parts e o servidor afoga-se com o erro Too many parts. Insira em lotes de pelo menos 1.000 linhas —idealmente entre 10.000 e 100.000— ou ative inserts assíncronos com async_insert=1.

Usar Nullable por costume. Cada coluna Nullable adiciona uma coluna extra de máscara e desativa algumas otimizações. Se pode usar um valor sentinela (0, cadeia vazia, 1970-01-01), faça-o.

Pôr uma coluna de alta cardinalidade primeira no ORDER BY. Se põe usuario_id ou um UUID ao início, destrói a compressão e a capacidade de saltar blocos. Baixa cardinalidade primeiro, sempre.

Esperar que UPDATE funcione como em Postgres. Funciona, mas é uma operação pesada. Se o seu design depende de atualizar linhas constantemente, repense o design (ou repense o banco de dados).

Conclusão

ClickHouse não é um banco de dados de propósito geral e esse é justamente o seu valor: faz uma coisa —agregar sobre volumes grandes— melhor do que quase ninguém, e fá-lo com uma pegada operativa ridiculamente pequena para o que oferece. Um binário, sem dependências, a correr desde um portátil até centenas de nós com o mesmo motor.

Para um maker a trabalhar só, esse último ponto é o que decide. Não precisa de uma equipa de dados para operar ClickHouse num VPS. Precisa de entender bem o seu ORDER BY e não inserir linha a linha.

Se vem do Postgres e os seus dashboards agonizam, dedique uma tarde a isto. A curva de aprendizagem inicial é de horas, não de semanas, e o salto de desempenho é dos que se notam sem necessidade de os medir.

Nos seguintes posts desta série aprofundamos as duas perguntas que vêm depois de o instalar:

Alternativas a ClickHouse: comparativa completa — DuckDB, StarRocks, Druid, Pinot, TimescaleDB e os warehouses cloud, com tabela comparativa e veredicto por caso de uso.
Guia avançada de ClickHouse — vistas materializadas, projections, codecs de compressão, TTL, tiering para S3 e diagnóstico de consultas lentas.

Perguntas frequentes

O ClickHouse é grátis?

O motor é open source com licença Apache 2.0 e pode autoalojá-lo sem custo nem limites de funcionalidade. ClickHouse Cloud é o serviço gerenciado pago, com um modelo baseado em consumo de computação e armazenamento separados e escalado a zero quando não há atividade.