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

# Backfill de Histórico via S3

> Ingira meses ou anos de eventos históricos diretamente em Parquet no S3, sem passar pela API de eventos.

# Backfill de Histórico

Se você já possui dados históricos de eventos (usuários, apostas, transações) armazenados no seu data warehouse, é possível enviá-los para o Atlas via **S3 + Parquet** — sem precisar reenviar tudo pela API de ingestão.

## Quando usar

<CardGroup cols={2}>
  <Card title="Migração histórica" icon="clock-rotate-left">
    Você tem meses ou anos de histórico que ainda não chegaram ao Atlas.
  </Card>

  <Card title="Alto volume" icon="gauge-high">
    O volume diário histórico é alto demais para a API HTTP processar em tempo útil.
  </Card>

  <Card title="Pré go-live" icon="rocket">
    Você quer popular dashboards retroativamente antes do lançamento.
  </Card>

  <Card title="Reprocessamento" icon="arrows-rotate">
    Precisa corrigir dados históricos após mudança de lógica no operador.
  </Card>
</CardGroup>

## Pré-requisitos

| Item             | Detalhe                                               |
| ---------------- | ----------------------------------------------------- |
| Bucket S3        | Mesma região do cluster ClickHouse Cloud (us-east-1)  |
| IAM User ou Role | Permissões `s3:GetObject` e `s3:ListBucket` no bucket |
| Formato          | **Parquet** (obrigatório)                             |
| Particionamento  | Por `organization_id / brand_id / year / month / day` |
| Schema           | Colunas com os tipos corretos (ver guia por domínio)  |

## Arquitetura

Real-time e backfill usam caminhos **separados** até `tbt_raw_events_{domain}`.
Real-time entra direto do ClickPipe na tabela persistida e dispara a cascade de
MVs Gold automaticamente. Backfill entra por uma Null table (`{domain}_events_inbound`)
que serve exclusivamente ao histórico — uma bridge MV normaliza e propaga
para `tbt_`, mas as Gold MVs **não** agregam em cascade a partir desse caminho.

```
Real-time:
  ClickPipes MSK → tbt_raw_events_{domain}
                  ↘ gold_* (cascade automática)

Backfill histórico:
  Parquet S3 → INSERT FROM s3() → {domain}_events_inbound (Null HUB)
                                → bridge MV → tbt_raw_events_{domain}
                                               ✗ gold_* NÃO é populado
```

<Warning>
  **Gold tables não agregam backfill automaticamente.** Os dados históricos chegam
  em `tbt_raw_events_{domain}`, mas as agregações Gold (GGR, volume, liability,
  etc.) precisam ser populadas via replay manual por período:
  `INSERT INTO atlas.gold_X SELECT ... FROM atlas.tbt_raw_events_Y WHERE event_timestamp BETWEEN ... AND ...`.
  Coordene com o time Atlas após o backfill para reprocessar as Gold do período.
</Warning>

## Fluxo geral

<Steps>
  <Step title="Exporte para S3">
    Você exporta os dados históricos para S3 no formato Parquet particionado.
  </Step>

  <Step title="Notifique o time Atlas">
    Envie: nome do bucket, prefixo, `organization_id`, `brand_id`, janela de datas e domínios.
  </Step>

  <Step title="Execução">
    O time Atlas executa os scripts de backfill, do dia mais recente para o mais antigo.
  </Step>

  <Step title="Acompanhamento">
    Você acompanha o progresso via consultas ao `backfill_log` (ver guia de monitoramento).
  </Step>
</Steps>

## Domínios suportados

| Domínio    | Eventos                          | Guia                                                            |
| ---------- | -------------------------------- | --------------------------------------------------------------- |
| Usuários   | `register`, `update`             | [S3 Export Guide](/guides/backfill/s3-export-guide#user)        |
| Casino     | `open`, `win`, `lose`            | [S3 Export Guide](/guides/backfill/s3-export-guide#casino)      |
| Transações | `deposit`, `withdraw`            | [S3 Export Guide](/guides/backfill/s3-export-guide#transaction) |
| Sportsbook | `open`, `win`, `lose`, `cashout` | [S3 Export Guide](/guides/backfill/s3-export-guide#sportsbook)  |

<Warning>
  O domínio `user-score` **não é suportado por backfill S3** — scores são calculados pelo worker de scoring a partir dos eventos reais. Para popular scores históricos, reprocesse os eventos originais.
</Warning>