Otimização de Consultas

O Data Warehouse é construído sobre o ClickHouse, um banco de dados colunar. Isso significa que as consultas se comportam de forma diferente de um banco de dados relacional tradicional. Aqui explicamos como aproveitar a estrutura para obter resultados rápidos.

Princípios Fundamentais

1. Sempre filtre por data

Todas as tabelas de fatos são particionadas por mês (toYYYYMM(created_at)). Filtrar por data permite ao ClickHouse pular partições inteiras sem lê-las.

-- Bom: ClickHouse lê apenas 1 partição
SELECT * FROM fact_conversations
WHERE created_at >= '2026-04-01' AND created_at < '2026-05-01'

-- Ruim: ClickHouse lê todas as partições
SELECT * FROM fact_conversations
WHERE agent_name = 'Juan'

2. Você não precisa filtrar por company_id

Seu usuário tem uma política de linha que filtra automaticamente pela sua empresa. Você não precisa adicionar WHERE company_id = ... — é aplicado de forma transparente.

3. Selecione apenas as colunas que precisa

ClickHouse é colunar: ele só lê as colunas que você menciona no seu SELECT. Menos colunas = menos dados lidos = mais rápido.

-- Bom: lê apenas 3 colunas
SELECT conversation_id, created_at, status
FROM fact_conversations
WHERE created_at >= now() - INTERVAL 7 DAY

-- Evite: lê todas as colunas
SELECT *
FROM fact_conversations
WHERE created_at >= now() - INTERVAL 7 DAY

4. Use LIMIT para explorar

Ao explorar dados, use LIMIT para evitar trazer milhões de linhas:

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

Estrutura Interna das Tabelas

Cada tabela tem uma ordem de classificação (sort key) que determina como os dados são organizados em disco. Consultas que filtram pelas primeiras colunas do sort key são muito mais eficientes.

Sort Keys por Tabela

Tabela	Sort Key	Filtra eficientemente por
`fact_conversations`	`(company_id, created_at, conversation_id)`	data, conversation_id
`fact_agent_messages`	`(company_id, created_at, message_id)`	data, message_id
`fact_redirections`	`(company_id, created_at, redirection_id)`	data
`fact_agent_status_changes`	`(company_id, agent_id, created_at)`	agent_id + data
`fact_agent_daily`	`(company_id, day, agent_id)`	dia, agent_id
`fact_sessions`	`(company_id, created_at, session_id)`	data, session_id
`fact_deployment_status`	`(company_id, timestamps_eta, deployment_id)`	data
`fact_deployment_daily`	`(company_id, day, poll_id)`	dia, poll_id
`fact_inbound_messages`	`(company_id, created_at, session_id)`	data
`fact_whatsapp_links`	`(company_id, created_at, event_id)`	data
`fact_hsm_responses`	`(company_id, response_date, interaction_answer_id)`	data

company_id é sempre a primeira coluna do sort key. Como seu usuário tem um filtro automático por empresa, todas as suas consultas aproveitam essa otimização sem que você precise fazer nada.

Índices Secundários

Algumas tabelas têm índices adicionais que ajudam a filtrar por colunas que não estão no sort key:

Tabela	Índice	Coluna	Tipo	Útil para
`fact_agent_messages`	`idx_conversation_id`	`conversation_id`	minmax	Buscar mensagens de uma conversa específica
`fact_agent_messages`	`idx_sender`	`sender`	bloom_filter	Filtrar por `sender = 'AGENT'` ou `sender = 'USER'`
`fact_sessions`	`idx_poll_id`	`poll_id`	minmax	Filtrar por campanha
`fact_sessions`	`idx_inbound_outbound`	`inbound_outbound`	bloom_filter	Filtrar por tipo INBOUND/OUTBOUND
`fact_deployment_status`	`idx_poll_id`	`poll_id`	minmax	Filtrar por campanha
`fact_deployment_status`	`idx_status`	`status`	bloom_filter	Filtrar por status de envio
`fact_inbound_messages`	`idx_poll_id`	`poll_id`	minmax	Filtrar por campanha
`fact_hsm_responses`	`idx_hsm_id`	`hsm_id`	minmax	Filtrar por template HSM
`fact_hsm_responses`	`idx_poll_id`	`poll_id`	minmax	Filtrar por campanha

