文档菜单
文档首页
/
MongoDB 手册
/
聚合操作
/
参考
/
阶段

$queryStats (聚合)

本页内容

  • 定义
  • 要求
  • 语法
  • 命令字段
  • 访问控制
  • 行为
  • 如何 $queryStats 跟踪查询统计信息
  • 如何 $queryStats 对返回的文档进行分组
  • 如何 $queryStats 使用 transformIdentifiers 转换数据
  • $queryStats 日志条目
  • 变更流
  • 输出
  • 集合类型
  • 查询形状
  • 示例
  • 未转换示例
  • 转换示例
  • MongoDB Atlas 数据收集

定义

$queryStats

警告

《$queryStats》聚合阶段不受支持，并且无法保证在未来版本中稳定。不要构建依赖于该阶段特定输出格式的功能，因为该阶段的输出可能在未来的版本中发生变化。

返回记录查询的运行时统计信息。

《$queryStats》收集并报告以下查询的指标：aggregate()、find() 和 distinct()。`$queryStats` 不收集使用 可查询加密 的查询信息。

要求

《$queryStats》阶段在部署到以下环境时启用MongoDB Atlas 且集群等级至少为 M10。

要运行《$queryStats》阶段，您的管道必须满足以下要求

  • 管道必须在 admin 数据库上运行。

  • 《$queryStats》必须是管道中的第一个阶段。

语法

db.adminCommand( {
   aggregate: 1,
   pipeline: [
      {
         $queryStats: {
            transformIdentifiers: {
               algorithm: <string>,
               hmacKey: <binData> /* subtype 8 - used for sensitive data */
            }
         }
      }
   ],
   cursor: { }
 } )

重要

您不能在特定的集合上运行《$queryStats》。有关完整示例，请参阅 示例。

命令字段

$queryStats 接受以下字段

字段
必要性
类型
描述
transformIdentifiers
可选
文档
指定 $queryStats 输出的额外转换选项。
transformIdentifiers
.algorithm
指定 transformIdentifiers 对象时必填
字符串
应用于输出命名空间信息和字段名的哈希转换类型。目前支持的唯一 algorithm 值是 hmac-sha-256。
transformIdentifiers
.hmacKey
指定 transformIdentifiers 对象时必填
binData
HMAC 转换中的私钥输入。

访问控制

如果您的部署强制执行访问控制，则运行 $queryStats 的用户必须具有以下权限

  • 要在没有 transformIdentifiers 选项的情况下运行 $queryStats，用户必须具有 queryStatsRead 权限操作。

  • 要在具有 transformIdentifiers 选项的情况下运行 $queryStats，用户必须具有 queryStatsRead 和 queryStatsReadTransformed 权限操作。

内置的 clusterMonitor 角色提供了 queryStatsRead 和 queryStatsReadTransformed 权限。以下示例在 admin 数据库上授予了 clusterMonitor 角色

db.grantRolesToUser(
   "<user>",
   [ { role: "clusterMonitor", db: "admin" } ]
)

行为

以下部分描述了$queryStats阶段的详细行为。

$queryStats如何跟踪查询统计信息

$queryStats阶段的统计信息存储在内存中的虚拟集合中。虚拟集合的内存限制为系统总内存的1%。

$queryStats如何对返回的文档进行分组

$queryStats将具有相同属性的查询分组到相同的输出文档中。生成的文档称为查询统计条目。

$queryStats通过将用户提供的字段值标准化到其数据类型来将相似查询分组在一起。例如，指定为{ item: 'card' }的过滤器被标准化为{ item : '?string'}。$queryStats还标准化了一些查询选项的值，如hint和comment。

$queryStats保留readConcern和readPreference等选项的原始值。

有关查询统计条目中包含的完整选项列表，请参阅find命令查询形状。

如何 $queryStats 通过 transformIdentifiers 转换数据

当指定 HMAC 密钥给 transformIdentifiers 选项时，$queryStats 使用 HMAC 密钥对以下数据进行 HMAC-SHA-256 哈希函数处理

  • 文档字段名

  • 集合名称

  • 数据库名称

