# 搜索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`: 规格过滤（嵌套字段，格式见[过滤器详解](./搜索API对接指南-01-搜索接口.md#33-过滤器详解)）

#### 范围字段

- `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子字段） |

---