Inteligência de mercado com dados de CNPJ — dbt + DuckDB + Parquet

Port do MVP de Engenharia de Dados (PUC-Rio) — originalmente notebooks Spark no Databricks Community Edition — para um pipeline dbt com DuckDB sobre arquivos Parquet locais (ou em S3/Tigris). Base: dados abertos de CNPJ da Receita Federal e tabelas da Base dos Dados.

Pergunta-guia (do original): "É viável abrir uma loja de tintas em Fundão/ES? Há muitos concorrentes? Há fornecedores por perto?" — agora generalizável para qualquer atividade (CNAE) e município.

Por que isso é interessante para você

• Consultor(a) / empreendedor(a): concorrentes, idade média, porte, taxa de sobrevivência em 3 anos e fornecedores num raio de X km para qualquer CNAE e município do Brasil — numa consulta.
• Analista de mercado / BI: pipeline mensal, idempotente e testado; agende make atualizar e, a cada mês novo da RFB, receba um modelo estrela pronto para o Power BI (Parquet) com série histórica e relatório de qualidade.
• Quem está aprendendo dbt: um projeto real, em português, com fontes, staging, marts, testes genéricos, singulares e unitários, contratos, freshness e um guia de dbt — tudo no laptop, custo zero.
• Avaliador(a): cada regra é rastreável — o que veio do MVP e o que é adição está marcado no código e em docs/ESCOPO.md; decisões em ADRs.

Documentos

Documento	Conteúdo
PRODUCT.md	ideia, personas, casos de uso, valores, fora de escopo
ARCHITECTURE.md	arquitetura geral e detalhada, contratos de dados, DQ, riscos
docs/adr/	decisões e justificativas
docs/ESCOPO.md	original × adaptado × adição
docs/PLANO.md	plano, equipe de agentes e modelos
docs/OPERACAO.md	pipeline real, atualização mensal, retenção, agendamento, requisitos de máquina
docs/EXECUCAO_REAL.md	execução real (2026-09), tempos, volumes, avisos e paridade com o notebook 4
docs/POWER_BI.md	modelo estrela e acesso pelo Power BI
docs/CAMADA_SEMANTICA.md	camada semântica (dbt/MetricFlow): conceitos de negócio do CNPJ (empresa × estabelecimento, porte, MEI, situação cadastral), ontologia, entidades, métricas e consultas salvas
docs/DICIONARIO_DADOS.md	dicionário de dados: o detalhe dos campos de cada tabela (fontes, staging, gold...), com tipo, grão, chaves, valores dos domínios, origem e linhagem entre tabelas; gerado e conferido no CI
docs/REGRAS_NEGOCIO.md	catálogo das regras e invariantes de negócio do cadastro (RN-01 a RN-29), com fonte primária e leitura de cada violação
docs/RELATORIO_REGRAS_NEGOCIO.md	inconsistências encontradas no dado real (2026-09), só com contagens, e a interpretação delas
docs/guia-dbt/	guia de uso do dbt
.specs/features/rfb-dbt-port/	spec (EARS) e tarefas

Uso rápido

make setup                 # uv sync + dbt deps
make ci                    # fluxo completo sobre fixtures sintéticas (sem rede)
make pipeline MES=2026-09  # dados reais: ingestão → freshness → dbt build → relatório (→ publicar)
make atualizar             # processa o mês mais recente publicado pela RFB, se houver novidade
make publicar              # opcional: publica o gold no MotherDuck (requer MOTHERDUCK_TOKEN e MOTHERDUCK_BANCO)
make semantica             # valida a camada semântica (MetricFlow) e lista as métricas; consultas com `mf query`
make regras                # confere as regras de negócio e gera docs/RELATORIO_REGRAS_NEGOCIO.md (não falha por violação)
make docs                  # dbt docs

Primeira execução

Ao clonar o repositório em um ambiente limpo, a primeira execução pode levar alguns minutos:

• O make setup executa uv sync --all-extras (criação do .venv e resolução de pacotes Python) e dbt deps (download dos pacotes dbt).
• Durante o teste de conexão S3 (dbt debug --target s3), o DuckDB baixa a extensão nativa pré-compilada httpfs para ~/.duckdb/extensions/.

Nas execuções seguintes, os caches locais (.venv, transform/dbt_packages, ~/.duckdb/extensions) já estão populados e o make ci (unit + pipeline sobre fixtures de dois meses + integração + lint) completa em ~2 minutos.

Migração (ADR-0014): DATA_ROOT→RAIZ_DADOS, DATA_ROOT_LOCAL→RAIZ_DADOS_LOCAL, DBT_DUCKDB_PATH→CAMINHO_DUCKDB; o diretório padrão data/ agora é dados/. As variáveis antigas causam erro.

Threads: DBT_THREADS (nós do dbt em paralelo) e DUCKDB_THREADS (threads do motor DuckDB) são variáveis distintas; ambas opcionais (padrões por alvo em transform/profiles.yml).

Licença

MIT (como o projeto original).