Nixiesearch索引创建教程：YAML Schema与字段类型映射完整解析

Nixiesearch索引创建教程：YAML Schema与字段类型映射完整解析

【免费下载链接】nixiesearchHybrid search engine, combining best features of text and semantic search worlds项目地址: https://gitcode.com/gh_mirrors/ni/nixiesearch

Nixiesearch 是一款开源的混合搜索引擎（Hybrid Search Engine），将传统文本检索与语义向量搜索的长处合二为一。与 Elasticsearch 等引擎不同，Nixiesearch 要求你在写入任何数据之前，先用一份YAML Schema 文件声明式地描述索引结构——本文将手把手带你完成Nixiesearch 索引创建：从理解 Schema 基本结构、搞懂全部字段类型，到为真实业务写出一份可直接运行的字段类型映射配置。 🎯

一、为什么 Nixiesearch 索引必须预先定义 Schema？

在 Nixiesearch 中，"先写数据、后补结构"的动态映射（schemaless）被认为是一种反模式。原因很直接：搜索引擎必须提前知道如何为每个字段构建底层索引结构——

• 磁盘存储方式：字段值如何落盘，由type决定；
• 索引结构：是否建倒排索引、向量索引、排序/过滤/分面索引，都取决于 Schema 中的开关；
• 数据校验：开启required后，缺失字段的文档会在入库时直接报错。

好消息是：Schema 只需写在一份 YAML 配置文件的schema段里，整个集群的索引定义一目了然。单机模式下，索引器（Indexer）与搜索器（Searcher）运行在同一进程中，读写都通过 REST API 完成：

⚠️ 注意：Nixiesearch 的搜索器不保存状态，索引只能静态创建——也就是说，新增索引需要修改配置文件并重启。

二、YAML Schema 基本结构：5 分钟看懂索引定义

每个索引是schema段下的一个键，核心就是fields字段定义块。以电影索引为例：

schema: movies: # 索引名称 fields: title: # 字段名 type: text # 字段类型（必填） search: true filter: true store: true year: type: int filter: true facet: true sort: true

几个关键规则要记住：

完整的索引映射规范可以参考官方文档 docs/docs/features/indexing/mapping.md。

三、字段类型完全清单

Nixiesearch 内置的字段类型覆盖了绝大多数业务场景，完整列表见 docs/docs/features/indexing/types/overview.md：

3.1 文本类型：text与text[]

这是唯一支持全文检索的类型，也是区分度最大的类型：

schema: movies: fields: title: type: text # 单值：一个文档只有一个标题 genres: type: text[] # 多值：一个文档可含多个类型标签

Nixiesearch 明确区分单值字段与多值字段（这是它和 Elasticsearch 的一大差异，后者所有字段默认可重复）。多值字段在响应中会返回数组，单值字段则返回标量。

3.2 数值类型：int、long、float、double及列表变体

数值字段不能做全文检索，但可以过滤、排序、分面，是构建筛选面板的主力：

price: type: float filter: true sort: true facet: true user_ratings: type: int[] # 数值列表：存储多个评分 filter: true store: true

数值列表类型int[]、long[]、float[]、double[]适用于"历史价格点""多维度尺寸"这类一字段多值的场景。

3.3 日期、地理与其他类型

文档中的嵌套对象会被自动展平为点号分隔字段：{"meta": {"asin": "A1"}}对应 Schema 中的meta.asin，这一点在映射嵌套 JSON 时尤其有用。

四、字段能力开关：一份配置决定字段"能干什么"

每个字段都支持一组能力开关，默认值需要特别注意（与直觉相反）：

💡最佳实践：sort/facet/filter都要求在后台维护额外的索引数据结构，只为你真正会用到的能力开启开关，可以显著减小索引体积、提升写入速度。

五、文本字段的三种搜索模式：词法、语义与混合

这是 Nixiesearch 最有含金量的部分——text字段的search开关支持三种模式，甚至可以在同一个字段上叠加：

5.1 词法检索（Lexical）

title: type: text search: lexical: analyze: english # 指定语言分词器，默认 generic

建议为词法检索显式指定analyze语言（英文、中文等），搜索引擎会选用对应的 Lucene 语言分析器，召回质量更好。

5.2 语义检索（Semantic）

overview: type: text search: semantic: model: e5-small # 引用 inference 段中定义的嵌入模型

语义模式需要先在配置的inference段声明一个嵌入模型（支持自托管 ONNX 模型，也支持外部 Embedding API）。

5.3 混合检索（Hybrid）——Nixiesearch 的招牌

title: type: text search: semantic: model: e5-small lexical: analyze: english

两者叠加即为混合检索：引擎并行执行词法查询与 kNN 向量查询，再用**倒数排名融合（RRF）**合并出最终排序。这也是"混合搜索引擎"名称的由来。

六、实战：为商品目录写一份完整 Schema

把前面的知识串起来，下面是一份可直接使用的电商索引配置：

inference: embedding: e5-small: model: intfloat/e5-small-v2 schema: products: alias: [shop] # 索引别名，方便日后无损切换版本 fields: title: type: text search: lexical: { analyze: english } semantic: { model: e5-small } suggest: true # 参与自动补全 price: type: float filter: true sort: true facet: true required: true user_ratings: type: int[] filter: true store: true active: type: bool filter: true created_date: type: datetime filter: true sort: true

对应文档示例：

{ "_id": "p-1001", "title": "Running Shoes", "price": 89.99, "user_ratings": [5, 4, 5, 3], "active": true, "created_date": "2024-01-15T10:30:00Z" }

配置完成后，启动服务并PUT文档即可完成索引创建。完整的端到端流程（含 Docker 启动命令）见官方快速上手文档 docs/docs/quickstart.md，数值列表等新特性的更多示例见 docs/docs/tutorial/schema.md。

七、进阶技巧：通配符与嵌套字段

面对字段名不固定的数据源，可以用通配符字段动态匹配，而不必逐个声明：

extra_*: type: text search: lexical: { analyze: english }

约束很简单：每个字段名只允许一个*，且不能与已声明的普通字段冲突；嵌套场景下支持meta.field_*_str这类"一个点 + 一个星号"的组合。搜索请求的fields参数同样支持通配符，可一次性取回所有匹配字段。

八、索引创建常见问题 FAQ

Q1：字段类型可以事后修改吗？A：索引结构是静态的，建议重建索引并通过alias别名平滑切换，用户侧 API 地址无需变动。

Q2：filter开了但搜索报错怎么办？A：检查是否只对单值字段开启了sort/facet（多值字段不支持这两项），以及type是否与文档实际值一致。

Q3：已有现成的向量，不想让 Nixiesearch 本地推理？A：可以把文档字段写成{"text": "...", "embedding": [...]}的预嵌入格式，或在 Schema 中用dim指定维度跳过服务端推理。

Q4：如何保证数据完整性？A：将关键字段设为required: true，入库时缺失即拒绝——这比事后清洗数据要高效得多。

掌握YAML Schema 结构、字段类型清单与能力开关三件套，你就已经完成了 Nixiesearch 索引创建的核心工作。接下来可以深入阅读字段类型的细节文档（文本、数值、日期、地理），或体验一下混合检索在真实数据上的效果——语义召回带来的惊喜，往往超出预期。 🚀

【免费下载链接】nixiesearchHybrid search engine, combining best features of text and semantic search worlds项目地址: https://gitcode.com/gh_mirrors/ni/nixiesearch