搜索API对接指南-08-数据模型与字段速查

本篇覆盖原文第 9 章：商品字段定义、字段类型速查、常用字段列表、支持的分析器。

9. 数据模型

9.1 商品字段定义

字段名	类型	描述
tenant_id	keyword	租户ID（多租户隔离）
spu_id	keyword	SPU ID
title.<lang>	object/text	商品标题（多语言对象，如 title.zh, title.en）
brief.<lang>	object/text	商品短描述（多语言对象，如 brief.zh, brief.en）
description.<lang>	object/text	商品详细描述（多语言对象，如 description.zh, description.en）
vendor.<lang>	object/text	供应商/品牌（多语言对象，且带 keyword 子字段，如 vendor.zh.keyword）
category_path.<lang>	object/text	类目路径（多语言对象，用于搜索，如 category_path.zh）
category_name_text.<lang>	object/text	类目名称（多语言对象，用于搜索，如 category_name_text.zh）
category_id	keyword	类目ID
category_name	keyword	类目名称（用于过滤）
category_level	integer	类目层级
category1_name, category2_name, category3_name	keyword	多级类目名称（用于过滤和分面）
tags	keyword	标签（数组）
specifications	nested	规格（嵌套对象数组）
option1_name, option2_name, option3_name	keyword	选项名称
min_price, max_price	float	最低/最高价格
compare_at_price	float	原价
sku_prices	float	SKU价格列表（数组）
sku_weights	long	SKU重量列表（数组）
sku_weight_units	keyword	SKU重量单位列表（数组）
total_inventory	long	总库存
sales	long	销量（展示销量）
skus	nested	SKU详细信息（嵌套对象数组）
create_time, update_time	date	创建/更新时间
title_embedding	dense_vector	标题向量（1024维，仅用于搜索）
image_embedding	nested	图片向量（嵌套，仅用于搜索）

所有租户共享统一的索引结构。文本字段支持中英文双语，后端根据 language 参数自动选择对应字段返回。

9.2 字段类型速查

类型	ES Mapping	用途
text	text	全文检索（支持中英文分析器）
keyword	keyword	精确匹配、聚合、排序
integer	integer	整数
long	long	长整数
float	float	浮点数
date	date	日期时间
nested	nested	嵌套对象（specifications, skus, image_embedding）
dense_vector	dense_vector	向量字段（title_embedding，仅用于搜索）

9.3 常用字段列表

过滤字段

• 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: 规格过滤（嵌套字段，格式见过滤器详解）

范围字段

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

排序字段

• price: 价格（后端自动根据sort_order映射：asc→min_price，desc→max_price）
• sales: 销量
• create_time: 创建时间
• update_time: 更新时间
• relevance_score: 相关性分数（默认，不指定sort_by时使用）

注意: 前端只需传 price，后端会自动处理：

• sort_by: "price" + sort_order: "asc" → 按 min_price 升序（价格从低到高）
• sort_by: "price" + sort_order: "desc" → 按 max_price 降序（价格从高到低）

9.4 支持的分析器

分析器	语言	描述
index_ik	中文	中文索引分析器（用于中文字段）
query_ik	中文	中文查询分析器（用于中文字段）
hanlp_index ⚠️ TODO（暂不支持）	中文	中文索引分析器（用于中文字段）
hanlp_standard ⚠️ TODO（暂不支持）	中文	中文查询分析器（用于中文字段）
english	英文	标准英文分析器（用于英文字段）
lowercase	-	小写标准化器（用于keyword子字段）

---