Docs 菜单
Docs 主页
/
MongoDB Manual
/
聚合操作
/
参考
/
阶段(Stages)

$queryStats（聚合）

在此页面上

  • 定义
  • 要求
  • 语法
  • 命令字段
  • 访问控制
  • 行为
  • $queryStats 如何追踪查询统计信息
  • $queryStats 如何对返回的文档进行分组
  • $queryStats 如何使用transformIdentifiers 转换数据
  • $queryStats Log Entries
  • Change Streams
  • 输出
  • collectionType
  • 查询结构
  • 示例
  • 未转换示例
  • 转换后的示例
  • MongoDB Atlas collection

定义

$queryStats

警告

$queryStats聚合阶段不受支持，也不能保证在未来版本中保持稳定。 不要构建依赖于此阶段的特定输出格式的功能，因为输出可能会在将来的版本中发生变化。

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

$queryStats 收集并报告 aggregate() 、 find()和distinct()查询的指标。 $queryStats不收集使用Queryable Encryption的查询信息。

要求

$queryStats阶段在集群层至少为 M 10的 MongoDB Atlas上托管的部署上启用。

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

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

  • $queryStats 必须是管道的第一阶段。

语法

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

重要

您无法在特定集合上运行$queryStats 。 有关完整示例，请参阅示例。

命令字段

$queryStats 采用以下字段：

字段
必要性
类型
说明
transformIdentifiers
Optional
文档
为$queryStats输出指定其他转换选项。
transformIdentifiers
.algorithm
如果指定transformIdentifiers对象，则为必填项
字符串
应用于输出中的命名空间信息和字段名称的哈希转换类型。 当前唯一支持的algorithm值为hmac-sha-256 。
transformIdentifiers
.hmacKey
如果指定transformIdentifiers对象，则为必填项
BinData
HMAC 转换中输入的私钥。

访问控制

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

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

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

行为

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

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

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

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

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

$queryStats 通过将用户提供的字段值规范化为其数据类型，将类似的查询分组在一起。 例如，指定为{ item: 'card' }的筛选器将规范化为{ item : '?string'} 。 $queryStats还会规范化某些查询选项（如hint和comment的值。

$queryStats 保留readConcern和readPreference等选项的字面值。

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

$queryStats 如何使用transformIdentifiers 转换数据

当为transformIdentifiers选项指定了 HMAC 密钥时， $queryStats使用该 HMAC 密钥对以下数据应用 HMAC-SHA-256 哈希函数：

  • 文档字段名称

  • 集合名称

  • 数据库名称

$queryStats 不会对以下数据应用 HMAC 转换：

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

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

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

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

$queryStats Log Entries

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

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

Change Streams

发生以下事件之一时，变更流的查询统计信息会更新：

  • 创建游标

  • getMore操作完成

  • 游标关闭

为变更流报告的查询统计信息具有以下行为：

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

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

  • firstResponseExecMicros 和totalExecMicros始终相同，因为会为每个getMore操作收集和更新统计信息。

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

输出

$queryStats 返回查询统计信息条目的数组。 某些查询统计信息条目属性包含字面值，某些属性已标准化以对常见查询进行分组。

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

文档
说明
key

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

每个唯一的属性组合都会在$queryStats虚拟collection中创建一个单独的条目。

asOf
$queryStats从$queryStats虚拟collection中读取此条目时的 UTC 时间。asOf不一定会为每个结果返回相同的 UTC 时间。 在内部，数据结构被分区，每个分区将在单独的时间点读取。
metrics
包含与每个查询统计信息条目关联的聚合运行时指标。 每个查询统计信息条目都记录共享相同密钥的每个查询的统计信息。

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

