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

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

# Douyin Monthly Product Sales / 抖音商品月度销量明细表

This page defines canonical public field names. Authenticated tools and runtime responses are authoritative for current execution capabilities, tenant access, and time coverage; use `describe(dataset)` only to recover from a contract or capability error.
此页定义 canonical 公共字段名。当前执行能力、租户权限和时间范围以认证后的工具面与运行时响应为准；仅在契约或能力错误后使用 `describe(dataset)` 恢复。

- Platform / 平台: Douyin / 抖音
- API ID: `dataset=douyin`
- Time grain / 时间粒度: `month`
- Entity types / 实体类型: `product, shop, seller`
- Filter fields / 可筛选字段: `product_id, shop_id, shop, seller_id, brand, category, category_id, category_l1_id, category_l1, category_l2_id, category_l2, category_l3_id, category_l3, category_l4_id, category_l4`

## Minimal call / 最小调用

`query_metrics`

```json
{
  "task_query": "查看抖音最近一个完整月的品牌销售额排名",
  "dataset": "douyin",
  "metrics": [
    "gmv"
  ],
  "group_by": [
    "brand"
  ],
  "time": {
    "last_complete_months": 1
  },
  "order_by": [
    {
      "field": "gmv",
      "dir": "desc"
    }
  ],
  "limit": 10
}
```


## Product search / 商品检索

- Availability / 可用性: `runtime_check_required` — check the authenticated tools/list and runtime before calling / 调用前请以认证后的 tools/list 和运行时能力为准
- Find product identity candidates by matching product title text. / 按商品标题文本查找商品身份候选。
- Search by product name or title to find identity candidates; this does not return sales metrics. / 按商品名称或标题只查找候选商品身份，不返回销售指标。
- If more than one candidate is returned, ask the user to choose; then pass the selected `product_id` to `query_metrics` or `query_details`. / 返回多个候选时先让用户选择，再把选定的 `product_id` 传给 `query_metrics` 或 `query_details`。
- `search_products` is separate from `search_values`: use the former for product names/titles and the latter for brand, shop, and category names. / `search_products` 与 `search_values` 分开：前者处理商品名称/标题，后者处理品牌、店铺和品类名称。

Candidate fields / 候选字段:

- `product_id` · required
- `title` · required
- `product_url` · optional
- `brand` · optional
- `category_l1` · optional
- `category_l2` · optional
- `category_l3` · optional
- `shop` · optional
- `available_months` · optional

Filters / 筛选: `brand`, `category_l1`, `category_l2`, `category_l3`, `shop`
Operators / 操作符: `eq`, `in`
Match mode / 匹配方式: `title_contains`


## Fields and capabilities / 字段与能力

