/ /

$planCacheStats

Definición

$planCacheStats

Devuelve Información de la caché de consultas para una colección. La etapa devuelve un documento para cada entrada de caché del plan.

La etapa $planCacheStats debe ser la primera etapa en la pipeline. La etapa tiene la siguiente sintaxis:

{
   $planCacheStats: {
      allHosts: <boolean>
   }
}

La etapa de agregación $planCacheStats tiene las siguientes opciones:

Opción

Descripción

allHosts

Configura cómo la etapa de agregación $planCacheStats apunta a los nodos en un clúster fragmentado.

Si true, mongos transmite la etapa de agregación $planCacheStats a todos los nodos (principal y secundarios) para cada partición afectada que contenga uno o más fragmentos de la colección objetivo.
Si false, la etapa de agregación $planCacheStats sigue la preferencia de lectura y solo recupera la caché de planes del nodo primario del conjunto de réplicas dirigido.

Los sets de réplicas y los servidores autónomos devuelven un error durante el análisis de la pipeline si allHosts está configurado en true. La opción solo está disponible para clústeres particionados.

Por defecto: false

Nuevo en la versión 7.1.

Tip

Planes de query

Considerations

pipeline

$planCacheStats debe ser la primera etapa en un pipeline de agregación.

Restricciones

$planCacheStats no está permitido en:
- Transacciones
- $facet etapa de agregación
$planCacheStats requiere nivel de consistencia de lectura "local".

Control de acceso

En los sistemas que se ejecutan con authorization, el usuario debe tener el privilegio planCacheRead para la colección.

restricción

When using Queryable Encryption, the $planCacheStats stage skips operations on encrypted collections, even though the operations are cached as normal.

preferencia de lectura

Cuando la opción allHosts se establece en false, $planCacheStats sigue la preferencia de lectura al seleccionar los host(s) desde los cuales devolver la información de la caché del plan.

Las aplicaciones pueden dirigirse a diferentes nodos de un set de réplicas. Como tal, cada nodo del conjunto de réplicas podría recibir diferentes comandos de lectura y disponer de información sobre la caché de planes que difiere de la de otros nodos. No obstante, ejecutar $planCacheStats en un set de réplicas o en un clúster fragmentado obedece a las reglas normales de preferencia de lectura. Es decir, en un set de réplicas, la operación recopila información de la caché de planes solo de un nodo del set de réplicas, y en un clúster, la operación recopila información de la caché de planes solo de un nodo de cada set de réplicas de particiones.

Salida

Modificado en la versión 7.0.

El resultado de $planCacheStats depende del motor de query utilizado para completar la query. El valor del campo version de $planCacheStats indica qué motor de consulta se utilizó:

1 indica que se utilizó el motor clásico.
2 indica que se utilizó el motor de ejecución de query basado en ranuras.

Para consultas que utilizan el motor de ejecución clásico, $planCacheStats devuelve un documento similar al siguiente:

{
   "version" : 1,
   "createdFromQuery" : <document>,
   "planCacheShapeHash" : <hexadecimal string>,
   "planCacheKey" : <hexadecimal string>,
   "isActive" :  <boolean>,
   "works" : <NumberLong>,
   "cachedPlan" : {
      "stage" : <STAGE1>,
      "filter" : <document>,
      "inputStage" : {
         "stage" : <STAGE2>,
         ...
      }
   },
   "timeOfCreation" : <date>,
   "creationExecStats" : [   // Exec Stats Document for each candidate plan
      {
         "nReturned" : <num>,
         "executionTimeMillisEstimate" : <num>,
         "totalKeysExamined" : <num>,
         "totalDocsExamined" :<num>,
         "executionStages" : {
            "stage" : <STAGE A>,
            ...
            "inputStage" : {
               "stage" : <STAGE B>,
               ...
            }
         }
      },
      ...
   ],
   "candidatePlanScores" : [
      <number>,
      ...
   ],
   "indexFilterSet" : <boolean>,
   "estimatedSizeBytes" : <num>,
   "querySettings" : <document>,
   "host" : <string>,
   "shard" : <string>
}

Cada documento incluye varias estadísticas sobre el plan del query y la ejecución, incluyendo:

Campo

Descripción

version

Un número que indica el motor de query usado para completar la query.

1 indica que se utilizó el motor clásico.
2 indica que se utilizó el motor de ejecución de query basado en ranuras.

createdFromQuery

