索引字段说明文档

设计思路

1. 针对店匠数据结构
   
   • 数据源处理：时间、数值字段的规范化直接在流水线中完成，因为只有一套数据源，不需要配置化；以我们的 SPU/SKU 为标准输入。
     
   • ES 索引方式：为了可扩展，需要定义多种索引方式，对于每个入 ES 的字段只需从中选择一种索引方式。
2. Doc 单位为 SPU
   
   • SKU 作为 SPU 的内部属性（ES 的 nested 结构），SKU 的价格字段展开为 min_price、max_price 作为 SPU 字段。
3. 多语言适配
   
   • 原始数据与用户环境均为多语言，需根据语言路由到不同分析器/索引方式，在线搜索时也要考虑多语言的适配。
4. 搜索接口适配
   
   • 接口简单，自动为多语言的数据源和 query 适配最优检索策略。
     
   • 返回的结果格式约定为店匠系列的 SPU/SKU（products/variants）嵌套结构。
     
   • 支撑 facet/过滤/排序业务需求：用户可以选择任何一个 keyword 或 HKText 类型的字段做筛选、聚合；也可以选择任何一个数值型字段做 Range 过滤或排序。

本文档详细说明了 Elasticsearch 索引中所有字段的类型、索引方式、数据来源等信息。

索引基本信息

• 索引名称: search_products
• 索引级别: SPU级别（商品级别）
• 数据结构: SPU文档包含嵌套的variants（SKU）数组

索引类型与处理说明

文本字段（多语言）

• 电商通用分析-中文
  json { "type": "text", "analyzer": "hanlp_index", "search_analyzer": "hanlp_standard" }
• 电商通用分析-英文
  json { "type": "text", "analyzer": "english" }
• 电商通用分析-日文
  json { "type": "text", "analyzer": "japanese" }
• 电商通用分析-阿拉伯文
  json { "type": "text", "analyzer": "arabic" }
• 电商通用分析-西班牙文
  json { "type": "text", "analyzer": "spanish" }
• 电商通用分析-俄文
  json { "type": "text", "analyzer": "russian" }

关键词字段

• ES 输入支持字符串或字符串数组，统一写入 keyword 字段，默认大小写敏感，必要时可通过 normalizer 统一大小写。
  json { "type": "keyword" }

Hybrid Keyword+Text（HKText）字段

• 该类型用于“精确匹配优先 + 模糊匹配兜底”的业务场景（如品牌、标签、SEO 关键词）。
  
• 典型 mapping：
  json { "type": "text", "analyzer": "factory_no_ngram_analyzer", "search_analyzer": "factory_no_query_analyzer", "fields": { "keyword": { "type": "keyword", "normalizer": "lowercase" } } }
• 业务命名：HKText。使用 字段.keyword 子字段满足过滤、聚合等精确需求，主字段支持 ngram 模糊搜索。

数值字段

• 整数：{ "type": "long" }
• 浮点数：{ "type": "float" }

日期字段

• 预处理：统一转换为 ISO8601（UTC）字符串或毫秒时间戳；空值保持 null。
  
• ES mapping：
  json { "type": "date", "format": "strict_date_optional_time||epoch_millis" }
• 查询：支持范围检索、排序与聚合。

文本-多语言向量化

• 调用“文本向量化”模块生成 1024 维向量，适用于标题、描述等语义检索场景。
  json { "type": "dense_vector", "dims": 1024, "index": true, "similarity": "dot_product" }

图片-向量化

• 调用“图片向量化”模块生成 1024 维向量，并保留图片 URL 以便回显。
  json { "type": "nested", "properties": { "vector": { "type": "dense_vector", "dims": 1024, "similarity": "dot_product" }, "url": { "type": "text" } } }

字段说明表

基础字段

索引字段名	ES字段类型	是否索引	索引方式	数据来源表	表中字段名	表中字段类型	说明
tenant_id	KEYWORD	是	精确匹配	SPU表	tenant_id	BIGINT	租户ID，用于多租户隔离
product_id	KEYWORD	是	精确匹配	SPU表	id	BIGINT	商品ID（SPU ID）
handle	KEYWORD	是	精确匹配	SPU表	handle	VARCHAR(255)	商品URL handle

文本搜索字段

索引字段名	ES字段类型	是否索引	索引方式	数据来源表	表中字段名	表中字段类型	Boost权重	说明
title	TEXT	是	english	SPU表	title	VARCHAR(512)	3.0	商品标题，权重最高
brief	TEXT	是	english	SPU表	brief	VARCHAR(512)	1.5	商品简介
description	TEXT	是	english	SPU表	description	TEXT	1.0	商品详细描述

SEO字段

索引字段名	ES字段类型	是否索引	索引方式	数据来源表	表中字段名	表中字段类型	Boost权重	是否返回	说明
seo_title	TEXT	是	english	SPU表	seo_title	VARCHAR(512)	2.0	否	SEO标题，用于提升相关性
seo_description	TEXT	是	english	SPU表	seo_description	TEXT	1.5	否	SEO描述
seo_keywords	HKText	是	english（模糊）+keyword（精确）	SPU表	seo_keywords	VARCHAR(1024)	2.0	否	SEO关键词，支持模糊匹配+精确过滤