- `product_id` — Stable Douyin product identifier from the source record, used for exact filtering and paired with the source product URL. / 上游记录中的抖音商品稳定标识，用于精确筛选，并与上游商品链接配套。 (identifier; detail-return; aggregate-select; group-by; sort; aggregate-filter=eq,in; detail-filter=eq,in)
- `title` — Product title recorded by the Douyin source for the calendar month; it is returned for display and grouping, not used as an exact product filter. / 抖音源数据记录的自然月商品标题，用于结果展示和分组，不作为精确商品筛选条件。 (attribute; detail-return; aggregate-select; group-by; sort; requires-group-by=product_id)
- `product_url` — Product-detail URL supplied by the Douyin source and paired with product_id; the value is returned as recorded without URL synthesis. / 抖音源数据提供的商品详情链接，与 product_id 配套；按源记录返回，不在查询层拼接。 (attribute; detail-return; aggregate-select; group-by; sort; requires-group-by=product_id)
- `shop_id` — Stable Douyin shop identifier recorded by the source, used for exact shop filtering and tenant scope selection when authorized. / 上游记录的抖音店铺稳定标识，用于精确店铺筛选及授权后的租户范围选择。 (identifier; detail-return; aggregate-select; group-by; sort; aggregate-filter=eq,in; detail-filter=eq,in)
- `shop` — Shop name recorded by the Douyin source for the product-month row; names may change over time and should be aligned through value search. / 抖音源数据记录的商品月度店铺名称，名称可能随时间变化，应通过值搜索进行对齐。 (dimension; detail-return; aggregate-select; group-by; sort; search; aggregate-filter=eq,neq,in,not_in,contains; detail-filter=eq,neq,in,not_in,contains)
- `seller_id` — Seller identifier recorded by the Douyin source for the product-month row; it is returned as an identifier and is not inferred from shop names. / 抖音源数据记录的商品月度卖家标识，按标识返回，不根据店铺名称推断。 (identifier; detail-return; aggregate-select; group-by; sort; aggregate-filter=eq,in; detail-filter=eq,in)
- `brand` — Brand name recorded by the Douyin source for the product-month row; the source may leave it empty for unbranded or unclassified products. / 抖音源数据记录的商品月度品牌名称，白牌或未分类商品可能为空。 (dimension; detail-return; aggregate-select; group-by; sort; search; aggregate-filter=eq,neq,in,not_in,contains; detail-filter=eq,neq,in,not_in,contains)
- `category` — Leaf category name recorded by the Douyin source for the product-month row; it is distinct from the four-level category hierarchy. / 抖音源数据记录的商品月度末级类目名称，与四级类目层级字段区分。 (dimension; detail-return; aggregate-select; group-by; sort; search; aggregate-filter=eq,neq,in,not_in,contains; detail-filter=eq,neq,in,not_in,contains)
- `category_id` — Leaf category identifier recorded by the Douyin source for the product-month row; it is returned without filling missing source values. / 抖音源数据记录的商品月度末级类目标识，按源数据返回，不填充缺失值。 (identifier; detail-return; aggregate-select; group-by; sort; aggregate-filter=eq,in; detail-filter=eq,in)
- `category_l1_id` — Level-1 category identifier recorded by the Douyin source and paired with the corresponding level-1 category name. / 抖音源数据记录的一级类目标识，与对应的一级类目名称配套。 (identifier; detail-return; aggregate-select; group-by; sort; aggregate-filter=eq,in; detail-filter=eq,in)
- `category_l1` — Level-1 category name recorded by the Douyin source and paired with category_l1_id in the source hierarchy. / 抖音源数据记录的一级类目名称，与源层级中的 category_l1_id 配套。 (dimension; detail-return; aggregate-select; group-by; sort; search; aggregate-filter=eq,neq,in,not_in,contains; detail-filter=eq,neq,in,not_in,contains)
- `category_l2_id` — Level-2 category identifier recorded by the Douyin source and paired with the corresponding level-2 category name. / 抖音源数据记录的二级类目标识，与对应的二级类目名称配套。 (identifier; detail-return; aggregate-select; group-by; sort; aggregate-filter=eq,in; detail-filter=eq,in)
- `category_l2` — Level-2 category name recorded by the Douyin source and paired with category_l2_id in the source hierarchy. / 抖音源数据记录的二级类目名称，与源层级中的 category_l2_id 配套。 (dimension; detail-return; aggregate-select; group-by; sort; search; aggregate-filter=eq,neq,in,not_in,contains; detail-filter=eq,neq,in,not_in,contains)
- `category_l3_id` — Level-3 category identifier recorded by the Douyin source and paired with the corresponding level-3 category name. / 抖音源数据记录的三级类目标识，与对应的三级类目名称配套。 (identifier; detail-return; aggregate-select; group-by; sort; aggregate-filter=eq,in; detail-filter=eq,in)
- `category_l3` — Level-3 category name recorded by the Douyin source and paired with category_l3_id in the source hierarchy. / 抖音源数据记录的三级类目名称，与源层级中的 category_l3_id 配套。 (dimension; detail-return; aggregate-select; group-by; sort; search; aggregate-filter=eq,neq,in,not_in,contains; detail-filter=eq,neq,in,not_in,contains)
- `category_l4_id` — Level-4 category identifier recorded by the Douyin source and paired with the corresponding level-4 category name. / 抖音源数据记录的四级类目标识，与对应的四级类目名称配套。 (identifier; detail-return; aggregate-select; group-by; sort; aggregate-filter=eq,in; detail-filter=eq,in)
- `category_l4` — Level-4 category name recorded by the Douyin source and paired with category_l4_id in the source hierarchy. / 抖音源数据记录的四级类目名称，与源层级中的 category_l4_id 配套。 (dimension; detail-return; aggregate-select; group-by; sort; search; aggregate-filter=eq,neq,in,not_in,contains; detail-filter=eq,neq,in,not_in,contains)
- `price` — Product price recorded by the Douyin source for the product-month row; it is a detail value and is not used as a monthly sales aggregate. / 抖音源数据记录的商品月度价格，是明细值，不作为月度销售额聚合指标。 (measure; detail-return)
- `is_first_seen` — First-seen marker recorded by the Douyin source for the product-month row; its source meaning is preserved without deriving a new date. / 抖音源数据记录的商品月度首次出现标记，保留源含义，不由查询层推导日期。 (attribute; detail-return)
- `month` — Calendar month to which the Douyin product record belongs, represented as the public monthly time dimension and not as the collection date. / 抖音商品记录所属自然月，是公开的月度时间维度，不等同于采集日期。 (time; detail-return; aggregate-select; group-by; sort)
- `sales` — Raw sales amount recorded by the Douyin source for one product-month row; aggregation uses SUM(sales) after the reviewed source grain is confirmed. / 抖音源数据记录的单商品月度原始销售额，确认源行粒度后按 SUM(sales) 聚合。 (measure; detail-return)
- `volume` — Raw units volume recorded by the Douyin source for one product-month row; aggregation uses SUM(volume) after duplicate handling is reviewed. / 抖音源数据记录的单商品月度原始销量，完成重复处理复核后按 SUM(volume) 聚合。 (measure; detail-return)
- `gmv` — Aggregated Douyin sales amount calculated as SUM(sales) over the requested product and calendar-month scope after source-quality validation. / 经过源数据质量验收后，按请求商品和自然月范围对 sales 求和得到的抖音汇总销售额。 (measure; aggregate-select; sort)
- `units` — Aggregated Douyin units sold calculated as SUM(volume) over the requested product and calendar-month scope after duplicate handling is validated. / 完成重复处理验收后，按请求商品和自然月范围对 volume 求和得到的抖音汇总销量。 (measure; aggregate-select; sort)
- `asp` — Weighted average selling price calculated as SUM(sales) divided by SUM(volume) over the requested scope; returns null when total volume is zero. / 按请求范围计算 SUM(sales) 除以 SUM(volume) 的加权平均成交价；总销量为零时返回空值。 (measure; aggregate-select; sort)