$queryStats 不会 对以下数据进行 HMAC 转换

  • 操作符名称等 MQL 关键字（例如，$gte）。

  • 参数名称，如 $setWindowFields 中的 partitionBy 参数。

  • 字段值。当记录查询时，$queryStats 将查询中的字段值规范化为其数据类型（如数字或字符串）。$queryStats 从不存储包含用户数据的字段值。

有关转换输出示例，请参阅 转换示例。

$queryStats 日志条目

MongoDB 在 部署日志 中记录 $queryStats 操作。默认情况下，MongoDB 只记录 $queryStats 操作的调用，而不记录操作输出。对于包含 transformIdentifiers 选项的 $queryStats 操作，您可以指定是否将转换输出包含在日志条目中。

要了解如何控制 $queryStats 日志行为，请参阅切换 $queryStats 日志输出。

Change Streams

当以下事件发生时，change streams 的查询统计信息会更新：

  • 创建了一个游标

  • getMore 操作完成

  • 游标关闭

change streams 报告的查询统计信息具有以下行为

  • 执行指标，如 totalExecMicros，包含最近操作（游标创建、getMore 或游标关闭）的信息。

  • 内部 getMore 操作会增加 execCount 指标。

  • firstResponseExecMicros 和 totalExecMicros 总是相同的，因为统计信息为每个 getMore 操作收集和更新。

  • 当游标关闭时，lastExecutionMicros 为 0。

输出

$queryStats 返回一个查询统计条目数组。一些查询统计条目属性包含文本值，而一些属性被归一化以分组常见查询。

查询统计条目包含以下顶级文档

文档
描述
key

定义查询统计输出条目的属性的唯一组合。`key` 包含以下属性：

每个属性的独特组合都会在虚拟集合$queryStats中创建一个独立的条目。

asOf
UTC时间，当时$queryStats从虚拟集合$queryStats读取此条目。asOf不一定为每个结果返回相同的UTC时间。内部，数据结构被分区，每个分区将在不同的时间点被读取。
metrics
包含与每个查询统计条目关联的聚合运行时度量。每个查询统计条目记录具有相同键的每个查询的统计信息。

输出数组中的每个文档包含以下字段

字段
类型
文字或标准化
描述
key
文档
文字
包含查询形状和将一组查询组合在一起的附加查询属性
key.queryShape
文档
文字
包含用于将类似查询组合在一起的属性。有关更多信息，请参阅查询形状。
key.client
文档
文字
描述与键关联的客户信息
key.client.application
文档
文字
客户端应用程序名称
key.client.driver
文档
文字
描述用于发出查询的驱动程序
key.client.driver.name
字符串
文字
用于发出查询的驱动程序名称。可能的值包括mongosh和nodejs。
key.client.driver.version
字符串
文字
用于发出查询的驱动程序的版本号
key.client.os
文档
文字
描述发出查询的客户端使用的操作系统
key.client.os.type
字符串
文字
操作系统类型
key.client.os.name
字符串
文字
操作系统名称
key.client.os.architecture
字符串
文字
操作系统的体系结构。可能的值包括arm64和x86_64。
key.client.os.version
字符串
文字
操作系统的版本号
key.readConcern
文档
文字
key.collectionType
字符串
文字
查询发出的集合类型。有关更多信息，请参阅集合类型。
key.hint
文档或字符串
标准化
用作查询提示的索引
key.batchSize
字符串
标准化
键的批大小。批大小指定MongoDB实例响应的每个批次中返回的文档数。
key.comment
字符串
标准化
与键关联的注释
key.maxTimeMS
字符串
标准化
与键关联的maxTimeMS值
key.noCursorTimeout
布尔值
标准化
与键关联的noCursorTimeout选项
key.allowPartialResults
字符串
文字
与键关联的allowPartialResults选项
key.readPreference
字符串
文字
与键关联的读取首选项
key.apiVersion
字符串
文字
与键关联的稳定API版本。请参阅稳定API。
key.apiStrict
布尔值
文字
与键关联的 apiStrict 参数值。请参阅稳定API参数。
key.apiDeprecationErrors
布尔值
文字
与键关联的 apiDeprecationErrors 参数值。请参阅稳定API参数。
keyHash
字符串
文字
key 中值的散列表示。每个唯一的 keyHash 值对应于 $queryStats 内存存储中的一个唯一条目。
metrics
文档
文字
描述键的运行时统计信息
metrics.lastExecutionMicros
NumberLong
文字
给定键的所有查询中最最近查询的执行时间
metrics.execCount
NumberLong
文字
给定键的查询被执行的次数
metrics.keysExamined
文档
文字
描述查询检查的键的数量
metrics
.keysExamined
.sum
Integer
文字
检查的键的总数
metrics
.keysExamined
.max
NumberLong
文字
检查的键的最大数量
metrics
.keysExamined
.min
NumberLong
文字
检查的键的最小数量
metrics
.keysExamined
.sumOfSquares
NumberDecimal
文字

