索引字段说明.md 18.7 KB
Edit Raw Blame History


索引字段说明文档
设计思路

针对店匠数据结构


数据源处理：时间、数值字段的规范化直接在流水线中完成，因为只有一套数据源，不需要配置化；以我们的 SPU/SKU 为标准输入。

ES 索引方式：为了可扩展，需要定义多种索引方式，对于每个入 ES 的字段只需从中选择一种索引方式。

Doc 单位为 SPU


SKU 作为 SPU 的内部属性（ES 的 nested 结构），SKU 的价格字段展开为 min_price、max_price 作为 SPU 字段。

多语言适配


原始数据与用户环境均为多语言，需根据语言路由到不同分析器/索引方式，在线搜索时也要考虑多语言的适配。

搜索接口适配


接口简单，自动为多语言的数据源和 query 适配最优检索策略。


返回的结果格式约定为店匠系列的 SPU/SKU嵌套结构。


支撑 facet/过滤/排序业务需求：用户可以选择任何一个 keyword 或 HKText 类型的字段做筛选、聚合；也可以选择任何一个数值型字段做 Range 过滤或排序。


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

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

索引类型与处理说明
文本字段（多语言）

电商通用分析-中文

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
BIGINT转字符串
租户ID，用于多租户隔离


spu_id
KEYWORD
是
SPU表
id
BIGINT
BIGINT转字符串
SPU ID（主键）


handle
KEYWORD
是
SPU表
handle
VARCHAR(255)

商品URL handle


数据预处理列留空表示该字段无需额外处理。
文本搜索字段


索引字段名
ES字段类型
是否索引
数据来源表
表中字段名
表中字段类型
Boost权重
数据预处理
说明


title
TEXT
是
SPU表
title
VARCHAR(512)
3.0

商品标题，权重最高


brief
TEXT
是
SPU表
brief
VARCHAR(512)
1.5

商品简介


description
TEXT
是
SPU表
description
TEXT
1.0

商品详细描述


SEO字段


索引字段名
ES字段类型
是否索引
数据来源表
表中字段名
表中字段类型
Boost权重
是否返回
数据预处理
说明


seo_title
TEXT
是
SPU表
seo_title
VARCHAR(512)
2.0
否

SEO标题，用于提升相关性


seo_description
TEXT
是
SPU表
seo_description
TEXT
1.5
否

SEO描述


seo_keywords
HKText
是
SPU表
seo_keywords
VARCHAR(1024)
2.0
否
按逗号分割为list，去除空白项
SEO关键词，支持模糊匹配+精确过滤


分类和标签字段


索引字段名
ES字段类型
是否索引
数据来源表
表中字段名
表中字段类型
Boost权重
是否返回
数据预处理
说明


vendor
HKText
是
SPU表
vendor
VARCHAR(255)
1.5
是

供应商/品牌，HKText字段自动提供 vendor.keyword 用于过滤、聚合


tags
HKText
是
SPU表
tags
VARCHAR(1024)
1.0
是

标签字段，支持模糊搜索；使用 tags.keyword 进行精确过滤


category
HKText
是
SPU表
category
VARCHAR(255)
1.5
是

类目字段，使用 category.keyword 进行过滤/分面


价格字段


索引字段名
ES字段类型
是否索引
数据来源表
表中字段名
表中字段类型
数据预处理
说明


min_price
FLOAT
是
SKU表（聚合计算）
price
DECIMAL(10,2)
聚合所有SKU最小值并转FLOAT
最低价格（从所有SKU中取最小值）


max_price
FLOAT
是
SKU表（聚合计算）
price
DECIMAL(10,2)
聚合所有SKU最大值并转FLOAT
最高价格（从所有SKU中取最大值）


compare_at_price
FLOAT
是
SKU表（聚合计算）
compare_at_price
DECIMAL(10,2)
聚合所有SKU最大值并转FLOAT
原价（从所有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
商品主图URL，仅用于展示


文本嵌入字段


索引字段名
ES字段类型
是否索引
数据来源表
表中字段名
表中字段类型
数据预处理
说明


title_embedding
TEXT_EMBEDDING
是
计算生成
title
VARCHAR(512)
BGE-M3模型生成1024维向量
标题的文本向量（1024维），用于语义搜索


说明：


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

时间字段


索引字段名
ES字段类型
是否索引
数据来源表
表中字段名
表中字段类型
是否返回
数据预处理
说明


create_time
DATE
是
SPU表
create_time
DATETIME
是
转换为UTC ISO8601字符串
创建时间


