Consultas avançadas (`querySpec`)

O knewin_aggregate publica no esquema o núcleo do querySpec. Este tópico documenta os recortes que funcionam igual e só não são listados no manifesto, por peso. Os filtros editoriais estão em Filtros avançados do clipping.

Tudo abaixo pode ser enviado normalmente. ⚠ Escreva o nome da chave exatamente como está aqui: no nível do querySpec, chave que o motor não conhece é ignorada em silêncio e a consulta roda sem ela — o número volta certo para outra pergunta. Só dentro de filter uma chave desconhecida vira erro.

O núcleo, para referência

{
  "entityLabel": "Marca X",
  "window": { "start": "2026-08-01", "end": "2026-08-31" },
  "querySpec": {
    "id": "vol-por-canal",
    "measures": ["unique", "nrs"],
    "groupBy": ["channel"],
    "orderBy": { "measure": "unique", "dir": "desc" },
    "limit": 20
  }
}

id é um slug curto que nomeia esta consulta — é por ele que o número vira fato citável. Para uma série em ordem cronológica, use orderBy: { "dimension": "day", "dir": "asc" }.

Baldes: a sua leitura vira medição

Use quando os valores crus não são a resposta. Cada balde é medido como um grupo — a matéria que cita dois valores do mesmo balde conta uma vez, que é o que somar as linhas na mão não faz.

{
  "querySpec": {
    "id": "leitura-por-tema",
    "measures": ["unique", "nrs"],
    "groupBy": ["extractedEntity"],
    "buckets": {
      "dimension": "extractedEntity",
      "linhas": [
        { "grupo": "Propulsão & Energia", "rotulo": "Motor", "valores": ["motor", "motor elétrico"] },
        { "grupo": "Propulsão & Energia", "rotulo": "Bateria", "valores": ["bateria", "autonomia"] },
        { "rotulo": "Concorrentes citados", "valores": ["marca y", "marca z"] }
      ]
    }
  }
}

• grupo é opcional e cria o segundo nível: a categoria também é medida como balde, nunca como soma das linhas.
• O que você não nomear fica de fora, e o corte volta declarado.
• Tom do balde: com dimensão que tem juízo próprio, pos/neg/neu/nrs saem dos valores-membro. Matéria que julga membros do mesmo balde de formas opostas conta em unlabeled — ausência de juízo único não é "neutro" (declarado em basis.bucketTone).

compute: médias, somas, picos

{
  "querySpec": {
    "id": "media-diaria",
    "measures": ["unique"],
    "compute": [
      { "fn": "avg", "of": "articles", "over": "day" },
      { "fn": "max", "of": "audience" },
      { "fn": "count_distinct", "of": "source" }
    ]
  }
}

of aceita articles, mentions, audience, reach, valuation, centimetrage e republications. over agrupa antes da conta ("média de matérias por dia").

⚠ Nunca some republications: cada matéria conta as outras cópias dela, e o número olha o clipping inteiro, não só o recorte. Use avg ou max.

Matéria sem o dado fica fora da base da medida (nunca conta como zero), e o resultado declara sobre quantas ela nasceu.

toneSubject: de quem é o juízo de tom

Agrupando por entidade citada, as medidas de tom podem descrever duas coisas, e você declara qual: "group" (o padrão ali) é o que a cobertura diz sobre o assunto; "brand" é o tom da marca dentro das matérias de cada assunto.

{ "querySpec": { "id": "tom-da-marca-por-tema", "measures": ["nrs"],
  "groupBy": ["extractedEntity"], "toneSubject": "brand" } }

Pedir "group" sem agrupar por algo com juízo próprio é recusado, com a explicação. Ver Sentimento.

weight: "copies"

Pondera pelas cópias colapsadas de cada matéria, em vez de contar uma por registro. Use quando a pergunta for sobre repercussão física da mesma peça.

Veja também

Campos de cada matéria (project), Filtros avançados do clipping, NRS e Volume.