检查的键数量的平方和。

高 sumOfSquares 值表示单个查询中检查的键数量的方差较高。

metrics.docsExamined
文档
文字
描述查询检查的文档数量
metrics
.docsExamined
.sum
Integer
文字
查询中检查的文档总数
metrics
.docsExamined
.max
NumberLong
文字
检查的文档的最大数量
metrics
.docsExamined
.min
NumberLong
文字
检查的文档的最小数量
metrics
.docsExamined
.sumOfSquares
NumberDecimal
文字

检查的文档数量的平方和。

高 sumOfSquares 值表示单个查询中检查的文档数量的方差较高。

metrics.hasSortStage
布尔值
文字
true 当MongoDB必须在从游标接收文档后对文档进行排序时。
metrics.usedDisk
布尔值
文字
true 当查询由于内存限制而将数据写入临时文件时。
metrics.fromMultiPlanner
布尔值
文字
true 当查询规划器在为查询选择获胜的执行计划之前评估多个计划时。
metrics.fromPlanCache
布尔值
文字
true 当查询规划器能够从计划缓存中使用计划时。
metrics.totalExecMicros
文档
文字

描述使用给定键运行查询所花费的总时间。如果查询导致了getMores，则 totalExecMicros 包括处理 getMore 请求所花费的时间。totalExecMicros 不包括等待客户端的时间。

totalExecMicros 的所有子字段均以微秒为单位报告。

metrics
.totalExecMicros
.sum
NumberLong
文字
使用给定键运行查询所花费的总时间
metrics
.totalExecMicros
.max
NumberLong
文字
使用给定键运行查询所花费的最长时间
metrics
.totalExecMicros
.min
NumberLong
文字
使用给定键运行查询所花费的最短时间
metrics
.totalExecMicros
.sumOfSquares
NumberDecimal
文字
所有给定键的查询的总执行时间的平方和。高 sumOfSquares 值表示查询执行时间的方差较高。
metrics
.firstResponseExecMicros
文档
文字

描述从键内的查询开始处理到服务器返回第一批结果所花费的时间

firstResponseExecMicros 的所有子字段均以微秒为单位报告。

metrics
.firstResponseExecMicros
.sum
NumberLong
文字
从查询处理开始到服务器返回第一批结果所花费的总时间
metrics
.firstResponseExecMicros
.max
NumberLong
文字
从查询处理开始到服务器返回第一批结果所花费的最长时间
metrics
.firstResponseExecMicros
.min
NumberLong
文字
从查询处理开始到服务器返回第一批结果所花费的最短时间
metrics
.firstResponseExecMicros
.sumOfSquares
NumberDecimal
文字

从查询处理开始到服务器返回第一批结果所花费的时间总和的平方

高 sumOfSquares 值表示查询处理时间的高方差。

metrics.docsReturned
文档
文字
描述了在关键字范围内查询返回的文档数量
metrics
.docsReturned
.sum
NumberLong
文字
具有给定关键字的查询返回的文档总数
metrics
.docsReturned
.max
NumberLong
文字
具有给定关键字的查询返回的文档的最大数量
metrics
.docsReturned
.min
NumberLong
文字
具有给定关键字的查询返回的文档的最少数量
metrics
.docsReturned
.sumOfSquares
NumberDecimal
文字