字段
类型
字面值或规范化值
说明
key
文档
$literal
包含查询结构和将一组查询分组在一起的其他查询属性
key.queryShape
文档
$literal
包含用于将相似查询群组在一起的属性。 有关详细信息，请参阅查询结构。
key.client
文档
$literal
描述与密钥关联的客户端信息
key.client.application
文档
$literal
客户端应用程序名称
key.client.driver
文档
$literal
描述用于发出查询的驱动程序
key.client.driver.name
字符串
$literal
用于发出查询的驱动程序的名称。 可能的值包括mongosh和nodejs 。
key.client.driver.version
字符串
$literal
用于发出查询的驱动程序的版本号
key.client.os
文档
$literal
描述发出查询的客户端使用的操作系统
key.client.os.type
字符串
$literal
操作系统类型
key.client.os.name
字符串
$literal
操作系统名称
key.client.os.architecture
字符串
$literal
操作系统的架构。 可能的值包括arm64和x86_64 。
key.client.os.version
字符串
$literal
操作系统的版本号
key.readConcern
文档
$literal
key.collectionType
字符串
$literal
发出查询的集合类型。 有关详细信息，请参阅集合类型。
key.hint
文档或字符串
标准化
用作查询提示的索引
key.batchSize
字符串
标准化
键的批处理大小。 批处理大小指定来自 MongoDB 实例的每批响应中要返回的文档数量。
key.comment
字符串
标准化
与键关联的注释
key.maxTimeMS
字符串
标准化
与键关联的maxTimeMS值
key.noCursorTimeout
布尔
标准化
与键关联的noCursorTimeout选项
key.allowPartialResults
字符串
$literal
与键关联的allowPartialResults选项
key.readPreference
字符串
$literal
key.apiVersion
字符串
$literal
与密钥关联的 Stable API 版本。 请参阅stable API。
key.apiStrict
布尔
$literal
与键关联的apiStrict参数值。 请参阅stable API 参数。
key.apiDeprecationErrors
布尔
$literal
与键关联的apiDeprecationErrors参数值。 请参阅stable API 参数。
keyHash
字符串
$literal
key中值的哈希表示。 每个唯一的keyHash值对应于$queryStats内存存储中的一个唯一条目。
metrics
文档
$literal
描述密钥的运行时统计信息
metrics.lastExecutionMicros
NumberLong
$literal
具有给定键的所有查询的最新查询的执行运行时
metrics.execCount
NumberLong
$literal
已执行具有给定键的查询的次数
metrics.keysExamined
文档
$literal
描述查询检查的键的数量
metrics
.keysExamined
.sum
整型
$literal
检查的键总数
metrics
.keysExamined
.max
NumberLong
$literal
检查的最大键数
metrics
.keysExamined
.min
NumberLong
$literal
检查的键数量最少
metrics
.keysExamined
.sumOfSquares
NumberDecimal
$literal

检查的键数量的平方和。

sumOfSquares值较高表示各个查询中检查的键数量差异较大。

metrics.docsExamined
文档
$literal
描述查询检查的文档数量
metrics
.docsExamined
.sum
整型
$literal
查询中检查的文档总数
metrics
.docsExamined
.max
NumberLong
$literal
检查的最大文档数
metrics
.docsExamined
.min
NumberLong
$literal
最少检查文件数量
metrics
.docsExamined
.sumOfSquares
NumberDecimal
$literal

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

sumOfSquares值较高表示各个查询中检查的文档数量差异较大。

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

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

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

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

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

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

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

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

sumOfSquares值较高表示查询处理时间的差异较大。

metrics.docsReturned
文档
$literal
描述键内查询返回的文档数量
metrics
.docsReturned
.sum
NumberLong
$literal
使用给定键的查询返回的文档总数
metrics
.docsReturned
.max
NumberLong
$literal
使用给定键的查询返回的最大文档数
metrics
.docsReturned
.min
NumberLong
$literal
使用给定键的查询返回的最少文档数
metrics
.docsReturned
.sumOfSquares
NumberDecimal
$literal

查询在键内返回的文档数量的平方和。

sumOfSquares值较高表示各个查询之间返回的文档数量差异较大。

metrics.firstSeenTimestamp
Date
$literal
自上次重启以来首次使用具有给定键的查询的时间
metrics.lastSeenTimestamp
Date
$literal
最近一次使用具有给定键的查询的时间

collectionType

key.collectionType字段表示发出记录查询的集合类型。 collectionType可以是以下值之一：

字段
说明
changeStream
collection
查询是对标准集合发出的。
nonExistent
对不存在的collection发出查询。
timeseries
view
查询是对视图发出的。
virtual

该查询是对虚拟集合发出的。 以下操作发生在虚拟collection中：

查询结构

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

key.queryShape中的字段因生成查询统计条目的命令而异。 $queryStats为aggregate 、 find和distinct命令创建查询统计信息条目。

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

find 命令查询结构

下表描述了find命令的查询结构属性。

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

aggregate 命令查询结构

下表描述了aggregate命令的查询结构属性。

字段
类型
字面值或规范化值
key.queryShape.pipeline
阵列
标准化
key.queryShape.explain
布尔
$literal
key.queryShape.allowDiskUse
布尔
$literal
key.queryShape.collation
文档
$literal
key.queryShape.hint
字符串或文档
标准化
key.queryShape.let
文档
标准化

distinct 命令查询结构

下表描述了distinct命令的查询结构属性。

字段
类型
字面值或规范化值
key.queryShape.key
字符串
$literal
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 collection

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

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

后退

$querySettings

来年

切换日志输出