Manual da Equipe Dados¶

Fonte oficial de documentação da equipe dados da Base dos Dados. Centraliza processos, infraestrutura, padrões de pipeline, observabilidade e governança que antes estavam fragmentados em wikis, Google Docs e Coda.

Como esta documentação é organizada¶

Seguimos o framework Diátaxis: cada página atende a um modo de leitura específico. Em vez de escolher um modo no topo, você escolhe primeiro o domínio (custos, observabilidade, pipelines…) e dentro dele encontra:

Explicação — entender por que algo é como é (conceitos, decisões, contexto)
Como-fazer — executar uma tarefa específica passo a passo
Referência — consultar valores, schemas, definições de métrica
Runbook — resolver um problema operacional recorrente
ADR — registro de decisão arquitetural

Para criar uma nova página, leia CONTRIBUTING.md — ele explica como escolher o modo certo.

Catálogo de páginas¶

Resumo de cada página publicada, agrupado por domínio na ordem do menu. O rótulo em código indica o modo de leitura Diátaxis.

Glossário ¶

referência · Dicionário dos termos transversais que aparecem repetidamente em toda a documentação, mantido em ordem alfabética com definições curtas que linkam para a referência ou explicação completa quando existe. Consolida o vocabulário compartilhado da equipe: BD Pro (assinatura paga com Row Access Policies bdpro_filter), Datalake House (a arquitetura híbrida lake+warehouse da BD), Manual de estilo, Pipeline vs. Pipeline semi-automatizada (automatizada no Prefect vs. dependente de execução humana), Tabela de arquitetura (a planilha revisada antes do table-approve) e as zonas de dev e prod na GCP. As entradas de zona detalham a topologia real de projetos e buckets: basedosdados-dev guarda as duas camadas no mesmo projeto, enquanto em prod basedosdados-staging (externas, não exposto) e basedosdados (materializadas pelo dbt, consultado pelos usuários) vivem separados. Use esta página sempre que topar com um termo ambíguo — é a fonte única para desambiguar conceitos antes de mergulhar numa página específica.

Onboarding¶

Onboarding ¶

índice · Ponto de entrada para novos membros da equipe dados e colaboradores. Diferente do resto do manual, esta seção é orientada a aprendizado: em vez de assumir que o leitor sabe o que procura, oferece trilhas guiadas que se percorrem do zero. Reúne três tutoriais que formam a rampa de entrada da equipe: Setup do repositório de pipelines (o que é o basedosdados/pipelines e como deixar o ambiente local pronto para desenvolver), Fluxo de dados e infraestrutura (os componentes de infra — GCS, BigQuery, Prefect, dbt, backend — e como o dado se move entre dev e prod, com diagramas para pipelines automatizadas e para códigos semi-automatizados) e Manual de estilo (a porta de entrada para as convenções de nomeação, tipagem e padronização da BD, leitura obrigatória antes de criar tabela ou preencher metadados). É o primeiro lugar que uma pessoa recém-chegada deve abrir. As três trilhas linkadas aqui ainda não estão no menu lateral, mas são o material canônico de ambientação.

Processos¶

Processos da equipe ¶

índice · Mapa do domínio de processos: o fluxo de trabalho operacional da equipe dados — como abrimos issues, revisamos PRs, planejamos sprints e tratamos bugs reportados por usuários. Separa o conteúdo entre páginas de executar tarefas (revisar um PR de pipeline, planejar e executar uma sprint) e de consultar (escala de pontuação de tarefas, respostas-padrão de suporte para Discord e HubSpot). Use como índice quando quiser localizar rapidamente a rotina ou a referência de processo relevante.

Como revisar um PR de pipeline ¶

como-fazer · Checklist que revisores devem aplicar antes de aprovar um PR que adiciona ou modifica uma pipeline em basedosdados/pipelines. Percorre quatro áreas na ordem, cada item uma verificação binária que, se falhar, bloqueia o merge com comentário apontando o item específico. Em schedule.py, confere frequência coerente com a fonte, parâmetros e label de produção e ausência de parâmetro obrigatório faltando. Em flows.py, valida parâmetros do flow e do materialization_flow, o time_delta da task update_django_metadata batendo com a query em queries-basedosdados, a presença de upstream_tasks = wait_upload_table, o link do flow ao schedule correto e a regra de que o arquivo de flow contém apenas orquestração, sem lógica embutida. No BigQuery, checa cobertura temporal declarada nos metadados e ausência de colunas inteiramente nulas. Nos metadados, verifica fonte externa registrada, todos os campos preenchidos (só Arquivos auxiliares e Partições no BigQuery são opcionais), nome de tabela legível e ordem de colunas do Django batendo com o BigQuery. Requer acesso de revisor, ao BQ de basedosdados-staging e ao Django de metadados.

Como planejar e executar uma sprint ¶

como-fazer · Fluxo padrão de seleção, estimativa e acompanhamento das tarefas da equipe dados, das cinco categorias de demanda absorvidas (novas pipelines, subida de dados, correções de dados, correções de metadados e ajustes de documentação). Descreve o ciclo em três momentos. Antes da planning, a pessoa de coordenação seleciona os cards mais prioritários do backlog e os marca como "a refinar". Durante a planning, para cada card os analistas avaliam as quatro dimensões da escala de pontuação (incerteza, complexidade, conhecimento e volume), atribuem pontos consultando a tabela, definem prioridades respeitando o limite de 13 pontos por sprint e dividem em sub-tarefas qualquer card que sozinho exceda 13. Durante a sprint, fazem acompanhamento diário — cards em progresso, bloqueios, replanejamento. A sprint está bem planejada quando a soma dos pontos selecionados é ≤ 13, nenhum card individual passa de 13 e cada card tem dono atribuído. Pré-requisitos: acesso ao board e cards candidatos já no backlog. Complementa a página de referência da escala de pontuação, que traz a tabela detalhada usada nesta rotina.

