Consulta genérica (query)

Consulta genérica — a tool query

Quando as ferramentas prontas (aggregate_orders, rank_items, …) não cobrem a pergunta, a tool query aceita uma consulta estruturada sobre entidades permitidas — com filtros, agrupamento e agregações computadas no servidor. Nunca aceita SQL.

Gramática

query := { entity, select?, filter?, group_by?, aggregate?, sort?, limit?, budget? }
filter    := { <campo>: { <op>: <valor> }, ..., "or"?: [filter, ...] }
aggregate := [ { op: sum|count|avg|min|max|count_distinct, field?, as } ]
group_by  := [ <campo> | { field: <campo-data>, bucket: "day"|"week"|"month" } ]
budget    := { max_upstream_calls?, max_rows_scanned?, timeout_ms? }

Entidades: orders, order_items, items, questions, claims. Operadores de filtro: eq, ne, gt, gte, lt, lte, in, nin, between, contains, starts_with, exists, after, before. O catálogo completo (campos por entidade) vem da tool describe_query_schema.

Regras de segurança/custo

  • orders/order_items/claims/items exigem filtro de data (date_created/date_closed) ou por id — varreduras ilimitadas são rejeitadas.
  • group_by em campo de alta cardinalidade (buyer_id, item_id) exige limit.
  • Toda resposta traz _meta { upstream_calls, rows_scanned, truncated }.

Exemplos prontos

Faturamento pago por dia (últimos 7 dias):

{
  "entity": "orders",
  "filter": {
    "status": { "eq": "paid" },
    "date_closed": { "between": ["2026-07-01", "2026-07-07"] }
  },
  "group_by": [{ "field": "date_closed", "bucket": "day" }],
  "aggregate": [
    { "op": "sum", "field": "total_amount", "as": "faturamento" },
    { "op": "count", "as": "pedidos" }
  ]
}

Top 10 itens por unidades vendidas no mês:

{
  "entity": "order_items",
  "filter": { "date_closed": { "after": "2026-07-01" } },
  "group_by": ["item_id"],
  "aggregate": [{ "op": "sum", "field": "quantity", "as": "unidades" }],
  "sort": [{ "field": "unidades", "dir": "desc" }],
  "limit": 10
}

Compradores únicos na semana:

{
  "entity": "orders",
  "filter": { "date_created": { "after": "2026-07-01" } },
  "aggregate": [{ "op": "count_distinct", "field": "buyer_id", "as": "compradores" }]
}
IndexFAQ