ClickHouse: do projeto à primeira consulta

O ClickHouse é a opção gerenciada da categoria Analytics para armazenar eventos e consultar dados por agregação. Este guia segue a ordem de uso: escolher um plano, criar o projeto, salvar a senha, conectar e consultar. Para dados transacionais da aplicação, compare antes com Banco de Dados.

Antes de começar

• Acesse uma organização na Console com permissão database.create em organization:*. Para visualizar o projeto depois, você precisa de project.read em project:<project-id>; para a conexão, database.connection.read em database:<project-id>.
• Escolha a SKU analytics-* conforme a capacidade e a topologia desejadas. Compare os planos antes de criar: Sandbox e Starter usam uma instância; Production e Enterprise têm três réplicas.
• Tenha um lugar seguro para guardar a senha no momento da criação. A Console não recupera a senha completa depois.

Crie o projeto

1. Na Console, escolha Criar projeto → Analytics → ClickHouse na sua organização.
2. Escolha um nome, uma SKU analytics-* disponível, versão e capacidade de armazenamento conforme as opções exibidas. Confira os valores e a franquia da SKU na própria Console antes de confirmar.
3. Envie a criação e acompanhe o estado do projeto até ficar pronto. A criação pode levar algum tempo; não trate o retorno inicial como garantia de que a consulta SQL já está disponível.
4. Na tela de conclusão, copie a senha e a conexão utilizável para um gerenciador de segredos. Não inclua a senha em código, mensagens ou screenshots. Ao fechar essa tela, a leitura da conexão volta a ser mascarada.
5. Em Projeto → Conexão, copie o host, o usuário, o banco e as duas portas atribuídas ao seu projeto. A porta Native TLS e a porta HTTPS/JDBC são diferentes; nunca suponha números fixos nem que uma possa substituir a outra.

Se a tela de conexão não mostrar a porta HTTPS/JDBC, não tente adivinhá-la. Confira o estado do projeto e use apenas os dados que a Console apresentar. Consulte Conexões e clientes para escolher o protocolo correto.

Conecte e valide

No DBeaver, selecione o driver ClickHouse atual, use a porta HTTPS/JDBC, habilite SSL e inclua explicitamente ssl=true na URL JDBC. No clickhouse-client, use a porta Native TLS com --secure. Configure usuário, senha e nome do banco a partir do seu projeto. O guia de conexões traz os campos e exemplos completos para ambos os clientes.

Com o cliente autenticado, execute:

SELECT 1;
SELECT currentDatabase();

SELECT 1 valida a consulta autenticada; currentDatabase() confirma o banco ativo. Um endpoint que responde a /ping ou uma porta TLS aberta não comprova que sua senha e suas consultas funcionam.

Crie dados para uma primeira análise

No exemplo a seguir, use o banco app apresentado para conexões novas. Se a Console indicar outro banco para seu projeto, adapte o identificador antes de executar. Os valores são ilustrativos; use dados próprios para uma aplicação real.

CREATE TABLE app.events
(
    event_time DateTime,
    event_type LowCardinality(String),
    user_id UInt64
)
ORDER BY (event_type, event_time, user_id);

INSERT INTO app.events (event_time, event_type, user_id) VALUES
    ('2026-01-01 12:00:00', 'page_view', 101),
    ('2026-01-01 12:01:00', 'signup', 101),
    ('2026-01-01 12:02:00', 'page_view', 102);

SELECT event_type, count() AS total
FROM app.events
GROUP BY event_type
ORDER BY total DESC;

No banco app, o usuário da Zenifra tem ReplicatedMergeTree como engine padrão para tabelas e o DDL é replicado. A instrução acima deixa a engine implícita de propósito. Em planos com três réplicas, declarar explicitamente uma engine não replicada (por exemplo, MergeTree) muda a garantia de disponibilidade dos dados dessa tabela. Evite aplicar exemplos genéricos do ClickHouse com essa engine sem entender a diferença. Para a semântica de SQL e das engines, consulte a documentação oficial de criação de tabelas.

Próximos passos

• Escolha ou compare a topologia dos planos.
• Configure DBeaver e clickhouse-client.
• Cuide da senha e resolva erros de conexão.