Escala de pontuação de tarefas ¶

referência · Tabela consultada na sprint planning para estimar o esforço de cada card. Usa uma escala discreta em Fibonacci (1, 2, 3, 5, 8, 13) indexada por quatro dimensões: incerteza (quão claro é o resultado e o caminho), complexidade (dificuldade técnica intrínseca), conhecimento (quanto a equipe já domina o necessário) e volume (tamanho do escopo — linhas, tabelas, datasets). A tabela mapeia combinações típicas dessas dimensões a pontos e a um tamanho nominal (de PPP a GG): tarefas conhecidas e de baixo risco pontuam 1–3; tarefas complexas ou novas pontuam 5–13. O limite por sprint é de 13 pontos. Para estimar, procura-se a linha cujas dimensões mais se aproximam do card; havendo dúvida entre duas linhas, arredonda-se para cima, porque subestimar é mais comum que superestimar. Cards que passariam de 13 pontos não entram inteiros — devem ser quebrados antes de pontuar. É o artefato de referência que a rotina de planejamento de sprint aplica na prática.

Respostas-padrão para suporte (Discord / HubSpot)¶

referência · Templates de resposta para os cenários recorrentes de contato de usuários no Discord, HubSpot e e-mail de suporte. É uma página de consulta: você já sabe o cenário e vem buscar o texto — o tom se adapta ao contexto, mas o conteúdo factual se mantém. Cobre seis situações: interesse em contribuir (pré-requisitos, frentes possíveis e o convite para a reunião semanal na sala-dados-1), dados pesados demais (recomendações de WHERE, partições, recorte de período/colunas e uso do read_sql), dados que não estão no datalake (a BD só disponibiliza dados públicos já mapeados; caminho é o órgão produtor), alterar dados cadastrais pessoais (a BD não produz o dado, solicitar ao órgão produtor), reporte de inconsistência nos dados (pedir a query que evidenciou o problema, encaminhar internamente e manter o usuário informado) e pergunta direta sobre um dado específico (educar sobre o modelo plataforma-não-consultoria enquanto orienta com dataset, cursos de SQL ou fonte primária). O dono é a pessoa de suporte da sprint; atualize quando processo, link ou política mudarem.

Infraestrutura¶

Infraestrutura ¶

índice · Mapa do domínio dos componentes técnicos que sustentam a Base dos Dados: projetos do BigQuery, orquestração com Prefect, repositórios no GitHub e integrações com a GCP. Aponta para as três frentes do domínio — BigQuery (os projetos basedosdados, basedosdados-dev, basedosdados-staging e buckets associados), Prefect (orquestração de pipelines) e as ADRs de infraestrutura. Use como ponto de partida para navegar a documentação técnica.

BigQuery ¶

índice · Página (em construção) dos projetos da Base dos Dados no BigQuery: basedosdados (produção), basedosdados-dev, basedosdados-staging e os buckets relacionados. Além do conteúdo previsto sobre os projetos, registra que, para além do acesso direto via BigQuery, o projeto basedosdados é exposto por pacotes clientes em Python e R que encapsulam autenticação, consultas SQL e download de tabelas para análise local, com links para as referências oficiais de API de cada linguagem. Consulte para localizar os pontos de acesso programático à BD enquanto a documentação detalhada dos projetos não é preenchida.

Prefect ¶

índice · Mapa do sub-domínio de orquestração de pipelines via Prefect 3, rodando em Kubernetes (GKE). Organiza toda a documentação do stack pelos modos Diátaxis: explicação (arquitetura do Prefect 3 no GKE e o conceito de workers), como-fazer (instalar o servidor, configurar os workers, fazer deploy de flow, ajustar recursos de pod e registrar metadados no backend), referência (recursos dos pods e service accounts) e a decisão (ADR-0004 sobre a migração do Prefect 0 para o 3). É a porta de entrada de quem opera ou evolui a orquestração — comece por aqui para achar a página certa do stack.

Arquitetura do Prefect 3 no GKE ¶

explicação · Explica como o stack do Prefect 3 está montado e o que mudou em relação ao Prefect 0.15.9 (linha 1.x), dando contexto a quem opera ou evolui a infraestrutura. Descreve o stack antigo — Server + Hasura + Apollo Gateway + Towel + UI conversando por GraphQL, com 3 agents Kubernetes e 1 Vertex AI — e o compara ao novo: API REST em FastAPI, um único prefect-server (UI e API no mesmo processo), workers com work pools no lugar dos agents, job template configurado no pool em vez de YAML no GCS, chart Helm oficial e schema de banco próprio e incompatível com o do Prefect 0. A simplificação central é o colapso de cinco componentes em um só e a troca do roteamento por labels pela camada de work pools intermediada por workers. Registra a ressalva de que o Prefect 3 self-hosted não expõe API keys nativas — a autenticação externa é feita por token Django validado pelo nginx — e a estratégia de migração por namespace prefect3 paralelo ao antigo, com cutover só após estabilização. O racional completo da decisão está na ADR-0004.

Workers do Prefect 3 (substitutos dos Agents)¶

