ÁLGEBRA DE CONJUNTOS sobre relações: interseção, união e diferença

true = inclui meta.total (contagem do universo filtrado). Custa uma consulta a mais.

Primeira relação.

Segunda relação.

Prende a outra ponta da relação A.

Prende a outra ponta da relação B.

Recorta o TIPO da outra ponta de A. issued sai da companhia tanto para instrument quanto para equity_security: sem isto, 'quem cede para FIDC e emite DÍVIDA' inclui quem só emitiu ação.

Idem para a relação B.

O que a coisa É. Papel (emissor, cedente, administrador) NÃO é kind — é aresta. equity_security é a ação (PETR4), distinta da companhia que a emitiu.

offering é a oferta pública, e é o único que não é uma COISA: é uma RELAÇÃO que virou objeto. Ela liga emissor, instrumento e tempo, e carrega atributos próprios (volume, rito, status, quantidade, preço) que não cabem numa aresta. Atravesse issued na direção in para chegar ao emissor.

market_event é o segundo do mesmo feitio: um ACONTECIMENTO que virou objeto. Ele existe porque aresta liga dois objetos, e sem nó do lado do evento não havia como compor — getObjectEvents responde 'o que aconteceu com este objeto' e nunca 'quais empresas foram citadas nos mesmos eventos que esta'. Atravesse mentions na direção in para ir do objeto aos eventos que falam dele, e out para ir do evento aos objetos citados. Só o evento com objeto carimbado vira nó: os demais seguem legíveis por getObjectEvents e não viram ilha no censo.

fund_share_class é a SUBCLASSE de fundo da RCVM 175 — o que o investidor efetivamente subscreve, distinto da classe que tem o CNPJ. Mesma separação de equity_security × company: o que se compra não é o veículo. Atravesse contains na direção in para chegar à classe. Ela nasce sem medidas: os atributos (situação, público-alvo) ainda não são servidos, e ausência aqui é isso, não 'a subclasse não tem'.

indicator × data_series, a regra, porque a pergunta se repete. indicator é o CONCEITO — existe fora do DataBolsa, tem nome próprio no mercado e é o que um contrato cita: IPCA, Selic, CDI, TR, IGP-M, INPC, dólar PTAX. data_series é uma PUBLICAÇÃO numerada: uma fonte, uma unidade, uma transformação, um calendário — bcb_sgs:433 é a variação mensal do IPCA e bcb_sgs:13522 é o acumulado em 12 meses do MESMO conceito. O conceito tem uma série headline e quantas variantes a fonte publicar; a série nunca tem conceito além do que ela mede.

Daí a consequência que surpreende: o que o DataBolsa CALCULA é data_series, não indicator, mesmo quando tem nome de conceito. juro_real_ex_ante, earnings_yield_agregado e os escores de regime são receitas nossas — a linhagem sai em lineage — e não coisas que uma escritura possa citar. São 7 conceitos e centenas de séries, e isso é o desenho, não cobertura faltando. Resolva pelo NOME e leia o kind que voltar, em vez de filtrar por kind=indicator esperando encontrar tudo.

Recorta dentro do tipo — fidc, fii, debenture…

Corte temporal (AAAA-MM-DD). SEM ele a resposta é 'quem JÁ se relacionou', não 'quem se relaciona' — a diferença é grande e silenciosa.

O RECORTE DEPENDE DA FORMA DO VERBO (shape, publicado em listObjectRelations):

• event (issued, indexed_to, succeeded_by): aconteceu numa data e não deixa de ter acontecido — entra tudo que ocorreu até at, sem limite superior. Aresta sem data declarada NÃO entra: o registro de ações não publica data de emissão, e afirmar que ela já existia numa data passada é afirmação que a fonte não faz.
• snapshot (holds, contains, assigned_to, exposed_to_issuer): retrato por competência, e nenhum retrato se afirma válido depois de ser tirado. A janela é contida (relação que saiu e voltou não aparece no buraco), e at mais recente que a última competência recua até ela — a resposta diz em meta.as_of qual data foi realmente aplicada. Cada verbo tem a competência DELE: holds fecha no trimestre da CDA, contains no pregão do dia.
• static (manages, administers, custodies, audits, same_owner, shareholder_of, measures, forecasts): o registro publica só o VIGENTE — 111.729 arestas sem início declarado. Com o verbo preso em rel, at no passado responde 400 em vez de devolver o gestor de hoje como gestor de 2020. Sem verbo preso, essas arestas são removidas do conjunto e meta.excluded_shapes diz que foram.

AS IRMÃS NÃO COMPARTILHAM O DEFAULT. Sem at: esta operação, listGlobalLinks, intersectObjects e findObjectPaths respondem 'quem JÁ se relacionou'; getObjectLinkStats resume o retrato VIGENTE (última competência do próprio conjunto); traverseObjectPath atravessa o retrato vigente POR SUJEITO em cada salto. As diferenças são deliberadas — histórico acumulado, resumo e travessia respondem perguntas distintas — e cada rota declara a sua no próprio at. Medido em 23/08/2026: 1 aresta no resumo contra 100+ na listagem, para o mesmo objeto, os dois certos.

Como ordenar. name (default) é alfabética. a_count/b_count/total ordenam pelo GRAU — quantas contrapartes distintas o objeto tem em cada relação — e é assim que se pede 'as três maiores da interseção' numa chamada só, em vez de paginar o universo e agregar no cliente. Em union e difference só a_count faz sentido: não há lado B a pesar.

intersect = nos dois; union = em qualquer um; difference = em A e não em B.