关键字范围内查询返回的文档数量的平方和

高 sumOfSquares 值表示单个查询之间返回的文档数量高方差。

metrics.firstSeenTimestamp
日期
文字
自上次重启以来，具有给定关键字的查询首次使用的时间
metrics.lastSeenTimestamp
日期
文字
具有给定关键字的查询最近使用的时间

集合类型

key.collectionType 字段指示记录的查询是在哪种集合上发出的。集合类型可以是以下值之一

字段
描述
changeStream
collection
查询是在标准 集合 上发出的。
nonExistent
查询是在不存在的集合上发出的。
timeseries
查询是在 时间序列集合 上发出的。
view
查询是在 视图 上发出的。
virtual

查询是在虚拟集合上发出的。虚拟集合中发生以下操作

查询形状

文档 key.queryShape 包含查询形状字段。要了解查询形状，请参阅 查询形状。

在 key.queryShape 中的字段根据导致查询统计条目生成的命令而异。 $queryStats 为 aggregate、find 和 distinct 命令创建查询统计条目。

每个查询形状属性对应一个查询选项。例如，key.queryShape.sort 对应于查询形状的 sort() 规范。

find 命令查询形状

以下表格描述了 find 命令的查询形状属性。

字段
类型
文字或标准化
key.queryShape.filter
文档
标准化
key.queryShape.sort
文档
文字
key.queryShape.projection
文档
标准化
key.queryShape.skip
Integer
标准化
key.queryShape.limit
Integer
标准化
key.queryShape.singleBatch
布尔值
文字
key.queryShape.max
文档
标准化
key.queryShape.min
文档
标准化
key.queryShape.returnKey
布尔值
文字
key.queryShape.showRecordId
布尔值
文字
key.queryShape.tailable
布尔值
文字
key.queryShape.oplogReplay
布尔值
文字
key.queryShape.awaitData
布尔值
文字
key.queryShape.collation
文档
文字
key.queryShape.allowDiskUse
布尔值
文字
key.queryShape.let
文档
标准化

aggregate 命令查询形状

以下表格描述了 aggregate 命令的查询形状属性。

字段
类型
文字或标准化
key.queryShape.pipeline
数组
标准化
key.queryShape.explain
布尔值
文字
key.queryShape.allowDiskUse
布尔值
文字
key.queryShape.collation
文档
文字
key.queryShape.hint
字符串或文档
标准化
key.queryShape.let
文档
标准化

独特的命令查询形状

下表描述了distinct命令的查询形状属性。

字段
类型
文字或标准化
key.queryShape.key
字符串
文字
key.queryShape.collation
文档
标准化
key.queryShape.query
文档
标准化

示例

要运行本节中的示例，请从以下数据开始

db.products.insertMany(
  [
    { item: "card", qty: 15 },
    { item: "envelope", qty: 20 },
    { item: "stamps" , qty: 30 }
  ]
)

然后运行以下命令

db.products.find( { item: "card" } )
db.products.aggregate( [
   {
      $match: { qty: { $gt: 20 } }
   }
] )

以下示例展示了使用不同类型的数据转换运行$queryStats的输出

未转换示例

输入

db.getSiblingDB("admin").aggregate( [
   {
      $queryStats: { }
   }
] )

输出