explicação · Explica o conceito de work pools e workers, que no Prefect 3 substituem os agents do Prefect 1.x. Onde antes o agent sabia diretamente onde executar os flows (via labels), agora existe uma camada intermediária: o work pool descreve a infraestrutura de execução (template do job Kubernetes, recursos, namespace) e o worker é o processo que faz polling no pool e materializa cada flow run como um Job no cluster — na cadeia Server → Work Pool → Worker → Flow Run. Traz o comparativo entre os agents antigos e os work pools novos e documenta a decisão de consolidar os 3 agents Kubernetes em 2 workers: um de produção (basedosdados) e um de dev (basedosdados-dev), ambos Kubernetes, com Vertex AI fora de uso no momento. Para os flows, a mudança prática é referenciar o work_pool_name no deploy em vez dos antigos labels do agent. Leitura de fundo para entender por que a configuração de deploy e de recursos passou a girar em torno de pools, com ponteiros para as páginas de configurar workers, ajustar recursos e a ADR-0004.

Como instalar o servidor Prefect 3 no GKE ¶

como-fazer · Passo a passo para subir o prefect-server no namespace prefect3: criar o banco no Cloud SQL via Terraform (com senha gerada e guardada no GCP Secret Manager, sem Vault), recuperar a senha, montar o sealed secret da connection string (fazendo URL-encode da senha para não quebrar o parser de URL do Python), aplicar os manifests do namespace (namespace, ExternalName service para o cloud-sql-proxy, issuer do cert-manager e ingress NGINX em prefect3.basedosdados.org) e instalar o chart Helm oficial prefecthq/prefect-server. Detalha as decisões de configuração no values.yaml — fullnameOverride fixo, PostgreSQL e Redis desabilitados (usa Cloud SQL externo), ingress e secret geridos por fora, e a URL pública da API para o UI. Inclui verificação via kubectl get pods/logs/ingress e port-forward, além de problemas comuns: -target do Terraform exigindo o prefixo module.cloudsql, permissão negada no Secret Manager (com fallback extraindo a senha do state), o erro Invalid IPv6 URL causado por [/] na senha e a annotation de ingress deprecada. Requer Terraform, kubectl, helm, kubeseal e gcloud autenticados e o repositório bd/iac.

Como configurar os workers do Prefect 3 ¶

como-fazer · Cria e conecta os workers Kubernetes (basedosdados e basedosdados-dev) ao servidor Prefect 3. Cobre os seis passos: criar os work pools na UI (tipo kubernetes), autenticar com a SA do Terraform no GKE (a conta pessoal não tem permissão; a SA precisa de roles/container.admin), aplicar RBAC para que os workers criem e gerenciem Jobs no próprio namespace, criar sealed secrets com as credenciais GCP (gcp-credentials, vault-credentials, gcp-sa etc., os mesmos dos agents antigos), montar os values.yaml e instalar os workers via chart prefecthq/prefect-worker, e — passo obrigatório — configurar os work pools via API: apontar o namespace dos jobs para o do worker (o default default não é permitido pelo RBAC), injetar gcp-credentials nos pods de flow via envFrom e definir o finished_job_ttl para os pods concluídos não ficarem para sempre no cluster. Traz verificação (worker online na UI, pods e logs via kubectl) e problemas comuns: imagem sem o pacote prefect-kubernetes (usar a tag 3-python3.12-kubernetes) e jobs criados no namespace errado quando o passo da API não foi aplicado. Requer o servidor já instalado e port-forward ativo.

Como fazer deploy de um flow no Prefect 3 ¶

como-fazer · Cobre a autenticação externa, o CI/CD do repositório pipelines, o deploy manual de um flow e o disparo/monitoramento de runs via API REST. Como o Prefect 3 self-hosted não tem API keys nativas, a autenticação usa um token Django que o nginx valida em backend.basedosdados.org/auth/ e repassa ao Prefect — o token permanente sai do admin de authtoken e vira o PREFECT_API_KEY. Lista os GitHub Secrets necessários para o CI/CD (GCP_PROJECT_ID, GCP_SA_KEY, PREFECT3_AUTH_TOKEN, PREFECT3_API_URL), mostra como o push da branch dispara o build da imagem Docker (e como forçá-lo com commit vazio), e como fazer deploy manual com deploy_flows.py (por arquivos e pool, ou --all para produção). Detalha o disparo e acompanhamento de um run via curl na API (listar deployments, criar flow run, checar estado). Verifica pelo estado Completed e pela aparição do run sob o work pool correto na UI. Entre os problemas comuns: dependências sem wheel para Python 3.12 (com a tabela de pacotes que precisaram subir de versão na migração) e OOM de flow, que aponta para a página de ajuste de recursos.

Como ajustar recursos de pod e resolver OOM ¶

como-fazer · Ensina a aumentar CPU/memória dos pods do Prefect 3 e a diagnosticar OOMKilled. A regra geral: o que importa para OOM é o job pod (que executa o flow), não o worker pod (que só faz polling) — mantenha o baseline do pool em 4Gi e suba caso a caso, sem inflar o global. Para diagnosticar, mostra como inspecionar o pod antes de ser deletado com kubectl describe procurando OOMKilled/Exit Code: 137. Apresenta três caminhos de correção: override por flow (recomendado) definindo job_variables no flows.py, que afeta só aquele deployment e é aplicado pelo deploy_flows.py no deploy; alterar o limite global do pool editando o base_job_template via PATCH na API (com exemplos em curl e em Python para atualizar os dois pools de uma vez); e alterar o pod do worker editando o values.yaml do chart e refazendo helm upgrade, raramente necessário. Verifica relendo resources pela API e confirmando que o próximo run não mostra mais OOMKilled. Complementa a página de referência de recursos dos pods, que traz os limites atuais.

