> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strattum.ai/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.

## 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](https://console.cloud.google.com), 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

> [!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.

**3. 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.

**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](https://docs.strattum.ai/data-pipelines/local-development.md)**
>
> Configure o ambiente local completo com Prefect, worker e Docker Compose.

> **[Quickstart — Data Pipelines](https://docs.strattum.ai/data-pipelines/quickstart)**
>
> Ative conectores via Console strattum.ai sem precisar de ambiente local.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.