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

Para quem: todo mundo; é a porta de entrada · Quando ler: primeiro, para achar o documento certo.

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, tabelas da Base dos Dados e fontes gratuitas baixadas direto do IBGE (CEMPRE, renda do Censo 2022 e REGIC 2018).

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. E, com as fontes do IBGE, a renda da população, para onde os moradores vão comprar e quantas pessoas trabalham no setor (cenários de uso; a resposta da pergunta-guia no dado real está no relatório do estudo de caso).
• 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 (guia Power BI).
• Quem quer perguntar em linguagem natural: entregue a um agente (LLM) o guia de consulta (quem constrói o agente lê construcao-agente.md), o catálogo de golden queries e acesso somente leitura à base, e pergunte "quantas lojas de tinta tem em Fundão?".
• 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 no ARCHITECTURE; decisões em ADRs.

Produto, personas e casos de uso: PRODUCT.md.

Início rápido

make setup                 # uv sync + dbt deps
make ci                    # fluxo completo sobre fixtures sintéticas (sem rede, ~2 min com cache)
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
cd transform && uv run mf query --saved-query estudo_caso_fundao_tintas   # a pergunta-guia, pela camada semântica

Antes da primeira execução real (máquina, disco, tempo, agendamento, S3, MotherDuck), leia a operação.

Documentação

Entrada	Para quê
Conceitos	o que os dados significam: empresa × estabelecimento, situação cadastral, porte, MEI, CNAE, ciclo de vida, fontes IBGE, glossário
Arquitetura	camadas, contratos, qualidade de dados, riscos, o escopo original × adaptado × adição e como estender (fonte, modelo, conceito ou documento novo)
Operação	rodar com dados reais, atualização mensal, requisitos e tempos medidos, agendamento, publicação
Uso	cenários · Power BI · consulta por agente · construir o agente
Referência	dicionário de dados · camada semântica · regras de negócio · qualidade · golden queries
Decisões	os ADRs, com contexto, alternativas e consequências

Também: relatórios do dado real (regras) · histórico · guia de dbt · CHANGELOG · .specs.

Licença

MIT (como o projeto original).