本文介绍文档数据库 MongoDB 版的检索功能。 ## 功能介绍在应用程序中构建检索能力时，传统方案通常需要引入 Elasticsearch 等独立搜索引擎，这会带来架构复杂化、数据同步链路脆弱和运维成本增高等问题。文档数据库 MongoDB 版检索功能通过在数据库实例内部署专用的搜索节点（`mongot`），实现检索能力与数据库的原生集成。您可以直接使用 MongoDB 标准聚合查询语法完成检索任务，无需维护外部搜索系统。检索功能提供以下两种检索方式。 |**检索类型** |**功能定位** |**对应聚合阶段** |**主要特点** |**应用场景** | |---|---|---|---|---| |全文搜索 |基于关键词的文本匹配

|`$search` |通过建立 Search 索引加速对文本字段的关键词查询，支持分词和相关性排序 |商品评价检索、文档内容查找、系统日志查询

| |向量搜索 |基于数据语义或内在含义的相似性搜索 |`$vectorSearch`

|在多维空间中寻找与查询向量相近的向量，距离越近语义越相似；可结合嵌入模型和生成模型使用 |语义检索、图像相似搜索、推荐系统、RAG 应用、AI Agent | ## 系统架构与工作原理无论使用哪种检索类型，其底层均由统一的检索架构支撑。文档数据库 MongoDB 版支持副本集和分片集群两种架构，检索功能在此架构基础上通过增加独立的 `mongot` 节点实现搜索能力的扩展。`mongot` 是基于 Apache Lucene 构建的索引与查询执行引擎，专门用于支持 MongoDB Search 和 Vector Search。 * **架构示意图** ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_4b7fed179e2189992dca8d4cd9953f43.png) **核心组件与职责** |**核心组件** |**职责** | |---|---| |Mongod 节点 |负责业务数据存储与常规读写操作。当收到 `$search`、`$searchMeta` 或 `$vectorSearch` 查询时，将检索请求转发至 mongot 节点执行。 | |Mongot 节点 |独立的搜索计算资源，承载全部 Search 索引，专职处理检索请求。每个 `mongot` 进程拥有独立的持久化存储，不与数据库或其他搜索节点共享。`mongot `负责管理索引定义、从数据库持续获取数据以实时更新索引、以及处理搜索查询。 | * **数据同步机制** `mongot` 通过 Change Stream（MongoDB 的变更流机制）异步订阅 `mongod` 的数据变更，实时更新索引，确保最终一致性。检索负载运行于独立的 `mongot` 节点上，不会对核心数据库的事务处理性能产生影响。 * **请求处理路径** 您通过 mongosh 或其他 MongoDB 官方驱动发起检索聚合查询。`mongos`（分片集群）或 `mongod`（副本集）接收该查询后，将搜索阶段转发至 mongot 节点执行。`mongot` 完成搜索后，将匹配文档的标识与相关性评分返回给接收请求的代理节点，由该节点完成完整文档的读取、与普通查询结果的合并，最终将统一的结果集返回给您。整个路由和执行过程对应用完全透明。您只需通过标准的聚合语法编写检索语句，无需关心请求如何分发、数据如何合并等内部细节，也无需为检索功能维护额外的连接或 API。 ## 使用限制使用检索功能前，请注意以下约束条件。 |**限制项** |**说明** | |---|---| |版本要求 |MongoDB 8.3 及以上版本。 | |实例类型 |副本集实例或分片集群实例 | |向量字段类型 |向量字段必须为 `int32`、`int64` 或 `double` 数据类型的数字数组。 | |索引隔离 |`mongot` 组件与单个副本集紧密耦合，不能跨多个数据库或副本集共享。 | |分片集群 |每个分片维护独立的 `mongot` 节点组，分片间不共享。 |

注意

针对分片集群实例，如果对已有 Search 索引的集合进行分片，分片索引构建期间可能遇到短暂的不完整搜索结果。为已有 Search 索引的分片集合添加新分片时，搜索查询可能返回不完整结果，直至新分片完成初始同步。