Como registrar metadados no backend ¶

como-fazer · Guia canônico, passo a passo, para popular o backend da Base dos Dados ao publicar um novo conjunto — do Dataset até Table, Column, ObservationLevel, CloudTable, Coverage, DatetimeRange e Update — usando as ferramentas MCP databasis. Usa o dataset CAGED como caso completo. Explica o modelo de dados e a ordem de criação, que importa: resolver IDs de referência (nunca chumbar IDs, que diferem entre dev e prod), verificar se o dataset existe, identificar a conta autenticada, criar/atualizar o dataset, as RawDataSource, e então, por tabela, criar a Table (sem raw_data_source_ids ainda), os ObservationLevel, subir colunas da planilha de arquitetura, ajustar coluna a coluna, criar a CloudTable, Coverage+DatetimeRange e Update, e religar as raw sources numa segunda chamada deferred (a API não faz update parcial). Traz uma referência de campos por entidade, o checkpoint obrigatório de aprovação humana antes de promover para prod, erros conhecidos (M2M idempotentes, directoryPrimaryKey ignorado em dev, publishedBy permission denied) e um apêndice com a ordem de execução resumida. É a referência de execução que as regras de qualidade de metadados pressupõem.

Recursos dos pods do Prefect 3 (CPU / Memória)¶

referência · Valores de referência dos recursos de CPU e memória dos pods do Prefect 3. Distingue os dois tipos de pod e onde cada um se configura: o worker pod (faz polling, configurado no values.yaml do Helm) e o job pod (executa o flow, criado a cada run, configurado no base_job_template do work pool via API) — e reforça que o que importa para OOM é sempre o job pod. Registra os limites atuais dos job pods (configurados em 2026-06-08: 500m CPU / 1Gi RAM de request e 2 CPU / 4Gi RAM de limite, iguais nos pools prod e dev), os limites dos worker pods, os dois pools disponíveis com seus namespaces e quando usar cada um, e a capacidade do cluster (3 nós de 4 CPU / ~12.6 GB alocável). Fecha explicando por que limitar é melhor que não limitar: sem limite o kernel mata processos de forma imprevisível sob pressão de memória; com limite o Kubernetes mata só o pod que excedeu, com erro claro. É a folha de consulta que a página de ajuste de recursos referencia.

Contas de Serviço GCP — Prefect (0 e 3)¶

referência · Mapeamento completo das service accounts usadas pelos workers/agents do Prefect: quais são, que permissões têm em cada projeto (basedosdados, basedosdados-dev, basedosdados-staging), como chegam ao pod e para que servem. Detalha as SAs dbt-rpc@ (escopo mínimo, só BigQuery, para rodar dbt) e prefect@ (com acesso a GCS, para upload via lib basedosdados), explicando por que existem separadas — a lib faz upload de arquivos ao GCS antes do dbt rodar, num fluxo download → upload (prefect@) → dbt run/test (dbt-rpc@). Documenta os 5 secrets injetados no job template do Prefect 0 (gcp-credentials, gcp-sa, credentials-dev, credentials-prod, vault-credentials), com as SAs e projetos exatos por namespace de agent, incluindo a pegadinha de o "target dev" apontar para a SA de prod. Cobre o estado atual no Prefect 3 (secret gcp-credentials por namespace via Sealed Secrets, decodificado pelo entrypoint.sh), os workarounds de credenciais em uso e a lista de pendências (falta gcp-sa/GOOGLE_APPLICATION_CREDENTIALS, vault-credentials e SA de dbt separada nos workers). Referência para depurar problemas de permissão em flows.

ADRs — Infraestrutura ¶

índice · Índice dos Architecture Decision Records sobre decisões que afetam a infraestrutura da BD. Cada ADR é numerada sequencialmente dentro do domínio (0001-titulo.md, …) e segue o template de ADR do repositório. Traz a tabela de índice com número, título, status e data das quatro decisões registradas: a migração do DBT de RPC para CLI (0001), a integração das pipelines com o ambiente de dev (0002), a manutenção do staging no processo de dados (0003) e a migração do Prefect 0 para o 3 (0004) — todas com status "aceito". Use para navegar o histórico de decisões de infraestrutura.

ADR-0001 — Migração da integração DBT de servidor RPC para CLI direta ¶

adr · Registra a decisão (aceita, 2025-03-18) de eliminar o servidor DBT-RPC sempre-ligado e invocar o DBT diretamente via CLI (dbtRunner) dentro do flow do Prefect. O contexto: a arquitetura RPC trazia atrito operacional — um componente com ciclo próprio de deploy e monitoramento, preso a uma versão fixa do projeto (dificultando testar modelos em branches), com credenciais persistidas em disco e logs presos ao servidor, tornando o debugging indireto. A nova arquitetura faz o flow clonar o repositório dbt na branch especificada, resolver credenciais por variáveis de ambiente, configurar o profiles.yml (com opções como custom_keyfile_path e use_env_credentials, suportando OAuth), instalar dependências e rodar os comandos dbt localmente, com tratamento de erro que extrai mensagens de múltiplas fontes e as exibe formatadas na UI do Prefect. Consequências positivas: infraestrutura mais simples, flexibilidade de branch, logs acoplados ao flow, mais segurança e melhor tratamento de erros. As negativas não foram documentadas no material original (candidatas: cold-start maior, clone do repo a cada run, menos cache). Status: aceito e implementado.

ADR-0002 — Integrar pipelines com o ambiente de dev antes de promover para produção ¶

