对于 AI 代理:可在 https://www.mongodb.com/zh-cn/docs/llms.txt 获取文档索引—通过在任何 URL 路径后添加 .md 可获取所有页面的 Markdown 版本。
Docs 菜单

解释MongoDB Vector Search 结果

当您使用 explain 方法运行MongoDB Vector Search查询时,该查询会返回一个BSON文档,其中包含查询计划和描述查询在内部运行方式的执行统计信息。

db.<myCollection>.explain("<verbosity>").aggregate([
{
"$vectorSearch": {
"exact": true | false,
"filter": {<filter-specification>},
"index": "<index-name>",
"limit": <number-of-results>,
"numCandidates": <number-of-candidates>,
"path": "<field-to-search>",
"queryVector": [<array-of-numbers>],
"explainOptions": {
"traceDocumentIds": [<array-of-document-IDs>]
}
}
}
])

详细模式控制 explain 的行为和返回的信息量。值可以是以下之一,按详细程度降序排列:

有关查询计划的信息,包括 stats 字段,其中包含查询的执行统计信息。包括在计划选择期间捕获的部分执行数据。

有关查询计划的信息,包括 stats 字段,其中包含查询的执行统计信息。

queryPlanner(默认)

有关查询计划的信息。不包括 stats 字段,其中包含查询的执行统计信息。

explain 方法返回包含以下字段的BSON文档。

选项
类型
必要性
用途

collectors

文档

Optional

描述收集器的执行统计信息。

metadata

文档

Optional

包含有用的元数据。

query

文档

Optional

描述查询的执行统计信息。这在 indexPartitionExplain 的顶层不存在。

resultMaterialization

文档

Optional

有关在查询执行后检索每个文档数据的详细信息。queryPlanner 详细模式不会返回此值。

resourceUsage

文档

Optional

详细说明执行查询时的资源使用情况。对于 queryPlanner 详细模式,不会返回此值。

vectorTracing

对象数组

Optional

跟踪有关指定文档中向量的详细信息,如下所示:

  • MongoDB 向量搜索在查询执行期间是否访问过该向量,该向量是否出现在 MongoDB 向量搜索结果集,如果没有,为何删除该向量。

  • 向量是否通常可访问,因为由于分层可导航小世界的概率性质,某些向量可能无法访问。

luceneVectorSegmentStats

对象数组

Optional

$vectorSearch 查询执行的每个 Lucene 分段的详细信息。

collectors 是包含以下字段的BSON文档:

字段
类型
必要性
用途

allCollectorStats

文档

必需

Statistics of all collectors of the query. Statistics reported represent either the maximum value across all collectors used in the query or a sum of the statistic across all the sub-collectors. The timing statistics are summed to reflect the total time spent across all collectors for the entire query. To learn more, see allCollectorStats.

allCollectorStats 是一个BSON文档,描述查询中指定的所有收集器的收集器统计信息。它包含以下键:

字段
说明

collect

追踪收集器收集的结果数量和持续时间。

competitiveIterator

统计信息跟踪从收集器请求 competitiveIterator 的总持续时间和次数。

setScorer

统计信息跟踪在收集器上设置记分器的总持续时间和次数。

metadata 包含有用的元数据,例如:

字段
类型
必要性
用途

mongotVersion

字符串

Optional

mongot 的当前版本。

mongotHostName

字符串

Optional

用于标识 mongot 主机的人类可读标签。

indexName

字符串

Optional

查询中使用的MongoDB Vector Search索引。

cursorOptions

文档

Optional

为 mongot 提供的游标选项。

totalLuceneDocs

整型

Optional

索引中的文档总数(包括已删除的文档)。

explain 响应是一个 BSON 文档,其中的键和值描述了查询的执行统计数据。结果集中的 explain 文档包含以下字段:

字段
类型
必要性
用途

path

字符串

Optional

所查询的 embedding 字段的路径(前提是它不是根)。

type

字符串

必需

向量搜索查询类型的名称。有关更多信息,请参阅 query。

args

文档

必需

向量搜索查询信息。有关更多信息,请参阅 query。

stats

文档

Optional

stats for the query if explain ran with executionStats or allPlansExecution verbosity.

The explain response contains information how the query was executed internally. The args field includes the following details:

  • 查询类型

  • 每种查询类型的结构化摘要示例

  • 结构化摘要中的查询选项

以下部分描述了查询类型和结构化摘要中的字段:

WrappedKnnQuery

