Tutorial — conectar o BigQuery do cliente como fonte

Estado: o conector BigQuery é Disponível (maturidade GA-candidato): dá para cadastrar e usar hoje, sem liberação caso a caso. A construção de consulta e o tratamento de partição são provados por teste. A extração real depende da service account da sua conta e do ambiente de nuvem do workspace estar configurado — sem ele a execução falha com mensagem. Custo faturado / latência = NÃO MEDIDO. Exemplos sintéticos.

Leia antes: Como os dados fluem · Catálogo de conectores.

O que é#

Conectar o BigQuery do SEU projeto como fonte de extração (modo pull). Aqui o Ingestia lê tabelas do seu BigQuery com a service account sua e as traz para a camada Bronze do seu workspace — igual ao pull de um banco relacional.

Não confunda com o BigQuery interno do Ingestia (o datalake destino, que roda com a nossa service account). Este tutorial é sobre usar o seu BigQuery como origem.

Para que serve#

Reaproveitar dados que já estão no seu data warehouse BigQuery (ex.: exportações de sistemas, tabelas de marketing) dentro do datalake do Ingestia.

Quando usar / quando não usar#

• Use quando: seus dados já estão em tabelas do BigQuery e você pode criar uma service account de leitura.
• Não use quando: os dados estão num banco relacional (use o conector do banco) ou em arquivos (use importar arquivo).

Plano e permissões#

• Núcleo do produto · verificação de acesso · chave de desligamento execução de ingestão.
• Papéis mínimos da service account do cliente:
  • roles/bigquery.dataViewer no projeto de dados;
  • roles/bigquery.jobUser no projeto de billing (ou no de dados, se for único).

Pré-requisitos#

1. Projeto de dados (Project ID) — onde os datasets/tabelas moram.
2. Projeto de billing (opcional) — onde os jobs de consulta rodam e são cobrados; vazio = o próprio projeto de dados paga.
3. Service account JSON com os papéis acima.
4. Opcional: dataset específico e location (ex.: US, southamerica-east1).

Passo a passo#

1. No console, vá em ETL/ELT → Conexões e escolha BigQuery (categoria Bancos de dados).
2. Projeto dos dados (Project ID) — ex.: meu-projeto-example.
3. Cobrança das consultas (billing):
   • No mesmo projeto dos dados (padrão), ou
   • Em outro projeto → informe o Projeto de billing (ex.: meu-projeto-billing).
4. Dataset — ex.: vendas (opcional; vazio lista todos os acessíveis).
5. Location — ex.: southamerica-east1 (opcional; vazio = automático).
6. Chave da service account (JSON) — cole o JSON da service account do cliente (é cifrado; nunca é exibido de novo).
7. Clique em Testar conexão e confirme que os datasets/tabelas aparecem.
8. Selecione as tabelas e salve a fonte.

Exemplo (sintético)#

Projeto de dados: meu-projeto-example
Billing: Em outro projeto
Projeto de billing: meu-projeto-billing
Dataset: vendas
Location: southamerica-east1
Service account: { "type": "service_account", "project_id": "meu-projeto-example",... }

Conceder acesso (exemplo com gcloud, valores fictícios):

# Leitura dos dados
gcloud projects add-iam-policy-binding meu-projeto-example \
  --member="serviceAccount:ingestia-ro@meu-projeto-example.iam.gserviceaccount.com" \
  --role="roles/bigquery.dataViewer"

# Rodar jobs de consulta (no projeto de billing)
gcloud projects add-iam-policy-binding meu-projeto-billing \
  --member="serviceAccount:ingestia-ro@meu-projeto-example.iam.gserviceaccount.com" \
  --role="roles/bigquery.jobUser"

Resultado esperado#

• Testar conexão OK e a descoberta lista os datasets/tabelas acessíveis.
• Na carga, o Ingestia cria o job de consulta, faz um probe de 1 linha (descartada) para validar SQL/partição antes de enviar qualquer fragmento — assim um retry nunca duplica dado na landing.
• Tabelas com require_partition_filter são tratadas automaticamente: o Ingestia monta um predicado que cobre todas as linhas em vez de falhar.

Limites e custos#

• Extração fragmentada: batchSize default 5.000 (100–50.000); maxRows default 200.000 (até 5.000.000).
• As consultas ao seu BigQuery são cobradas no seu projeto de billing (modelo on-demand do BigQuery). O Ingestia estima, mas o custo faturado real = NÃO MEDIDO.
• A carga para o Bronze do Ingestia é uma operação de carga cobrável no lado do Ingestia.

Segurança#

• Identificadores (projeto/dataset/tabela/coluna de watermark) são sanitizados antes de entrar no SQL; o filtro incremental usa parâmetro nomeado (@since), nunca concatenação.
• A chave JSON da service account é cifrada e redigida em qualquer erro/log.
• Escopo por workspace: os dados vão para o Bronze do seu workspace.

Erros comuns#

Diagnóstico#

• Use Testar conexão para separar permissão (dataViewer/jobUser) de configuração (dataset/location).
• Confirme que a service account tem acesso ao projeto de billing correto quando billing e dados são projetos diferentes.

Relacionados#

• Conectar PostgreSQL
• Criar pipeline incremental por watermark
• Custo, limites e segurança por workspace

Última revisão: 2026-09-08.