/ /

$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 de un proceso 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.

Redacción

Al utilizar el cifrado consultable, la $planCacheStats etapa omite las operaciones contra colecciones cifradas, incluso aunque las operaciones se almacenen en caché de manera normal.

preferencia de lectura

Cuando la opción allHosts se establece en false, $planCacheStats sigue la preferencia de lectura al seleccionar el/los host(s) desde donde devolver la información de 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á activo, el planificador de consultas está utilizando actualmente la entrada para generar planes de consulta.
Si está inactivo, el planificador de queries no está utilizando actualmente la entrada para generar planes del query.

Consulte Estado de entrada de caché del plan.

planCacheShapeHash

Cadena hexadecimal que representa el hash de la forma de la consulta.explain.queryPlanner.planCacheShapeHash Véase.

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 de consultas durante el período de prueba, cuando el planificador de consultas evalúa los planes candidatos. Para más información,explain.executionStats.executionStages.works consulte.

timeOfCreation

Momento de creación de la entrada.

creationExecStats

Una matriz de documentos de estadísticas de ejecución. La matriz contiene un documento para cada plan 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 valor booleano que indica si existe un filtro de índice para la forma de consulta de 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

Espacio de nombres para sugerencias 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 consultas basado en ranuras. Para más detalles, consulte Motor de ejecución de consultas basado en ranuras.

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

Cadena hexadecimal que representa el hash de la forma de la consulta.explain.queryPlanner.planCacheShapeHash Véase.

planCacheKey

isActive

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

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

Consulte Estado de entrada de caché del plan.

works

cachedPlan

indexFilterSet

Un valor booleano que indica si existe un filtro de índice para la forma de consulta de 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

Espacio de nombres para sugerencias 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 consultas basado en ranuras. Para más detalles, consulte Motor de ejecución de consultas basado en ranuras.

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.

Devolver información para todas las entradas en la caché de consultas

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 información de caché del plan para un hash de consulta particular, la etapa$planCacheStatspuede ser seguida por un$matchen el campo planCacheKey.

La siguiente canalización de agregación utiliza $planCacheStats seguido de una etapa para devolver información específica para un hash de consulta $match 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

Consulte 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.

Devolver información para todas las entradas en la caché de consultas

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 información de caché del plan para un hash de consulta particular, incluya una etapa $match que verifique un hash de consulta 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