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

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

# PDD 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 / 平台: PDD / 拼多多
- API ID: `dataset=pdd`
- Time grain / 时间粒度: `month`
- Entity types / 实体类型: `product, shop`
- Filter fields / 可筛选字段: `product_id, shop_id, shop, brand, category_l1, category_l2, category_l3, billion_subsidy_tag, ori_category_l1, ori_category_l2, ori_category_l3`

## Minimal call / 最小调用

`query_metrics`

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


## Fields and capabilities / 字段与能力

- `product_id` — Stable PDD product identifier used for exact filtering and paired with the canonical product-detail URL in public results. / 拼多多商品的稳定标识，用于精确筛选，并在公开结果中与标准商品详情链接配套。 (identifier; detail-return; aggregate-select; group-by; sort; aggregate-filter=eq,in; detail-filter=contains,eq,in,neq,not_in; references=pdd_product_id,pdd_product_url)
- `title` — Product title recorded by the PDD source for the month; it is available in returned rows and grouping, but not as a title-search field. / 拼多多源数据记录的月度商品标题，可用于结果返回和分组，但不作为标题搜索字段。 (dimension; detail-return; aggregate-select; group-by; sort; detail-filter=contains,eq,in,neq,not_in)
- `product_url` — Canonical PDD product-detail URL generated from product_id; it identifies the product reference and requires product-level grouping when used in aggregates. / 根据 product_id 生成的标准拼多多商品详情链接，用于商品引用；在汇总中使用时需要按商品粒度分组。 (attribute; aggregate-select; group-by; sort; requires-group-by=product_id)
- `shop_id` — Stable PDD shop identifier used for exact filtering and scope selection; no verified canonical shop URL is available in this release. / 拼多多店铺的稳定标识，用于精确筛选和范围选择；本版本没有已验证的标准店铺链接。 (identifier; detail-return; aggregate-select; group-by; sort; aggregate-filter=contains,eq,in,neq,not_in; detail-filter=contains,eq,in,neq,not_in)
- `shop` — Shop name recorded by the PDD source; names can change over time and should be resolved with search_values before use as a filter. / 拼多多源数据记录的店铺名称，名称可能随时间变化；用作筛选前应通过 search_values 对齐。 (dimension; aggregate-select; group-by; sort; search; aggregate-filter=contains,eq,in,neq,not_in)
- `brand` — Brand name recorded by the PDD source; values may be empty or vary in spelling, so resolve names before treating them as a filter. / 拼多多源数据记录的品牌名称，可能为空或存在写法差异；作为筛选条件前应先对齐名称。 (dimension; aggregate-select; group-by; sort; search; aggregate-filter=contains,eq,in,neq,not_in)
- `category_l1` — Level-1 category name in the PDD standard category hierarchy; it is an open upstream value and may be missing. / 拼多多标准类目体系中的一级类目名称；这是上游开放值，可能为空。 (dimension; aggregate-select; group-by; sort; search; aggregate-filter=contains,eq,in,neq,not_in)
- `category_l2` — Level-2 category name in the PDD standard category hierarchy; it is an open upstream value and may be missing. / 拼多多标准类目体系中的二级类目名称；这是上游开放值，可能为空。 (dimension; aggregate-select; group-by; sort; search; aggregate-filter=contains,eq,in,neq,not_in)
- `category_l3` — Level-3 category name in the PDD standard category hierarchy; it is an open upstream value and may be missing. / 拼多多标准类目体系中的三级类目名称；这是上游开放值，可能为空。 (dimension; aggregate-select; group-by; sort; search; aggregate-filter=contains,eq,in,neq,not_in)
- `month` — Calendar month to which the PDD product sales record belongs, formatted as YYYY-MM; the public dataset grain is monthly. / 拼多多商品销售记录所属自然月，格式为 YYYY-MM；公开数据集按月粒度提供。 (time; detail-return; aggregate-select; group-by; sort; detail-filter=contains,eq,in,neq,not_in)
- `billion_subsidy_tag` — Flag indicating whether the record is associated with PDD's billion-subsidy program; upstream values remain open and are not a closed enum. / 标记记录是否关联拼多多百亿补贴计划；上游取值保持开放，不声明为固定枚举。 (dimension; detail-return; aggregate-select; group-by; sort; search; aggregate-filter=contains,eq,in,neq,not_in; detail-filter=contains,eq,in,neq,not_in)
- `ori_category_l1` — Original level-1 category value supplied by the PDD upstream source; use it for crosswalks rather than assuming it matches the standard category. / 拼多多上游提供的原始一级类目值，用于类目对照，不应假定它与标准类目一致。 (dimension; aggregate-select; group-by; sort; search; aggregate-filter=contains,eq,in,neq,not_in)
- `ori_category_l2` — Original level-2 category value supplied by the PDD upstream source; use it for crosswalks rather than assuming it matches the standard category. / 拼多多上游提供的原始二级类目值，用于类目对照，不应假定它与标准类目一致。 (dimension; aggregate-select; group-by; sort; search; aggregate-filter=contains,eq,in,neq,not_in)
- `ori_category_l3` — Original level-3 category value supplied by the PDD upstream source; use it for crosswalks rather than assuming it matches the standard category. / 拼多多上游提供的原始三级类目值，用于类目对照，不应假定它与标准类目一致。 (dimension; aggregate-select; group-by; sort; search; aggregate-filter=contains,eq,in,neq,not_in)
- `gmv` — Post-subsidy gross merchandise value calculated as SUM(discount_sales); it is the primary comparable sales amount for this PDD release. / 补贴后商品交易总额，按 SUM(discount_sales) 计算；是本 PDD 版本用于比较的主要销售额口径。 (measure; aggregate-select; sort; certified)
- `units` — Monthly units sold calculated as SUM(count), where count comes from the upstream monthly volume rather than cumulative total_volume. / 月销量按 SUM(count) 计算，其中 count 来自上游月度 volume，不是累计 total_volume。 (measure; aggregate-select; sort; certified)
- `asp` — Weighted average post-subsidy selling price calculated from SUM(discount_sales) divided by SUM(count), with zero-count protection. / 补贴后加权平均成交价，按 SUM(discount_sales) 除以 SUM(count) 计算，并对销量为零做保护。 (measure; aggregate-select; sort; certified)
- `platform` — Constant platform marker identifying these rows as PDD data; it is supplied by the canonical import projection and is not an upstream business field. / 标识这些记录属于拼多多数据的平台常量，由规范导入投影补充，并非上游业务字段。 (attribute; detail-return; detail-filter=contains,eq,in,neq,not_in)
- `price` — Listed product price reported by the PDD source; it is a row-level numeric detail field and is not a monthly sales metric. / 拼多多源数据报告的商品挂牌价格，是行级数值明细字段，不是月度销售指标。 (measure; detail-return; detail-filter=eq,gt,gte,in,lt,lte,neq,not_in)
- `count` — Monthly incremental units from the upstream volume field; do not interpret it as the historical cumulative total_volume value. / 来自上游 volume 字段的月度增量销量；不要将其解释为历史累计 total_volume。 (measure; detail-return; detail-filter=eq,gt,gte,in,lt,lte,neq,not_in)
- `sales` — Listed-price sales amount derived from the upstream value field; it is retained beside post-subsidy sales for transparent comparison. / 由上游 value 字段提供的挂牌价销售额，与补贴后销售额并列保留以便透明比较。 (measure; detail-return; detail-filter=eq,gt,gte,in,lt,lte,neq,not_in)
- `brand_name` — Raw brand-name column from the PDD source; the canonical brand field is projected from this value and it can be empty. / 拼多多源数据中的原始品牌名称列，规范 brand 字段由此投影而来，且该值可能为空。 (attribute; detail-return; detail-filter=contains,eq,in,neq,not_in)
- `shop_name` — Raw shop-name column from the PDD source; the canonical shop field is projected from this value and names may change. / 拼多多源数据中的原始店铺名称列，规范 shop 字段由此投影而来，名称可能变化。 (attribute; detail-return; detail-filter=contains,eq,in,neq,not_in)
- `tech_date` — Upstream technical date-like value retained for detail inspection; it is not the sales month and must not drive time analysis. / 保留用于明细核查的上游技术日期样式字段；它不是销售月份，不得用于时间分析。 (attribute; detail-return; detail-filter=contains,eq,in,neq,not_in)
- `category_1` — Raw level-1 category-name column from the PDD source, renamed to category_l1 in the public semantic contract. / 拼多多源数据中的原始一级类目名称列，在公开语义契约中改名为 category_l1。 (attribute; detail-return; detail-filter=contains,eq,in,neq,not_in)
- `category_2` — Raw level-2 category-name column from the PDD source, renamed to category_l2 in the public semantic contract. / 拼多多源数据中的原始二级类目名称列，在公开语义契约中改名为 category_l2。 (attribute; detail-return; detail-filter=contains,eq,in,neq,not_in)
- `category_3` — Raw level-3 category-name column from the PDD source, renamed to category_l3 in the public semantic contract. / 拼多多源数据中的原始三级类目名称列，在公开语义契约中改名为 category_l3。 (attribute; detail-return; detail-filter=contains,eq,in,neq,not_in)
- `total_volume` — Historical cumulative units reported by the PDD source; it is retained for detail output and must not be used as monthly units. / 拼多多源数据报告的历史累计销量，保留用于明细输出，不得当作月销量使用。 (measure; detail-return; detail-filter=eq,gt,gte,in,lt,lte,neq,not_in)
- `total_comment_count` — Historical cumulative comment count reported by the PDD source; it is a detail field and not a monthly review increment. / 拼多多源数据报告的历史累计评价数，是明细字段，不是月度评价增量。 (measure; detail-return; detail-filter=eq,gt,gte,in,lt,lte,neq,not_in)
- `estimate_flag` — Upstream flag indicating that a source value may be estimated; it is disclosed in detail output but is not exposed as a filter dimension in this release. / 上游用于标记数值可能为估算值的字段，在明细中披露，但本版本不开放为筛选维度。 (attribute; detail-return; detail-filter=contains,eq,in,neq,not_in)
- `discount_sales` — Post-subsidy sales amount supplied by the PDD source; it is the physical input used by the public gmv metric. / 拼多多源数据提供的补贴后销售额，是公开 gmv 指标使用的物理输入字段。 (measure; detail-return; detail-filter=eq,gt,gte,in,lt,lte,neq,not_in)
- `ori_category_1` — Raw upstream level-1 category value retained for detail output and category crosswalk analysis; it is distinct from category_1. / 保留用于明细输出和类目对照分析的上游原始一级类目值，与 category_1 不同。 (attribute; detail-return; detail-filter=contains,eq,in,neq,not_in)
- `ori_category_2` — Raw upstream level-2 category value retained for detail output and category crosswalk analysis; it is distinct from category_2. / 保留用于明细输出和类目对照分析的上游原始二级类目值，与 category_2 不同。 (attribute; detail-return; detail-filter=contains,eq,in,neq,not_in)
- `ori_category_3` — Raw upstream level-3 category value retained for detail output and category crosswalk analysis; it is distinct from category_3. / 保留用于明细输出和类目对照分析的上游原始三级类目值，与 category_3 不同。 (attribute; detail-return; detail-filter=contains,eq,in,neq,not_in)
- `product_intro` — Product introduction text supplied by the PDD source; it is retained for detail output but is not treated as a structured specification. / 拼多多源数据提供的商品简介文本，保留用于明细输出，但不作为结构化商品规格。 (attribute; detail-return; detail-filter=contains,eq,in,neq,not_in)