Limites do Sistema

Seu usuário tem os seguintes limites para proteger a estabilidade do sistema:

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
Máximo de memória	2 GB

Se sua consulta exceder algum desses limites, ela será cancelada automaticamente. Para evitar:

Adicione filtros de data mais estreitos
Selecione menos colunas
Use LIMIT
Pré-agregue com GROUP BY em vez de trazer linhas individuais

Padrões Comuns

JOIN entre tabelas de fatos

Você pode cruzar tabelas usando conversation_id ou survey_user_id:

-- Mensagens de uma conversa com dados da conversa
SELECT
    fc.conversation_id,
    fc.agent_name,
    fm.created_at AS data_mensagem,
    fm.sender,
    fm.content
FROM client_analytics.fact_conversations fc
INNER JOIN client_analytics.fact_agent_messages fm
    ON fm.conversation_id = fc.conversation_id
WHERE fc.created_at >= now() - INTERVAL 7 DAY
ORDER BY fm.created_at
LIMIT 1000

JOIN com dimensões

-- Produtividade por equipe (team_name vem da dimensão)
SELECT
    at.team_name,
    sum(ad.chats_handled) AS chats,
    round(avg(ad.avg_first_response_sec), 0) AS resposta_media_seg
FROM client_analytics.fact_agent_daily ad
INNER JOIN client_analytics.dim_agent_tags at ON at.agent_id = ad.agent_id
WHERE ad.day >= today() - 30
GROUP BY at.team_name
ORDER BY chats DESC

Nível de serviço personalizado

-- Defina seu próprio limite de SLA
SELECT
    toDate(created_at) AS dia,
    count() AS conversas,
    countIf(first_response_sec <= 60) AS dentro_60s,
    countIf(first_response_sec <= 120) AS dentro_120s,
    countIf(first_response_sec <= 300) AS dentro_5min,
    round(countIf(first_response_sec <= 120) * 100.0 / count(), 1) AS sla_pct
FROM client_analytics.fact_conversations
WHERE created_at >= now() - INTERVAL 30 DAY
  AND first_response_sec IS NOT NULL
GROUP BY dia
ORDER BY dia DESC

Começar

Meta

Construa com o Treble

Plataforma Principal

Plataforma de Agentes

Integrações

Data Warehouse

Otimização de Consultas

Otimização de Consultas

Princípios Fundamentais

1. Sempre filtre por data

2. Você não precisa filtrar por company_id

3. Selecione apenas as colunas que precisa

4. Use LIMIT para explorar

Estrutura Interna das Tabelas

Sort Keys por Tabela

Índices Secundários

Limites do Sistema

Padrões Comuns

JOIN entre tabelas de fatos

JOIN com dimensões

Nível de serviço personalizado

​Otimização de Consultas

​Princípios Fundamentais

​1. Sempre filtre por data

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

​3. Selecione apenas as colunas que precisa

​4. Use LIMIT para explorar

​Estrutura Interna das Tabelas

​Sort Keys por Tabela

​Índices Secundários

​Limites do Sistema

​Padrões Comuns

​JOIN entre tabelas de fatos

​JOIN com dimensões

​Nível de serviço personalizado

Otimização de Consultas

Princípios Fundamentais

1. Sempre filtre por data

2. Você não precisa filtrar por company_id

3. Selecione apenas as colunas que precisa

4. Use LIMIT para explorar

Estrutura Interna das Tabelas

Sort Keys por Tabela

Índices Secundários

Limites do Sistema

Padrões Comuns

JOIN entre tabelas de fatos

JOIN com dimensões

Nível de serviço personalizado