update_time
DATE
是
SPU表
update_time
DATETIME
是
转换为UTC ISO8601字符串
更新时间


shoplazza_created_at
DATE
是
SPU表
shoplazza_created_at
DATETIME
否
转换为UTC ISO8601字符串
店匠系统创建时间


shoplazza_updated_at
DATE
是
SPU表
shoplazza_updated_at
DATETIME
否
转换为UTC ISO8601字符串
店匠系统更新时间


嵌套SKUs字段（SKU级别）


索引字段名
ES字段类型
是否索引
数据来源表
表中字段名
表中字段类型
数据预处理
说明


skus
JSON (nested)
是
SKU表
-
-
汇总同SPU下SKU记录，构建nested数组
SKU数组（嵌套结构）


SKUs子字段


索引字段名
ES字段类型
是否索引
数据来源表
表中字段名
表中字段类型
数据预处理
说明


skus.sku_id
keyword
是
SKU表
id
BIGINT
BIGINT转字符串
SKU ID


skus.title
text
是
SKU表
title
VARCHAR(500)

SKU标题


skus.price
float
是
SKU表
price
DECIMAL(10,2)
DECIMAL转FLOAT
SKU价格


skus.compare_at_price
float
是
SKU表
compare_at_price
DECIMAL(10,2)
DECIMAL转FLOAT
原价


skus.sku
keyword
是
SKU表
sku
VARCHAR(100)

SKU编码


skus.stock
long
是
SKU表
inventory_quantity
INT(11)
INT转LONG
库存数量


skus.options
object
是
SKU表
option1/option2/option3
VARCHAR(255)
合并option1/2/3并去除空值
选项（颜色、尺寸等）


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）
系统定义了多个查询域，用于在不同场景下搜索不同的字段组合：


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


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

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


包含字段：title, seo_title
Boost: 2.0

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


包含字段：vendor
Boost: 1.5

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


包含字段：category
Boost: 1.5

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


包含字段：tags, seo_keywords
Boost: 1.0


数据转换规则
数据类型转换

BIGINT → KEYWORD: 数字ID转换为字符串（如 spu_id, sku_id）
DECIMAL → FLOAT: 价格字段从DECIMAL转换为FLOAT
INT → LONG: 库存数量从INT转换为LONG
DATETIME → DATE: 时间字段转换为ISO格式字符串

特殊处理

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

注意事项

多租户隔离: 所有查询必须包含 tenant_id 过滤条件
嵌套查询: 查询variants字段时需要使用nested查询语法
字段命名: 用于过滤的字段应使用 *_keyword 后缀的字段
向量搜索: title_embedding字段用于语义搜索，需要配合文本查询使用
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 - 店匠更新时间


spu表全部字段
"Field" "Type"  "Null"  "Key"   "Default"   "Extra"
"id"    "bigint(20)"    "NO"    "PRI"       "auto_increment"
"shop_id"   "bigint(20)"    "NO"    "MUL"       ""
"shoplazza_id"  "varchar(64)"   "NO"    ""      ""
"handle"    "varchar(255)"  "YES"   "MUL"       ""
"title" "varchar(500)"  "NO"    ""      ""
"brief" "varchar(1000)" "YES"   ""      ""
"description"   "text"  "YES"   ""      ""
"spu"   "varchar(100)"  "YES"   ""      ""
"vendor"    "varchar(255)"  "YES"   ""      ""
"vendor_url"    "varchar(500)"  "YES"   ""      ""
"seo_title" "varchar(500)"  "YES"   ""      ""
"seo_description"   "text"  "YES"   ""      ""
"seo_keywords"  "text"  "YES"   ""      ""
"image_src" "varchar(500)"  "YES"   ""      ""
"image_width"   "int(11)"   "YES"   ""      ""
"image_height"  "int(11)"   "YES"   ""      ""
"image_path"    "varchar(255)"  "YES"   ""      ""
"image_alt" "varchar(500)"  "YES"   ""      ""
"inventory_policy"  "varchar(50)"   "YES"   ""      ""
"inventory_quantity"    "int(11)"   "YES"   ""  "0" ""
"inventory_tracking"    "tinyint(1)"    "YES"   ""  "0" ""
"published" "tinyint(1)"    "YES"   ""  "0" ""
"published_at"  "datetime"  "YES"   "MUL"       ""
"requires_shipping" "tinyint(1)"    "YES"   ""  "1" ""
"taxable"   "tinyint(1)"    "YES"   ""  "0" ""
"fake_sales"    "int(11)"   "YES"   ""  "0" ""
"display_fake_sales"    "tinyint(1)"    "YES"   ""  "0" ""
"mixed_wholesale"   "tinyint(1)"    "YES"   ""  "0" ""
"need_variant_image"    "tinyint(1)"    "YES"   ""  "0" ""
"has_only_default_variant"  "tinyint(1)"    "YES"   ""  "0" ""
"tags"  "text"  "YES"   ""      ""
"note"  "text"  "YES"   ""      ""
"category"  "varchar(255)"  "YES"   ""      ""
"shoplazza_created_at"  "datetime"  "YES"   ""      ""
"shoplazza_updated_at"  "datetime"  "YES"   "MUL"       ""
"tenant_id" "bigint(20)"    "NO"    "MUL"       ""
"creator"   "varchar(64)"   "YES"   ""  ""  ""
"create_time"   "datetime"  "NO"    ""  "CURRENT_TIMESTAMP" ""
"updater"   "varchar(64)"   "YES"   ""  ""  ""
"update_time"   "datetime"  "NO"    ""  "CURRENT_TIMESTAMP" "on update CURRENT_TIMESTAMP"
"deleted"   "bit(1)"    "NO"    ""  "b'0'"  ""
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


