搜索API对接指南-01-搜索接口.md 29.3 KB
Edit Raw Blame History


搜索API对接指南-01-搜索接口（POST /search/ 与响应）
本篇以 POST /search/ 为主线，包含：


请求参数：3.2、过滤器：3.3、分面：3.4、SKU筛选维度：3.5
响应格式：第 4 章（4.1~4.5）
常见场景示例：第 8 章（示例整体并入本篇，避免散落）

搜索接口
3.1 接口信息

端点: POST /search/
描述: 执行文本搜索查询，支持多语言、过滤器和分面搜索
租户标识：tenant_id 通过 HTTP 请求头 X-Tenant-ID 传递（推荐）；也可通过 URL query 参数 tenant_id 传递。不要放在请求体中。


请求示例（推荐）:
url = f"{base_url.rstrip('/')}/search/"
headers = {
    "Content-Type": "application/json",
    "X-Tenant-ID": "162",  # 租户ID，必填
}
response = requests.post(url, headers=headers, json={"query": "芭比娃娃"})


cURL 示例（复制即可试）

将 BASE_URL、TENANT_ID 换成你的环境与租户。本地开发默认后端为 http://localhost:6002（见 scripts/start_backend.sh）。
export BASE_URL="${BASE_URL:-http://localhost:6002}"
export TENANT_ID="${TENANT_ID:-162}"   # 改成真实租户


1）基础检索：关键词、分页、language 控制返回字段语言。
curl -sS "$BASE_URL/search/" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -d '{
    "query": "芭比娃娃",
    "size": 20,
    "from": 0,
    "language": "zh"
  }'


2）过滤 + 价格区间 + 分面 + 排序：联调最常见组合（品牌 OR、min_price 区间、类目与颜色分面、按最低价升序）。
curl -sS "$BASE_URL/search/" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -d '{
    "query": "手机",
    "size": 20,
    "from": 0,
    "language": "zh",
    "filters": {
      "vendor.zh.keyword": ["品牌A", "品牌B"]
    },
    "range_filters": {
      "min_price": {"gte": 50, "lte": 200}
    },
    "facets": [
      {"field": "category1_name", "size": 15, "type": "terms"},
      {"field": "specifications.color", "size": 20, "type": "terms"}
    ],
    "sort_by": "min_price",
    "sort_order": "asc"
  }'


3）规格过滤 + SKU 维度 + 调试：specifications 嵌套过滤、sku_filter_dimension 每组只保留一个 SKU；debug: true 便于对照 ES 与解析结果。
curl -sS "$BASE_URL/search/" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -d '{
    "query": "手机",
    "size": 10,
    "from": 0,
    "language": "zh",
    "filters": {
      "specifications": {"name": "color", "value": "white"}
    },
    "sku_filter_dimension": ["color"],
    "debug": true
  }'


需要美化 JSON 输出时，在命令末尾追加 | jq .（需本机安装 jq）。
3.2 请求参数
完整请求体结构
{
  "query": "string (required)",
  "size": 10,
  "from": 0,
  "language": "zh",
  "filters": {},
  "range_filters": {},
  "facets": [],
  "sort_by": "string",
  "sort_order": "desc",
  "min_score": 0.0,
  "sku_filter_dimension": ["string"],
  "debug": false,
  "enable_rerank": null,
  "rerank_query_template": "{query}",
  "rerank_doc_template": "{title}",
  "user_id": "string",
  "session_id": "string"
}

参数详细说明


参数
类型
必填
默认值
说明


query
string
Y
-
搜索查询字符串（统一文本检索策略）


size
integer
N
10
返回结果数量（1-100）


from
integer
N
0
分页偏移量（用于分页）


language
string
N
"zh"
返回语言：zh（中文）或 en（英文）。后端会根据此参数选择对应的中英文字段返回


filters
object
N
null
精确匹配过滤器（见过滤器详解）


range_filters
object
N
null
数值范围过滤器（见过滤器详解）


facets
array
N
null
分面配置（见分面配置）


