Pular para o conteúdo
Atualizado em 2026-10-04

BigQuery — conector

Extrai dados de um projeto BigQuery seu (via SQL, com projeto de billing opcional) e carrega na nossa cloud.

Nesta página (15)

Leia antes: ../conectores.md (mapa de estados) e fichas.md (índice das fichas).


O que é#

Extrai dados de um projeto BigQuery seu (via SQL, com projeto de billing opcional) e carrega na nossa cloud.

Modos de ingestão suportados:

  • Nós buscamos — Nós buscamos os dados na sua fonte.

Para que serve#

Trazer os dados de BigQuery para o seu datalake e disponibilizá-los às camadas Bronze/Silver/Gold, aos modelos de BI e ao wizard de perguntas em linguagem natural.

Quando usar / quando não usar#

Use quando você precisa consolidar esta fonte no datalake de forma agendada, com isolamento por workspace.

Evite enviar arquivos com esquema instável sem antes conferir o profiling e o schema drift.

Plano e permissões#

  • Plano: núcleo do produto (conectores fazem parte de todos os planos; o limite é o número de fontes do plano).
  • Acesso: exige workspace ativo — com a assinatura em atraso, suspensa ou cancelada, a execução fica bloqueada.
  • Desligamento: a execução de ingestão pode ser desligada temporariamente (manutenção ou incidente). Quando isso acontece, a tela informa que o recurso está indisponível no momento.

Pré-requisitos#

  • Uma conta de serviço do seu projeto, com a chave JSON em mãos. Não há usuário/senha nem modo de rede neste conector: a autenticação é a chave da conta de serviço e o acesso é pela API do BigQuery.
  • Papéis mínimos dessa conta de serviço: roles/bigquery.dataViewer no projeto dos dados e roles/bigquery.jobUser no projeto de billing (ou no próprio projeto dos dados, quando ele também paga as consultas).
  • Opcionalmente, a location dos datasets: a consulta roda na location informada, que precisa ser a dos dados (vazio = automático).

Credenciais#

Campos sensíveis. Eles são cifrados (AES-256-GCM) e nunca ficam no config da conexão, na definição do pipeline, no export ou na DAG. Por padrão o valor cifrado fica no banco; mover a credencial desta conexão para o cofre externo de credenciais é uma escolha explícita, feita por conexão depois de salvar — ver ../../administracao/credenciais-e-rotacao.md.

  • Chave de acesso (arquivo JSON) (serviceAccountJson) — Abra o arquivo .json da conta de serviço e cole o conteúdo inteiro aqui.

Segredos nunca são reexibidos e passam pela redação em todo erro/log (token cru, URL-encoded e em JSON).

Campos do formulário#

CampoRótuloTipoObrigatórioObservação
projectIdProjeto dos dados (Project ID)textosimO código do projeto onde estão as tabelas (aparece no topo do console).
billingModeCobrança das consultas (billing)seleçãonãopadrão: same; opções: same / separate
billingProjectIdProjeto de billing (Project ID)textonãoaparece quando billingMode = separate
datasetDatasettextonão—
locationLocationtextonão—
serviceAccountJson 🔒Chave de acesso (arquivo JSON)senha/segredosimsegredo (cifrado; cofre externo opcional); Abra o arquivo .json da conta de serviço e cole o conteúdo inteiro aqui.

Passo a passo#

  1. No menu Dados → Conexões, use Nova conexão.
  2. Escolha BigQuery no catálogo.
  3. Preencha os campos do formulário (veja a tabela acima).
  4. Use Testar conexão. O resultado vem separado em Conectividade, Autenticação e Listagem/leitura — cada um com OK, Falhou, Não se aplica ou Não testado. Aqui a Conectividade aparece como Não se aplica: o BigQuery é HTTPS com a API do Google, não um host:porta — o OK vem da Listagem/leitura.
  5. Use Salvar conexão. Salvar NÃO inicia ingestão nenhuma.
  6. No cartão da conexão, use Montar extração (ou vá em Orquestração → Pipelines e use Conectar fonte). O pipeline aponta para a conexão salva — a credencial não é copiada.
  7. Na revisão, Publicar (agenda desligada) cria a versão 1 sem executar nada. Depois, Ativar agenda e Executar agora são ações separadas.

Exemplo — teste de conexão#

Configuração de exemplo (todos os valores são fictícios; segredos aparecem mascarados):

text
# Exemplo sintético (valores fictícios — não são credenciais reais)
projectId = meu-projeto-exemplo
billingMode = same
dataset = vendas
location = southamerica-east1
serviceAccountJson = •••••• (cifrado — nunca exibido)

Resultado esperado#

O Testar conexão retorna a lista de tabelas/recursos descobertos. Após a primeira carga, as linhas aparecem na camada Bronze do seu workspace, prontas para o pipeline.

Limites e custos#

  • Paginação: teto duro por execução (default 10.000 páginas / 5.000.000 linhas); guarda anti-loop.
  • Volume estimado: ~5 GB/mês (estimativa de catálogo, não medição).
  • Custo: a extração em si não é cobrada pela plataforma; a carga Bronze consome processamento do datalake (cobrável).

Segurança#

  • Escopo por workspace: cada cliente lê e escreve só no seu próprio datalake (<prefixo>_bronze / _silver / _gold); nunca há vazamento entre workspaces.
  • Segredos cifrados: material sensível é cifrado com AES-256-GCM antes de ser gravado. O cofre externo de credenciais é opcional e ligado por conexão; sem ele, o valor cifrado fica no banco. Trocar o valor aqui NÃO revoga a credencial na origem.
  • Redaction: todo erro/log passa pela redação de segredos (cru, URL-encoded e em JSON).
  • Produção não finge: um caminho que cairia em mock aciona a guarda de produção (falha explícita em vez de simular sucesso).

Erros comuns#

  • Chave da service account inválida — a mensagem é literal: cole o JSON completo. Um JSON truncado, ou sem client_email, é recusado antes de qualquer chamada.
  • Permissão negada (403) — falta roles/bigquery.dataViewer no projeto dos dados ou roles/bigquery.jobUser no projeto de billing. O teste separa autenticação de leitura pelo código devolvido pela API.
  • Não encontrado (404) — confira o Project ID dos dados, o nome do dataset e o da tabela (a extração referencia dataset.tabela).
  • Location divergente — a consulta roda na location informada; dataset em outra região faz a execução falhar. Deixe o campo vazio para automático ou informe a mesma location dos dados.
  • Tabela que exige filtro de partição — não é erro seu: a extração detecta o require_partition_filter e reaplica um predicado que não descarta linhas.

Solução de problemas#

  • Use Testar conexão para isolar problemas de credencial/rede antes de agendar.
  • Acompanhe as execuções na observabilidade por conector (taxa de erro, p50/p95, freshness).
  • Uma mudança de esquema na origem é sinalizada pelo schema drift (coluna nova = info; coluna removida/tipo mudado = atenção).

Relacionados#


Última revisão: 2026-10-04. Ficha gerada automaticamente do catálogo de conectores do produto.

Links relacionados