用于组合多个查询的ANN向量搜索的包装器查询。结构化摘要包含有关以下选项的详细信息:

字段
类型
必要性
说明

query

阵列

必需

向量搜索中使用的子查询数组,通常包含 KnnFloatVectorQuery 和 DocAndScoreQuery。

KnnFloatVectorQuery

特定于浮点向量上的ANN搜索的查询类型。结构化摘要包含有关以下选项的详细信息:

字段
类型
必要性
说明

field

字符串

必需

正在搜索的向量字段路径(Field Path)。

k

整型

必需

要检索的最近邻数量。

DocAndScoreQuery

一种处理文档匹配和评分的查询类型。结构化摘要通常包括有关查询执行的统计信息。

ExactVectorSearchQuery

用于新奥向量搜索的查询类型。结构化摘要包含有关以下选项的详细信息:

字段
类型
必要性
说明

field

字符串

必需

正在搜索的向量字段路径(Field Path)。

similarityFunction

字符串

必需

使用的相似度函数(dotProduct、cosine 或 euclidean)。

filter

文档

Optional

用于限制向量搜索范围的预过滤查询。

BooleanQuery

If you use a pre-filter in your vector search query, your explain results include the BooleanQuery type. To learn more about the fields for this type and other query types specific to your pre-filter query, refer to the Query Types on the MongoDB Search Explain Page.

DefaultQuery

未由其他查询显式定义的查询将使用默认查询进行序列化。结构化摘要包含有关以下选项的详细信息:

字段
类型
必要性
说明

queryType

字符串

必需

查询类型。

The explain response for executionStats and allPlansExecution verbosity modes includes a stats field that contains information on how much time a query spends in various stages of query execution.

时间细分描述了与查询执行区域相关的执行统计信息。以下字段显示时间细分:

字段
类型
说明

millisElapsed

Long

在该区域执行任务所用的大约时间,包括查询子级在此区域所用的时间。该值是在该区域中执行任务时经过的近似毫秒数。

invocationCounts

文档

Number of invocations of tasks included in this area. The value is a map of task names to their invocation count.

统计信息可用于以下查询领域:

选项
说明

context

与向量搜索查询执行相关的统计信息。此区域中枚举了两个任务的调用计数:

  • createScorer: Scorer 遍历文档并为每个文档生成一个分数。调用 createScorer 会创建负责评分的对象。请注意,与此任务相关的时间并非实际用于对文档进行评分的时间。计数包括 scorerSupplier 调用的次数。

  • createWeight: Weight 存储与查询和 IndexSearcher 相关的省/市/自治区。计数包含 createWeight 次调用的数量。

The time spent in this area is related to the structure of the query, and is not based on the number of results that are iterated through and scored.

例如:

"context" : {
"millisElapsed" : NumberDouble(4.934751),
"invocationCounts" : {
"createWeight" : NumberLong(1),
"createScorer" : NumberLong(10)
}
}

match

与遍历和匹配结果文档相关的统计信息。 此统计信息显示确定下一个匹配的文档所需的时间。 根据查询的性质,匹配结果所花费的时间可能会有很大差异。 此区域中枚举了两个任务的调用计数:

  • nextDoc:用于推进到结果集中的下一个文档的请求。这涉及识别并跳过跳过项,或执行查找下一个匹配项所需的其他任务。计数包括 nextDoc 和 advance 调用次数。

  • refineRoughMatch:执行更彻底的匹配。某些查询以两阶段过程执行,其中文档首先被“粗略”匹配,并且仅在满足第一次粗略匹配后才通过第二个更彻底的阶段进行检查。refineRoughMatch 任务是两阶段过程的第二阶段。计数包括 refineRoughMatch 调用的次数。

例如:

"match" : {
"millisElapsed" : NumberDouble(4.901597),
"invocationCounts" : {
"nextDoc" : NumberLong(541),
"refineRoughMatch" : NumberLong(0)
}
}

score

与结果集中的文档评分相关的统计信息。 此区域中枚举了两个任务的调用计数:

  • score: 对结果集中的每个文档进行评分。计数包括 score 次调用的数量。

  • setMinCompetitiveScore:忽略分数低于给定值的文档。表示查询可能通过忽略分数低于某些非竞争性阈值的文档,减少了执行的评分操作数量。计数包括 setMinCompetitiveScore 次调用的数量。

例如:

"score" : {
"millisElapsed" : NumberDouble(3.931312),
"invocationCounts" : {
"score" : NumberLong(536),
"setMinCompetitiveScore" : NumberLong(0)
}
}