## Query Patterns / 查询模式

- [`aggregate_drilldown`](https://docs.asklearai.com/capabilities/pdd/tasks/aggregate_drilldown) — Query a category scope, then rank products under the same filters. / 先查询品类汇总，再在相同筛选条件下对商品排名。
- [`brand_share`](https://docs.asklearai.com/capabilities/pdd/tasks/brand_share) — Compute brand share from two atomic GMV results. / 通过两个原子销售额结果计算品牌份额。
- [`brand_trend`](https://docs.asklearai.com/capabilities/pdd/tasks/brand_trend) — Query monthly atomic metrics for one exact brand. / 查询一个精确品牌的月度原子指标。
- [`category_product_ranking`](https://docs.asklearai.com/capabilities/pdd/tasks/category_product_ranking) — Rank exact product IDs within a resolved category. / 在已对齐的品类内对商品 ID 排名。
- [`cross_period_products`](https://docs.asklearai.com/capabilities/pdd/tasks/cross_period_products) — Compare product-ID sets returned by one bundled period call. / 比较一次组合调用返回的两个期间商品 ID 集合。
- [`product_comparison`](https://docs.asklearai.com/capabilities/pdd/tasks/product_comparison) — Compare multiple exact PDD product references over one time range. / 在同一时间范围内比较多个精确拼多多商品引用。
- [`product_contribution`](https://docs.asklearai.com/capabilities/pdd/tasks/product_contribution) — Attribute cross-period GMV change from two product-level atomic queries. / 通过两次商品级原子查询归因跨期销售额变化。
- [`product_performance`](https://docs.asklearai.com/capabilities/pdd/tasks/product_performance) — Query monthly sales metrics for one exact PDD product reference. / 查询一个精确拼多多商品引用的月度销售指标。
- [`raw_category_crosswalk`](https://docs.asklearai.com/capabilities/pdd/tasks/raw_category_crosswalk) — Compare standardized and upstream raw category values. / 对照标准类目与上游原始类目。
- [`shop_name_performance`](https://docs.asklearai.com/capabilities/pdd/tasks/shop_name_performance) — Resolve a shop name and query monthly metrics. / 对齐店铺名并查询月度指标。
- [`shop_performance`](https://docs.asklearai.com/capabilities/pdd/tasks/shop_performance) — Query monthly metrics for one exact PDD shop ID. / 按精确拼多多店铺 ID 查询月度指标。
- [`subsidy_comparison`](https://docs.asklearai.com/capabilities/pdd/tasks/subsidy_comparison) — Compare PDD metrics by the upstream subsidy flag. / 按上游百亿补贴标记比较拼多多销售指标。

## Limitations / 限制

- Monthly grain only / 仅支持月粒度数据
- Product filters accept an exact product_id or a canonical mobile.yangkeduo.com product URL; results may return titles, but lookup by name, alias, fuzzy term, or short link is unsupported / 商品筛选仅支持精确 product_id 或标准 mobile.yangkeduo.com 商品链接;结果可返回标题,但不支持按名称、别名、模糊词或短链查找商品
- Shops accept an exact shop_id or a shop name aligned through search_values; upstream publishes no shop URL / 店铺可使用精确 shop_id 或经 search_values 对齐后的店铺名;上游未提供店铺链接
- gmv is the post-subsidy sales amount (upstream value_after_subsidy); the list-price amount is kept in the sales detail field / gmv 为补贴后销售额(上游 value_after_subsidy);挂牌价销售额保留在明细字段 sales 中,两者仅对百亿补贴商品不同
- About 7.3% of rows are marked by upstream as estimates (detail field estimate_flag) and are included in the metrics; that field is not offered as a filter in this release / 约 7.3% 的行由上游标记为估算值(明细字段 estimate_flag),已计入指标;该字段本版不开放为筛选维度
- The total_volume and total_comment_count detail fields are running totals, not monthly values, and must not be mixed with units / 明细字段 total_volume 与 total_comment_count 是历史累计值,不是当月值,不可与 units 混用
- The tech_date detail field is an upstream bookkeeping field, not a sale date, and cannot be used for time analysis / 明细字段 tech_date 是上游技术字段,不是销售日期,不可用于时间分析
- brand_name is frequently empty (about 85% for 2026-06); brand rankings drop the empty value / brand_name 空值比例较高(2026-06 约 85%),品牌榜单会剔除空值
- No review, traffic, inventory, causal explanation, or other-platform data is provided / 不提供评价、流量、库存、因果解释或其他平台数据
- Year-over-year, period-over-period, share, contribution, and cross-period set differences are computed by the agent from atomic query results / 同比、环比、份额、贡献度和跨期集合差异由 Agent 基于原子查询结果计算