> ## Documentation Index
> Fetch the complete documentation index at: https://strattumai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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                                                |

<Tip>
  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.
</Tip>

## Pré-requisitos

<CardGroup cols={2}>
  <Card title="Projeto no Google Cloud" icon="google">
    Um projeto com a BigQuery API habilitada e os datasets que você quer sincronizar.
  </Card>

  <Card title="Service Account com acesso ao BigQuery" icon="user-shield">
    Uma Service Account com permissão de leitura e de execução de jobs de query. O passo a passo está abaixo.
  </Card>
</CardGroup>

## Configuração

<Steps>
  <Step title="Crie uma Service Account">
    No [Google Cloud Console](https://console.cloud.google.com), acesse **IAM & Admin → Service Accounts → Create Service Account**. Dê um nome como `strattum-bigquery-reader`.
  </Step>

  <Step title="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

    <Tip>
      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.
    </Tip>
  </Step>

  <Step title="Gere a chave JSON">
    Na Service Account, acesse **Keys → Add Key → Create new key**, selecione **JSON** e baixe o arquivo.

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

  <Step title="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)
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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

<CardGroup cols={2}>
  <Card title="Guia de desenvolvimento local" icon="terminal" href="/data-pipelines/local-development">
    Configure o ambiente local completo com Prefect, worker e Docker Compose.
  </Card>

  <Card title="Quickstart — Data Pipelines" icon="rocket" href="/data-pipelines/quickstart">
    Ative conectores via Console strattum.ai sem precisar de ambiente local.
  </Card>
</CardGroup>