Exportação para BI

Quem faz análise de dados costuma querer os números da loja fora da loja: em um data lake, em um Looker, num notebook. A exportação para BI (warehouse export) copia seis conjuntos de dados para um bucket S3 (ou compatível, como MinIO ou Cloudflare R2) que você controla, em arquivos Parquet ou CSV, em horário fixo, mandando só o que mudou desde a última vez.

Você configura dois recursos: um destino (o bucket e as credenciais) e um ou mais jobs (qual conjunto exportar, em que formato e com que frequência).

Estas rotas não têm relação com armazém físico ou estoque de depósito: "warehouse" aqui é data warehouse.

Como funciona

1. Crie o destino

   Informe bucket, região, endpoint (se não for AWS) e as chaves. Use Testar para conferir que a plataforma consegue gravar no bucket.

2. Crie um job por conjunto de dados

   Escolha dataset, format, csv_style e schedule. Já nasce ativo e com marca d'água zerada: a primeira execução exporta tudo.

3. Deixe rodar, ou rode agora

   O agendador executa o job quando ele vence. Para antecipar, use Executar agora.

4. Acompanhe

   Cada execução vira um registro (success ou failed) com a quantidade de linhas e o caminho do último arquivo.

Conceitos-chave

Marca d'água

A marca d'água é a data da última linha exportada. Cada execução pede ao banco as linhas com data de alteração (ou de criação, em conjuntos que nunca mudam) maiores que ela e só a avança depois que o arquivo foi gravado no bucket com sucesso. Uma queda no meio nunca perde linhas: no pior caso, repete. Zerar a marca d'água reexporta tudo na próxima execução.

Arquivos no bucket

Cada página de até 50 mil linhas vira um arquivo em <prefix>/<dataset>/v1/dt=<AAAA-MM-DD>/<tempo>_<id>.<parquet|csv>. O dt= usa o dia em que o arquivo foi gerado, no fuso da loja. O v1 é a versão do esquema.

Parquet e CSV

Parquet é o padrão: compacto e tipado. No CSV, csv_style: "international" escreve centavos como inteiro e datas em ISO 8601; "brazilian" escreve reais com vírgula (49,90) e datas dd/mm/aaaa hh:mm:ss.

Endpoints

Erros comuns

1. Esperar validação dos campos do destino. A API aceita name e bucket vazios; o erro só aparece no teste ou na primeira execução.
2. Usar PUT de job com um campo só. O PUT regrava format, csv_style, schedule e is_active; o que faltar vira vazio e a gravação é recusada.
3. Criar o mesmo job duas vezes. A combinação destino, conjunto e formato é única.
4. Achar que a resposta de criação reflete o estado. A criação do job devolve is_active: false e marca d'água zerada mesmo que o job tenha nascido ativo.
5. Ignorar deleted_at. Registros apagados na loja seguem no arquivo; aplique a exclusão no seu lado.
6. Esperar execução imediata ao criar. O agendador roda a cada 15 minutos.

Próximos passos