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

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

# Brand share / 品牌份额

Compute a brand's share from two atomic GMV results returned by one bundled call. / 通过一次组合调用返回的两个原子销售额结果计算品牌份额。

## Required inputs / 必要输入

- `brand` — `search_values`; required (`brand`): Exact brand value
  精确品牌值
- `scope` — `search_values`; required (`category_l3`): Exact category scope
  精确品类范围
- `time` — `user_required`; required: Analysis time range
  分析时间范围

## Steps / 步骤

1. `resolve_values` · `search_values` — Resolve brand and category values.
   对齐品牌和品类值。
   - search `brand` with `${brand}`, `category_l3` with `${scope}`
2. `query_brand` · `query_metrics` — Query brand GMV in the selected scope.
   查询所选范围内的品牌销售额。
   - bundle: `share_inputs` (one `query_metrics` call)
   - metrics: `gmv`
   - filters: `brand eq ${brand}`, `category_l3 eq ${scope}`
   - time: `${time}`
3. `query_scope` · `query_metrics` — Query total GMV in the same scope.
   查询相同范围内的总销售额。
   - bundle: `share_inputs` (one `query_metrics` call)
   - metrics: `gmv`
   - filters: `category_l3 eq ${scope}`
   - time: `${time}`

## Call example / 调用示例

Replace the example values with exact user inputs or values returned by `search_values`. / 将示例值替换为用户的精确输入或 `search_values` 返回的平台原始值。

`search_values`

```json
{
  "task_query": "使用 tmall 数据执行品牌份额；brand=示例品牌，scope=示例品类，time={\"last_complete_months\":3}",
  "dataset": "tmall",
  "field": "brand",
  "kw": "示例品牌",
  "limit": 10,
  "additional_searches": [
    {
      "name": "search_category_l3",
      "field": "category_l3",
      "kw": "示例品类",
      "limit": 10
    }
  ]
}
```

`query_metrics`

```json
{
  "metrics": [
    "gmv"
  ],
  "time": {
    "last_complete_months": 3
  },
  "filters": [
    {
      "field": "brand",
      "op": "eq",
      "value": "示例品牌"
    },
    {
      "field": "category_l3",
      "op": "eq",
      "value": "示例品类"
    }
  ],
  "task_query": "使用 tmall 数据执行品牌份额；brand=示例品牌，scope=示例品类，time={\"last_complete_months\":3}",
  "dataset": "tmall",
  "main_query_name": "query_brand",
  "additional_queries": [
    {
      "name": "query_scope",
      "metrics": [
        "gmv"
      ],
      "time": {
        "last_complete_months": 3
      },
      "filters": [
        {
          "field": "category_l3",
          "op": "eq",
          "value": "示例品类"
        }
      ]
    }
  ]
}
```


## Agent computation / Agent 计算

- `compute_share` · `ratio` from `query_brand`, `query_scope` — Divide brand GMV by total scope GMV.
  用品牌销售额除以范围总销售额。

## Output requirements / 输出要求

- Show numerator, denominator, and percentage.
  展示分子、分母和百分比。

## Limitations / 限制

- The numerator and denominator must use identical time and scope.
  分子与分母必须使用相同时间和范围。

## Stop conditions / 停止条件

- Stop if the denominator is zero or values are ambiguous.
  分母为零或取值有歧义时停止。