sort_by
string
N
null
排序字段名。支持：price（价格）、sales（销量）、create_time（创建时间）、update_time（更新时间）。默认按相关性排序


sort_order
string
N
"desc"
排序方向：asc（升序）或 desc（降序）。注意：price+asc=价格从低到高，price+desc=价格从高到低（后端自动映射为min_price或max_price）


min_score
float
N
null
最小相关性分数阈值


sku_filter_dimension
array[string]
N
null
子SKU筛选维度列表（见SKU筛选维度）


debug
boolean
N
false
是否返回调试信息


enable_rerank
boolean/null
N
null
是否开启重排（调用外部重排服务对 ES 结果进行二次排序）。不传/传 null 使用服务端 rerank.enabled。当有效开启且 from + size <= rerank_window 时：ES 先取前 rerank_window 条，重排后再按 from/size 截取当前页；若 from + size > rerank_window，则不进行窗口内重排，直接按请求的 from/size 查询 ES（rerank_window 见 config.yaml 的 rerank.rerank_window，仓库示例默认 400）


rerank_query_template
string
N
null
重排 query 模板（可选）。支持 {query} 占位符；不传则使用服务端 rerank.rerank_query_template


rerank_doc_template
string
N
null
重排 doc 模板（可选）。支持 {title} {brief} {vendor} {description} {category_path} 等占位符（由 search/rerank_client.py 按语言字段拼装）；不传则使用服务端 rerank.rerank_doc_template


与后端代码的对应关系（便于联调）：HTTP POST /search/ 请求体由 api/models.py 的 SearchRequest 校验；路由 api/routes/search.py 将字段原样传入 Searcher.search(...)（含上述三个重排相关字段）。CLI python main.py search 目前未暴露这些参数，走配置默认值。
| user_id | string | N | null | 用户ID（用于个性化，预留） |
| session_id | string | N | null | 会话ID（用于分析，预留） |
3.3 过滤器详解
3.3.1 精确匹配过滤器 (filters)
用于精确匹配或多值匹配。对于普通字段，数组表示 OR 逻辑（匹配任意一个值）；对于 specifications 字段，按维度分组处理。任意字段名加 _all 后缀表示多值 AND 逻辑（必须同时匹配所有值）。

格式:
{
  "filters": {
    "category_name": "手机",                      // 可以为单值 或者 数组 匹配数组中任意一个（OR）
    "category1_name": "服装",                    // 可以为单值 或者 数组 匹配数组中任意一个（OR）
    "category2_name": "男装",                    // 可以为单值 或者 数组 匹配数组中任意一个（OR）
    "category3_name": "衬衫",                    // 可以为单值 或者 数组 匹配数组中任意一个（OR）
    "vendor.zh.keyword": ["奇乐", "品牌A"],      // 可以为单值 或者 数组 匹配数组中任意一个（OR）
    "tags": "手机",                              // 可以为单值 或者 数组 匹配数组中任意一个（OR）
    "tags_all": ["手机", "促销", "新品"],        // *_all：多值为 AND，必须同时包含所有标签
    "category1_name_all": ["服装", "男装"],     // 同上，适用于任意可过滤字段
    // specifications 嵌套过滤（特殊格式）
    "specifications": {
      "name": "color",
      "value": "white"
    }
  }
}


支持的值类型:


字符串：精确匹配
整数：精确匹配
布尔值：精确匹配
数组：匹配任意值（OR 逻辑）；若字段名以 _all 结尾，则数组表示 AND 逻辑（必须同时匹配所有值）
对象：specifications 嵌套过滤（见下文）


*_all 语义（多值 AND）:


任意过滤字段均可使用 _all 后缀，对应 ES 字段名为去掉 _all 后的名称。
例如：tags_all: ["A", "B"] 表示文档的 tags 必须同时包含 A 和 B；vendor.zh.keyword_all: ["奇乐", "品牌A"] 表示同时匹配两个品牌（通常用于 keyword 多值场景）。
specifications_all：传列表 [{"name":"color","value":"white"},{"name":"size","value":"256GB"}] 时，表示所有列出的规格条件都要满足（与 specifications 多维度时的 AND 一致；若同维度多值则要求文档同时满足多个值，一般用于嵌套多值场景）。