sku全部字段
"Field" "Type"  "Null"  "Key"   "Default"   "Extra"
"id"    "bigint(20)"    "NO"    "PRI"       "auto_increment"
"spu_id"    "bigint(20)"    "NO"    "MUL"       ""
"shop_id"   "bigint(20)"    "NO"    "MUL"       ""
"shoplazza_id"  "varchar(64)"   "NO"    ""      ""
"shoplazza_product_id"  "varchar(64)"   "NO"    "MUL"       ""
"shoplazza_image_id"    "varchar(64)"   "YES"   ""      ""
"title" "varchar(500)"  "YES"   ""      ""
"sku"   "varchar(100)"  "YES"   "MUL"       ""
"barcode"   "varchar(100)"  "YES"   ""      ""
"position"  "int(11)"   "YES"   ""  "0" ""
"price" "decimal(10,2)" "YES"   ""      ""
"compare_at_price"  "decimal(10,2)" "YES"   ""      ""
"cost_price"    "decimal(10,2)" "YES"   ""      ""
"option1"   "varchar(255)"  "YES"   ""      ""
"option2"   "varchar(255)"  "YES"   ""      ""
"option3"   "varchar(255)"  "YES"   ""      ""
"inventory_quantity"    "int(11)"   "YES"   ""  "0" ""
"weight"    "decimal(10,2)" "YES"   ""      ""
"weight_unit"   "varchar(10)"   "YES"   ""      ""
"image_src" "varchar(500)"  "YES"   ""      ""
"wholesale_price"   "json"  "YES"   ""      ""
"note"  "text"  "YES"   ""      ""
"extend"    "json"  "YES"   ""      ""
"shoplazza_created_at"  "datetime"  "YES"   ""      ""
"shoplazza_updated_at"  "datetime"  "YES"   ""      ""
"tenant_id" "bigint(20)"    "NO"    "MUL"       ""
"creator"   "varchar(64)"   "YES"   ""  ""  ""
"create_time"   "datetime"  "NO"    ""  "CURRENT_TIMESTAMP" ""
"updater"   "varchar(64)"   "YES"   ""  ""  ""
"update_time"   "datetime"  "NO"    ""  "CURRENT_TIMESTAMP" "on update CURRENT_TIMESTAMP"
"deleted"   "bit(1)"    "NO"    ""  "b'0'"  ""
TODO
多语言问题。
店匠的products接口返回的 title tags note category  seo_title seo_description 等字段，为商家销售区域所使用语言，因此英文为主，各种语言都有。
不同语言需要用不同的分析器，需要拆分不同的字段。

考虑的方法是：


索引层面：
每种文本字段，都设置多份语言索引，暂时先包括 zh en 两种即可。
以下字段做两份，如果以后对接的商家达到8种语言，那么这些字段也对应的扩展到8份。
title brief description seo_title seo_description seo_keywords vendor vendor_keyword product_type product_type_keyword category
tenant - 数据灌入：
对每个tenant设置一一个语言，作为tenant的一个基本配置。
写入索引的时候，根据语言配置将title 等文本字段写入对应的索引字段（比如 title_en）
查询的时候，将query转为商家所用语言，并到对应的field去查。
在线搜索时：
多语言搜索作为效果优化的高级特性，比如某个用户配置了 zh, en 两种语言，那么 如索引的时候会进行不全，入两个字段。
搜索的时候 也准备 query_en query_zh 两个查询词 分别到多个字段搜索。