Un documento que contiene la consulta específica que resultó en esta entrada de caché. Por ejemplo:

{
  "query" : <document>,
  "sort" : <document>,
  "projection" : <document>
}

isActive

Un valor booleano que indica si el registro está activo o inactivo.

Si está activado, el planificador de queries está utilizando actualmente la entrada para generar planes del query.
Si está inactivo, el planificador de queries no está utilizando actualmente la entrada para generar planes del query.

Consulta Estado de entrada de caché de plan.

planCacheShapeHash

Una string hexadecimal que representa el hash de la forma del query. Ver explain.queryPlanner.planCacheShapeHash.

A partir de MongoDB 8.0, el campo queryHash existente se duplica en un nuevo campo llamado planCacheShapeHash. Si estás utilizando una versión anterior de MongoDB, solo verás el campo queryHash. Las versiones futuras de MongoDB removerán el campo queryHash obsoleto y deberás utilizar el campo planCacheShapeHash en su lugar.

planCacheKey

Una string hexadecimal que representa el hash de la clave utilizada para encontrar la entrada de caché de plan asociada con esta query. La clave de caché de planes es una función tanto de la forma del query de la caché de planes como de los índices disponibles actualmente para esa forma. Consulte explain.queryPlanner.planCacheKey.

cachedPlan

Los detalles del plan en caché. Los campos incluidos en el cachedPlan varían según si la consulta se completó utilizando el motor clásico o el motor de ejecución de consultas basado en slots. Para obtener más información sobre los planes del query, consulte explain.queryPlanner.

works

El número de "unidades de trabajo" realizadas por el plan de ejecución del query durante el periodo de prueba cuando el planificador del query evalúa los planes candidatos. Para obtener más información, consulta explain.executionStats.executionStages.works.

timeOfCreation

Momento de creación de la entrada.

creationExecStats

Un arreglo de documentos de estadísticas de ejecución. El arreglo contiene un documento para cada plan de candidato.

Para obtener detalles sobre las estadísticas de ejecución, consulte explain.executionStats.

candidatePlanScores

Un arreglo de puntuaciones para los planes candidatos listados en el arreglo creationExecStats.

indexFilterSet

Un booleano que indica si existe un filtro de índice para la forma de consulta caché del plan.

estimatedSizeBytes

El tamaño estimado en bytes de una entrada en la caché de planes.

querySettings

Nuevo en la versión 8.0.

Un documento que contiene configuraciones de query previamente establecidas mediante setQuerySettings:

querySettings: {
   indexHints: [ {
      ns: { db: <string>, coll: <string> },
      allowedIndexes: <array>
   }, ... ],
   queryFramework: <string>
}

querySettings campo:

Campo

Tipo

Descripción

indexHints.ns

Documento

namespace para pistas de índice.

`db`	string	Nombre de la base de datos para sugerencias de índices.
`coll`	string	Nombre de la colección para sugerencias de índices.

indexHints.allowedIndexes

arreglo

Arreglo de índices para pistas de índices. Para más detalles, consulta Índices y hint().

queryFramework

string

La cadena de estructura del query puede ser:

classic para el motor clásico.
sbe para el motor de ejecución de query basado en slots. Para más detalles, consulte el Motor de ejecución de query basado en slots.

host

El nombre de host y el puerto de la instancia de mongod de la que se devolvió la información de la caché de planes.

Cuando se ejecuta en un clúster particionado, la operación devuelve información de las entradas de la caché de planes de un solo nodo en cada set de réplicas de partición. Este nodo es identificado con los campos partición y host. Consulte también restricción.

shard

El nombre de la partición del que $planCacheStats recuperó la entrada de caché.

Solo disponible si se ejecuta en un clúster fragmentado.

Para las querys que utilizan el motor de ejecución de querys basado en slot, $planCacheStats devuelve un documento similar al siguiente:

{
   "version" : 2,
   "planCacheShapeHash" : <hexadecimal string>,
   "planCacheKey" : <hexadecimal string>,
   "isActive" :  <boolean>,
   "works" : <NumberLong>,
   "cachedPlan" : {
      "slots" : <string>,
      "stages": <string>
   },
   "indexFilterSet" : <boolean>,
   "estimatedSizeBytes" : <num>,
   "querySettings" : <document>,
   "host" : <string>
}

Cada documento incluye varias estadísticas sobre el plan del query y la ejecución, incluyendo:

Campo

Descripción

version

