Otimização de Consultas

O Analytics Warehouse roda em ClickHouse, um banco de dados colunar. As queries se comportam de forma diferente de um banco de dados relacional tradicional — alguns hábitos as tornam dramaticamente mais rápidas.

Princípios-chave

1. Sempre filtre por data

Os dados são organizados fisicamente por tempo. Um filtro de data permite que o ClickHouse pule blocos inteiros de histórico sem lê-los — e como o warehouse agora serve o histórico completo (não apenas 3 meses), os filtros de data importam mais do que nunca. Cada tabela tem uma coluna de tempo principal para filtrar:

Tabela	Filtre por
`fact_treble_sessions`, `fact_treble_session_messages`, `fact_treble_session_variables`, `fact_ad_sessions`	`created_at`
`fact_treble_session_nodes`	`entered_at`
`fact_campaign_sends`	`scheduled_at`
`fact_campaign_daily`, `fact_agent_daily`	`day`
`fact_agent_conversations`, `fact_agent_conversation_messages`, `fact_agent_conversation_transfers`, `fact_agent_status_changes`, `fact_whatsapp_link_events`, `fact_target_events`	`created_at`
`fact_hsm_responses`	`responded_at`

-- Bom: lê apenas a fatia relevante do histórico
SELECT count() FROM fact_treble_sessions
WHERE created_at >= '2026-07-01' AND created_at < '2026-08-01'

-- Ruim: varre todo o histórico da tabela
SELECT count() FROM fact_treble_sessions
WHERE poll_name = 'Welcome flow'

2. Você não precisa filtrar por company_id

Seu usuário tem uma row policy que filtra pela sua empresa automaticamente, e os dados são ordenados primeiro por empresa — todas as queries se beneficiam disso sem que você precise adicionar nada.

3. Selecione apenas as colunas de que você precisa

O ClickHouse lê apenas as colunas que você menciona. Isso importa principalmente nas colunas de texto largas (text, content, ai_automator_instructions): deixá-las fora de um SELECT pode reduzir o custo de uma query em uma ordem de magnitude.

-- Bom: 3 colunas estreitas
SELECT session_id, created_at, status
FROM fact_treble_sessions
WHERE created_at >= now() - INTERVAL 7 DAY

-- Evite: SELECT * arrasta todas as colunas largas junto
SELECT * FROM fact_treble_session_messages
WHERE created_at >= now() - INTERVAL 7 DAY

4. Agregue no banco de dados, não na sua ferramenta

Extraia respostas, não linhas brutas. Um GROUP BY sobre milhões de linhas retorna em bem menos de um segundo; baixar esses milhões de linhas para uma ferramenta de BI, não.

5. Use os resumos diários quando eles atenderem

fact_campaign_daily e fact_agent_daily pré-calculam as métricas de dashboard mais comuns. Um dashboard sobre um resumo diário lê milhares de linhas em vez de milhões.

6. Use LIMIT ao explorar

SELECT * FROM fact_treble_session_messages
WHERE created_at >= now() - INTERVAL 1 DAY
ORDER BY created_at DESC
LIMIT 100

Dicas de JOIN

Faça join por ids, não por nomes: session_id, agent_conversation_id, hsm_id — os nomes são para exibição.
Coloque a tabela pequena do lado direito do JOIN — o ClickHouse carrega o lado direito na memória. As dimensões são sempre pequenas; o join entre duas tabelas de fatos grandes funciona melhor quando os dois lados carregam um filtro de data.
Inclua company_id na chave do join ao juntar fatos com dimensões (como fazem os exemplos desta documentação).

-- Sessões enriquecidas com o nome de exibição do canal
SELECT s.poll_name, c.display_name, count() AS sessions
FROM fact_treble_sessions AS s
LEFT JOIN dim_channels AS c
    ON c.company_id = s.company_id AND c.channel_id = s.channel_id
WHERE s.created_at >= today() - 30
GROUP BY s.poll_name, c.display_name

Limites do sistema

Seu usuário roda com limites de proteção que mantêm a plataforma estável para todos:

Limite	Valor
Tempo máximo de execução	30 segundos
Máximo de linhas lidas	50 milhões
Máximo de bytes lidos	5 GB
Máximo de linhas no resultado	500.000
Memória máxima por query	2 GB
Máximo de colunas lidas por query	50

Se uma query for cancelada por um limite:

Adicione ou restrinja o filtro de data (a solução em quase todos os casos)
Remova colunas desnecessárias — especialmente colunas de texto largas
Agregue com GROUP BY em vez de extrair linhas brutas
Divida extrações muito grandes em blocos de um mês (veja Sincronização Incremental para o padrão que evita extrações grandes por completo)

Começar

Meta

Construa com o Treble

Plataforma Principal

Plataforma de Agentes

Integrações

Analytics Warehouse

Data Warehouse (Legacy)

Otimização de Consultas

Otimização de Consultas

Princípios-chave

1. Sempre filtre por data

2. Você não precisa filtrar por company_id

3. Selecione apenas as colunas de que você precisa

4. Agregue no banco de dados, não na sua ferramenta

5. Use os resumos diários quando eles atenderem

6. Use LIMIT ao explorar

Dicas de JOIN

Limites do sistema

​Otimização de Consultas

​Princípios-chave

​1. Sempre filtre por data

​2. Você não precisa filtrar por company_id

​3. Selecione apenas as colunas de que você precisa

​4. Agregue no banco de dados, não na sua ferramenta

​5. Use os resumos diários quando eles atenderem

​6. Use LIMIT ao explorar

​Dicas de JOIN

​Limites do sistema

Otimização de Consultas

Princípios-chave

1. Sempre filtre por data

2. Você não precisa filtrar por company_id

3. Selecione apenas as colunas de que você precisa

4. Agregue no banco de dados, não na sua ferramenta

5. Use os resumos diários quando eles atenderem

6. Use LIMIT ao explorar

Dicas de JOIN

Limites do sistema