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

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

# Category product ranking / 品类商品排名

Rank exact product IDs within a resolved category. / 在已对齐的品类内对商品 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`: Product ranking metric
  商品排名指标
- `top_n` — `user_required`; optional; default `20`: Number of products
  商品数量

## 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 selected 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": "使用 douyin 数据执行品类商品排名；category=示例品类，time={\"last_complete_months\":3}，ranking_metric=gmv，top_n=10",
  "dataset": "douyin",
  "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": "使用 douyin 数据执行品类商品排名；category=示例品类，time={\"last_complete_months\":3}，ranking_metric=gmv，top_n=10",
  "dataset": "douyin"
}
```


## Agent computation / Agent 计算

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

## Output requirements / 输出要求

- Return product IDs, titles, URLs, and ranking metrics.
  返回商品 ID、标题、链接和排名指标。

## Limitations / 限制

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

## Stop conditions / 停止条件

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