Un número que indica el motor de query usado para completar la query.

1 indica que se utilizó el motor clásico.
2 indica que se utilizó el motor de ejecución de query basado en ranuras.

planCacheShapeHash

Una string hexadecimal que representa el hash de la forma del query. Ver explain.queryPlanner.planCacheShapeHash.

planCacheKey

isActive

Un valor booleano que indica si el registro está activo o inactivo.

Si está activado, el planificador de queries está utilizando actualmente la entrada para generar planes del query.
Si está inactivo, el planificador de queries no está utilizando actualmente la entrada para generar planes del query.

Consulta Estado de entrada de caché de plan.

works

cachedPlan

indexFilterSet

Un booleano que indica si existe un filtro de índice para la forma de consulta caché del plan.

estimatedSizeBytes

El tamaño estimado en bytes de una entrada en la caché de planes.

querySettings

Nuevo en la versión 8.0.

Un documento que contiene configuraciones de query previamente establecidas mediante setQuerySettings:

querySettings: {
   indexHints: [ {
      ns: { db: <string>, coll: <string> },
      allowedIndexes: <array>
   }, ... ],
   queryFramework: <string>
}

querySettings campo:

Campo

Tipo

Descripción

indexHints.ns

Documento

namespace para pistas de índice.

`db`	string	Nombre de la base de datos para sugerencias de índices.
`coll`	string	Nombre de la colección para sugerencias de índices.

indexHints.allowedIndexes

arreglo

Arreglo de índices para pistas de índices. Para más detalles, consulta Índices y hint().

queryFramework

string

La cadena de estructura del query puede ser:

classic para el motor clásico.
sbe para el motor de ejecución de query basado en slots. Para más detalles, consulte el Motor de ejecución de query basado en slots.

host

El nombre de host y el puerto de la instancia de mongod de la que se devolvió la información de la caché de planes.

Ejemplos

Los ejemplos de esta sección utilizan la siguiente colección orders:

db.orders.insertMany( [
    { "_id" : 1, "item" : "abc", "price" : Decimal128("12"), "quantity" : 2, "type": "apparel" },
    { "_id" : 2, "item" : "jkl", "price" : Decimal128("20"), "quantity" : 1, "type": "electronics" },
    { "_id" : 3, "item" : "abc", "price" : Decimal128("10"), "quantity" : 5, "type": "apparel" },
    { "_id" : 4, "item" : "abc", "price" : Decimal128("8"), "quantity" : 10, "type": "apparel" },
    { "_id" : 5, "item" : "jkl", "price" : Decimal128("15"), "quantity" : 15, "type": "electronics" }
] )

Cree los siguientes índices en la colección:

db.orders.createIndex( { item: 1 } );
db.orders.createIndex( { item: 1, quantity: 1 } );
db.orders.createIndex( { quantity: 1 } );
db.orders.createIndex( { quantity: 1, type: 1 } );
db.orders.createIndex(
    { item: 1, price: 1 },
    { partialFilterExpression: { price: { $gte: Decimal128("10")} } }
);

Nota

El índice { item: 1, price: 1 } es un índice parcial y solo indexa documentos con el campo price mayor o igual a Decimal128("10").

Ejecutar algunas consultas contra la colección:

db.orders.find( { item: "abc", price: { $gte: Decimal128("10") } } )
db.orders.find( { item: "abc", price: { $gte: Decimal128("5") } } )
db.orders.find( { quantity: { $gte: 20 } } )
db.orders.find( { quantity: { $gte: 5 }, type: "apparel" } )

Las queries anteriores se completan utilizando el motor de ejecución de queries basado en slots.

Información de retorno para todos los registros en la caché de query

El siguiente pipeline de agregación utiliza $planCacheStats para devolver información sobre las entradas de la caché de planes para la colección:

db.orders.aggregate( [
    { $planCacheStats: { } }
] )

Salida:

[
  {                                             // Plan Cache Entry 1
    version: '2',
    planCacheShapeHash: '478AD696',
    planCacheKey: '21AE23AD',
    isActive: true,
    works: Long("7"),
    timeOfCreation: ISODate("2023-05-22T20:33:49.031Z"),
    cachedPlan: {
      ...
    },
    indexFilterSet: false,
    isPinned: false,
    estimatedSizeBytes: Long("8194"),
    host: 'mongodb1.example.net:27018'
  },
  {                                             // Plan Cache Entry 2
        version: '2',
        planCacheShapeHash: '3D8AFDC6',
        planCacheKey: '1C2C4360',
        isActive: true,
        works: Long("6"),
        timeOfCreation: ISODate("2023-05-22T20:33:50.584Z"),
        cachedPlan: {
          ...
        },
        indexFilterSet: false,
        isPinned: false,
        estimatedSizeBytes: Long("11547"),
        host: 'mongodb1.example.net:27018'
      },
      {                                          // Plan Cache Entry 3
        version: '2',
        planCacheShapeHash: '27285F9B',
        planCacheKey: '20BB9404',
        isActive: true,
        works: Long("1"),
        timeOfCreation: ISODate("2023-05-22T20:33:49.051Z"),
        cachedPlan: {
          ...
        },
        indexFilterSet: false,
        isPinned: false,
        estimatedSizeBytes: Long("7406"),
        host: 'mongodb1.example.net:27018'
      },
      {                                          // Plan Cache Entry 4
        version: '2',
        planCacheShapeHash: '478AD696',
        planCacheKey: 'B1435201',
        isActive: true,
        works: Long("5"),
        timeOfCreation: ISODate("2023-05-22T20:33:49.009Z"),
        cachedPlan: {
          ...
        },
        indexFilterSet: false,
        isPinned: false,
        estimatedSizeBytes: Long("7415"),
        host: 'mongodb1.example.net:27018'
      }
    ],

Advertencia

Consulte también planCacheKey.

Encuentra los detalles de la entrada de caché para un hash de query

Para devolver la información de caché del plan para un hash de query específico, la etapa $planCacheStats puede ir seguida de un $match en el campo planCacheKey.

El siguiente pipeline de agregación utiliza $planCacheStats seguido de una etapa $match para devolver información específica para un hash de query particular:

db.orders.aggregate( [
    { $planCacheStats: { } },
    { $match: { planCacheKey: "B1435201"} }
] )

Salida:

[
  {
    version: '2',
    planCacheShapeHash: '478AD696',
    planCacheKey: 'B1435201',
    isActive: true,
    works: Long("5"),
    timeOfCreation: ISODate("2023-05-22T20:33:49.009Z"),
    cachedPlan: {
      slots: '$$RESULT=s11 env: { s3 = 1684787629009 (NOW), s6 = Nothing, s5 = Nothing, s1 = TimeZoneDatabase(Asia/Kuwait...Etc/UCT) (timeZoneDB), s10 = {"item" : 1, "price" : 1}, s2 = Nothing (SEARCH_META) }',
      stages: '[2] nlj inner [] [s4, s7, s8, s9, s10] \n' +
        '    left \n' +
        '        [1] cfilter {(exists(s5) && exists(s6))} \n' +
        '        [1] ixseek s5 s6 s9 s4 s7 s8 [] @"358822b7-c129-47b7-ad7f-40017a51b03c" @"item_1_price_1" true \n' +
        '    right \n' +
        '        [2] limit 1 \n' +
        '        [2] seek s4 s11 s12 s7 s8 s9 s10 none none [] @"358822b7-c129-47b7-ad7f-40017a51b03c" true false \n'
    },
    indexFilterSet: false,
    isPinned: false,
    estimatedSizeBytes: Long("7415"),
    host: 'mongodb1.example.net:27018'
  }
]

Advertencia

Consulta también planCacheKey y planCacheShapeHash.

Para utilizar el controlador de MongoDB Node.js para agregar una etapa de $planCacheStats a una canalización de agregación, utilice el Operador $planCacheStats en un objeto de canalización.

Información de retorno para todos los registros en la caché de query

El siguiente ejemplo crea una fase de pipeline que devuelve información sobre las entradas de caché de planes para la colección. El ejemplo luego ejecuta la canalización de agregación:

const pipeline = [{ $planCacheStats: {} }];
const cursor = collection.aggregate(pipeline);
return cursor;

Encuentra los detalles de la entrada de caché para un hash de query

Para devolver la información de la caché de planes para un hash de query en particular, incluya una fase $match que verifique un hash de query específico en el campo planCacheKey.

El siguiente ejemplo crea un pipeline que devuelve información para un valor hash de query de "B1435201". A continuación, el ejemplo ejecuta la pipeline de agregación:

const pipeline = [
 $planCacheStats: {} },
  { $match: { planCacheKey: "B1435201"} }
];
const cursor = collection.aggregate(pipeline);
return cursor;

Volver

$out

$project