O VOCABULÁRIO dos verbos: o que cada relação afirma, e o que ela NÃO afirma
Leia isto ANTES de atravessar o grafo. O nome do verbo não basta: `manages` é o GESTOR e não o administrador fiduciário; `shareholder_of` é quadro societário SEM percentual e SEM qualificação, então nenhuma dessas arestas afirma controle; `same_owner` é simétrica e liga dois cedentes que compartilham sócio pessoa jurídica; `exposed_to_issuer` responde COM QUEM e nunca QUANTO. `shape` decide o que 'quantos' significa e qual `at` reproduz a contagem: `event` é total de todos os tempos, `snapshot` é o último retrato, `static` é o vigente — e verbo `static` RECUSA data passada, porque a fonte não publica série. `domain_kinds` e `range_kinds` dizem quais tipos podem estar em cada ponta, o que permite descartar uma travessia impossível antes de pagar por ela: `holds` termina em instrumento, fundo ou papel, nunca na companhia emissora. Catálogo fechado e pequeno, sem paginação. Traz também os verbos que ainda não têm nenhuma aresta — o range é declarado antes de o objeto nascer.
curl -X GET "https://api.databolsa.com/v1/objects/relations"{
"meta": {
"next_cursor": "string",
"count": 0,
"total": 0,
"subject": {
"property1": "string",
"property2": "string"
}
},
"data": [
{
"rel": "string",
"shape": "event",
"max_gap_days": 0,
"last_valid_to": "string",
"domain_kinds": [
"string"
],
"range_kinds": [
"string"
],
"note": "string"
}
]
}{
"type": "string",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string"
}Atravessa uma relação a partir (ou em direção a) este objeto
Uma linha por AFIRMAÇÃO, com o outro lado já resolvido em nome e tipo — a mesma relação afirmada por duas fontes, ou interrompida e retomada, ocupa mais de uma linha. Para contar objetos, agrupe por `other_id`. `magnitude` é o tamanho que a fonte publicou (participação, peso no índice, valor de mercado) e **nulo não é zero**: significa que a fonte não publicou valor plausível. Prova documental é `getObjectEvidence`, não este campo. `valid_from`/`valid_to` delimitam o período — use `?at=` para o presente. **JÁ VEM ORDENADO POR `magnitude` DECRESCENTE, com nulo por último — então `limit=5` É o top-5.** Está escrito aqui porque a ausência custou caro: numa sondagem de 22/08/2026 um consumidor competente pediu "os cinco maiores donos da Vale", baixou as 341 arestas inteiras (160 mil caracteres) e ordenou por fora para chegar exatamente às cinco linhas que `limit=5` já devolveria. Capacidade que existe e não se anuncia é indistinguível de capacidade que não existe. No pior caso a diferença é entre uma chamada e o impossível: a ISA Energia tem **4.925** detentores, e a lista inteira não cabe em resposta nenhuma. O critério é o TAMANHO da aresta, não a data — e `magnitude` é o MÁXIMO do segmento, nunca o valor pontual, então isto ordena por "maior posição do período" e não por "maior posição hoje".
Ordena e FILTRA uma coorte por medidas — nível ou variação
O quarto eixo. Os outros três já existiam e cada um sozinho: QUEM (`kind`, `subkind` e as relações do grafo), O QUÊ (`listFactCatalog`) e QUANDO (`at`, `from`). Faltava o que fazer com o CONJUNTO — e sem isso 'a companhia que mais perdeu margem' exigia ler o histórico de milhares de companhias, uma chamada cada. **Quase toda triagem tem DUAS medidas, e `where` é a segunda.** Ordene por uma e corte pelas outras na mesma chamada: `fact=fidc_impaired_ratio&measure=delta&where=fidc_portfolio>50000000` responde 'quem mais piorou ENTRE os grandes'. Sem isso o corte vira uma leitura por objeto — medido em 20/08/2026, a mesma pergunta custou 14 chamadas a quem não viu o parâmetro. `meta.filterable_facts` lista, na própria resposta, o que mais cabe ali, e cada linha volta com `where_values` — o valor dela em CADA corte, já calculado para filtrar. Não peça um segundo ranking para reler o segundo número. **`expand` traz o objeto ligado em cada linha.** `kind=offering&expand=issued` responde 'as maiores ofertas E quem emitiu cada uma' numa chamada só, com o nome e a chave do emissor na própria linha. **Para um PERÍODO, use `at` com `since`**: `at` é o teto da data-base e `since` o piso. Não existe `until` porque `at` já é ele. Em `delta` e `pct_change`, `since_from` é o piso da ponta INICIAL — sem ele a janela pedida não é a janela recebida. **Leia `unit` antes de comparar com outra medida.** `ratio` é fração (0,08 é 8%) e `pct` é percentual (8,0 é 8%). **`pct_change` não serve para medida que cruza o zero**: margem indo de -1% para -2% devolve +100% de 'crescimento'. Para essas, `delta`. **Quem não tem valor nas DUAS pontas não entra**, e não entrar não é valer zero — `cohort_size` é o denominador honesto. Cada linha declara `as_of` e `as_of_from` porque medida trimestral cai na última competência publicada até a data pedida, e duas companhias podem estar comparando trimestres diferentes. **`availability: unknown` significa que a fonte não publica data de entrega** e o corte é só pela data-base: um ranking numa data passada enxerga números que ainda não eram públicos. Com `filed`, o corte é point-in-time completo.