[
  {
    key: {
      queryShape: {
        cmdNs: { db: 'test', coll: 'products' },
        command: 'find',
        filter: { item: { '$eq': '?string' } }
      },
      client: {
        driver: { name: 'nodejs|mongosh', version: '5.1.0' },
        os: {
          type: 'Darwin',
          name: 'darwin',
          architecture: 'arm64',
          version: '22.6.0'
        },
        platform: 'Node.js v16.19.1, LE (unified)',
        version: '5.1.0|1.8.0',
        application: { name: 'mongosh 1.8.0' }
      },
      collectionType: 'collection'
    },
    keyHash: 'dsoJ+LHAru0z6MJ1/IygJnnLTrlpVYYmPnlmNZbZrLI=',
    metrics: {
      lastExecutionMicros: Long("4254"),
      execCount: Long("1"),
      totalExecMicros: {
        sum: Long("4254"),
        max: Long("4254"),
        min: Long("4254"),
        sumOfSquares: Decimal128("18096516")
      },
      firstResponseExecMicros: {
        sum: Long("4254"),
        max: Long("4254"),
        min: Long("4254"),
        sumOfSquares: Decimal128("18096516")
      },
      docsReturned: {
        sum: Long("1"),
        max: Long("1"),
        min: Long("1"),
        sumOfSquares: Decimal128("1")
      },
      firstSeenTimestamp: ISODate("2023-09-14T12:30:27.989Z"),
      latestSeenTimestamp: ISODate("2023-09-14T12:30:27.989Z")
    },
    asOf: Timestamp({ t: 1694695007, i: 0 })
  },
  {
    key: {
      queryShape: {
        cmdNs: { db: 'test', coll: 'products' },
        command: 'aggregate',
        pipeline: [
          { '$match': { qty: { '$gt': '?number' } } }
        ]
      },
      apiVersion: '1',
      client: {
        driver: { name: 'nodejs|mongosh', version: '5.1.0' },
        os: {
          type: 'Darwin',
          name: 'darwin',
          architecture: 'arm64',
          version: '22.6.0'
        },
        platform: 'Node.js v16.19.1, LE (unified)',
        version: '5.1.0|1.8.0',
        application: { name: 'mongosh 1.8.0' }
      },
      collectionType: 'collection',
      cursor: { batchSize: '?number' }
    },
    keyHash: '2QLBfL0m1lliStdN4XvBjqVBtZQ6ffaB2L1pJ99twT8=',
    metrics: {
      lastExecutionMicros: Long("350"),
      execCount: Long("3"),
      totalExecMicros: {
        sum: Long("3084"),
        max: Long("2499"),
        min: Long("235"),
        sumOfSquares: Decimal128("6422726")
      },
      firstResponseExecMicros: {
        sum: Long("3084"),
        max: Long("2499"),
        min: Long("235"),
        sumOfSquares: Decimal128("6422726")
      },
      docsReturned: {
        sum: Long("3"),
        max: Long("1"),
        min: Long("1"),
        sumOfSquares: Decimal128("3")
      },
      firstSeenTimestamp: ISODate("2023-11-29T21:16:17.796Z"),
      latestSeenTimestamp: ISODate("2023-11-29T21:17:12.385Z")
    },
    asOf: Timestamp({ t: 1701292827, i: 0 })
  }
]

转换示例

输入

db.getSiblingDB("admin").aggregate( [
   {
      $queryStats: {
         transformIdentifiers: {
            algorithm: "hmac-sha-256" ,
            hmacKey: BinData(8, "87c4082f169d3fef0eef34dc8e23458cbb457c3sf3n2")
         }
       }
    }
 ] )

输出

