Definición
PlanCache.list(<pipeline>)Devuelve un arreglo de entradas de caché del plan para una colección.
El método solo está disponible desde el
plan cache objectde una colección específica; es decir.db.collection.getPlanCache().list(<pipeline>) ParameterTipoDescripciónArreglo
opcional. Pipeline de agregación para filtrar/procesar las formas de consulta de la caché de planes.
Puedes ejecutar este método desde una
mongodo unamongos. Cuando se ejecuta en un clúster particionado, el método retorna información de la entrada de la caché de planes de un único miembro de cada set de réplicas de la partición. Este nodo se identifica con los campos partición y host. Ver también preferencia de lectura.El método
PlanCache.list()engloba el$planCacheStatspipeline de agregación. Es decir,db.collection.getPlanCache().list([<stage1>, <stage2>, ...] ) es equivalente a
db.collection.aggregate([ <$planCacheStats stage>, <stage1>, <stage2>, ... ]).toArray(); Para obtener detalles sobre la salida, consulte la salida $planCacheStats.
No todas las queries colocan automáticamente un plan del query en la caché.
PlanCache.list()devuelve un arreglo vacío si actualmente no existen formas de los query de caché de planes con planes del query almacenados en caché.
Compatibilidad
Este método está disponible en implementaciones alojadas en los siguientes entornos:
MongoDB Atlas: El servicio totalmente gestionado para implementaciones de MongoDB en la nube
MongoDB Enterprise: La versión basada en suscripción y autogestionada de MongoDB
MongoDB Community: La versión de MongoDB con código fuente disponible, de uso gratuito y autogestionada.
Considerations
Configuración de query
A partir de MongoDB 8.0, utiliza la configuración del query en lugar de añadir filtros de índice. Los filtros de índices están en desuso a partir de MongoDB 8.0.
La configuración de queries tiene más funcionalidades que los filtros de índices. Además, los filtros de índice no son persistentes y no puedes crear fácilmente filtros de índice para todos los nodos del clúster. Para añadir ajustes de query y explorar ejemplos, consulta setQuerySettings.
Restricciones
PlanCache.list() no está permitido en transacciones.
Query Hash y Query Shapes de caché de planes
Para ayudar a identificar queries lentos con la misma forma del query de caché de planes, cada forma del query de caché de planes está asociada con un hash del query. El hash de la forma del query de la caché del plan es un string hexadecimal que representa un hash de la forma del query y depende únicamente de la forma del query.
Nota
Como con cualquier función encriptada, dos formas del query diferentes pueden dar como resultado el mismo valor encriptado. Sin embargo, es poco probable que ocurran colisiones encriptadas entre diferentes formas del query.
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.
El optimizador del query sólo almacena en caché el plan de una forma del query de caché de planes que puede tener más de un plan viable.
Cada entrada en la caché del plan se asocia con un planCacheShapeHash.
Advertencia
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.
preferencia de lectura
PlanCache.list() 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 PlanCache.list() 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.
Acceso requerido
En los sistemas que se ejecutan con authorization, el usuario debe tener el privilegio planCacheRead para la colección.
Ejemplos
Nota
No todas las queries automáticamente sitúan un plan del query en la caché.
PlanCache.list()devuelve un arreglo vacío si actualmente no hay formas del query con planes del query en caché.Para obtener detalles sobre la salida, consulte la salida $planCacheStats.
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( { item: 1, price: 1 }, { partialFilterExpression: { price: { $gte: Decimal128("10")} } } ); db.orders.createIndex( { quantity: 1 } ); db.orders.createIndex( { quantity: 1, type: 1 } );
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" } )
Información de retorno para todos los registros en la caché de query
Lo siguiente devuelve las formas del query de la caché de planes que tienen planes almacenados en caché para la colección orders:
db.orders.getPlanCache().list()
El método devuelve un arreglo de las formas del query del caché de plan que se encuentran actualmente en el caché. En el ejemplo, la colección orders tenía planes del query en caché asociados a las siguientes estructuras:
[ { "createdFromQuery" : { "query" : { "quantity" : { "$gte" : 5 }, "type" : "apparel" }, "sort" : { }, "projection" : { } }, "planCacheShapeHash" : "4D151C4C", "planCacheKey" : "DD67E353", "isActive" : false, "works" : Long(4), "cachedPlan" : { "stage" : "FETCH", "filter" : { "type" : { "$eq" : "apparel" } }, "inputStage" : { "stage" : "IXSCAN", "keyPattern" : { "quantity" : 1 }, "indexName" : "quantity_1", "isMultiKey" : false, "multiKeyPaths" : { "quantity" : [ ] }, "isUnique" : false, "isSparse" : false, "isPartial" : false, "indexVersion" : 2, "direction" : "forward", "indexBounds" : { "quantity" : [ "[5.0, inf.0]" ] } } }, "timeOfCreation" : ISODate("2020-02-06T15:57:18.219Z"), "creationExecStats" : [ { "nReturned" : 2, "executionTimeMillisEstimate" : 0, "totalKeysExamined" : 3, "totalDocsExamined" : 3, "executionStages" : { "stage" : "FETCH", "filter" : { "type" : { "$eq" : "apparel" } }, "nReturned" : 2, "executionTimeMillisEstimate" : 0, "works" : 4, ... } }, { "nReturned" : 2, "executionTimeMillisEstimate" : 0, "peakTrackedMemBytes" : 795, // Available starting in MongoDB 8.3 "totalKeysExamined" : 3, "totalDocsExamined" : 2, "executionStages" : { "stage" : "FETCH", "nReturned" : 2, "executionTimeMillisEstimate" : 0, "works" : 4, ... } } ], "candidatePlanScores" : [ 1.5002, 1.5002 ], "indexFilterSet" : false, "estimatedSizeBytes" : Long(3160), // Available starting in MongoDB 5.0 "host" : "mongodb1.example.net:27018", "shard" : "shardA" // Available if run on sharded cluster }, { "createdFromQuery" : { "query" : { "quantity" : { "$gte" : 20 } }, "sort" : { }, "projection" : { } }, "planCacheShapeHash" : "23B19B75", "planCacheKey" : "6F23F858", "isActive" : false, "works" : Long(1), ... }, { "createdFromQuery" : { "query" : { "item" : "abc", "price" : { "$gte" : Decimal128("5") } }, "sort" : { }, "projection" : { } }, "planCacheShapeHash" : "117A6B10", "planCacheKey" : "A1824628", "isActive" : false, "works" : Long(4), ... }, { "createdFromQuery" : { "query" : { "item" : "abc", "price" : { "$gte" : Decimal128("10") } }, "sort" : { }, "projection" : { } }, "planCacheShapeHash" : "117A6B10", "planCacheKey" : "2E6E536B", "isActive" : false, "works" : Long(3), ... } ]
Advertencia
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.
Para obtener detalles sobre la salida, consulte la salida $planCacheStats.
Lista de formas del query de caché de planes
Para obtener una lista de todas las formas del query que cuentan con un plan en caché, puedes utilizar el PlanCache.list(). Por ejemplo, la siguiente operación pasa por un pipeline con una etapa $project para mostrar solo el campo createdFromQuery y el campo planCacheShapeHash.
db.orders.getPlanCache().list( [ { $project: {createdFromQuery: 1, planCacheShapeHash: 1 } } ] )
Advertencia
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.
La operación devuelve las siguientes formas de consulta de caché de planes:
[ { "createdFromQuery" : { "query" : { "quantity" : { "$gte" : 5 }, "type" : "apparel" }, "sort" : { }, "projection" : { } }, "planCacheShapeHash" : "4D151C4C" }, { "createdFromQuery" : { "query" : { "quantity" : { "$gte" : 20 } }, "sort" : { }, "projection" : { } }, "planCacheShapeHash" : "23B19B75" }, { "createdFromQuery" : { "query" : { "item" : "abc", "price" : { "$gte" : Decimal128("5") } }, "sort" : { }, "projection" : { } }, "planCacheShapeHash" : "117A6B10" }, { "createdFromQuery" : { "query" : { "item" : "abc", "price" : { "$gte" : Decimal128("10") } }, "sort" : { }, "projection" : { } }, "planCacheShapeHash" : "117A6B10" } ]
Para obtener detalles sobre la salida, consulte la salida $planCacheStats.
Encuentra los detalles de la entrada de caché para una forma del query de plan de caché
Para devolver información de la caché de planes para una forma del query, pasa un pipeline con un $match en el campo planCacheKey.
db.orders.getPlanCache().list([ { $match: { planCacheKey: "DD67E353"} } ] )
La operación devuelve lo siguiente:
[ { "createdFromQuery" : { "query" : { "quantity" : { "$gte" : 5 }, "type" : "apparel" }, "sort" : { }, "projection" : { } }, "planCacheShapeHash" : "4D151C4C", "planCacheKey" : "DD67E353", "isActive" : false, "works" : Long(4), "cachedPlan" : { "stage" : "FETCH", "filter" : { "type" : { "$eq" : "apparel" } }, "inputStage" : { "stage" : "IXSCAN", "keyPattern" : { "quantity" : 1 }, "indexName" : "quantity_1", "isMultiKey" : false, "multiKeyPaths" : { "quantity" : [ ] }, "isUnique" : false, "isSparse" : false, "isPartial" : false, "indexVersion" : 2, "direction" : "forward", "indexBounds" : { "quantity" : [ "[5.0, inf.0]" ] } } }, "timeOfCreation" : ISODate("2020-02-11T17:14:33.873Z"), "creationExecStats" : [ { "nReturned" : 2, "executionTimeMillisEstimate" : 0, "peakTrackedMemBytes" : 795, // Available starting in MongoDB 8.3 "totalKeysExamined" : 3, "totalDocsExamined" : 3, "executionStages" : { "stage" : "FETCH", "filter" : { "type" : { "$eq" : "apparel" } }, "nReturned" : 2, "executionTimeMillisEstimate" : 0, "works" : 4, "advanced" : 2, "needTime" : 1, "needYield" : 0, "saveState" : 0, "restoreState" : 0, "isEOF" : 1, "docsExamined" : 3, "alreadyHasObj" : 0, "inputStage" : { "stage" : "IXSCAN", "nReturned" : 3, "executionTimeMillisEstimate" : 0, "works" : 4, "advanced" : 3, "needTime" : 0, "needYield" : 0, "saveState" : 0, "restoreState" : 0, "isEOF" : 1, "keyPattern" : { "quantity" : 1 }, "indexName" : "quantity_1", "isMultiKey" : false, "multiKeyPaths" : { "quantity" : [ ] }, "isUnique" : false, "isSparse" : false, "isPartial" : false, "indexVersion" : 2, "direction" : "forward", "indexBounds" : { "quantity" : [ "[5.0, inf.0]" ] }, "keysExamined" : 3, "seeks" : 1, "dupsTested" : 0, "dupsDropped" : 0 } } }, { "nReturned" : 2, "executionTimeMillisEstimate" : 0, "totalKeysExamined" : 3, "totalDocsExamined" : 2, "executionStages" : { "stage" : "FETCH", "nReturned" : 2, "executionTimeMillisEstimate" : 0, "works" : 4, "advanced" : 2, "needTime" : 1, "needYield" : 0, "saveState" : 0, "restoreState" : 0, "isEOF" : 1, "docsExamined" : 2, "alreadyHasObj" : 0, "inputStage" : { "stage" : "IXSCAN", "nReturned" : 2, "executionTimeMillisEstimate" : 0, "peakTrackedMemBytes" : 795, // Available starting in MongoDB 8.3 "works" : 4, "advanced" : 2, "needTime" : 1, "needYield" : 0, "saveState" : 0, "restoreState" : 0, "isEOF" : 1, "keyPattern" : { "quantity" : 1, "type" : 1 }, "indexName" : "quantity_1_type_1", "isMultiKey" : false, "multiKeyPaths" : { "quantity" : [ ], "type" : [ ] }, "isUnique" : false, "isSparse" : false, "isPartial" : false, "indexVersion" : 2, "direction" : "forward", "indexBounds" : { "quantity" : [ "[5.0, inf.0]" ], "type" : [ "[\"apparel\", \"apparel\"]" ] }, "keysExamined" : 3, "seeks" : 2, "dupsTested" : 0, "dupsDropped" : 0 } } } ], "candidatePlanScores" : [ 1.5002, 1.5002 ], "indexFilterSet" : false, "estimatedSizeBytes" : Long(3160), // Available starting in MongoDB 5.0 "host" : "mongodb1.example.net:27018", "shard" : "shardA" // Available if run on sharded cluster } ]
Advertencia
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.
Para obtener detalles sobre la salida, consulte la salida $planCacheStats.