Specifications 嵌套过滤:

specifications 是嵌套字段，支持按规格名称和值进行过滤。

单个规格过滤:
{
  "filters": {
    "specifications": {
      "name": "color",
      "value": "white"
    }
  }
}


查询规格名称为"color"且值为"white"的商品。

多个规格过滤（按维度分组）:
{
  "filters": {
    "specifications": [
      {"name": "color", "value": "white"},
      {"name": "size", "value": "256GB"}
    ]
  }
}


查询同时满足所有规格的商品（color=white 且 size=256GB）。

相同维度的多个值（OR 逻辑）:
{
  "filters": {
    "specifications": [
      {"name": "size", "value": "3"},
      {"name": "size", "value": "4"},
      {"name": "size", "value": "5"},
      {"name": "color", "value": "green"}
    ]
  }
}


查询满足 (size=3 或 size=4 或 size=5) 且 color=green 的商品。

过滤逻辑说明:


不同维度（不同的 name）之间是 AND 关系（求交集）
相同维度（相同的 name）的多个值之间是 OR 关系（求并集）


常用过滤字段（详见常用字段列表）:


category_name: 类目名称
category1_name, category2_name, category3_name: 多级类目
category_id: 类目ID
vendor.zh.keyword, vendor.en.keyword: 供应商/品牌（使用keyword子字段）
tags: 标签（keyword类型，支持数组）
option1_name, option2_name, option3_name: 选项名称
specifications: 规格过滤（嵌套字段，格式见上文）
以上任意字段均可加 _all 后缀表示多值 AND，如 tags_all、category1_name_all。

3.3.2 范围过滤器 (range_filters)
用于数值字段的范围过滤。

格式:
{
  "range_filters": {
    "min_price": {
      "gte": 50,    // 大于等于
      "lte": 200    // 小于等于
    },
    "max_price": {
      "gt": 100     // 大于
    },
    "create_time": {
      "gte": "2024-01-01T00:00:00Z"  // 日期时间字符串
    }
  }
}


支持的操作符:


gte: 大于等于 (>=)
gt: 大于 (>)
lte: 小于等于 (
lt: 小于 (


注意: 至少需要指定一个操作符。

常用范围字段（详见常用字段列表）:


min_price: 最低价格
max_price: 最高价格
compare_at_price: 原价
create_time: 创建时间
update_time: 更新时间

3.4 分面配置
用于生成分面统计（分组聚合），常用于构建筛选器UI。
3.4.1 配置格式
{
  "facets": [
    {
      "field": "category1_name",
      "size": 15,
      "type": "terms",
      "disjunctive": false
    },
    {
      "field": "brand_name",
      "size": 10,
      "type": "terms",
      "disjunctive": true
    },
    {
      "field": "specifications.color",
      "size": 20,
      "type": "terms",
      "disjunctive": true
    },
    {
      "field": "min_price",
      "type": "range",
      "ranges": [
        {"key": "0-50", "to": 50},
        {"key": "50-100", "from": 50, "to": 100},
        {"key": "100-200", "from": 100, "to": 200},
        {"key": "200+", "from": 200}
      ]
    }
  ]
}

3.4.2 Facet 字段说明


字段
类型
必填
默认值
说明


field
string
是
-
分面字段名


size
int
否
10
返回的分面值数量（1-100）


type
string
否
"terms"
分面类型：terms（词条聚合）或 range（范围聚合）


disjunctive
bool
否
false
是否支持多选（disjunctive faceting）。启用后，选中该分面的过滤器时，仍会显示其他可选项


ranges
array
否
null
范围配置（仅 type="range" 时需要）


3.4.3 disjunctive字段说明
重要特性: disjunctive 字段控制分面的行为模式。启用后，选中该分面的过滤器时，仍会显示其他可选项

标准模式 (disjunctive: false):


行为: 选中某个分面值后，该分面只显示选中的值
适用场景: 层级类目、互斥选择
示例: 类目下钻（玩具 > 娃娃 > 芭比）


Multi-Select 模式 (disjunctive: true) ⭐:


行为: 选中某个分面值后，该分面仍显示所有可选项
适用场景: 颜色、品牌、尺码等可切换属性
示例: 选择了"红色"后，仍能看到"蓝色"、"绿色"等选项


推荐配置:


分面类型
disjunctive
原因


颜色
true
用户需要切换颜色


品牌
true
用户需要比较品牌


尺码
true
用户需要查看其他尺码


类目
false
层级下钻


价格区间
false
互斥选择


3.4.4 规格分面说明
specifications 是嵌套字段，支持两种分面模式：

模式1：所有规格名称的分面:
{
  "facets": [
    {
      "field": "specifications",
      "size": 10,
      "type": "terms"
    }
  ]
}


返回所有规格名称（name）及其对应的值（value）列表。每个 name 会生成一个独立的分面结果。

模式2：指定规格名称的分面:
{
  "facets": [
    {
      "field": "specifications.color",
      "size": 20,
      "type": "terms",
      "disjunctive": true
    },
    {
      "field": "specifications.size",
      "size": 15,
      "type": "terms",
      "disjunctive": true
    }
  ]
}


只返回指定规格名称的值列表。格式：specifications.{name}，其中 {name} 是规格名称（如"color"、"size"、"material"）。

返回格式示例:
{
  "facets": [
    {
      "field": "specifications.color",
      "label": "color",
      "type": "terms",
      "values": [
        {"value": "white", "count": 50, "selected": true},  // ✓ selected 字段由后端标记
        {"value": "black", "count": 30, "selected": false},
        {"value": "red", "count": 20, "selected": false}
      ]
    },
    {
      "field": "specifications.size",
      "label": "size",
      "type": "terms",
      "values": [
        {"value": "256GB", "count": 40, "selected": false},
        {"value": "512GB", "count": 20, "selected": false}
      ]
    }
  ]
}

3.5 SKU筛选维度
功能说明:
sku_filter_dimension 用于控制搜索列表页中 每个 SPU 下方可切换的子款式（子 SKU）维度，为字符串列表。

在店铺的 主题装修配置 中，商家可以为店铺设置一个或多个子款式筛选维度（例如 color、size），前端列表页会在每个 SPU 下展示这些维度对应的子 SKU 列表，用户可以通过点击不同维度值（如不同颜色）来切换展示的子款式。

当指定 sku_filter_dimension 后，后端会根据店铺的这项配置，从所有 SKU 中筛选出这些维度组合对应的子 SKU 数据：系统会按指定维度组合对 SKU 进行分组，每个维度组合只返回第一个 SKU（从简实现，选择该组合下的第一款），其余不在这些维度组合中的子 SKU 将不返回。

支持的维度值:


直接选项字段: option1、option2、option3


直接使用对应的 option1_value、option2_value、option3_value 字段进行分组

规格/选项名称: 通过 option1_name、option2_name、option3_name 匹配


例如：如果 option1_name 为 "color"，则可以使用 sku_filter_dimension: ["color"] 来按颜色分组


示例:

按颜色筛选（假设 option1_name = "color"）:
{
  "query": "芭比娃娃",
  "sku_filter_dimension": ["color"]
}


按选项1筛选:
{
  "query": "芭比娃娃",
  "sku_filter_dimension": ["option1"]
}


按颜色 + 尺寸组合筛选（假设 option1_name = "color", option2_name = "size"）:
{
  "query": "芭比娃娃",
  "sku_filter_dimension": ["color", "size"]
}

响应格式说明
4.1 标准响应结构
{
  "results": [
    {
      "spu_id": "12345",
      "title": "芭比时尚娃娃",
      "brief": "高品质芭比娃娃",
      "description": "详细描述...",
      "vendor": "美泰",
      "category": "玩具",
      "category_path": "玩具/娃娃/时尚",
      "category_name": "时尚",
      "category_id": "cat_001",
      "category_level": 3,
      "category1_name": "玩具",
      "category2_name": "娃娃",
      "category3_name": "时尚",
      "tags": ["娃娃", "玩具", "女孩"],
      "price": 89.99,
      "compare_at_price": 129.99,
      "currency": "USD",
      "image_url": "https://example.com/image.jpg",
      "in_stock": true,
      "sku_prices": [89.99, 99.99, 109.99],
      "sku_weights": [100, 150, 200],
      "sku_weight_units": ["g", "g", "g"],
      "total_inventory": 500,
      "option1_name": "color",
      "option2_name": "size",
      "option3_name": null,
      "specifications": [
        {"sku_id": "sku_001", "name": "color", "value": "pink"},
        {"sku_id": "sku_001", "name": "size", "value": "standard"}
      ],
      "skus": [
        {
          "sku_id": "67890",
          "price": 89.99,
          "compare_at_price": 129.99,
          "sku": "BARBIE-001",
          "stock": 100,
          "weight": 0.1,
          "weight_unit": "kg",
          "option1_value": "pink",
          "option2_value": "standard",
          "option3_value": null,
          "image_src": "https://example.com/sku1.jpg"
        }
      ],
      "relevance_score": 8.5
    }
  ],
  "total": 118,
  "max_score": 8.5,
  "facets": [
    {
      "field": "category1_name",
      "label": "category1_name",
      "type": "terms",
      "values": [
        {
          "value": "玩具",
          "label": "玩具",
          "count": 85,
          "selected": false
        }
      ]
    },
    {
      "field": "specifications.color",
      "label": "color",
      "type": "terms",
      "values": [
        {
          "value": "pink",
          "label": "pink",
          "count": 30,
          "selected": false
        }
      ]
    }
  ],
  "query_info": {
    "original_query": "芭比娃娃",
    "query_normalized": "芭比娃娃",
    "rewritten_query": "芭比娃娃",
    "detected_language": "zh",
    "translations": {
      "en": "barbie doll"
    },
    "domain": "default"
  },
  "suggestions": [],
  "related_searches": [],
  "took_ms": 45,
  "performance_info": null,
  "debug_info": null
}

4.2 响应字段说明


字段
类型
说明


results
array
搜索结果列表（SpuResult对象数组）


results[].spu_id
string
SPU ID


results[].title
string
商品标题


results[].price
float
价格（min_price）


results[].skus
array
SKU列表（如果指定了sku_filter_dimension，则按维度过滤后的SKU）


results[].relevance_score
float
相关性分数


total
integer
匹配的总文档数


max_score
float
最高相关性分数


facets
array
分面统计结果


query_info
object
query处理信息


took_ms
integer
搜索耗时（毫秒）


debug_info
object/null
调试信息，仅当请求传 debug=true 时返回


4.2.1 query_info 说明
query_info 包含本次搜索的查询解析与处理结果：


子字段
类型
说明


original_query
string
用户原始查询


query_normalized
string
归一化后的查询（去空白、大小写等预处理，用于后续解析与改写）


rewritten_query
string
重写后的查询（同义词/词典扩展等）


detected_language
string
检测到的查询语言（如 zh、en）


translations
object
翻译结果，键为语言代码，值为翻译文本


domain
string
查询域（如 default、title、brand 等）


4.2.2 debug_info 说明
debug_info 主要用于检索效果评估、融合打分分析与 bad case 排查。

debug_info.query_analysis 常见字段：


子字段
类型
说明


original_query
string
原始查询


query_normalized
string
归一化后的查询


rewritten_query
string
重写后的查询


detected_language
string
检测到的语言


translations
object
翻译结果


has_vector
boolean
是否生成了向量


debug_info.per_result[] 常见字段：


子字段
类型
说明


spu_id
string
结果 SPU ID


es_score
float
ES 原始 _score


rerank_score
float
重排分数


text_score
float
文本相关性大分（由 base_query / base_query_trans_* 聚合而来）


text_source_score
float
base_query 分数


text_translation_score
float
base_query_trans_* 里的最大分数


text_primary_score
float
文本大分中的主证据部分


text_support_score
float
文本大分中的辅助证据部分


knn_score
float
knn_query 分数


fused_score
float
最终融合分数


matched_queries
object/array
ES named queries 命中详情


4.3 SpuResult字段说明


字段
类型
说明


spu_id
string
SPU ID


title
string
商品标题（根据language参数自动选择 title.zh 或 title.en）


brief
string
商品短描述（根据language参数自动选择）


description
string
商品详细描述（根据language参数自动选择）


vendor
string
供应商/品牌（根据language参数自动选择）


category
string
类目（兼容字段，等同于category_name）


category_path
string
类目路径（多级，用于面包屑，根据language参数自动选择）


category_name
string
类目名称（展示用，根据language参数自动选择）


category_id
string
类目ID


category_level
integer
类目层级（1/2/3）


category1_name
string
一级类目名称


category2_name
string
二级类目名称


category3_name
string
三级类目名称


tags
array[string]
标签列表


price
float
价格（min_price）


compare_at_price
float
原价


currency
string
货币单位（默认USD）


image_url
string
主图URL


in_stock
boolean
是否有库存（任意SKU有库存即为true）


sku_prices
array[float]
所有SKU价格列表


sku_weights
array[integer]
所有SKU重量列表


sku_weight_units
array[string]
所有SKU重量单位列表


total_inventory
integer
总库存


sales
integer
销量（展示销量）


option1_name
string
选项1名称（如"color"）


option2_name
string
选项2名称（如"size"）


option3_name
string
选项3名称


specifications
array[object]
规格列表（与ES specifications字段对应）


skus
array
SKU 列表


relevance_score
float
相关性分数（默认为 ES 原始分数；当开启 AI 搜索时为融合后的最终分数）


4.4 SkuResult字段说明


字段
类型
说明


sku_id
string
SKU ID


price
float
价格


compare_at_price
float
原价


sku
string
SKU编码（sku_code）


stock
integer
库存数量


weight
float
重量


weight_unit
string
重量单位


option1_value
string
选项1取值（如color值）


option2_value
string
选项2取值（如size值）


option3_value
string
选项3取值


image_src
string
SKU图片地址


4.5 多语言字段说明

title, brief, description, vendor, category_path, category_name 会根据请求的 language 参数自动选择对应的中英文字段
language="zh": 优先返回 *_zh 字段，如果为空则回退到 *_en 字段
language="en": 优先返回 *_en 字段，如果为空则回退到 *_zh 字段


8. 常见场景示例
以下示例仅展示请求体（body）；实际调用时请加上请求头 X-Tenant-ID: <租户ID>（或 URL 参数 tenant_id），参见 3.1 接口信息。
8.1 基础搜索与排序
按价格从低到高排序:
{
  "query": "玩具",
  "size": 20,
  "from": 0,
  "sort_by": "price",
  "sort_order": "asc"
}


按价格从高到低排序:
{
  "query": "玩具",
  "size": 20,
  "from": 0,
  "sort_by": "price",
  "sort_order": "desc"
}


按销量从高到低排序:
{
  "query": "玩具",
  "size": 20,
  "from": 0,
  "sort_by": "sales",
  "sort_order": "desc"
}


按默认（相关性）排序:
{
  "query": "玩具",
  "size": 20,
  "from": 0
}

8.2 过滤搜索
需求: 搜索"玩具"，筛选类目为"益智玩具"，价格在50-200之间
{
  "query": "玩具",
  "size": 20,
  "language": "zh",
  "filters": {
    "category_name": "益智玩具"
  },
  "range_filters": {
    "min_price": {
      "gte": 50,
      "lte": 200
    }
  }
}


需求: 搜索"手机"，筛选多个品牌，价格范围
{
  "query": "手机",
  "size": 20,
  "language": "zh",
  "filters": {
    "vendor.zh.keyword": ["品牌A", "品牌B"]
  },
  "range_filters": {
    "min_price": {
      "gte": 50,
      "lte": 200
    }
  }
}

8.3 分面搜索
需求: 搜索"玩具"，获取类目和规格的分面统计，用于构建筛选器
{
  "query": "玩具",
  "size": 20,
  "language": "zh",
  "facets": [
    {"field": "category1_name", "size": 15, "type": "terms"},
    {"field": "category2_name", "size": 10, "type": "terms"},
    {"field": "specifications", "size": 10, "type": "terms"}
  ]
}


需求: 搜索"手机"，获取价格区间和规格的分面统计
{
  "query": "手机",
  "size": 20,
  "language": "zh",
  "facets": [
    {
      "field": "min_price",
      "type": "range",
      "ranges": [
        {"key": "0-50", "to": 50},
        {"key": "50-100", "from": 50, "to": 100},
        {"key": "100-200", "from": 100, "to": 200},
        {"key": "200+", "from": 200}
      ]
    },
    {
      "field": "specifications",
      "size": 10,
      "type": "terms"
    }
  ]
}

8.4 规格过滤与分面
需求: 搜索"手机"，筛选color为"white"的商品
{
  "query": "手机",
  "size": 20,
  "language": "zh",
  "filters": {
    "specifications": {
      "name": "color",
      "value": "white"
    }
  }
}


需求: 搜索"手机"，筛选color为"white"且size为"256GB"的商品
{
  "query": "手机",
  "size": 20,
  "language": "zh",
  "filters": {
    "specifications": [
      {"name": "color", "value": "white"},
      {"name": "size", "value": "256GB"}
    ]
  }
}


需求: 搜索"手机"，筛选size为"3"、"4"或"5"，且color为"green"的商品
{
  "query": "手机",
  "size": 20,
  "language": "zh",
  "filters": {
    "specifications": [
      {"name": "size", "value": "3"},
      {"name": "size", "value": "4"},
      {"name": "size", "value": "5"},
      {"name": "color", "value": "green"}
    ]
  }
}


需求: 搜索"手机"，获取所有规格的分面统计
{
  "query": "手机",
  "size": 20,
  "language": "zh",
  "facets": [
    {"field": "specifications", "size": 10, "type": "terms"}
  ]
}


需求: 只获取"color"和"size"规格的分面统计
{
  "query": "手机",
  "size": 20,
  "language": "zh",
  "facets": [
    {"field": "specifications.color", "size": 20, "type": "terms"},
    {"field": "specifications.size", "size": 15, "type": "terms"}
  ]
}


需求: 搜索"手机"，筛选类目和规格，并获取对应的分面统计
{
  "query": "手机",
  "size": 20,
  "language": "zh",
  "filters": {
    "category_name": "手机",
    "specifications": {
      "name": "color",
      "value": "white"
    }
  },
  "facets": [
    {"field": "category1_name", "size": 15, "type": "terms"},
    {"field": "category2_name", "size": 10, "type": "terms"},
    {"field": "specifications.color", "size": 20, "type": "terms"},
    {"field": "specifications.size", "size": 15, "type": "terms"}
  ]
}

8.5 SKU筛选
需求: 搜索"芭比娃娃"，每个SPU下按颜色筛选，每种颜色只显示一个SKU
{
  "query": "芭比娃娃",
  "size": 20,
  "sku_filter_dimension": ["color"]
}


说明:


如果 option1_name 为 "color"，则使用 sku_filter_dimension: ["color"] 可以按颜色分组
每个SPU下，每种颜色只会返回第一个SKU
如果维度不匹配，返回所有SKU（不进行过滤）

8.6 分页查询
需求: 获取第2页结果（每页20条）
{
  "query": "手机",
  "size": 20,
  "from": 20
}


cURL（第 2 页，每页 20 条）：
curl -sS "${BASE_URL:-http://localhost:6002}/search/" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: ${TENANT_ID:-162}" \
  -d '{
    "query": "手机",
    "size": 20,
    "from": 20,
    "language": "zh"
  }'