resourceUsage 文档显示了用于运行查询的资源。它包含以下字段:

字段
类型
必要性
用途

majorFaults

Long

必需

主要页面错误的数量,当系统在查询执行期间无法在内存中找到所需数据,导致从磁盘等后备存储中读取数据时,就会发生这种错误。

minorFaults

Long

必需

次要页面错误的数量,当数据在页面缓存中,但尚未映射到进程的页表时发生。

userTimeMs

Long

必需

在用户空间中花费的 CPU 时间,以毫秒为单位。

systemTimeMs

Long

必需

在系统空间中花费的 CPU 时间,以毫秒为单位。

maxReportingThreads

整型

必需

在所有批处理中执行查询期间,mongot 使用的最大线程数。对于非并发解释查询,值为 1。

numBatches

整型

必需

处理查询时请求 mongot 的批处理总数。

vectorTracing数组包含对象列表,每个文档一个对象,其中包含有关文档中向量的以下详细信息:

字段
类型
必要性
用途

visited

布尔

必需

指定在查询执行期间是否访问过跟踪向量的标志。

dropReason

字符串

可选的

删除向量的原因。仅当访问了向量并将其从结果中删除时,才会出现此问题。值可以是:

  • Merge

  • NonCompetitiveScore

  • Filter

  • Rescoring

vectorSearchScore

double

可选的

与向量关联的分数。仅当向量被访问时才会出现

luceneSegment

整型

必需

Lucene segment number to which the vector belongs. To learn more, see luceneVectorSegmentStats.

unreachable

布尔

可选的

指定向量是否无法访问的标志。仅当向量无法访问时才会出现此问题。

luceneVectorSegmentStats 对象数组包含 $vectorSearch 查询执行的每个 Lucene 段的细分。每个分段都由一个数字标识,并包含描述查询执行详细信息的参数。

{
"0": {
"executionType": "Approximate",
"approximateTimeMillis": 0.10825,
"filterMatchedDocsCount": 0,
"docCount": 100
},
"1": {
"executionType": "Exact",
"exactTimeMillis": 0.10825,
"filterMatchedDocsCount": 0,
"docCount": 55
},
"2": {
"executionType": "ApproximateToExactFallback",
"approximateTimeMillis": 0.10825,
"exactTimeMillis": 0.10825,
"filterMatchedDocsCount": 0,
"docCount": 55
}
}
字段
类型
必要性
用途

executionType

字符串

必需

执行策略。值可以是以下之一:

  • Approximate

  • Exact

  • ApproximateToExactFallback

approximateStage

Float

可选的

近似阶段的时间(以毫秒为单位)。仅针对 Approximate 和 ApproximateFallbackToExact 执行类型返回此值。

exactStage

Float

可选的

Exact 阶段的时间(以毫秒为单位)。仅针对 Exact 和 ApproximateFallbackToExact 执行类型返回此值。

filterMatchedDocsCount

整型

Optional

如果您在查询中指定了前置筛选器,则为与查询筛选条件匹配的文档数。

docCount

整型

必需

该分段中的文档总数。

The following examples use the explain method on sample ANN and ENN queries. If you want to run the following examples in your own environment, you must first complete the MongoDB Vector Search Quick Start using mongosh.

The following example runs the explain method on an ANN and ENN vector search query for the plot_embedding_voyage_3_large field with the allPlansExecution verbosity mode.

db.embedded_movies.explain("allPlansExecution").aggregate([
{
"$vectorSearch": {
"index": "vector_index",
"path": "plot_embedding_voyage_3_large",
"queryVector": QUERY_EMBEDDING,
"numCandidates": 150,
"limit": 10
}
}
])

The following example runs the explain method on an ANN and ENN vector search query for the plot_embedding_voyage_3_large field with the queryPlanner verbosity mode.

db.embedded_movies.explain("queryPlanner").aggregate([
{
"$vectorSearch": {
"index": "vector_index",
"path": "plot_embedding_voyage_3_large",
"queryVector": QUERY_EMBEDDING,
"numCandidates": 150,
"limit": 10
}
}
])

The following example runs the explain method on an ANN and ENN vector search query for the plot_embedding_voyage_3_large field with the executionStats verbosity mode.

db.embedded_movies.explain("executionStats").aggregate([
{
"$vectorSearch": {
"index": "vector_index",
"path": "plot_embedding_voyage_3_large",
"queryVector": QUERY_EMBEDDING,
"numCandidates": 150,
"limit": 10
}
}
])