> ## Documentation Index
> Fetch the complete documentation index at: https://help.treble.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Otimização de Consultas

> Como escrever queries rápidas e eficientes no Analytics Warehouse.

# 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` |

```sql theme={null}
-- 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.

```sql theme={null}
-- 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`](/pt/docs/data-warehouse-v2/fact-campaign-daily) e [`fact_agent_daily`](/pt/docs/data-warehouse-v2/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

```sql theme={null}
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).

```sql theme={null}
-- 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](/pt/docs/data-warehouse-v2/incremental-sync) para o padrão que evita extrações grandes por completo)