/ /

Operadores

Etapas de la pipeline de agregación

Docs Home

Manual de base de datos

Referencia

Operadores

Etapas de la pipeline de agregación

$planCacheStats

Esta versión de la documentación se archivó y ya no se admite. Para actualizar tu implementación de 6.0, consulta el Procedimientos de actualización de MongoDB 7.0 .

Definición

$planCacheStats

Nuevo en la versión 4.2.

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. El escenario toma un documento vacío como parámetro y tiene la siguiente sintaxis:

{ $planCacheStats: { } }

Nota

4.4 Cambios

A partir de la versión 4.4,

La etapa $planCacheStats se puede ejecutar en instancias de mongos, así como en instancias de mongod. En 4.2, La etapa $planCacheStats solo se puede ejecutar en instancias mongod.
$planCacheStats incluye nuevos campos: el campo host y, cuando se ejecuta en un mongos, el campo partición.
mongo shell proporciona el método PlanCache.list() como un contenedor para la etapa de agregación $planCacheStats.
MongoDB remueve lo siguiente:
- planCacheListPlans y planCacheListQueryShapes comandos, y
- PlanCache.getPlansByQuery() y PlanCache.listQueryShapes() métodos.
Utiliza $planCacheStats o PlanCache.list() en su lugar.

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

preferencia de lectura

$planCacheStats observa la preferencia de lectura al seleccionar el(los) host(s) del cual devolver la información de la caché de planes.

Las aplicaciones pueden dirigirse a diferentes nodos de un set de réplicas. Como tal, es posible que cada nodo del conjunto de réplicas reciba diferentes comandos de lectura y tenga información de caché de planes que difiera de otros nodos. Sin embargo, ejecutar $planCacheStats en un set de réplicas o un clúster particionado obedece las reglas normales de preferencia de lectura. Es decir, en un set de réplicas, la operación reúne información de caché de planificación de un solo nodo del set de réplicas, y en un clúster dividido en sectores (sharded), la operación reúne información de caché de planificación de un solo nodo de cada set de réplicas de la partición.

Salida

Para cada entrada del caché de planes, la etapa $planCacheStats devuelve un documento similar al siguiente:

{
   "createdFromQuery" : <document>,
   "queryHash" : <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>, // Available starting in MongoDB 5.0, 4.4.3, 4.2.12
   "host" : <string>,   // Available starting in MongoDB 4.4
   "shard" : <string>   // Available starting in MongoDB 4.4 if run on sharded cluster
}

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

Campo

Descripción

createdFromQuery

Un documento que contiene la query específica que resultó en esta entrada de caché; es decir,

{
  "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.

Tip

Estado de la entrada de caché de planes

queryHash

Una cadena hexadecimal que representa el hash de la forma del query. Para obtener más información, consulte explain.queryPlanner.queryHash

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é del plan es una función tanto de la forma del query como de los índices actualmente disponibles para esa forma. Para más información, consulte explain.queryPlanner.planCacheKey

cachedPlan

Los detalles del plan en caché. Ver 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 más información, consulte 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 valor booleano que indica si existe un filtro de índice para la forma del query.

estimatedSizeBytes

Un número que describe el tamaño estimado en bytes de una entrada de caché de planes.

Nuevo en la versión 5.0.

A partir de MongoDB 5.0, 4.4.3 y 4.2.12, este campo está disponible.

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, la operación devuelve información de entradas de caché de plan de un solo nodo en cada set de réplicas de partición. Este nodo se identifica mediante los campos partición y host. Consulte también Preferencia de lectura.

Nuevo en la versión 4.4.

partición

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

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

Nuevo en la versión 4.4.

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'
      }
    ]

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'
  }
]

Vea también planCacheKey y queryHash.

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