## Query Patterns / 查询模式

- [`aggregate_drilldown`](https://docs.asklear.cn/capabilities/douyin/tasks/aggregate_drilldown) — Query a category scope, then rank products under the same filters. / 先查询品类汇总，再在相同筛选条件下对商品排名。
- [`brand_share`](https://docs.asklear.cn/capabilities/douyin/tasks/brand_share) — Compute brand share from two atomic GMV results. / 通过两个原子销售额结果计算品牌份额。
- [`category_product_ranking`](https://docs.asklear.cn/capabilities/douyin/tasks/category_product_ranking) — Rank exact product IDs within a resolved category. / 在已对齐的品类内对商品 ID 排名。
- [`shop_name_performance`](https://docs.asklear.cn/capabilities/douyin/tasks/shop_name_performance) — Resolve a shop name and query monthly metrics. / 对齐店铺名并查询月度指标。

## Limitations / 限制

- Data is partitioned by calendar month. / 数据按自然月分区
- search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id because this dataset does not expose a standard product URL filter. / search_products 可按商品名称或标题查找候选商品身份；query_metrics 和 query_details 的商品筛选仍需精确 product_id，本数据集未提供标准商品链接筛选
- Shops accept an exact shop_id or a shop name aligned with search_values. / 店铺可使用精确 shop_id 或经 search_values 对齐后的店铺名
- Reviews, traffic, inventory, causal explanations, and other platform data are not provided. / 不提供评价、流量、库存、因果解释或其他平台数据
- YoY, MoM, share, contribution, and cross-period set differences are computed by the Agent from atomic query results. / 同比、环比、份额、贡献度和跨期集合差异由 Agent 基于原子查询结果计算
- Metric definitions, coverage volume, refresh timing, and access entitlement are pending upstream confirmation. / 指标口径、覆盖量级、更新时间和访问授权仍待上游确认
- The catalog currently registers the 2026-06 month; coverage, duplicate-row handling, and metric definitions remain pending confirmation. / 当前目录仅登记 2026-06 月份；覆盖范围、重复行处理和指标口径待确认