当您使用 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 的行为和返回的信息量。值可以是以下之一,按详细程度降序排列:
有关查询计划的信息,包括 | |
有关查询计划的信息,包括 | |
queryPlanner(默认) | 有关查询计划的信息。不包括 |
解释结果
explain 方法返回包含以下字段的BSON文档。
选项 | 类型 | 必要性 | 用途 |
|---|---|---|---|
| 文档 | Optional | 描述收集器的执行统计信息。 |
| 文档 | Optional | 包含有用的元数据。 |
| 文档 | Optional | 描述查询的执行统计信息。这在 |
| 文档 | Optional | 有关在查询执行后检索每个文档数据的详细信息。 |
| 文档 | Optional | 详细说明执行查询时的资源使用情况。对于 |
| 对象数组 | Optional | 跟踪有关指定文档中向量的详细信息,如下所示:
|
| 对象数组 | Optional |
|
collectors
collectors 是包含以下字段的BSON文档:
字段 | 类型 | 必要性 | 用途 |
|---|---|---|---|
| 文档 | 必需 | 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文档,描述查询中指定的所有收集器的收集器统计信息。它包含以下键:
字段 | 说明 |
|---|---|
| 追踪收集器收集的结果数量和持续时间。 |
| 统计信息跟踪从收集器请求 |
| 统计信息跟踪在收集器上设置记分器的总持续时间和次数。 |
metadata
metadata 包含有用的元数据,例如:
字段 | 类型 | 必要性 | 用途 |
|---|---|---|---|
| 字符串 | Optional |
|
| 字符串 | Optional | 用于标识 |
| 字符串 | Optional | 查询中使用的MongoDB Vector Search索引。 |
| 文档 | Optional | 为 |
| 整型 | Optional | 索引中的文档总数(包括已删除的文档)。 |
query
explain 响应是一个 BSON 文档,其中的键和值描述了查询的执行统计数据。结果集中的 explain 文档包含以下字段:
字段 | 类型 | 必要性 | 用途 |
|---|---|---|---|
| 字符串 | Optional | 所查询的 embedding 字段的路径(前提是它不是根)。 |
| 字符串 | 必需 | 向量搜索查询类型的名称。有关更多信息,请参阅 |
| 文档 | 必需 | 向量搜索查询信息。有关更多信息,请参阅 |
| 文档 | Optional |
|
args
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整型
必需
要检索的最近邻数量。
ExactVectorSearchQuery用于新奥向量搜索的查询类型。结构化摘要包含有关以下选项的详细信息:
字段类型必要性说明field字符串
必需
正在搜索的向量字段路径(Field Path)。
similarityFunction字符串
必需
使用的相似度函数(
dotProduct、cosine或euclidean)。filter文档
Optional
用于限制向量搜索范围的预过滤查询。
BooleanQueryIf you use a pre-filter in your vector search query, your explain results include the
BooleanQuerytype. 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.
stats
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.
时序细分
时间细分描述了与查询执行区域相关的执行统计信息。以下字段显示时间细分:
查询区域
统计信息可用于以下查询领域:
选项 | 说明 | |||||||
|---|---|---|---|---|---|---|---|---|
| 与向量搜索查询执行相关的统计信息。此区域中枚举了两个任务的调用计数:
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. 例如: | |||||||
| 与遍历和匹配结果文档相关的统计信息。 此统计信息显示确定下一个匹配的文档所需的时间。 根据查询的性质,匹配结果所花费的时间可能会有很大差异。 此区域中枚举了两个任务的调用计数:
例如: | |||||||
| 与结果集中的文档评分相关的统计信息。 此区域中枚举了两个任务的调用计数:
例如: |
resourceUsage
resourceUsage 文档显示了用于运行查询的资源。它包含以下字段:
字段 | 类型 | 必要性 | 用途 |
|---|---|---|---|
| Long | 必需 | 主要页面错误的数量,当系统在查询执行期间无法在内存中找到所需数据,导致从磁盘等后备存储中读取数据时,就会发生这种错误。 |
| Long | 必需 | 次要页面错误的数量,当数据在页面缓存中,但尚未映射到进程的页表时发生。 |
| Long | 必需 | 在用户空间中花费的 CPU 时间,以毫秒为单位。 |
| Long | 必需 | 在系统空间中花费的 CPU 时间,以毫秒为单位。 |
| 整型 | 必需 | 在所有批处理中执行查询期间, |
| 整型 | 必需 | 处理查询时请求 |
vectorTracing
vectorTracing数组包含对象列表,每个文档一个对象,其中包含有关文档中向量的以下详细信息:
字段 | 类型 | 必要性 | 用途 |
|---|---|---|---|
| 布尔 | 必需 | 指定在查询执行期间是否访问过跟踪向量的标志。 |
| 字符串 | 可选的 | 删除向量的原因。仅当访问了向量并将其从结果中删除时,才会出现此问题。值可以是:
|
| double | 可选的 | 与向量关联的分数。仅当向量被访问时才会出现 |
| 整型 | 必需 | Lucene segment number to which the vector belongs. To learn more, see |
| 布尔 | 可选的 | 指定向量是否无法访问的标志。仅当向量无法访问时才会出现此问题。 |
luceneVectorSegmentStats
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 } }
字段 | 类型 | 必要性 | 用途 |
|---|---|---|---|
| 字符串 | 必需 | 执行策略。值可以是以下之一:
|
| Float | 可选的 | 近似阶段的时间(以毫秒为单位)。仅针对 |
| Float | 可选的 | Exact 阶段的时间(以毫秒为单位)。仅针对 |
| 整型 | Optional | 如果您在查询中指定了前置筛选器,则为与查询筛选条件匹配的文档数。 |
| 整型 | 必需 | 该分段中的文档总数。 |
示例
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.
allPlansExecution
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 } } ])
db.embedded_movies.explain("allPlansExecution").aggregate([ { "$vectorSearch": { "index": "vector_index", "path": "plot_embedding_voyage_3_large", "queryVector": QUERY_EMBEDDING, "exact": true, "limit": 10 } } ])
queryPlanner
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 } } ])
db.embedded_movies.explain("queryPlanner").aggregate([ { "$vectorSearch": { "index": "vector_index", "path": "plot_embedding_voyage_3_large", "queryVector": QUERY_EMBEDDING, "exact": true, "limit": 10 } } ])
executionStats
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 } } ])
db.embedded_movies.explain("executionStats").aggregate([ { "$vectorSearch": { "index": "vector_index", "path": "plot_embedding_voyage_3_large", "queryVector": QUERY_EMBEDDING, "exact": true, "limit": 10 } } ])
db.embedded_movies.explain("executionStats").aggregate([ { "$vectorSearch": { "index": "vector_index", "path": "plot_embedding_voyage_3_large", "queryVector": QUERY_EMBEDDING, "numCandidates": 150, "limit": 10, "explainOptions": { "traceDocumentIds": [ ObjectId('573a13d8f29313caabda6557'), ObjectId('573a1398f29313caabce98d9'), ObjectId('573a1391f29313caabcd8319'), ObjectId('573a1398f29313caabceb500'), ObjectId('573a1397f29313caabce780e') ] } } } ])