[
  {
    key: {
      queryShape: {
        cmdNs: {
          db: 'Mtrt3iG7dsX5c5uCSIhSVlcu5qD3u3xx2EQnS1dJLxM=',
          coll: '3oJE6AyOuf8h5NqWiXETxulFlPm3QUXbMnMjL2EqAU4='
        },
        command: 'find',
        filter: {
          'VWVRow7Ure92ajRPfrpWiU8OtDeWcLePFIq0+tooBng=': { '$eq': '?string' }
        }
      },
      client: {
        driver: { name: 'nodejs|mongosh', version: '5.1.0' },
        os: {
          type: 'Darwin',
          name: 'darwin',
          architecture: 'arm64',
          version: '22.6.0'
        },
        platform: 'Node.js v16.19.1, LE (unified)',
        version: '5.1.0|1.8.0',
        application: { name: 'mongosh 1.8.0' }
      },
      collectionType: 'collection'
    },
    keyHash: 'q4vxam+wbk8tTrl8D0MDFH1LQAbI8fWspfkGKhEUROk=',
    metrics: {
      lastExecutionMicros: Long("4254"),
      execCount: Long("1"),
      keysExamined: {
        sum: Int("5"),
        max: Long("5"),
        min: Long("5"),
        sumOfSquares: Decimal128("25")
      },
      docsExamined: {
        sum: Long("1"),
        max: Long("1"),
        min: Long("1"),
        sumOfSquares: Decimal128("1")
      },
      hasSortStage: false,
      usedDisk: false,
      fromMultiPlanner: false,
      fromPlanCache: true,
      totalExecMicros: {
        sum: Long("4254"),
        max: Long("4254"),
        min: Long("4254"),
        sumOfSquares: Decimal128("18096516")
      },
      firstResponseExecMicros: {
        sum: Long("4254"),
        max: Long("4254"),
        min: Long("4254"),
        sumOfSquares: Decimal128("18096516")
      },
      docsReturned: {
        sum: Long("1"),
        max: Long("1"),
        min: Long("1"),
        sumOfSquares: Decimal128("1")
      },
      firstSeenTimestamp: ISODate("2023-09-14T12:30:27.989Z"),
      latestSeenTimestamp: ISODate("2023-09-14T12:30:27.989Z")
    },
    asOf: Timestamp({ t: 1694695712, i: 0 })
  },
  {
    key: {
      queryShape: {
        cmdNs: {
          db: 'Mtrt3iG7dsX5c5uCSIhSVlcu5qD3u3xx2EQnS1dJLxM=',
          coll: '3oJE6AyOuf8h5NqWiXETxulFlPm3QUXbMnMjL2EqAU4='
        },
        command: 'aggregate',
        pipeline: [
          {
            '$match': {
              'RVqrwNEPotzdKnma/T7s4YcgNvpqO29BMDoni2N4IMI=': { '$gt': '?number' }
            }
          }
        ]
      },
      apiVersion: '1',
      client: {
        driver: { name: 'nodejs|mongosh', version: '5.1.0' },
        os: {
          type: 'Darwin',
          name: 'darwin',
          architecture: 'arm64',
          version: '22.6.0'
        },
        platform: 'Node.js v16.19.1, LE (unified)',
        version: '5.1.0|1.8.0',
        application: { name: 'mongosh 1.8.0' }
      },
      collectionType: 'collection',
      cursor: { batchSize: '?number' }
    },
    keyHash: 'HEhpQTYB+/wVoHLkOkMd+EC2jguQlMJ1N/vTE7+b8Js=',
    metrics: {
      lastExecutionMicros: Long("350"),
      execCount: Long("3"),
      keysExamined: {
        sum: Int("5"),
        max: Long("5"),
        min: Long("5"),
        sumOfSquares: Decimal128("25")
      },
      docsExamined: {
        sum: Long("1"),
        max: Long("1"),
        min: Long("1"),
        sumOfSquares: Decimal128("1")
      },
      hasSortStage: false,
      usedDisk: false,
      fromMultiPlanner: false,
      fromPlanCache: true,
      totalExecMicros: {
        sum: Long("3084"),
        max: Long("2499"),
        min: Long("235"),
        sumOfSquares: Decimal128("6422726")
      },
      firstResponseExecMicros: {
        sum: Long("3084"),
        max: Long("2499"),
        min: Long("235"),
        sumOfSquares: Decimal128("6422726")
      },
      docsReturned: {
        sum: Long("3"),
        max: Long("1"),
        min: Long("1"),
        sumOfSquares: Decimal128("3")
      },
      firstSeenTimestamp: ISODate("2023-11-29T21:16:17.796Z"),
      latestSeenTimestamp: ISODate("2023-11-29T21:17:12.385Z")
    },
    asOf: Timestamp({ t: 1701293302, i: 0 })
  },
]

MongoDB Atlas 数据收集

MongoDB Atlas 定期使用 $queryStats 收集关于您的查询的匿名数据，这有助于改进 MongoDB 产品。您的数据还可能被用于根据使用情况提出功能建议。MongoDB 将使用 $queryStats 收集的数据保留四年。

当 Atlas 在您的部署上运行 $queryStats 时，它使用 Atlas 组织的每个独特的 HMAC 密钥来转换您的数据，以避免收集敏感信息。

返回

$querySettings

下一页

切换日志输出