---
document_id: agent.dataset.tmall.task.category_product_ranking
schema_version: 2
parent_document_id: agent.dataset.tmall
section: capabilities
---

<!-- Generated by scripts.build_agent_guide; do not edit. -->

# Category product ranking / 品类商品排名

Rank exact product IDs within a resolved category and time range. / 在已对齐的品类和时间范围内对精确商品 ID 排名。

## Required inputs / 必要输入

- `category` — `search_values`; required (`category_l3`): Exact category value
  精确品类值
- `time` — `user_required`; required: Analysis time range
  分析时间范围
- `ranking_metric` — `user_required`; optional; default `gmv`; allowed: `gmv, units`: Metric used to rank products
  商品排名所用指标
- `top_n` — `user_required`; optional; default `20`: Number of products to return
  返回商品数量

## Steps / 步骤

1. `resolve_category` · `search_values` — Resolve the category value.
   对齐品类值。
   - search `category_l3` with `${category}`
2. `query_products` · `query_metrics` — Query and order products by the requested metric.
   查询商品并按用户要求的指标排序。
   - metrics: `gmv`, `units`
   - group_by: `product_id`, `title`, `product_url`
   - result entity: `product`
   - filters: `category_l3 eq ${category}`
   - time: `${time}`
   - order_by: `${ranking_metric}` desc
   - limit: `${top_n}`

## Call example / 调用示例

Replace the example values with exact user inputs or values returned by `search_values`. / 将示例值替换为用户的精确输入或 `search_values` 返回的平台原始值。

`search_values`

```json
{
  "task_query": "使用 tmall 数据执行品类商品排名；category=示例品类，time={\"last_complete_months\":3}，ranking_metric=gmv，top_n=10",
  "dataset": "tmall",
  "field": "category_l3",
  "kw": "示例品类",
  "limit": 10
}
```

`query_metrics`

```json
{
  "metrics": [
    "gmv",
    "units"
  ],
  "time": {
    "last_complete_months": 3
  },
  "group_by": [
    "product_id",
    "title",
    "product_url"
  ],
  "filters": [
    {
      "field": "category_l3",
      "op": "eq",
      "value": "示例品类"
    }
  ],
  "order_by": [
    {
      "field": "gmv",
      "dir": "desc"
    }
  ],
  "limit": 10,
  "task_query": "使用 tmall 数据执行品类商品排名；category=示例品类，time={\"last_complete_months\":3}，ranking_metric=gmv，top_n=10",
  "dataset": "tmall"
}
```


## Agent computation / Agent 计算

- `rank_products` · `rank` from `query_products` — Preserve the server ordering and requested limit.
  保留服务端排序和用户要求的数量限制。

## Output requirements / 输出要求

- Return product IDs, titles, canonical URLs, and the values used for ranking.
  返回商品 ID、标题、标准链接和用于排名的指标值。

## Limitations / 限制

- Product titles are not available for fuzzy resolution.
  不支持通过商品标题进行模糊解析。

## Stop conditions / 停止条件

- Stop if the category cannot be resolved exactly.
  无法精确对齐品类时停止。