$queryStats(集計)
項目一覧
バージョン7.0.12の新機能: ( 6.0.7以降でも利用可能)
定義
警告
$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 | 任意 | ドキュメント | $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 コマンド クエリシェイプ を参照してください。
transformIdentifiers を使用して $queryStats がデータを変換する方法
HMAC キーがtransformIdentifiers
オプションに指定されている場合、 $queryStats
は HMAC キーを使用して、次のデータに HMAC-SHA-256 ハッシュ関数を適用します。
ドキュメント フィールド名
コレクション名
データベース名
$queryStats
では、次のデータには HMAC 変換は適用されません。
演算子名などの MQL キーワード(例:
$gte
)。パラメータ名(
$setWindowFields
のpartitionBy
パラメータなど)フィールド値。
$queryStats
は、クエリが記録されるときに、クエリ内のフィールド値をデータ型( 数値 やstringなど)に正規化します。$queryStats
はユーザー データを含むフィールド値を保存しません。
変換された出力の例については、「変換された例 」を参照してください。
$queryStats Log Entries
MongoDB は配置ログに$queryStats
操作を記録します。デフォルトでは、MongoDB は$queryStats
操作の呼び出しのみをログに記録し、操作の出力は記録しません。transformIdentifiers
オプションを含む$queryStats
操作の場合、変換された出力をログ エントリに含めるかどうかを指定できます。
$queryStats
のログ動作を制御する方法については、「 $queryStats ログ出力の切り替え 」を参照してください。
出力
$queryStats
は、クエリ統計エントリの配列を返します。 一部のクエリ統計エントリ プロパティにはリテラル値が含まれており、一部のプロパティは一般的なクエリをグループ化するように正規化されています。
クエリ統計エントリには、次の最上位ドキュメントが含まれます。
ドキュメント | 説明 |
---|---|
key | クエリ統計出力のエントリを定義する属性の一意の組み合わせ。
属性の一意の組み合わせごとに、 |
asOf | $queryStats が$queryStats 仮想コレクションからこのエントリを読み取った 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 | キーの 読み取り保証 ( read concern ) |
key.collectionType | 文字列 | literal | クエリが発行されたコレクションのタイプ。 詳細については、「コレクション タイプ 」を参照してください。 |
key.hint | ドキュメントまたは文字列 | 正規化 | クエリのヒントとして使用されたインデックス |
key.batchSize | 文字列 | 正規化 | キーのバッチ サイズ。 バッチ サイズは、MongoDB インスタンスからの応答の各バッチで返されるドキュメントの数を指定します。 |
key.comment | 文字列 | 正規化 | キーに関連付けられたコメント |
key.maxTimeMS | 文字列 | 正規化 | キーに関連付けられたmaxTimeMS値 |
key.noCursorTimeout | ブール値 | 正規化 | キーに関連付けられたnoCursorTimeoutオプション |
key.allowPartialResults | 文字列 | literal | キーに関連付けられたallowPartialResultsオプション |
key.readPreference | 文字列 | literal | キーに関連付けられた読み込み設定(read preference ) |
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 | 検査されたキーの数の正方形の合計。
|
metrics.docsExamined | ドキュメント | literal | クエリによって検査されたドキュメントの数を示します |
metrics .docsExamined .sum | 整数 | literal | クエリで検査されたドキュメントの合計数 |
metrics .docsExamined .max | NumberLong | literal | 検査されたドキュメントの最大数 |
metrics .docsExamined .min | NumberLong | literal | 検査されたドキュメントの最小数 |
metrics .docsExamined .sumOfSquares | NumberDecimal | literal | 検査されたドキュメント数の正方形の合計。
|
metrics.hasSortStage | ブール値 | literal | true MongoDB がカーソルからドキュメントを受け取った後、ドキュメントをソートする必要がある場合。 |
metrics.usedDisk | ブール値 | literal | true メモリ制限により、クエリが一時ファイルにデータを書込む場合。 |
metrics.fromMultiPlanner | ブール値 | literal | true クエリ プランナーがクエリの最適な実行プランを選択する前に複数のプランを評価する場合。 |
metrics.fromPlanCache | ブール値 | literal | true クエリ プランナーがプラン キャッシュのプランを使用できる場合。 |
metrics.totalExecMicros | ドキュメント | literal | 指定されたキーでクエリの実行に費やされた合計時間を説明します。 クエリで
|
metrics .totalExecMicros .sum | NumberLong | literal | 指定されたキーでクエリの実行に費やされた時間の合計 |
metrics .totalExecMicros .max | NumberLong | literal | 指定されたキーでクエリの実行に費やされた最も長い時間 |
metrics .totalExecMicros .min | NumberLong | literal | 指定されたキーでクエリの実行に費やされた最も短い時間 |
metrics .totalExecMicros .sumOfSquares | NumberDecimal | literal | 指定されたキーを持つすべてのクエリの合計実行時間の正方形の合計。 sumOfSquares 値が高い場合は、クエリ実行時間の分散が大きいことを示します。 |
metrics .firstResponseExecMicros | ドキュメント | literal | キー内のクエリの処理が開始されてから、サーバーが結果の最初のバッチを返すまでに費やされた時間を説明します
|
metrics .firstResponseExecMicros .sum | NumberLong | literal | クエリ処理の開始からサーバーが結果の最初のバッチを返すまでに費やされた時間の合計 |
metrics .firstResponseExecMicros .max | NumberLong | literal | クエリ処理の開始からサーバーが結果の最初のバッチを返すまでに費やされた時間の最長 |
metrics .firstResponseExecMicros .min | NumberLong | literal | クエリ処理の開始からサーバーが結果の最初のバッチを返すまでに費やされる最も短い時間 |
metrics .firstResponseExecMicros .sumOfSquares | NumberDecimal | literal | クエリ処理の開始からサーバーが結果の最初のバッチを返すまでに費やされた時間の正方形の合計。
|
metrics.docsReturned | ドキュメント | literal | キー内のクエリによって返されたドキュメントの数を示します |
metrics .docsReturned .sum | NumberLong | literal | 指定されたキーを持つクエリによって返されたドキュメントの合計数 |
metrics .docsReturned .max | NumberLong | literal | 指定されたキーを持つクエリによって返されるドキュメントの最大数 |
metrics .docsReturned .min | NumberLong | literal | 指定されたキーを持つクエリによって返されたドキュメントの最小数 |
metrics .docsReturned .sumOfSquares | NumberDecimal | literal | キー内のクエリによって返されたドキュメント数の正方形の合計。
|
metrics.firstSeenTimestamp | 日付 | literal | 前回の再起動以降、指定されたキーを持つクエリが最初に使用された時間 |
metrics.lastSeenTimestamp | 日付 | literal | 指定されたキーを持つクエリが最後に使用された時間 |
collectionType
key.collectionType
フィールドは、記録されたクエリが発行されたコレクションのタイプを示します。 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 | ドキュメント | 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
コマンドのクエリシェイプ プロパティを説明しています。
フィールド | タイプ | リテラルまたは正規化 |
---|---|---|
key.queryShape.pipeline | 配列 | 正規化 |
key.queryShape.explain | ブール値 | literal |
key.queryShape.allowDiskUse | ブール値 | literal |
key.queryShape.collation | ドキュメント | literal |
key.queryShape.hint | 文字列またはドキュメント | 正規化 |
key.queryShape.let | ドキュメント | 正規化 |
個別のコマンドクエリシェイプ
以下の表では、 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 Data Collection
MongoDB Atlas は定期的に$queryStats
を使用してクエリに関する匿名化データを収集し、MongoDB 製品の改善に役立ちます。 データは、使用状況に基づいて機能の提案を作成する目的でも使用される場合があります。 MongoDB は$queryStats
で収集したデータを 4 年間保持します。
Atlas が配置で$queryStats
を実行する場合、Atlas 組織ごとに一意の HMAC キーを使用してデータを変換し、機密情報の収集を回避します。