# 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? }
```

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):

```json
{
  "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:

```json
{
  "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:

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