Referência técnica · atualizada em novembro de 2026
Como o rodado é feito
As análises deste site saem todas de um lugar só: um espelho local de dados públicos brasileiros, mais uma camada semântica que diz como as tabelas se ligam e onde elas enganam. Esta página descreve os dois, e os caminhos de acesso somente-leitura.
O espelho
1.759 tabelas em 295 datasets de 140 fontes, 521 GB e 33,7 bilhões de linhas em 11 de novembro de 2026. 1.216 tabelas espelham a Base dos Dados; as outras 543 são raspadas direto de quem publica, para cobrir as lacunas: listas de sanções, SICAF, microdados do SINAN, reclamações de consumidor, pagamentos da CGU e outras. Cada tabela é uma pasta de arquivos Parquet comprimidos com zstd, e o DuckDB lê os arquivos direto, sem importar nada para um banco.
Um catálogo de metadados registra linhas, tamanho, URL da fonte, data da coleta, status e procedência de cada tabela. Ele é refeito a cada atualização, e é o que o terminal SQL mostra quando uma tabela é aberta.
Arquitetura
| Camada | O que roda ali |
|---|---|
| Armazenamento | Disco local num servidor doméstico: ~/rodado/<dataset>/<tabela>/*.parquet. Backup só de acréscimo num segundo disco a cada 6 horas. |
| Cópia pública | Os mesmos arquivos sincronizados num armazenamento de objetos (Hetzner, Helsinque) depois de cada atualização. Cada arquivo é lido inteiro e validado antes de ser copiado. |
| Acesso público | db.rodado.xyz: um contêiner que lê a cópia pública. Oferece um terminal SQL no navegador, POST /query para curl e o servidor MCP por HTTP. Aberto e somente-leitura, com limite de requisições por IP e cota diária de linhas. |
| Acesso por agentes | mcp/mcp_server.py: 17 ferramentas MCP somente-leitura, servidas localmente por stdio (as consultas vão ao servidor doméstico por SSH) ou remotamente em https://db.rodado.xyz/mcp. Configuração: MCP. |
| Camada semântica | Arquivos YAML versionados no repositório (próxima seção), lidos pelas ferramentas MCP na hora da consulta. |
| Site | Páginas estáticas no GitHub Pages. A página inicial, o índice de plataformas e o Atlas de tabelas e chaves de join são gerados a partir do catálogo e da camada semântica. |
Toda sessão abre em modo somente-leitura, com os diretórios legíveis numa lista fechada e a configuração travada. A SQL vem de um modelo ou de um desconhecido, e uma consulta que só lê ainda pode ler o arquivo errado.
Camada semântica
Nome de tabela e de coluna não basta para consultar 1.759 tabelas direito. O mesmo código significa coisas diferentes em anos diferentes, e duas colunas de mesmo nome podem guardar grandezas diferentes. A camada semântica registra isso uma vez, medido no dado real e datado, para que a consulta não precise redescobrir.
| Peça | Tamanho | O que faz |
|---|---|---|
| Conceitos de join | 68 | resolve_join(a, b) devolve uma cláusula ON pronta, incluindo a normalização da chave, como CNPJ sem zeros à esquerda. |
| Falsos amigos | 21 | Mesmo nome de coluna, significado diferente: uma coluna chamada só valor aparece em 153 tabelas. |
| Codificados de outro jeito | 13 | Conceitos como sexo e raça cujos códigos mudam por dataset e por ano. |
| Métricas nomeadas | 16 | Valores per capita, taxas e razões com unidade verificada. get_metric() vem antes de qualquer fórmula escrita à mão. |
| Hierarquias | 3 | Agregações territoriais, de CNAE e de CID-10. |
| Armadilhas | 290 datasets | Alertas por dataset devolvidos por describe_table: tabelas só com o último retrato, anos vazios, identificadores mascarados. |
| Ontologia | 87 classes · 137 relações | O modelo de domínio em 13 domínios: município, empresa, pessoa, contrato, evento de saúde e assim por diante. |
| Panoramas por tema | 47 | Resumos curtos por tema, usados como contexto pelos agentes. |
Chaves de join
| Chave | Tabelas | Objeto |
|---|---|---|
ano | 658 | Ano (partição) |
sigla_uf | 510 | UF |
id_municipio | 401 | Município |
mes | 173 | Mês (partição) |
cnpj / cnpj_basico | 59 | Empresa |
id_setor_censitario | 39 | Setor censitário |
id_municipio_tse | 29 | Município (código eleitoral) |
cpf | 26 | Pessoa |
cbo_2002 | 8 | Ocupação |
cnae_2_subclasse | 7 | Atividade econômica |
Escolha das tabelas
Com 1.759 tabelas, o passo difícil é escolher as poucas que valem a leitura antes de escrever qualquer SQL. Uma escolha errada ali produz joins que parecem válidos e não são. O harness local põe o catálogo inteiro de datasets no prompt (cerca de 2.000 tokens, em cache depois da primeira pergunta) e acerta o dataset em 88% das vezes. Um índice de embeddings sobre cerca de oito perguntas sintéticas por tabela ficou perto de 53% no mesmo teste e foi removido. Os agentes então afunilam com list_datasets → list_tables → describe_table.
Consultas de exemplo
Três perguntas respondidas com o espelho. As três rodam como estão escritas no esquema atual (conferido em 13 de novembro de 2026).
Contratos federais assinados com fornecedores sancionados
Contratos assinados enquanto o fornecedor estava no cadastro de sanções da CGU (CEIS).
SELECT c.cpf_cnpj_contratado,
any_value(c.nome_contratado) AS contratado,
COUNT(DISTINCT c.id_contrato) AS contratos,
SUM(c.valor_final_compra) AS total_brl,
any_value(s.categoria_sancao) AS sancao
FROM br_cgu_licitacao_contrato.contrato_compra c
JOIN br_cgu_sancoes.ceis s
ON s.cpf_cnpj_sancionado = c.cpf_cnpj_contratado
AND c.data_assinatura_contrato >= s.data_inicio_sancao
AND (s.data_final_sancao IS NULL OR c.data_assinatura_contrato <= s.data_final_sancao)
WHERE c.ano = 2024
GROUP BY 1
ORDER BY total_brl DESC
LIMIT 20
A abrangência da sanção (abrangencia_sancao) importa: uma suspensão pode valer só para o órgão que a aplicou.
Municípios com menos leitos hospitalares do SUS
Leitos do SUS por mil habitantes nos municípios com mais de 50 mil habitantes, ao lado do IDEB dos anos iniciais.
SELECT m.nome, m.sigla_uf, pop.populacao,
ROUND(cnes.leitos_sus * 1000.0 / NULLIF(pop.populacao, 0), 2) AS leitos_sus_por_mil,
ideb.ideb AS ideb_anos_iniciais
FROM br_bd_diretorios_brasil.municipio m
JOIN br_ibge_populacao.municipio pop
ON m.id_municipio = pop.id_municipio AND pop.ano = 2024
JOIN ( SELECT id_municipio,
SUM(quantidade_leito_cirurgico + quantidade_leito_clinico
+ quantidade_leito_complementar) AS leitos_sus
FROM br_ms_cnes.estabelecimento
WHERE ano = 2024 AND mes = 12 AND indicador_vinculo_sus = 1
GROUP BY id_municipio ) cnes ON m.id_municipio = cnes.id_municipio
JOIN br_inep_ideb.municipio ideb
ON m.id_municipio = ideb.id_municipio AND ideb.ano = 2023
AND ideb.rede = 'publica' AND ideb.ensino = 'fundamental'
AND ideb.anos_escolares = 'iniciais (1-5)'
WHERE pop.populacao > 50000
ORDER BY leitos_sus_por_mil ASC, ideb_anos_iniciais ASC
LIMIT 50
Fornecedores de campanha que depois ganharam contratos federais
O CPF no cadastro de sócios vem mascarado, então a ligação passa pelo CNPJ do fornecedor, e não pelo CPF do candidato.
WITH fornecedores AS (
SELECT d.cpf_cnpj_fornecedor, c.nome, c.sigla_partido, c.cargo,
SUM(d.valor_despesa) AS pago_na_campanha
FROM br_tse_eleicoes.despesas_candidato d
JOIN br_tse_eleicoes.candidatos c
ON c.ano = d.ano AND c.sigla_uf = d.sigla_uf
AND c.sequencial = d.sequencial_candidato
WHERE d.ano = 2022 AND d.sigla_uf = 'SP'
AND length(d.cpf_cnpj_fornecedor) = 14
GROUP BY 1, 2, 3, 4
HAVING SUM(d.valor_despesa) >= 50000
)
SELECT f.nome, f.sigla_partido, f.cargo,
COUNT(DISTINCT f.cpf_cnpj_fornecedor) AS fornecedores_contratados,
SUM(f.pago_na_campanha) AS pago_na_campanha,
SUM(k.valor_federal) AS contratos_federais_2023_2025
FROM fornecedores f
JOIN ( SELECT cpf_cnpj_contratado, SUM(valor_final_compra) AS valor_federal
FROM br_cgu_licitacao_contrato.contrato_compra
WHERE ano BETWEEN 2023 AND 2025
GROUP BY 1 ) k ON k.cpf_cnpj_contratado = f.cpf_cnpj_fornecedor
GROUP BY 1, 2, 3
HAVING contratos_federais_2023_2025 > 1000000
ORDER BY contratos_federais_2023_2025 DESC
O filtro de pagamento mínimo importa: sem ele, fornecedores nacionais de telefonia e de serviços públicos, pagos com poucos reais por centenas de campanhas, dominam o ranking.
Qualidade do dado
| Partições | Tabelas grandes pedem filtro por ano, mes ou sigla_uf. |
| Identificadores | CPF e CNPJ são só para leitura e nunca exportados em massa. O mascaramento varia por fonte, então CPFs mascarados de fontes diferentes não se ligam entre si. |
| Atualidade | Varia por fonte: CNPJ mensal, dados de saúde com 12 a 18 meses de atraso, o censo em 2010 e 2022. As tabelas do CNPJ guardam só o último retrato; o histórico fica nas tabelas *_historico. |
| Quando a fonte encolhe | Quem publica às vezes tira colunas ou anos numa nova versão. O espelho funde em vez de substituir, então o que só o espelho ainda tem fica guardado. |
| Antes de publicar um número | Dizer a ordem de grandeza esperada, marcar as linhas acima dela e conferir a contagem por dois caminhos independentes. |
Ferramentas
DuckDB · Parquet + zstd · Python e Bun/TypeScript · MCP · YAML na camada semântica · Caddy e um contêiner na Hetzner para o db.rodado.xyz · GitHub Pages para o site.
Referência de engenharia completa (ambiente, configuração do MCP, ordem de regeneração): docs/tecnico/TECHNICAL.md no repositório.