adr · Decisão (aceita, 2026-05-07) de reorganizar o fluxo das pipelines para que toda a testagem ocorra primeiro em dev, promovendo dados para produção só se nenhum teste falhar. O problema: os testes rodavam direto em produção (projeto basedosdados), então uma falha de teste dbt já sujava o ambiente que o produto consome, e a correção também tinha de ser feita lá — quando basedosdados deveria ser apenas réplica de dados já validados. No fluxo novo, o flow sobe dados para o bucket basedosdados-dev, cria a tabela em basedosdados-dev_staging, materializa em basedosdados-dev e roda os testes ali; só em caso de sucesso replica em basedosdados-staging, materializa em basedosdados e roda update_django_metadata ao final. A segunda metade se assemelha à action table-approve, condicionada a uma checagem de sucesso da materialização em dev. Lista pontos abertos (parâmetro de modo dev-only vs. completo, mudanças em update_django_metadata e wait_for_flow_run, labels) e consequências: falhas isoladas em dev e produção como réplica limpa, ao custo de mais etapas, mais gasto de recursos e mais código condicional. Status: aceito e implementado (flow new_arch_pipeline).

ADR-0003 — Manter buckets e projeto de staging no processo de dados ¶

adr · Decisão (aceita, 2026-05-07) de manter o bucket e o projeto BigQuery basedosdados-staging como parte do processo de dados, em vez de removê-los. O contexto surge da adoção do fluxo integrado com dev (ADR-0002): como hoje só usamos tabelas materializadas (não mais Views conectadas ao Storage, que eram a razão histórica do staging), o staging passou a parecer uma herança que só adiciona etapas, consumo de recursos e complexidade. A decisão de mantê-lo se baseia em dois benefícios que superam o ganho de simplificação: produção funciona como backup informal (não há política de backup ativa, e a replicação completa dev → prod via staging dá tolerância a falhas), e a governança fica simples e barata (evita ter de implementar backup formal sobre basedosdados-dev, que seria o único repositório de dados brutos se o staging sumisse); como bônus, dev permanece descartável para testagem extensiva. As negativas assumidas: mais etapas, mais custo de CPU/storage/BQ e complexidade adicional nas pipelines. Status: aceito, substituível se uma política de backup formal tornar a redundância desnecessária.

ADR-0004 — Migração do Prefect 0 para o Prefect 3 ¶

adr · Decisão (aceita, 2026-06-10) de migrar a orquestração de Prefect 0.15.9 para Prefect 3 subindo o novo stack em um namespace prefect3 paralelo, sem derrubar o antigo até o cutover final. O contexto: o Prefect 0 rodava um stack pesado (Server + Hasura + Apollo + Towel + UI, GraphQL, 3 agents Kubernetes + 1 Vertex AI), obsoleto e distante do Prefect atual — e o upgrade não era trivial, porque o schema de banco do Prefect 3 é incompatível, a API mudou de GraphQL para REST, os agents deram lugar a workers com work pools e o chart local seria trocado pelo oficial, inviabilizando migração in-place sem downtime e risco de perder flows agendados. Concretamente: banco Cloud SQL novo via Terraform, chart oficial prefect-server (deployment único), API REST e UI no mesmo processo, e workers + work pools consolidados em 2 (basedosdados prod e basedosdados-dev dev), sem Vertex AI por ora. Consequências: stack muito mais simples e versão suportada, ao custo de resolver a autenticação externa (sem API keys nativas, via token Django + nginx) e portar os flows. Status: aceito, migração concluída para a maioria dos flows.

Pipelines¶

Pipelines ¶

índice · Mapa do domínio de pipelines: padrões de design, módulos reutilizáveis, validações e tratamentos específicos das pipelines da equipe dados. É a porta de entrada para o conteúdo de pipelines — atualmente com as páginas de como abrir issues e PRs no repositório e o índice de ADRs de pipelines. Domínio em estágio inicial, previsto para crescer com os padrões de design e tratamento de dados.

Abrir uma issue no repositório `pipelines`¶

como-fazer · Define como abrir issues em basedosdados/pipelines de forma consistente, para que o backlog seja filtrável por tipo, priorizável por label e legível à primeira leitura. Assenta em três princípios: um tipo → um prefixo → uma label (o prefixo do título e a label são redundantes de propósito); o título descreve o quê, não o como; e português com prefixo minúsculo e sem placeholders esquecidos. Apresenta o vocabulário canônico de sete prefixos — [bug], [databug], [data], [update], [feat], [chore], [docs] — cada um com quando usar e a label correspondente, sem combinações. Traz heurísticas de decisão: [bug] vs [databug] ("se o código estivesse perfeito, o problema sumiria?" — sim é bug, não é databug) e [data] vs [update] (tabela já existe? precisa de raspagem nova? é projeto ou re-run?). Detalha o formato do título com bons e maus exemplos extraídos do histórico, as labels ortogonais ao tipo (pro, good first issue, suporte, milestone-pipelines), o alerta de que labels [PR] não vão em issues e a nota sobre a label triage inexistente. Recomenda abrir via template quando possível e normalizar issues antigas ao tocá-las, sem mutirão retroativo.

Abrir um pull request no repositório `pipelines`¶

