---
document_id: agent.cookbook.sales_analysis
schema_version: 2
parent_document_id: agent.cookbook
section: cookbook
---

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

# E-commerce sales queries and analysis / 电商销量查询与分析

Query monthly sales volume and revenue in Tmall (tmall), JD (jd), Douyin Commerce (douyin), and PDD (pdd) sales tables. Supports single-platform and multi-platform totals, rankings, and trends. / 仅用于天猫（tmall）、京东（jd）、抖音商城（douyin）、拼多多（pdd）的月度销量明细表，查询单平台或多平台的销量、销售额、排行和趋势。

## Business questions / 商业问题

- What are this brand's sales volume and revenue this year?
  这个品牌今年的销量和销售额是多少？
- How does this brand or category sell across Tmall, JD, Douyin Commerce, and PDD?
  这个品牌或品类在天猫、京东、抖音商城、拼多多分别卖得怎么样？
- Which products sold the most in the selected month?
  这个月销量最高的商品有哪些？
- How have this brand's sales changed over recent months?
  这个品牌最近几个月卖得怎么样？
- I want to develop an airplane blanket. Which related products have sold well over the last year or two?
  想开发飞机毯，最近一两年哪些相关产品卖得好？

## Approach / 方法

1. Clarify the question. Reuse the stated subject, platforms, period, and metrics. Query directly when clear; ask only when ambiguity changes the query. For exploratory goals such as finding what sells well, first identify a workable product scope.
   确认问题。沿用已有对象、平台、时间和指标，明确就直接查；只有歧义会改变查询时才追问。“看看什么卖得好”等探索问题，先确定商品范围。
2. Choose platforms. Use the requested tables among tmall, jd, douyin, and pdd. For a multi-platform or unspecified domestic-platform request, check coverage and access across these four, state which can be queried, and query them separately. Do not silently reduce it to one platform or extend it to other sources.
   选择平台。按用户要求选择 tmall、jd、douyin、pdd。用户问多平台或泛指国内电商时，检查四张表的覆盖与权限，说明可查哪些，再分别查询；不擅自缩成单平台，也不扩展到其他来源。
3. Resolve subjects on each platform. Use search_values for brands, shops, and categories, available search_products for product names, and reuse exact references. Check Chinese, English, and common mixed brand spellings; use eq or in with confirmed raw values and never silently enlarge the brand scope. For terms such as airplane blanket, inspect related categories and a few products to define the scope. Resolve each platform separately; never copy category values or product IDs between platforms.
   逐平台对齐对象。品牌、店铺、品类用 search_values，商品名称用可用的 search_products，精确引用直接复用。品牌检索兼顾中文、英文和常见混写，已确认的原始值用 eq 或 in，不自动扩大品牌范围。“飞机毯”等业务词先找相关类目和少量商品，说明取数范围。各平台分别对齐，不能复制类目值或商品 ID。
4. Align time. Keep the requested period; recent monthly requests use last_complete_months. For a simple lookup without a period, state the latest complete month being used. Check data_through for each platform. Compare common covered months, or keep differing periods separate; do not silently shorten the request or treat missing months as zero or a partial year as a full year.
   对齐时间。保留指定时期，近期月度问题用 last_complete_months；简单查数未给时间时，可说明后采用最近完整月。逐平台核实 data_through，比较时取共同覆盖月份，或将不同时期分开展示；不静默缩短用户范围，不把缺月当零或把部分年份当全年。
5. For Tmall/JD brand queries, verify official Chinese and English names using reliable official sources; retain source URLs and verification date, and mark an unverified counterpart rather than inventing a translation. Search both names and known variants, preserving every distinct raw value and available ID, including case, mixed spelling, punctuation and historical variants. Separate sub-brands, collaborations, generic short terms and unrelated matches. Present numbered candidates by platform with relationship notes and optional period product counts/GMV; ask the user which values to include, reusing applicable earlier confirmation. Mark truncated or sampled candidates as incomplete. No match does not prove no sales.
   天猫/京东品牌查询：优先通过品牌官网等可靠官方来源核实中英文名称，保留来源链接与核实日期；没有可靠对应名就标为未核实，不自行翻译。检索两种名称及已知变体，保留每个不同原始值及实际可用 ID，覆盖大小写、中英混写、标点和历史写法。子品牌、联名、通用短词和疑似无关项单列。按平台展示编号候选、关系说明和可选的期间商品量/销售额，让用户选择；已有且适用的确认直接复用。截断或样本候选标为不完整，无匹配不等于无销售。
