/ /

$planCacheStats

Definición

$planCacheStats

Devuelve Información de lacaché de planes para una colección. La etapa devuelve un documento por cada entrada de la caché de planes.

La etapa $planCacheStats debe ser la primera etapa del pipeline. 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 es, transmitemongos la $planCacheStats etapa de agregación a todos los nodos (primarios y secundarios) para cada fragmento afectado que contenga uno o más fragmentos de la colección de destino.
Si false es, la $planCacheStats etapa de agregación sigue la preferencia de lectura y solo recupera el caché del plan del conjunto de réplicas principal de destino.

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

Tubería

$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 leer nivel de "local" preocupación.

Control de acceso

En los sistemas que se ejecutan con, el authorization planCacheRead usuario debe tener el privilegio para la recopilació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 está establecida 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 miembros de un conjunto de réplicas. Por lo tanto, cada miembro del conjunto de réplicas puede recibir comandos de lectura diferentes y tener información de caché de plan diferente a la de los demás miembros. Sin embargo, ejecutar $planCacheStats en un conjunto de réplicas o en un clúster fragmentado sigue las reglas de preferencia de lectura habituales. Es decir, en un conjunto de réplicas, la operación recopila información de caché de plan de un solo miembro del conjunto de réplicas, mientras que en un clúster fragmentado, la operación recopila información de caché de plan de un solo miembro de cada conjunto de réplicas fragmentado.

Salida

Modificado en la versión 7.0.

La salida de $planCacheStats depende del motor de consulta utilizado para completar la consulta. 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 consultas basado en ranuras.

Para las 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 varios planes de consulta y estadísticas de ejecución, entre ellos:

Campo

Descripción

version

Un número que indica el motor de consulta utilizado para completar la consulta.

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

createdFromQuery

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

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

isActive

Un valor booleano que indica si la entrada está activa o inactiva.

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

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 cadena hexadecimal que representa el hash de la clave utilizada para encontrar la entrada de caché de planes asociada a esta consulta. La clave de caché de planes depende tanto de la forma de la consulta de caché de planes como de los índices disponibles para dicha forma.explain.queryPlanner.planCacheKey Véase.

cachedPlan

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

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,explain.executionStats consulte.

candidatePlanScores

Una matriz de puntuaciones para los planes candidatos enumerados en la matriz 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 de caché del plan.

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 campos:

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 índice.
`coll`	string	Nombre de la colección de sugerencias de índice.

indexHints.allowedIndexes

arreglo

Matriz de índices para sugerencias de índice. Para más detalles, consulte Índices hint()y.

queryFramework

string

La cadena del marco de consulta 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 desde la que se devolvió la información de caché del mongod plan.

Al ejecutarse en un clúster fragmentado, la operación devuelve información de entrada de la caché del plan de un único miembro de cada conjunto de réplicas de fragmentos. Este miembro se identifica con los campos de fragmento y host. Consulte también Redacción.

shard

El nombre del fragmento desde el cual $planCacheStats recuperó la entrada de caché.

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

Para las consultas que utilizan el motor de ejecución de consultas basado en ranuras, $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 varios planes de consulta y estadísticas de ejecución, entre ellos:

Campo

Descripción

version

Un número que indica el motor de consulta utilizado para completar la consulta.

1 Indica que se utilizó el motor clásico.
2 Indica que se utilizó el motor de ejecución de consultas 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 la entrada está activa o inactiva.

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

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 de caché del plan.

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 campos:

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 índice.
`coll`	string	Nombre de la colección de sugerencias de índice.

indexHints.allowedIndexes

arreglo

Matriz de índices para sugerencias de índice. Para más detalles, consulte Índices hint()y.

queryFramework

string

La cadena del marco de consulta 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 desde la que se devolvió la información de caché del mongod plan.

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 price campo mayor o igual Decimal128("10") a.

Ejecute 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 consultas anteriores se completan utilizando el motor de ejecución de consultas basado en ranuras.

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

La siguiente canalización de agregación utiliza $planCacheStats para devolver información sobre las entradas de caché del plan 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

Véase también planCacheKey.

Buscar detalles de entrada de caché para un hash de consulta

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 etapa de canalización que devuelve información sobre las entradas de caché del plan para la colección. A continuación, el ejemplo ejecuta la canalización de agregación:

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

Buscar detalles de entrada de caché para un hash de consulta

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 una canalización que devuelve información para un valor hash de consulta de "B1435201". A continuación, el ejemplo ejecuta la canalización de agregación:

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

Volver

$out

$project