como-fazer · Documenta as labels específicas de pull requests em basedosdados/pipelines — o conjunto com prefixo [PR] na descrição, que não deve ser aplicado a issues porque serve como gatilho de CI ou marcador de fluxo de PR. Descreve cada uma com função e quando aplicar: check-metadata (dispara a validação de metadados entre BigQuery e a API de produção), deploy-flow (faz deploy dos flows alterados no work pool basedosdados-dev para teste em staging), table-approve (dispara Table.approve() no merge, promovendo a tabela de staging para produção), test-dev-model (roda testes dbt nos models modificados em basedosdados-dev), conflict (marcador de PR com conflito, tipicamente automático) e hacktoberfest-accepted (só durante a campanha). Alerta que as quatro primeiras são gatilhos que custam tempo de CI e podem afetar ambientes, devendo ser aplicadas só quando o PR está pronto para o efeito, e que labels de tipo de issue não se aplicam a PRs — a relação PR↔issue se faz pelo texto (closes #123). Escopo deliberadamente restrito às labels; convenções de título, descrição, revisão e merge virão em iterações futuras. Complementa a página de abertura de issues.

ADRs — Pipelines ¶

índice · Índice dos ADRs sobre decisões que afetam pipelines, em especial deprecações — quando descontinuamos uma pipeline, por quê, o que a substitui e quem é impactado. Como os demais índices de ADR, cada registro é numerado sequencialmente e segue o template do repositório. Estabelece regras próprias para deprecações: título no formato Deprecar pipeline <nome>, contexto indicando substituto e downstream impactado, e a exigência obrigatória de linkar o PR de deprecação no repositório basedosdados/pipelines (no front-matter pr: e no corpo) — sem PR vinculado, a ADR não é aceita. Ainda não há nenhuma ADR de pipelines registrada; a página traz o índice vazio à espera da primeira.

Observabilidade¶

Observabilidade ¶

índice · Mapa do domínio de observabilidade: painéis, métricas e logs que dão visibilidade sobre o estado da plataforma de dados. Organiza o conteúdo por intenção — entender como funciona (o dashboard Central da Equipe Dados e o cálculo do status de atualização) e consultar uma métrica específica (o catálogo de métricas e a auditoria de consultas no BigQuery) — e registra o painel principal em uso, o Central da Equipe Dados no Metabase (panorama geral, atualização, custos, qualidade de metadados). Ponto de partida para achar a explicação ou a referência de métrica que você procura.

O dashboard Central da Equipe Dados ¶

explicação · Explica o dashboard Central da Equipe Dados no Metabase, a central de acompanhamento da equipe, que reúne indicadores da plataforma em páginas temáticas para evitar que cada pessoa monte sua própria visão a partir de queries soltas. Descreve os quatro grupos de informação: Panorama de Dados (estatísticas gerais do BQ de produção e do banco de metadados), Atualização (proporção de tabelas, pipelines e semi-automatizadas por status), Prefect (flows com schedule ativa, de br_bd_metadados.prefect_flows) e Custos (séries históricas de gasto com a GCP em USD e BRL). Registra que a página de Qualidade de Metadados está prevista mas não implementada, e os pontos ausentes conhecidos: metadados de BQ só cobrem basedosdados (faltam dev e staging), não há estatísticas de buckets nem custos por pipeline. Traz um disclaimer importante sobre custos: a mudança da conta de faturamento de USD para BRL em jan/2025 e a não-reativação da exportação levaram à perda das tabelas detalhadas entre fev e set/2025, contornada por um compilado do painel de billing. Discute os trade-offs de centralizar no Metabase e de separar as tabelas semi-automatizadas.

Cálculo do status de atualização ¶

explicação · Explica a lógica por trás da classificação de cada tabela em Atualizada, Em observação ou Desatualizado na seção Atualização do dashboard, e por que existe a categoria intermediária. O cálculo combina três metadados — latest (última atualização bem-sucedida), frequency (multiplicador da frequência) e o slug da entidade temporal (day, week, month, quarter, year) — e deriva date_diff (idade real dos dados em dias) e frequency_days (produto do multiplicador pela base de dias da unidade). A régua de triagem com zona de escape: se date_diff <= frequency_days a tabela está Atualizada; se ultrapassa mas fica dentro de frequency_days + tolerance_days está Em observação; acima disso, Desatualizado. O tolerance_days depende da periodicidade (ex.: 7 dias para mensais, 90 para anuais). A categoria "Em observação" existe para acomodar a volatilidade de fontes públicas sem cronograma fixo, evitando falsos positivos de "desatualizado" a cada pequeno atraso. Explica ainda como se distingue pipeline de tabela semi-automatizada pela coluna pipeline_id (não-nula vs. nula). Discute os trade-offs da tolerância dependente da frequência e de manter a categoria intermediária visível. É a lógica que as métricas de atualização referenciam.

Catálogo de métricas ¶

índice · Índice das páginas de referência das métricas do painel Central da Equipe Dados, agrupadas pelas seções do dashboard. Cada página filha descreve, por métrica, o que ela mede, qual tabela alimenta o cálculo e a frequência de atualização. Aponta para as quatro seções — Panorama de Dados (volumes, contagens, status de publicação), Atualização (proporções por status), Prefect (flows com schedule ativa) e Custos (séries de gasto em USD e BRL) — e indica o template de referência a usar ao adicionar uma métrica nova. Use como sumário do catálogo de métricas.

Métricas — Panorama de Dados ¶

referência · Referência das métricas da seção Panorama de Dados, que reúne estatísticas gerais do BigQuery de produção (basedosdados) e do banco de metadados de produção da API. Do lado do BigQuery, com fonte comum na tabela bigquery_tables (pipeline br_bd_metadados.bigquery_tables, que compila o INFORMATION_SCHEMA, atualização diária): volume de dados armazenados em TB, quantidade de datasets e quantidade de tabelas. Do lado do banco de metadados (fonte na tabela tables): quantidade de datasets (COUNT(DISTINCT dataset_id)), quantidade de tabelas (COUNT(DISTINCT table_id)), quantidade de tabelas com pipeline associada (pipeline_id IS NOT NULL) e distribuição das tabelas por status de publicação (ativa/não-ativa), que serve para ver quais tabelas estão de fato disponíveis no produto. Cada métrica vem com o que é, a definição/fonte e a cadência de atualização. Consulte para saber exatamente o que cada número do Panorama significa e de onde vem.

Métricas — Atualização ¶

referência · Referência das três métricas que monitoram o frescor das tabelas em relação à frequência esperada de atualização — a lógica de classificação (Atualizada / Em observação / Desatualizado) está na explicação do cálculo do status. As métricas são a proporção de atualização das Tabelas por status (escopo: todas as tabelas registradas, com listagem das em observação ou desatualizadas), a proporção das Pipelines por status (escopo: pipeline_id IS NOT NULL, tabelas com automação no Prefect) e a proporção das Tabelas Semi-automatizadas por status (escopo: pipeline_id IS NULL, que têm código de ELT/ETL no repositório mas dependem de trabalho humano). Cada uma remete à mesma definição de cálculo, mudando apenas o recorte da população. Consulte para entender o que cada gráfico da seção Atualização mede e qual subconjunto de tabelas ele cobre.

Métricas — Prefect ¶

referência · Referência (curta) da métrica da seção Prefect do dashboard: a quantidade de flows com schedule ativa na API do Prefect. Descreve o que a métrica mede, a fonte — br_bd_metadados.prefect_flows, extraída diariamente da API do Prefect — e a frequência de atualização (diária). Registra a pendência de incluir também o acompanhamento da feature de desativação dos flows. Consulte para saber o significado e a origem do indicador de flows agendados exibido no painel.

Métricas — Custos ¶

referência · Referência das métricas de custo com a GCP exibidas no dashboard, com ponteiro para o contexto (por que há séries em USD e outras em BRL, e a perda de dados detalhados entre fev e set/2025) na explicação do dashboard. Cobre as séries históricas em USD — custo mensal com todos os serviços e custo mensal com os principais serviços (os de maior gasto identificados, os demais agrupados em "outros") — com fonte nas tabelas de billing exportadas no conjunto br_bd_indicadores. E as métricas mensais e semestrais a partir de 2026 em BRL — gasto mensal com os principais serviços no semestre, custo total por semestre e custo por serviço por semestre — com fonte na tabela gcp_billing_export_resource_v1_... da nova conta de faturamento (que traz BRL e USD). Cada métrica vem com o que é, a definição e a fonte. Consulte para interpretar os gráficos de custo e saber qual tabela alimenta cada série.

Auditoria de consultas no BigQuery (Cloud Audit Logs)¶

referência · Referência sobre os eventos de interação com o BigQuery (consultas, tentativas de acesso) registrados pelo Cloud Audit Logs, com fonte em basedosdados.logs.cloudaudit_googleapis_com_data_access e export horário. Documenta as limitações (quando o conjunto tem permissionamento de linhas ou é aberto, os logs não coletam identificação do usuário no projeto basedosdados; e os logs registram eventos de infraestrutura, não só consultas — é preciso filtrar) e o funil de filtragem em três etapas: filtrar por methodName (jobservice.insert/jobservice.query), achatar o array authorizationInfo com UNNEST, e filtrar por permission (bigquery.tables.getData ou bigquery.rowAccessPolicies.getFilteredData) para focar em leitura de dados. Contrasta o comportamento de tabelas sem permissionamento (1 evento linear por tabela) com o de tabelas com Row Access Policies (BD Pro) (3+ eventos por consulta, com sufixos de policy), explicando a lógica do campo granted (true/false/NULL) e trazendo uma tabela de interpretação por tipo de usuário. Fecha com um SQL de referência completo que gera as métricas de acesso (por conjunto, mês, tipo de conexão e tipo de acesso). Consulta essencial para montar métricas confiáveis de uso a partir dos logs.

Governança¶

Governança ¶

índice · Mapa do domínio de governança: as regras, políticas e processos que governam o que entra na Base dos Dados, como entra, quem acessa e quanto custa. Aponta para os quatro sub-domínios — Metadados (regras de preenchimento e validação de datasets/tabelas/colunas), Qualidade (testes dbt e regras de negócio das bases), Acessos GCP (IAM, Row Access Policies, BD Pro) e Custos (billing GCP, séries históricas, contexto da migração USD→BRL). Use como porta de entrada para navegar as regras e políticas da BD.

Metadados ¶

índice · Mapa do sub-domínio de metadados: as regras de preenchimento e validação dos metadados de datasets, tabelas e colunas. Organiza o conteúdo por modo — entender (o Manual de estilo: o que é, o que cobre e seu papel na infraestrutura), executar tarefas (como subir metadados de um conjunto e suas tabelas) e referências (a pasta canônica das tabelas de arquitetura no Google Drive, com ponteiro para a ADR-0001 que explica por que elas vivem lá). Ponto de partida para as rotinas e regras de metadados.

Como subir metadados de um conjunto e suas tabelas ¶

como-fazer · Rotina padrão, orientada à interface do Django de metadados, para registrar os metadados de um novo conjunto e suas tabelas na plataforma da BD. Percorre quatro etapas: criar dataset e tabelas (preencher os metadados básicos do conjunto, configurar as cloud tables, adicionar colunas e completar versão, descrição e demais campos obrigatórios de cada tabela); verificação inicial (abrir basedosdados.org, localizar o conjunto e validar visualmente que os campos foram preenchidos); preencher metadados complementares (frequência de atualização, cobertura temporal, vinculação com diretórios, nível de observação e partições no BigQuery em nível de coluna); e verificação final (atualizar as tabelas no BQ e revalidar todos os obrigatórios, a ordem de colunas batendo com o BQ e os nomes amigáveis). A subida está completa quando o conjunto aparece no site com todas as tabelas, todos os obrigatórios estão preenchidos, a ordem das colunas bate com o BQ e frequência/cobertura são consistentes com a fonte. Lista problemas comuns (só Arquivos auxiliares e Partições no BigQuery são opcionais; corrigir a ordem no Django para refletir o BQ) e remete ao checklist de revisão de PR. Pré-requisitos: organização/fontes/temas já cadastrados, acesso ao Django e tabelas já materializadas.

ADRs — Metadados ¶

índice · Índice dos ADRs sobre decisões que afetam metadados, arquitetura de tabelas e fluxos de governança de dados. Como os outros índices de ADR, numeração sequencial dentro do domínio e template padrão do repositório. Traz a tabela de índice com a única decisão registrada até agora: manter as tabelas de arquitetura no Google Drive (0001, aceito, 2026-05-22). Use para navegar as decisões de governança de metadados.

ADR-0001 — Manter tabelas de arquitetura no Google Drive ¶

adr · Decisão (aceita, 2026-05-22) de manter as tabelas de arquitetura como planilhas no Google Drive e não migrá-las para arquivos YAML versionados no Git. A tabela de arquitetura descreve a estrutura de uma tabela antes de subi-la ao BigQuery (colunas, tipos, cobertura, unidade, diretórios, dados sensíveis, partições) e é o artefato revisado pela equipe. A proposta (issue #1115) de mover para YAML/Git tinha argumentos fortes a favor — histórico versionado, revisão no mesmo fluxo de PR, tipos nativos validáveis por CI, proteção contra edição/exclusão acidental, geração mais direta do schema.yml e revisão por bot/IA. Mas foi descartada pelo peso de dois contra-argumentos: a ergonomia de edição visual é muito superior em planilha para tabelas com muitas colunas (o caso comum na BD), e o formato planilha é próximo do formato tabular que o usuário vê no site, reduzindo erros percebidos só após o deploy — além da menor barreira para contribuidores externos. As negativas assumidas: seguimos sem versionamento nem trilha de auditoria das arquiteturas, sem validação de CI e com revisão fora do PR de código. Status: aceito, revisitável se o volume crescer ou surgir ferramenta que una edição tabular a versionamento.

Qualidade de dados ¶

índice · Mapa do sub-domínio de qualidade: os testes do modelo dbt e as regras de negócio que governam a qualidade das bases publicadas. Atualmente aponta para a referência de regras de negócio do preenchimento de metadados (as restrições que uma base deve satisfazer antes de publicar). Domínio em construção, com tópicos previstos: catálogo de testes dbt padrão, particularidades de bases anuais grandes (ex.: br_me_rais) e o processo de revisão de qualidade antes de publicar.

Regras de negócio do preenchimento de metadados ¶

referência · Catálogo das regras de negócio que governam a consistência dos metadados de Dataset, Table, RawDataSource e Column no backend — restrições que devem ser validadas antes de um conjunto ser considerado apto a publicar em produção; para o passo a passo de como popular cada entidade, remete à página de registrar metadados no backend. Cada regra vem com entidade, vínculo, severidade (todas bloqueiam publicação), o enunciado e o porquê. Em Tables: todo ObservationLevel deve estar ligado à Column que identifica a entidade (senão a granularidade fica não-auditável) e toda Table deve ter last update preenchido (o sinal de frescor exibido no site — automático em pipelines, manual em semi-automatizadas). Em RawDataSource: toda Table deve ter uma RawDataSource vinculada (o ponteiro auditável para a origem, o bloco "Fonte original" no site), toda fonte deve ter data de poll (última verificação, distinguindo "fonte parada" de "fonte não checada") e toda fonte deve ter last update (última atualização real da origem, distinta do poll). É a folha de regras que a página de registro de metadados pressupõe e que sustenta a rastreabilidade e o frescor exibidos ao usuário.

Acessos GCP ¶

índice · Página (em construção) do sub-domínio de acessos na GCP: políticas de IAM, Row Access Policies (bdpro_filter, allusers_filter), gestão de service accounts e o processo de concessão e revogação de acesso. Ainda sem conteúdo detalhado; serve por ora como marcador do domínio e do escopo previsto. Para o mapeamento atual das service accounts do Prefect, veja a referência de service accounts na infraestrutura.

Custos ¶

índice · Página (em construção) do sub-domínio de custos: acompanhamento e governança dos gastos com a GCP. O escopo previsto inclui as séries históricas, o contexto da migração da conta de billing de USD para BRL em janeiro/2025, a explicação do gap de dados entre fev e set/2025, as tabelas de billing exportadas, as métricas semestrais e os processos de revisão mensal de custos. Por ora funciona como marcador do domínio; para as métricas de custo já disponíveis no painel, veja a referência de métricas de custos na observabilidade.

Convenções¶

Toda pasta tem um index.md que serve de mapa do domínio.
Todo arquivo tem frontmatter com tipo: (tutorial, como-fazer, referencia, explicacao, runbook, adr).
Nomes de arquivo carregam o modo quando útil: como-X.md, referencia-Y.md, runbook-Z.md.
Uma página por unidade atômica: uma métrica, uma decisão, um runbook.