6. After brand confirmation, discover related flagship stores using both names and resolve platform plus shop ID, current/historical names and official-identity evidence. A name containing official or flagship is a lead, not proof of ownership throughout the requested period. Under identical platform, period, category and validity conditions, B is the confirmed brand record set and S is each candidate store's full record set without a brand prefilter; I = S \ B. Present the store total, brand-covered total, incremental products and GMV, both product and GMV increment shares, and representative product IDs/titles with their raw brand values when retrievable. Disclose other-brand, collaboration, bundle and unresolved attribution. Ask whether to keep the brand scope, add selected full stores, or add stores with explicit exclusions. Full-store inclusion needs acceptance of mixed-brand inventory; with no increment, say the selected brand values already cover that store in the available scope.
   品牌确认后，用中英文名找相关旗舰店，按平台+店铺ID定位，展示当前/历史店名及官方身份依据。店名含“官方”“旗舰”只是线索，不能证明整个期间的归属。相同平台、期间、类目及有效记录条件下，B 是已确认品牌记录，S 是各候选店铺全部记录，不先加品牌条件；I = S \ B。展示店铺总量、品牌已覆盖量、增量商品量及销售额、商品和金额的增量占比，以及可取得的代表商品 ID/标题和原始品牌值。其他品牌、联名、套装及未核实归属要说明。让用户选择维持品牌范围、补指定全店或带明确排除条件补；全店可能混入其他品牌，需要用户接受。无增量则说明当前可用范围内已覆盖，不强行扩圈。
7. Use only supported contracts for this comparison. If search_values rejects a physical scan as too broad, follow its hint: query one authorized month with contains and group by that field, with a credit cap. Structured contains need not share dictionary case folding; search observed case variants separately. One month does not exhaust a longer requested period. For counts, obtain complete identity sets at the verified grain using supported queries and demonstrably disjoint batches; monthly product keys include platform/product ID and shop keys include platform/shop ID. Distinguish products present in incremental records from entirely new products: one product can occur in both record sets. Never substitute units, dictionary rows, Top N, or truncated samples for exact counts. Missing brand values can be omitted by grouping under the current contract: compare to an ungrouped store total, flag an unreconciled difference, and do not label it target-brand sales or silently lose it via not_in (NULL handling differs). If exact counts or raw-brand examples remain unavailable within the authorized scope, show that limitation and stop those claims; do not invent a count or export automatically.
   对比只用实际支持的契约。search_values 因物理扫描超限被拒时，按提示在授权单月内用 contains 并按该字段分组，设置费用上限；结构化 contains 不一定像词表搜索一样忽略大小写，应分别查实际变体。单月候选不能声称穷尽更长期间。计数须依据已核实粒度，用受支持查询和可证明不重叠的分批取得完整身份集合；月内商品键含平台+商品ID，店铺键含平台+店铺ID。增量记录中的商品量与全新商品量要区分，同一商品可能在两个记录集合中均出现。不能拿销量、词表行数、Top N 或截断样本代替精确计数。当前契约的品牌分组可能省略缺失值，应与不按品牌分组的店铺总额核对；未对平差额标为待核实，不归入目标品牌，也不直接用 not_in 代替补漏（NULL 语义不同）。授权范围内无法取得精确计数或原始品牌样例时，明确限制并停止相应结论，不编数字、不自动导出。
8. Choose the query shape. Use query_metrics for totals; group by month for trends; sort by the requested metric for rankings. If field or metric names are unclear, read that dataset's definitions once instead of probing invented names; reuse applicable known definitions. Add supported dimensions only when needed. Request sales volume or revenue as asked, not every metric or product detail. Suggest supporting metrics without querying them by default.
   组织查询。用 query_metrics 查总量；趋势按月分组；排行按所需指标排序。字段或指标名不明时按需读取一次该数据集词表，不试探虚构名称；已知且适用的词表直接复用。需要时才增加支持的维度，只取用户要求的销量、销售额等指标，不默认全取或补商品详情。可提醒辅助指标的用途，但不默认增加查询。
9. After store-scope confirmation, restate platform, period, category, exact brand values/usable IDs, selected shop IDs, exclusions, grain and metric definition. Reuse unchanged confirmation. Common conditions constrain every branch; store-specific exclusions affect only the store branch. Union selected stores first, then use B + S - (B ∩ S) for additive GMV/units and S - (B ∩ S) for incremental contribution; never sum overlapping store totals. For distinct counts use identity-set unions/differences rather than subtracting counts of record intersections. Suggest monthly distinct shops/products, units and weighted ASP only as needed; ASP is total GMV / total units, null at zero units. Preserve the source's SPU/SKU/link grain and amount/refund definitions; cross-platform counts are platform listings, not unique real-world products. Return brand contribution, confirmed store increment and union total, with zero-denominator shares null. Coverage describes only the checked stores, never the whole market.
   店铺范围确认后，回显平台、期间、类目、品牌精确原始值/可用ID、店铺ID、排除条件、粒度和指标定义；未变条件复用确认。公共条件约束所有分支，店铺专属排除只作用于店铺分支。多个已选店铺先做并集，金额/销量按 B + S - (B ∩ S) 合计，补充贡献按 S - (B ∩ S) 计算，不直接相加重叠店铺总额。去重计数用身份集合并差，不能减去记录交集的去重数量。按需建议月度去重店铺量/商品量、销量和加权均价；均价用总额/总销量，零销量为空。遵守源数据 SPU/SKU/链接粒度及金额、退款口径；跨平台商品量是平台商品链接量，不是现实商品去重数。展示品牌贡献、已确认店铺增量和并集合计，比例零分母为空；覆盖比例仅指已检查店铺，不代表全市场。