分类和标签字段

索引字段名	ES字段类型	是否索引	索引方式	数据来源表	表中字段名	表中字段类型	Boost权重	是否返回	说明
vendor	TEXT	是	english	SPU表	vendor	VARCHAR(255)	1.5	是	供应商/品牌（文本搜索）
vendor_keyword	HKText	是	模糊+精确	SPU表	vendor	VARCHAR(255)	-	否	供应商/品牌（HKText类型，keyword子字段用于过滤）
product_type	TEXT	是	english	SPU表	category	VARCHAR(255)	1.5	是	商品类型（文本搜索）
product_type_keyword	HKText	是	模糊+精确	SPU表	category	VARCHAR(255)	-	否	商品类型（HKText类型）
tags	HKText	是	模糊+精确	SPU表	tags	VARCHAR(1024)	1.0	是	标签（HKText类型，支持搜索+过滤）
tags_keyword	HKText	是	模糊+精确	SPU表	tags	VARCHAR(1024)	-	否	标签keyword别名（HKText类型）
category	TEXT	是	english	SPU表	category	VARCHAR(255)	1.5	是	类目（文本搜索）
category_keyword	HKText	是	模糊+精确	SPU表	category	VARCHAR(255)	-	否	类目（HKText类型）

价格字段

索引字段名	ES字段类型	是否索引	索引方式	数据来源表	表中字段名	表中字段类型	说明
min_price	FLOAT	是	数值范围	SKU表（聚合计算）	price	DECIMAL(10,2)	最低价格（从所有SKU中取最小值）
max_price	FLOAT	是	数值范围	SKU表（聚合计算）	price	DECIMAL(10,2)	最高价格（从所有SKU中取最大值）
compare_at_price	FLOAT	是	数值范围	SKU表（聚合计算）	compare_at_price	DECIMAL(10,2)	原价（从所有SKU中取最大值）

价格计算逻辑：

• min_price: 取该SPU下所有SKU的price字段的最小值
• max_price: 取该SPU下所有SKU的price字段的最大值
• compare_at_price: 取该SPU下所有SKU的compare_at_price字段的最大值（如果存在）

图片字段

索引字段名	ES字段类型	是否索引	索引方式	数据来源表	表中字段名	表中字段类型	说明
image_url	KEYWORD	否	不索引	SPU表	image_src	VARCHAR(500)	商品主图URL，仅用于展示

文本嵌入字段

索引字段名	ES字段类型	是否索引	索引方式	数据来源表	表中字段名	表中字段类型	说明
title_embedding	TEXT_EMBEDDING	是	向量相似度（dot_product）	计算生成	title	VARCHAR(512)	标题的文本向量（1024维），用于语义搜索

说明：

• 向量维度：1024
• 相似度算法：dot_product（点积）
• 数据来源：基于title字段通过BGE-M3模型生成

时间字段

索引字段名	ES字段类型	是否索引	索引方式	数据来源表	表中字段名	表中字段类型	是否返回	说明
create_time	DATE	是	日期范围	SPU表	create_time	DATETIME	是	创建时间
update_time	DATE	是	日期范围	SPU表	update_time	DATETIME	是	更新时间
shoplazza_created_at	DATE	是	日期范围	SPU表	shoplazza_created_at	DATETIME	否	店匠系统创建时间
shoplazza_updated_at	DATE	是	日期范围	SPU表	shoplazza_updated_at	DATETIME	否	店匠系统更新时间

嵌套Variants字段（SKU级别）

索引字段名	ES字段类型	是否索引	索引方式	数据来源表	表中字段名	表中字段类型	说明
variants	JSON (nested)	是	嵌套对象	SKU表	-	-	商品变体数组（嵌套结构）

Variants子字段

索引字段名	ES字段类型	是否索引	索引方式	数据来源表	表中字段名	表中字段类型	说明
variants.variant_id	keyword	是	精确匹配	SKU表	id	BIGINT	变体ID（SKU ID）
variants.title	text	是	english	SKU表	title	VARCHAR(500)	变体标题
variants.price	float	是	数值范围	SKU表	price	DECIMAL(10,2)	变体价格
variants.compare_at_price	float	是	数值范围	SKU表	compare_at_price	DECIMAL(10,2)	变体原价
variants.sku	keyword	是	精确匹配	SKU表	sku	VARCHAR(100)	SKU编码
variants.stock	long	是	数值范围	SKU表	inventory_quantity	INT(11)	库存数量
variants.options	object	是	对象	SKU表	option1/option2/option3	VARCHAR(255)	选项（颜色、尺寸等）

Variants结构说明：

• variants 是一个嵌套对象数组，每个元素代表一个SKU
• 使用ES的nested类型，支持对嵌套字段进行独立查询和过滤
• options 对象包含 option1、option2、option3 三个字段，分别对应SKU表中的选项值

字段类型说明

ES字段类型映射