## 使用流程检索功能依靠 Search 索引实现，因此您需要在执行检索前预先创建好索引。以下按任务类型分别介绍索引创建与检索执行的完整步骤。 ### 创建向量索引向量索引用于支持语义相似性搜索。建议在确认索引状态变为**运行中**后再执行搜索。 1. 准备向量数据业务代码中需引入 LLM Embedding 模型，将待检索的数据转换为向量数组后存储。向量维度不得超过 8192，且必须与后续索引定义中的 numDimensions 一致。 2. 创建索引使用 createSearchIndexes() 方法创建向量索引，核心定义结构如下。 ```JSON { "fields": [{ "type": "vector", "path": "<向量字段路径>", "numDimensions": <维度数>, "similarity": "euclidean | cosine | dotProduct", "quantization": "none | scalar | binary" }] } ``` 参数说明 |**参数** |**是否必填** |**`说明`** | |---|---|---| |`path` |是 |向量字段的路径。对于嵌套字段，使用点分法来指定嵌入式字段的路径，例如 `info.vector`。 | |`numDimensions` |是 |向量维度数量，取值范围 1~8192。

注意

该值必须与 mongod 中存储的向量数据维度完全一致。

| |`similarity`

|是 |相似度计算方式。取值范围如下：

* `dotProduct`（默认）：点积，基于向量之间的夹角和幅度来衡量相似度。

* `euclidean`：欧氏距离，测量向量端点之间的距离，可用于从不同维度来衡量相似度。

* `cosine`：余弦相似度，基于向量之间的夹角来测量相似度，可用于衡量不受幅度（Magnitude）缩放影响的相似度。 | |`quantization` |否 |量化方式，通过降低向量数据精度来减少索引对存储空间和内存的占用。选项如下：

* `none`：不量化，保证向量完全不失真。

* `scalar`：标量量化，对向量的每一个维度进行独立量化，精度较高，是大多数场景的推荐选项。

* `binary`：二值量化，对向量的数值信息二值化。若业务对搜索速度和成本有较高要求，可以选择此方式。

注意

使用二值量化时，similarity 必须为 euclidean，且 numDimensions 须为 8 的倍数。

| 3. 执行搜索在聚合管道中使用 $vectorSearch 阶段。

说明

向量搜索支持近似最近邻（ANN，Approximate Nearest Neighbor）和精确最近邻（ENN，Exact Nearest Neighbor）两种搜索模式。ANN 搜索速度快，适用于大数据集；ENN 搜索精度高，但计算开销大。您可以通过 exact 参数控制搜索模式。

```Bash { "$vectorSearch": { "path": "<向量字段路径>", "queryVector": [<数字数组>], "numCandidates": <候选数量>, "limit": <返回数量>, "filter": { <预过滤条件> }, "index": "<索引名称>" } } ``` 参数说明 |**参数** |**是否必填** |**说明** | |---|---|---| |`path` |是 |向量字段路径，须与索引定义一致。 | |`queryVector` |是 |查询向量数组，维度须与 `numDimensions` 一致。 | |`numCandidates` |是 |ANN 搜索的候选数量，建议值 ≥ `limit` × 20，以提高召回率。 | |`limit` |是 |返回的文档数量。 | |`filter` |否 |预过滤条件，支持 MQL 表达式。 | |`index` |否 |索引名称，默认为 `"default"`。 | |`exact` |否 |控制搜索模式：`false`（默认，ANN 近似搜索）或 `true`（ENN 精确搜索）。 | 您也可以通过 `$search` 阶段的 `vectorSearch` 操作符实现。 ### 创建全文索引全文索引用于对集合中已存储的文本字段内容进行关键词检索。 1. 创建索引使用 `createSearchIndexes()` 方法创建 Search 索引。以下示例创建了一个名为 `full_text_index` 的索引，并通过 `mappings.dynamic: true` 让 MongoDB 自动为集合中的所有字段建立索引。 ```JSON // 在集合上创建名为 'full_text_index' 的 Search 索引 db.<集合>.createSearchIndex({ name: "full_text_index", definition: { "mappings": { "dynamic": true // 自动索引集合中所有字段，使任何字段都可被 $search 检索 } } }); ``` 参数说明 |**参数** |**是否必填** |**说明** | |---|---|---| |`name` |是 |索引名称，用于在执行 `$search` 时指定。 | |`definition.mappings.dynamic` |否 |是否自动索引所有字段。`true` 表示自动索引所有可索引字段，无需在 `fields`中逐一声明。默认为 `false`。 | 2. 执行搜索在聚合管道中使用 $search 阶段的 text 操作符。

