Pular para conteúdo

Metadados de layout de instrumentos (BVBG.028 UP2DATA)

Leitura dos metadados de layout da família BVBG.028: a planilha autoritativa BVBG.028 para UP2DATA.xlsx que a B3 publica, com um sheet por tipo de arquivo e uma linha por campo (nome, abreviação da tag, cardinalidade, tipo de dado, caminho XML no BVBG.028).

Veja também: Visão geral da seção · Arquivo de instrumentos (o reader de dados que este layout descreve) · Uso.

Descrição

InstrumentsLayoutMetaReader baixa a planilha UP2DATA e parseia o sheet InstrumentsConsolidatedFile (o layout do arquivo IN da Pesquisa por Pregão) em um snapshot tipado: uma linha por campo declarado, já com o nome de coluna canônico derivado do mesmo jeito que os readers de dados derivam os seus — pascal_to_upper_snake da abreviação da tag BVBG.028 (TckrSymb → TCKR_SYMB, CFICd → CFICD).

Colunas do snapshot: COLUMN_ORDER (Int64), FIELD_NAME, FIELD_ABBREVIATION, CANONICAL_COLUMN, CARDINALITY, DATA_TYPE, BVBG_PATH, mais as seis colunas de proveniência (incluindo content_hash da planilha bruta).

Como a fonte é uma planilha, o reader reaproveita o seam tabular (read_table, com o cabeçalho na segunda linha — a primeira é o título do sheet), não o seam XML. É um snapshot atual, então não recebe date_ref.

Dois usos

  • Snapshot para datalake — um registro versionável do layout que a B3 publica, com proveniência e content_hash, para que o datalake consumidor guarde o histórico de como a especificação mudou ao longo do tempo.
  • Oráculo de deriva de contrato — o job semanal bin/check_contract_drift.py lê o conjunto CANONICAL_COLUMN e o compara com o que o reader de instrumentos mapeia.

Exemplos

Baixar o snapshot de layout

from filings_b3.search_trading_session import InstrumentsLayoutMetaReader

df = InstrumentsLayoutMetaReader().read()
print(df[["COLUMN_ORDER", "FIELD_NAME", "CANONICAL_COLUMN", "BVBG_PATH"]].head())

Manter a planilha bruta (camada bronze)

from pathlib import Path

df = InstrumentsLayoutMetaReader(path_raw=Path("/data/bronze/b3/meta")).read()
print(df[["source_key", "content_hash", "updated_at"]].iloc[0])

Deriva de layout (job semanal)

A B3 pode mudar o layout depois de embarcarmos o reader. Nenhum check de PR consegue pegar isso — só um job que rebaixa o layout publicado. O contract-drift.yaml (semanal, workflow_dispatch) roda bin/check_contract_drift.py, que:

  1. baixa o layout via este reader e extrai o conjunto de CANONICAL_COLUMN;
  2. compara — nos dois sentidos — com o conjunto de colunas que o reader de instrumentos mapeia;
  3. abre ou atualiza uma única issue (label contract-drift) quando há divergência.

Os dois sentidos são sinais reais: uma coluna mapeada que sumiu do layout → o reader passa a produzir uma coluna silenciosamente nula; uma coluna do layout que o reader não mapeia → a B3 adicionou um campo que deveríamos passar a ler. O job nunca reprova o CI — uma queda da B3 e uma deriva real não podem virar o mesmo check vermelho.