10. When new brand values, shops or exclusions change scope, show the impact, obtain confirmation for the change, and recompute the entire comparison period with one fixed rule; label the scope version in the result/query record rather than building a new versioning service. Do not enlarge only recent months and report artificial growth. Deliver the current stage only: name evidence and candidates, store comparisons and choices, or confirmed monthly results. Keep reproducible queries or query files, resolved conditions, query IDs, data_through, charged_credits and upper_bound_credits when returned. Mark unresolved attribution, incomplete counts, missing/partial months and source limitations. Explain changes with supported associations, not invented causality.
   新增品牌值、店铺或排除条件改变范围时，先展示影响并确认变更，再按统一规则对整个比较期间重算，在结果/查询记录标明口径版本即可，不新建版本服务。不能只扩大新月份造成虚假增长。分阶段交付名称依据及候选、店铺对比及选择，或已确认月度结果；保留可复现查询或查询文件、实际条件、query_id、data_through 及返回的 charged_credits/upper_bound_credits。标明未核实归属、计数不完整、缺月/部分月和来源限制；变化解释只说数据支持的关联。
11. Compare platforms. Query each table separately and organize results by platform on the client. Compare only after checking metric definitions, months, and product scope; sum with code only when they align, and name the included platforms. Shares need matching numerator and denominator scopes. Keep incompatible results separate and mark unavailable platforms as gaps.
   跨平台比较。各表独立查询，在客户端按平台整理。先核对指标口径、月份和商品范围，再比较；一致时才用程序合计，并注明包含的平台。份额的分子、分母须同范围；不可比的分别保留，查不到的平台标为缺口。
12. Check completeness before more analysis. Deduplicate overlapping query results at the verified fact grain, preserving distinct platform, month, shop and brand records rather than collapsing them by product ID alone. Count products separately with platform/product identity. For truncated results, retrieve more under the contract or narrow the scope before totaling, stating the remaining gap. Add a query only for a concrete gap or question, such as which products drove growth. Reuse results and stop when sufficient; follow the query guide for budget and approval rules.
   按缺口补查。重叠查询结果依已核实的事实粒度去重，保留不同平台、月份、店铺及品牌记录，不能只按商品 ID 混并；商品量另用平台+商品身份计数。结果截断就按契约补取或收窄后再汇总，并说明剩余缺口。只有需要解释增长来源等具体问题时才下钻；复用结果，够用就停，预算和审批按查询指南。

## Boundaries / 边界

- This method excludes Amazon and other overseas sources, live product collection, reviews, and social content. Use capability discovery and the relevant guide for those tasks; their data cannot replace these monthly sales tables.
  本方法不适用于 Amazon 等海外来源、实时商品采集、评论或社媒数据。这些任务另走能力发现与相应指南，不能替代四张月度销量表。
- Tmall/JD flagship-store supplementation requires a separately confirmed store scope; never silently add full-store inventory. Candidate discovery is exploratory, not a final brand total. Do not extend this store-supplement workflow to Douyin/PDD without checking their contracts and agreeing on scope. Business terms need not be platform categories. A keyword-matched set, Top N, or a selected product sample is not the whole market. A total across the queried platforms is not an all-channel total.
  天猫/京东旗舰店补充需要单独确认店铺范围，不擅自补入全店商品；候选发现属于探索，不是最终品牌总量。抖音/拼多多不直接套用本补充流程，需另核实契约并确认范围。业务词不一定是平台类目；关键词集合、Top N 或筛选样本不等于全市场。已查平台的合计也不等于全网销量。
- Use code or fixed formulas for totals, growth, and shares. One month does not establish a trend, concurrent changes do not establish causality, and average transaction price changes do not prove same-product price changes.
  汇总、增长和份额用程序或固定公式计算。单月不能证明趋势，同步变化不能证明因果，成交均价变化不能直接证明同款涨跌价。
