Resume uma coorte — soma, média ou mediana, repartida por propriedade ou relação

A outra metade de `rankObjects`. Aquele responde QUEM se destaca; este responde QUANTO DÁ, repartido. "O patrimônio dos FIDCs somado por gestora" não tinha caminho: a saída era paginar o ranking inteiro e agrupar no cliente, o que só funciona se a coorte couber na página. **A COORTE é a mesma de `rankObjects`** — `kind`, `subkind`, `rel`/`rel_to` e `where`, com a mesma sintaxe e o mesmo significado. Troque `rankObjects` por `aggregateObjects` na mesma consulta e você resume exatamente o conjunto que ordenaria. **`group_by` aceita PROPRIEDADE ou RELAÇÃO**, e a resposta diz qual em `meta.group_by_kind`. `group_by=situation` reparte por atributo; `group_by=manages` reparte pelo objeto do outro lado da aresta — e aí cada grupo traz `entity_id`, porque gestora é objeto. Quando o grupo é palavra, `entity_id` vem nulo: é assim que se distingue, e o formato da linha nunca muda. `meta.groupable` lista, na própria resposta, o que cabe aqui. **`group_by_direction` diz onde a COORTE está na aresta**, igual a `rel_direction`. `manages` liga gestora a fundo, então uma coorte de fundos está na ponta de ENTRADA (`in`). Errar a direção devolve lista vazia — e nesse caso `meta.empty_reason` diz qual direção funcionaria, em vez de deixar a resposta parecer "não há dado". **`sum` é RECUSADO em percentual, razão, múltiplo e ponto de índice.** Somar o dividend yield de 300 FIIs devolve um número, responde 200 e não significa nada. `avg`, `median`, `min` e `max` valem para qualquer unidade — a média de um percentual é um percentual. **Três números de cobertura, e eles não são detalhe.** `cohort_objects` é a coorte inteira e `cohort_with_value` o subconjunto que tem número na medida — este segundo é o que `rankObjects` chama de `cohort_size`, e os nomes diferem de propósito para que ninguém leia um pelo outro. `ungrouped` conta quem ficou FORA de todo grupo (medido: 20.098 dos 57.090 fundos não declaram situação), e sem ele o total dos grupos parece completo sendo parcial. `multi_group` conta quem caiu em MAIS DE UM grupo: zero num verbo funcional, grande em `issued`, onde o mesmo objeto entra numa vez por emissão e o `sum` o conta várias — o número não fica errado, a leitura muda. Cada grupo traz `objects` e `with_value`. Diferença entre os dois é cobertura parcial: um grupo com 36 objetos e nenhum valor devolve `value: null`, nunca zero. **Para o TOTAL do mercado, leia `meta.cohort_value` — não some a página.** É a mesma agregação aplicada à coorte inteira, antes de repartir: inclui os `ungrouped` e não depende do `limit`. O `group_by` continua obrigatório, mas deixou de ser o único caminho até o total. **`order_by=objects` ordena pelos grupos MAIORES em objetos** — "as gestoras com mais fundos" é essa pergunta. O default `value` ordena pela agregação, e com o teto de grupos as duas ordens podem devolver PÁGINAS diferentes. **Sem `fact`, com `agg=count`, a operação vira CENSO**: conta OBJETOS por grupo. É o único caminho de contagem para tipo que só tem propriedades — "quantas assessorias ativas por UF" é `kind=service_provider&agg=count&group_by=advisor_state&where=advisor_situation=EM FUNCIONAMENTO NORMAL`, sem medida nenhuma envolvida. `meta.fact` volta nulo e `value` = `objects`.

curl -X GET "https://api.databolsa.com/v1/objects/aggregate?kind=company&subkind=string&fact=string&agg=sum&group_by=string&group_by_direction=in&at=string&rel=string&rel_to=string&rel_direction=in&where=string&limit=50&order_by=value"

{
  "data": [
    {
      "key": "string",
      "label": "string",
      "entity_id": "string",
      "value": 0,
      "objects": 0,
      "with_value": 0
    }
  ],
  "meta": {
    "next_cursor": null,
    "count": 0,
    "fact": "string",
    "unit": "brl",
    "agg": "sum",
    "group_by": "string",
    "group_by_kind": "property",
    "source": "string",
    "cadence": "daily",
    "grain": "object",
    "description": "string",
    "cohort_objects": 0,
    "cohort_with_value": 0,
    "cohort_value": 0,
    "order_by": "value",
    "total_groups": 0,
    "groups_truncated": true,
    "ungrouped": 0,
    "multi_group": 0,
    "filterable_properties": [
      {
        "name": "string",
        "vocabulary": [
          "string"
        ]
      }
    ],
    "groupable": [
      {
        "name": "string",
        "kind": "property"
      }
    ],
    "empty_reason": "string"
  }
}

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}