注意

$search 阶段必须是其所在聚合管道中的第一个阶段。

```JSON { "$search": { "index": "full_text_index", "text": { "query": "<搜索字符串>", "path": "<字段名>", "fuzzy": { "maxEdits": 1 | 2, "prefixLength": <字符数>, "maxExpansions": <数量> }, "matchCriteria": "any" | "all" } } } ``` 参数说明 |**参数** |**是否必填** |**说明** | |---|---|---| |`index` |否 |要使用的 Search 索引名称，默认为 `"default"`。 | |`text.query` |是 |要搜索的文本字符串。支持多个关键词。 | |`text.path` |是 |要搜索的字段路径，支持数组指定多个字段。 | |`text.fuzzy` |否 |模糊匹配配置。`maxEdits `为最大编辑距离（默认 2），`prefixLength `为前缀精确匹配长度（默认 0），`maxExpansions `为最大变体数（默认 50）。 | |`text.matchCriteria` |否

|匹配条件，`"any"`（任一术语匹配）或 `"all"`（全部术语匹配），默认 `"any"`。 | ### 完整示例以下 JSON 代码段展示了从连接数据库、创建向量索引到执行向量搜索的完整流程（以 Node.js 驱动为例）。您可以将示例中的占位符（如 `<连接字符串>`）替换为实际值。 ```Bash [ { "//": "步骤1: 连接数据库并获取集合", "connect": { "driver": "Node.js (mongodb)", "uri": "<您的MongoDB连接字符串>", "database": "<数据库名>", "collection": "<集合名>" } }, { "//": "步骤2: 创建向量索引（如果尚未创建）", "createSearchIndex": { "name": "vector_index_example", "definition": { "fields": [ { "type": "vector", "path": "plot_embedding", "numDimensions": 384, "similarity": "cosine" } ] } } }, { "//": "步骤3: 执行向量搜索", "aggregate": { "pipeline": [ { "$vectorSearch": { "index": "vector_index_example", "path": "plot_embedding", "queryVector": [0.1, -0.2, 0.3 /* ... 请替换为您的384维向量 */], "numCandidates": 100, "limit": 5 } }, { "$project": { "_id": 0, "title": 1, "plot": 1 } } ] } } ] ```

注意

索引创建（createSearchIndex）是一个异步操作，需要一定时间完成，建议在确认索引状态变为运行中后再执行搜索。

## 相关 API |**API** |**描述** | |---|---| |[CreateDBInstance](https://docs.volcengine.com/docs/6447/100735) |调用 CreateDBInstance 接口创建 MongoDB 实例。 | |[DescribeNodeSpecs](https://docs.volcengine.com/docs/6447/100734) |调用 DescribeNodeSpecs 接口查询 MongoDB 支持的节点规格列表。 | |[DescribeDBInstances](https://docs.volcengine.com/docs/6447/100741) |调用 DescribeDBInstances 接口查询 MongoDB 实例的基本信息。 | |[DescribeDBInstanceDetail](https://docs.volcengine.com/docs/6447/100738) |调用 DescribeDBInstanceDetail 接口查询目标 MongoDB 实例的详细信息。 |