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

Migração histórica

Você tem meses ou anos de histórico que ainda não chegaram ao Atlas.

Alto volume

O volume diário histórico é alto demais para a API HTTP processar em tempo útil.

Pré go-live

Você quer popular dashboards retroativamente antes do lançamento.

Reprocessamento

Precisa corrigir dados históricos após mudança de lógica no operador.

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

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.

Fluxo geral

1. Exporte para S3

   Você exporta os dados históricos para S3 no formato Parquet particionado.

2. Notifique o time Atlas

   Envie: nome do bucket, prefixo, organization_id, brand_id, janela de datas e domínios.

3. Execução

   O time Atlas executa os scripts de backfill, do dia mais recente para o mais antigo.

4. Acompanhamento

   Você acompanha o progresso via consultas ao backfill_log (ver guia de monitoramento).

Domínios suportados

Domínio	Eventos	Guia
Usuários	register, update	S3 Export Guide
Casino	open, win, lose	S3 Export Guide
Transações	deposit, withdraw	S3 Export Guide
Sportsbook	open, win, lose, cashout	S3 Export Guide

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.