BigQuery

Configure o conector BigQuery para ingerir tabelas do data warehouse do Google Cloud na plataforma strattum.ai.

O conector BigQuery ingere tabelas do data warehouse BigQuery na infraestrutura strattum.ai. Você seleciona quais tabelas sincronizar, cada uma em modo incremental ou full refresh, e os dados aparecem no Data Catalog com linhagem registrada.

Capacidades

• Sincroniza tabelas específicas de qualquer dataset do projeto.
• Carga incremental por coluna de cursor ou full refresh a cada ciclo.
• Autenticação via Service Account do Google Cloud.
• Consultas executadas e faturadas no projeto informado.

Objetos suportados

O conector trabalha sobre as tabelas que você seleciona. Cada tabela vira um recurso no formato {dataset}__{table}.

Objeto	O que vem
Tabela (modo incremental)	Apenas linhas novas ou alteradas desde o último ciclo, usando a coluna de cursor definida
Tabela (modo full refresh)	A tabela inteira, recarregada a cada ciclo

Em modo incremental, use a coluna de particionamento da tabela como cursor sempre que possível. Um cursor sobre coluna não particionada força uma varredura da tabela inteira (e o faturamento correspondente) a cada ciclo.

Pré-requisitos

Projeto no Google Cloud

Um projeto com a BigQuery API habilitada e os datasets que você quer sincronizar.

Service Account com acesso ao BigQuery

Uma Service Account com permissão de leitura e de execução de jobs de query. O passo a passo está abaixo.

Configuração

1. Crie uma Service Account

   No Google Cloud Console, acesse IAM & Admin → Service Accounts → Create Service Account. Dê um nome como strattum-bigquery-reader.

2. Atribua os papéis de leitura

   Conceda à Service Account:

   • BigQuery Data Viewer (roles/bigquery.dataViewer) — ler as tabelas
   • BigQuery Job User (roles/bigquery.jobUser) — executar as queries de extração

   Para restringir o acesso a datasets específicos, conceda o Data Viewer no nível do dataset em vez do projeto, e mantenha o Job User no projeto.

3. Gere a chave JSON

   Na Service Account, acesse Keys → Add Key → Create new key, selecione JSON e baixe o arquivo.

   A chave JSON é uma credencial de longa duração e não expira automaticamente. Trate-a como senha crítica e rotacione periodicamente.

4. Adicione o conector no Console

   No menu lateral do Console, clique em Conectores → + Nova Conexão e selecione BigQuery. Preencha os campos:

   • Nome do Conector — identificador na lista de conectores (Obrigatório)
   • Project ID — projeto onde as queries rodam e são faturadas (Obrigatório)
   • Service Account JSON — cole o conteúdo do arquivo JSON baixado (Obrigatório)
5. Teste e salve

   Clique em Testar Conexão e, em seguida, em Salvar Conector. Selecione as tabelas (dataset + tabela), o modo de carga e a coluna de cursor de cada uma.

Autenticação e escopos

A autenticação é por Service Account do Google Cloud. As permissões são concedidas por papéis IAM, não por escopos OAuth.

Papel IAM	Para que serve
roles/bigquery.dataViewer	Ler as tabelas e datasets a sincronizar
roles/bigquery.jobUser	Executar os jobs de query da extração no projeto

Frequência de sync

O conector sincroniza a cada 1 hora. A primeira execução após a ativação roda como sample sync (amostra) e, ao concluir, o ciclo completo passa a rodar no schedule padrão.

Limitações conhecidas

• Cada ciclo executa jobs de query no BigQuery e gera faturamento; um cursor sobre coluna não particionada escaneia a tabela inteira toda vez.
• O modo incremental exige uma coluna de cursor monotônica.
• Linhas deletadas na origem não são removidas automaticamente em modo incremental.
• A chave JSON da Service Account não expira; a rotação é manual.

Troubleshooting

Sintoma	Causa provável	O que fazer
service_account_info is not valid JSON	Conteúdo colado incompleto ou malformado	Cole o arquivo JSON completo, incluindo chaves de abertura e fechamento
403 Access Denied	Faltam papéis IAM	Confirme bigquery.dataViewer no dataset e bigquery.jobUser no projeto
Custo de query mais alto que o esperado	Cursor em coluna não particionada	Use a coluna de particionamento como cursor incremental
Criação de chaves desativada (iam.disableServiceAccountKeyCreation)	Política da organização bloqueia chaves	Um admin de políticas da organização precisa liberar a criação de chaves

Próximos passos

Guia de desenvolvimento local

Configure o ambiente local completo com Prefect, worker e Docker Compose.

Quickstart — Data Pipelines

Ative conectores via Console strattum.ai sem precisar de ambiente local.