ES字段类型	Elasticsearch映射	用途
KEYWORD	keyword	精确匹配、过滤、聚合、排序
TEXT	text	全文检索（支持分词）
HKText	text + keyword子字段	精确优先的模糊/过滤混合场景
FLOAT	float	浮点数（价格、权重等）
LONG	long	整数（库存、计数等）
DATE	date	日期时间
TEXT_EMBEDDING	dense_vector	文本向量（1024维）
IMAGE_VECTOR	nested+dense_vector	图片语义检索（含URL）
JSON	object/nested	嵌套对象

分析器说明

分析器名称	语言	说明
chinese_ecommerce	中文	Ansj中文分词器（电商优化），用于中文文本的分词和搜索

索引配置

索引设置

• 分片数: 1
• 副本数: 0
• 刷新间隔: 30秒

查询域（Query Domains）

系统定义了多个查询域，用于在不同场景下搜索不同的字段组合：

1. default（默认索引）: 搜索所有文本字段

   • 包含字段：title, brief, description, seo_title, seo_description, seo_keywords, vendor, product_type, tags, category
   • Boost: 1.0

2. title（标题索引）: 仅搜索标题相关字段

   • 包含字段：title, seo_title
   • Boost: 2.0

3. vendor（品牌索引）: 仅搜索品牌字段

   • 包含字段：vendor
   • Boost: 1.5

4. category（类目索引）: 仅搜索类目字段

   • 包含字段：category
   • Boost: 1.5

5. tags（标签索引）: 搜索标签和SEO关键词

   • 包含字段：tags, seo_keywords
   • Boost: 1.0

数据转换规则

数据类型转换

1. BIGINT → KEYWORD: 数字ID转换为字符串（如 product_id, variant_id）
2. DECIMAL → FLOAT: 价格字段从DECIMAL转换为FLOAT
3. INT → LONG: 库存数量从INT转换为LONG
4. DATETIME → DATE: 时间字段转换为ISO格式字符串

特殊处理

1. 价格聚合: 从多个SKU的价格中计算min_price、max_price、compare_at_price
2. 图片URL处理: 如果image_src不是完整URL，会自动添加协议前缀
3. 选项合并: 将SKU表的option1、option2、option3合并为options对象

注意事项

1. 多租户隔离: 所有查询必须包含 tenant_id 过滤条件
2. 嵌套查询: 查询variants字段时需要使用nested查询语法
3. 字段命名: 用于过滤的字段应使用 *_keyword 后缀的字段
4. 向量搜索: title_embedding字段用于语义搜索，需要配合文本查询使用
5. Boost权重: 不同字段的boost权重影响搜索结果的相关性排序

数据来源表结构

SPU表（shoplazza_product_spu）

主要字段：

• id: BIGINT - 主键ID
• tenant_id: BIGINT - 租户ID
• handle: VARCHAR(255) - URL handle
• title: VARCHAR(512) - 商品标题
• brief: VARCHAR(512) - 商品简介
• description: TEXT - 商品描述
• vendor: VARCHAR(255) - 供应商/品牌
• category: VARCHAR(255) - 类目
• tags: VARCHAR(1024) - 标签
• seo_title: VARCHAR(512) - SEO标题
• seo_description: TEXT - SEO描述
• seo_keywords: VARCHAR(1024) - SEO关键词
• image_src: VARCHAR(500) - 图片URL
• create_time: DATETIME - 创建时间
• update_time: DATETIME - 更新时间
• shoplazza_created_at: DATETIME - 店匠创建时间
• shoplazza_updated_at: DATETIME - 店匠更新时间

SKU表（shoplazza_product_sku）

主要字段：

• id: BIGINT - 主键ID（对应variant_id）
• spu_id: BIGINT - SPU ID（关联字段）
• title: VARCHAR(500) - 变体标题
• price: DECIMAL(10,2) - 价格
• compare_at_price: DECIMAL(10,2) - 原价
• sku: VARCHAR(100) - SKU编码
• inventory_quantity: INT(11) - 库存数量
• option1: VARCHAR(255) - 选项1
• option2: VARCHAR(255) - 选项2
• option3: VARCHAR(255) - 选项3

TODO

多语言问题。 店匠的products接口返回的 title tags note category seo_title seo_description 等字段，为商家销售区域所使用语言，因此英文为主，各种语言都有。 不同语言需要用不同的分析器，需要拆分不同的字段。

考虑的方法是：

1. 索引层面： 每种文本字段，都设置多份语言索引，暂时先包括 zh en 两种即可。 以下字段做两份，如果以后对接的商家达到8种语言，那么这些字段也对应的扩展到8份。 title brief description seo_title seo_description seo_keywords vendor vendor_keyword product_type product_type_keyword category

2. tenant - 数据灌入： 对每个tenant设置一一个语言，作为tenant的一个基本配置。 写入索引的时候，根据语言配置将title 等文本字段写入对应的索引字段（比如 title_en） 查询的时候，将query转为商家所用语言，并到对应的field去查。

3. 在线搜索时： 多语言搜索作为效果优化的高级特性，比如某个用户配置了 zh, en 两种语言，那么 如索引的时候会进行不全，入两个字段。 搜索的时候 也准备 query_en query_zh 两个查询词 分别到多个字段搜索。