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

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

# Tmall 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 / 平台: Tmall / 天猫
- API ID: `dataset=tmall`
- Time grain / 时间粒度: `month`
- Entity types / 实体类型: `product, shop`
- Filter fields / 可筛选字段: `product_id, shop_id, brand, category_l1, category_l2, category_l3, shop, is_live, has_bybt, bc_type`

## Minimal call / 最小调用

`query_metrics`

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


## Fields and capabilities / 字段与能力

- `product_id` — Stable Tmall product identifier used for exact filtering and paired with product_url. / 天猫商品的稳定标识，用于精确筛选，并与 product_url 对应。 (identifier; detail-return; aggregate-select; group-by; sort; aggregate-filter=eq,in; detail-filter=eq,in; references=tmall_product_id,tmall_product_url)
- `title` — Product title recorded for the month; available for output, but not for title search or filtering. / 该自然月记录的商品标题；可返回展示，但不支持按标题搜索或筛选。 (attribute; detail-return; aggregate-select; group-by; sort; requires-group-by=product_id)
- `product_url` — Canonical Tmall product-detail URL generated from product_id. / 根据 product_id 生成的标准天猫商品详情页链接。 (attribute; detail-return; aggregate-select; group-by; sort; requires-group-by=product_id)
- `shop_id` — Stable Tmall shop identifier used for exact filtering and paired with shop_url. / 天猫店铺的稳定标识，用于精确筛选，并与 shop_url 对应。 (identifier; detail-return; aggregate-select; group-by; sort; aggregate-filter=eq,in; detail-filter=eq,in; references=tmall_shop_id,tmall_shop_url)
- `shop_url` — Canonical Tmall shop-page URL generated from shop_id. / 根据 shop_id 生成的标准天猫店铺页面链接。 (attribute; detail-return; aggregate-select; group-by; sort; requires-group-by=shop_id)
- `brand_id` — Upstream Tmall brand identifier paired with brand; it may be missing when the source does not identify a brand. / 天猫上游提供的品牌标识，与 brand 对应；上游未识别品牌时可能为空。 (identifier; detail-return; detail-filter=eq,in)
- `brand` — Brand name recorded by the upstream Tmall data, paired with brand_id; it may be missing or vary in spelling. / 天猫上游记录的品牌名称，与 brand_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_l1_id` — Identifier of category_l1 in the upstream Tmall category hierarchy; it may be missing. / 天猫上游品类体系中 category_l1 对应的一级品类标识；可能为空。 (identifier; detail-return; detail-filter=eq,in)
- `category_l1` — Level-1 category name in the upstream Tmall hierarchy, paired with category_l1_id. / 天猫上游品类体系中的一级品类名称，与 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` — Identifier of category_l2 in the upstream Tmall category hierarchy; it may be missing. / 天猫上游品类体系中 category_l2 对应的二级品类标识；可能为空。 (identifier; detail-return; detail-filter=eq,in)
- `category_l2` — Level-2 category name in the upstream Tmall hierarchy, paired with category_l2_id. / 天猫上游品类体系中的二级品类名称，与 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` — Identifier of category_l3 in the upstream Tmall category hierarchy; it may be missing. / 天猫上游品类体系中 category_l3 对应的三级品类标识；可能为空。 (identifier; detail-return; detail-filter=eq,in)
- `category_l3` — Level-3 category name in the upstream Tmall hierarchy, paired with category_l3_id. / 天猫上游品类体系中的三级品类名称，与 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)
- `shop` — Shop name recorded by Tmall, paired with shop_id; it may change over time. / 天猫记录的店铺名称，与 shop_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)
- `specification` — Product specification attributes, usually encoded as a JSON object string; keys vary by category, the value may be empty, and it is available only in detail output. / 商品规格属性集合，通常编码为 JSON 对象字符串；属性键因品类而异，内容可能为空，仅支持明细返回。 (attribute; detail-return)
- `month` — Calendar month to which the product sales record belongs, formatted as YYYY-MM; the dataset grain is monthly. / 商品销售记录所属自然月，格式为 YYYY-MM；该数据集为月粒度。 (time; detail-return; aggregate-select; group-by; sort)
- `is_live` — Whether the product has appeared in live commerce during the record month; null or empty means unknown, not no. / 商品是否上过直播；指记录月份内是否出现在天猫直播场景；空值或空字符串表示未知，不表示否。 (dimension; detail-return; aggregate-select; group-by; sort; aggregate-filter=eq,neq,in,not_in,is_unknown,is_known; detail-filter=eq,neq,in,not_in,is_unknown,is_known)
- `has_bybt` — Whether the product participates in the RMB 10B subsidy program during the record month; null or empty means unknown, not no. / 商品是否参加百亿补贴；指记录月份内是否参加天猫百亿补贴；空值或空字符串表示未知，不表示否。 (dimension; detail-return; aggregate-select; group-by; sort; aggregate-filter=eq,neq,in,not_in,is_unknown,is_known; detail-filter=eq,neq,in,not_in,is_unknown,is_known)
- `bc_type` — Tmall B/C shop type after trimming blank values; null means the type is unknown. / 天猫店铺 B/C 类标识；去除空白后使用，空值表示店铺类型未知。 (dimension; detail-return; aggregate-select; group-by; sort; search; aggregate-filter=eq,neq,in,not_in,is_unknown,is_known; detail-filter=eq,neq,in,not_in,is_unknown,is_known)
- `gmv` — Post-coupon sales amount in CNY; aggregate queries sum the selected scope, while detail queries return the value for one product-month record. / 券后销售额，单位为人民币元；聚合查询返回所选范围合计，明细查询返回单条商品月记录的金额。 (measure; detail-return; aggregate-select; sort; certified)
- `units` — Units sold; aggregate queries sum the selected scope, while detail queries return the value for one product-month record. / 商品销量；聚合查询返回所选范围合计，明细查询返回单条商品月记录的销量。 (measure; detail-return; aggregate-select; sort)
- `asp` — Weighted average selling price in CNY, calculated as SUM(gmv) / SUM(units); null when total units is zero, and available only in aggregate queries. / 加权平均成交价，单位为人民币元，按 SUM(gmv) / SUM(units) 计算；总销量为 0 时返回空，仅支持聚合查询。 (measure; aggregate-select; sort)

## Query Patterns / 查询模式

- [`aggregate_drilldown`](https://docs.asklearai.com/capabilities/tmall/tasks/aggregate_drilldown) — Query an aggregate scope, then rank products under exactly the same filters. / 先查询汇总范围，再在完全相同的筛选条件下对商品下钻排序。
- [`bc_shop_comparison`](https://docs.asklearai.com/capabilities/tmall/tasks/bc_shop_comparison) — Compare monthly atomic sales metrics across normalized B/C shop groups. / 按归一化后的 B/C 店铺分组比较月度原子销售指标。
- [`brand_share`](https://docs.asklearai.com/capabilities/tmall/tasks/brand_share) — Compute a brand's share from two atomic GMV results returned by one bundled call. / 通过一次组合调用返回的两个原子销售额结果计算品牌份额。
- [`brand_trend`](https://docs.asklearai.com/capabilities/tmall/tasks/brand_trend) — Query monthly atomic metrics for one exact brand. / 查询一个精确品牌的月度原子指标。
- [`bybt_coverage`](https://docs.asklearai.com/capabilities/tmall/tasks/bybt_coverage) — Inspect monthly atomic sales metrics grouped by the normalized subsidy indicator. / 按归一化后的百亿补贴标识分组查看月度原子销售指标。
- [`category_product_ranking`](https://docs.asklearai.com/capabilities/tmall/tasks/category_product_ranking) — Rank exact product IDs within a resolved category and time range. / 在已对齐的品类和时间范围内对精确商品 ID 排名。
- [`cross_period_products`](https://docs.asklearai.com/capabilities/tmall/tasks/cross_period_products) — Compare product-ID sets returned by one bundled period call. / 比较一次组合调用返回的两个期间商品 ID 集合。
- [`live_sales_comparison`](https://docs.asklearai.com/capabilities/tmall/tasks/live_sales_comparison) — Compare monthly atomic sales metrics by the normalized live-commerce indicator. / 按归一化后的直播标识比较月度原子销售指标。
- [`product_comparison`](https://docs.asklearai.com/capabilities/tmall/tasks/product_comparison) — Compare multiple exact Tmall product references over one time range. / 在同一时间范围内比较多个精确天猫商品引用。
- [`product_contribution`](https://docs.asklearai.com/capabilities/tmall/tasks/product_contribution) — Attribute cross-period GMV change from two product-level atomic queries. / 通过两次商品级原子查询归因跨期销售额变化。
- [`product_performance`](https://docs.asklearai.com/capabilities/tmall/tasks/product_performance) — Query monthly sales metrics for one exact Tmall product reference. / 查询一个精确天猫商品引用的月度销售指标。
- [`shop_name_performance`](https://docs.asklearai.com/capabilities/tmall/tasks/shop_name_performance) — Resolve one spoken shop name and query its monthly atomic metrics. / 对齐一个口语店铺名并查询月度原子指标。
- [`shop_performance`](https://docs.asklearai.com/capabilities/tmall/tasks/shop_performance) — Query monthly atomic metrics for one exact Tmall shop ID or standard URL. / 按精确天猫店铺 ID 或标准链接查询月度原子指标。

## Limitations / 限制

- Only monthly-grain data is available; 2026-06 is the first published waterline, not a subscription start month. / 仅支持月粒度数据；2026-06 是首发水位，不是订阅起始月份
- Products and shops require exact IDs or confirmed HTTPS Taobao links. / 商品和店铺只支持精确 ID 或已确认的 HTTPS 淘宝链接格式
- NULL and empty strings consistently mean unknown, not no. / NULL 和空字符串统一表示未知，不等同于否