Guia de acesso aos dados

Este guia é para quem conhece a pergunta de negócio, mas ainda não conhece o layout do lake. Ele ajuda a encontrar a tabela certa e a escolher a superfície de acesso com segurança. Não substitui a evidência da página da tabela, o catálogo técnico ou os runbooks operacionais.

Onde acessar?

Use a primeira linha que corresponde ao seu objetivo. A coluna SQL fala apenas sobre consulta: SQL não é necessário para descobrir uma tabela ou ler a documentação.

Objetivo	Plataforma	Link/rota	Pré-requisito de rede	Interface	SQL
Descobrir fontes, semântica, IDs e limitações	Catálogo visual	Home do catálogo	Rede interna/Tailscale; ver aviso de certificado abaixo	Browser	não aplicável
Entregar contexto estruturado a uma ferramenta	`catalog_context.json`	`/catalogo/catalog_context.json`	Rede interna/Tailscale; o snapshot publicado precisa estar acessível	Browser, terminal ou Python	não aplicável
Obter um índice textual curto	`llms.txt`	`/catalogo/llms.txt`	Rede interna/Tailscale; o snapshot publicado precisa estar acessível	Browser ou terminal	não aplicável
Ler ou baixar Parquet do lake	Parquet + DuckDB local	`CIANO_LAKE_ROOT/{raw,bronze,silver,gold}` · receitas CDA/BACEN	Acesso ao filesystem/mount do lake; não exige Tailscale	Terminal ou Python	opcional — SQL local via DuckDB
Diagnosticar, medir ou automatizar cargas	CLI/Python	`uv run python -m ciano_lake ...` · README	Repositório, dependências e `CIANO_LAKE_ROOT` acessíveis	Terminal ou Python	não aplicável
Consultar serving relacional ou dashboard	Postgres/Metabase	bi.cianoinvestimentos.space	Rede interna/Tailscale e autorização já concedida; não documente credenciais	Browser ou SQL	opcional — GUI; obrigatório no editor SQL

DuckDB é uma opção local e somente leitura para abrir Parquet; não é o Postgres/Metabase e não torna o serving disponível. No Metabase, a interface gráfica pode ser usada sem escrever SQL, enquanto uma pergunta no editor SQL exige SQL. Para qualquer serving, confirme na página da tabela queryable, a camada, a competência/era e a prontidão: o serving pode estar indisponível para uma tabela ou partição mesmo que exista no catálogo.

Acesso interno e certificado

O catálogo publicado é uma superfície interna, acessível pela rede Tailscale: https://100.70.145.60/catalogo/. O acesso por IP pode mostrar um aviso de certificado porque o certificado foi emitido para um nome DNS, não para esse IP. Isso é esperado no endereço atual; não significa que o site seja público, nem autoriza publicar dados ou credenciais fora da rede interna.

Se a página não abrir, confirme a conectividade com a rede interna e consulte o runbook de publicação do catálogo. Não coloque tokens, DSNs, chaves privadas ou outros segredos neste guia.

Quick-start: escolha o próximo passo

Entender: abra a home do catálogo visual, encontre a página e confirme dataset_id, tabela_id, competência/era, camada, grain, queryable e prontidão.
Ler/baixar: se a página apontar para uma partição disponível, defina CIANO_LAKE_ROOT e leia o Parquet localmente. Siga as receitas CDA/BACEN; elas mostram caminhos, filtros e granularidade sem copiar dados reais para o repositório.
Consultar com SQL: SQL é opcional. Use DuckDB local sobre Parquet quando quiser filtrar/agregar; use Postgres/Metabase somente se a página indicar queryable e o serving publicado para aquela tabela/competência.
Usar Metabase: conecte-se pela rede interna/Tailscale em bi.cianoinvestimentos.space, escolha um dashboard ou a GUI quando a superfície estiver marcada como disponível. Não presuma schema, cobertura ou credencial a partir do nome da tabela.

Árvore de decisão

Use a primeira opção que descreve sua necessidade:

Você precisa...
├─ entender o que existe ou ler a definição da tabela?
│  └─ Catálogo visual → página da tabela → IDs, grain, queryable e limites
├─ fornecer contexto a uma ferramenta ou agente?
│  ├─ precisa de campos estruturados e status?
│  │  └─ catalog_context.json
│  └─ precisa de um índice textual curto?
│     └─ llms.txt (índice; não substitui a evidência técnica)
├─ ler ou baixar dados?
│  └─ Parquet em CIANO_LAKE_ROOT → receitas → camada, competência/era e grain
├─ consultar com SQL?
│  ├─ localmente → DuckDB sobre Parquet (SQL opcional)
│  └─ remotamente → Postgres/Metabase (somente se queryable/serving estiverem
│     indicados na página; SQL só é obrigatório no editor SQL)
└─ usar Metabase?
   └─ rede interna/Tailscale → GUI/dashboard em bi.cianoinvestimentos.space

O guia de receitas é o próximo passo para consultas CDA e BACEN. Este documento define a escolha da superfície e os critérios de leitura; a receita detalhada continua separada para não esconder caminhos, filtros ou contratos de camada.

Como localizar uma tabela sem confundir os IDs

Os identificadores são técnicos e devem permanecer intactos na consulta e na comunicação com ferramentas:

Campo	Como localizar	Exemplo	O que confirmar
`dataset_id`	Cabeçalho e URL da página do dataset no catálogo	`cvm.fundos.cda_fi` ou `bacen.instituicoes.ifdata_valores`	Domínio, fonte e partes/eras declaradas
`tabela_id`	Identificador completo da tabela na página	`cvm.fundos.cda_fi/blc_1` ou `cvm.fundos.cda_fi/blc_7`	Nome da tabela, grain e evidências
Competência	Partição temporal indicada pela página e pelo catálogo	`202605` em uma série mensal; `202603` em um trimestre BACEN	Formato, período coberto e se o arquivo é mensal, trimestral ou anual
Era	Parte do catálogo que rege o layout no período	corrente ou uma parte `historico_*`	Colunas, filtro de linha e vigência daquela parte
`chave_status`	Bloco de qualidade da página, derivado do catálogo	`verificada`, `tolerada` ou `tolerada_com_residuo`	Medição, caps, resíduos e qualquer whitelist de nulos

Os exemplos desta publicação usam estes IDs completos: cvm.fundos.cda_fi/blc_1, cvm.fundos.cda_fi/blc_7, bacen.instituicoes.ifdata_valores/valores, bacen.instituicoes.ifdata_cadastro/cadastro e publish.gold_bacen/fct_balance_sheet.

O catálogo técnico é a fonte dos nomes e das regras: catálogo CVM e catálogo BACEN. A documentação semântica curada também está disponível em semantic.yml e deep_docs.yml. Use o alias para encontrar uma página, mas valide o ID completo antes de abrir dados.

Para uma tabela como blc_1, não pule diretamente para um arquivo com esse nome: confirme primeiro que ele pertence a cvm.fundos.cda_fi, qual era rege a competência e qual é o grain. A mesma abreviação pode ser ambígua fora do dataset.

Camadas: escolha de uso, não selo automático de prontidão

O fluxo é raw → bronze → silver → gold, mas cada camada responde a uma necessidade diferente. Camada não é sinônimo de cobertura, frescor ou prontidão analítica.

Camada	Uso principal	Limite que precisa ser verificado
raw	Preservar o arquivo original, com versionamento por `baixado`	É fonte imutável para rastreabilidade; não é a superfície mais segura para uma análise sem leitura do layout
bronze	Representar as colunas da fonte como texto e aplicar o quality gate	Não deduplica; duplicidades, nulos de chave e resíduos continuam sendo fatos a interpretar
silver	Tipar e normalizar regras de negócio	A cobertura de transformações varia por domínio e pelo catálogo atual; confirme a tabela e a política disponíveis
gold	Oferecer fatos/agregações prontos para uma análise específica	Só use se a página indicar a tabela, a granularidade e o serving/materialização disponíveis

O README resume a arquitetura e os comandos existentes; o AGENTS.md mantém o mapa de status, convenções e pendências. Quando houver divergência entre uma descrição antiga e o estado atual, reavalie o catálogo e os manifests de execução antes de concluir que a série está pronta.

Prontidão, qualidade e limitações

Antes de usar um número, leia estes sinais na página e, quando necessário, na evidência apontada por ela:

chave_status: verificada significa que a chave foi medida; tolerada registra repetições byte-a-byte dentro de um limite; tolerada_com_residuo permite um número separado e limitado de grupos não idênticos. O status não elimina a necessidade de ler o comentário e os caps.
NULL não é zero. Um campo nulo significa ausência, desconhecimento ou não aplicabilidade conforme a fonte; não o transforme em zero sem uma regra explícita. Uma tabela sem linhas também não prova que o valor seja zero.
Duplicidade não é automaticamente erro nem autorização para deduplicar no bronze. Verifique o grain, os caps declarados e, quando existir, _residuos.json junto da partição promovida. Resíduos são evidência de uma exceção da fonte e devem permanecer auditáveis.
Frescor deve ser lido na evidência da publicação, do run ou da partição correspondente. A existência de uma página, o nome do dataset ou um chave_status medido não garante que a competência mais recente esteja materializada.
Estado unknown na página é uma informação: não há inventário suficiente para afirmar que a partição existe. Não preencha essa lacuna por inferência.

Atenção especial a `cad_fi`

O bronze cad_fi tem uma linha por fundo por atribuição de gestor (e eventos de recadastramento), não uma linha por cnpj_fundo. Fazer join do bronze apenas por cnpj_fundo multiplica linhas. Para um join por fundo, use a visão silver de fundo corrente indicada na documentação da tabela; confirme também o critério temporal e o tie-break descritos na evidência. Nunca resolva essa multiplicação com um DISTINCT improvisado.

Superfícies e referências

Estes links formam o caminho de navegação do guia:

Home do catálogo visual: descoberta e leitura das páginas de dataset/tabela.
catalog_context.json: snapshot estruturado para consumo por máquina; confira o snapshot_id e o estado da publicação.
llms.txt: índice textual curto derivado do mesmo snapshot; não substitui a página nem o catálogo técnico.
AGENTS.md: status vivo, convenções e comandos de verificação.
Runbook de publicação: como o snapshot é construído, validado, servido e revertido.
README: entrada prática e resumo das camadas.

Postgres/Metabase só entra na árvore quando a página da tabela ou a evidência de publicação disser que aquela superfície está disponível. A ausência de um link de serving é uma limitação declarada, não um convite para adivinhar um schema, uma tabela ou uma credencial.

IDs estáveis verificados nesta publicação

cvm.fundos.cda_fi/blc_1
cvm.fundos.cda_fi/blc_7
bacen.instituicoes.ifdata_valores/valores
bacen.instituicoes.ifdata_cadastro/cadastro
publish.gold_bacen/fct_balance_sheet