Menu Docs

Página inicial do Docs → Desenvolver aplicações → Manual do MongoDB

PlanCache.list()

Nesta página

  • Definição
  • Consideração
  • Acesso obrigatório
  • Exemplos

Definição

PlanCache.list(<pipeline>)

Retorna uma matriz de entradas de cache do plano para uma collection.

O método está disponível somente a partir do plan cache object de uma collection específica; p ex.,

db.collection.getPlanCache().list(<pipeline>)
Parâmetro
Tipo
Descrição
gasoduto
Array

Opcional. Aggregation pipeline para filtrar/processar as formas de query.

Você pode executar este método de uma instância do mongod ou mongos . Quando executado em um cluster fragmentado, o método retorna informações de entrada do cache do plano de um único membro em cada conjunto de réplicas de shard. Este membro é identificado com os campos de fragmento e host . Consulte também Preferência de leitura.

O método PlanCache.list() envolve o aggregation pipeline $planCacheStats . Ou seja,

db.collection.getPlanCache().list([<stage1>, <stage2>, ...] )

é equivalente a

db.collection.aggregate([ <$planCacheStats stage>, <stage1>, <stage2>, ... ]).toArray();

Para obter detalhes sobre a saída, consulte saída $planCacheStats.

Nem todas as queries colocam automaticamente um plano de query no cache. PlanCache.list() retorna uma array vazia se não houver atualmente nenhuma forma de query com planos de query em cache.

Dica

Veja também:

Consideração

Restrições

PlanCache.list() não é permitido em transações.

Hash de query e formas de query

Para ajudar a identificar queries lentas com a mesma forma de query, começando no MongoDB 4.2, cada forma de query está associada a um queryHash. O queryHash é uma string hexadecimal que representa um hash da forma de query e depende somente da forma de query.

Observação

Como em qualquer função de hash, duas formas de query diferentes podem resultar no mesmo valor de hash. No entanto, a ocorrência de colisões de hash entre diferentes formas de query é improvável.

O otimizador de query armazena em cache apenas os planos para as formas de query que podem ter mais de um plano compatível.

Cada entrada no cache do plano está associada a um queryHash.

readPreference

PlanCache.list() observa a read preference ao selecionar o(s) host(s) a partir do(s) qual(is) retornar as informações do cache do plano.

Os aplicativos podem ter como alvo diferentes nós de um conjunto de réplicas. Dessa forma, cada membro do conjunto de réplicas pode receber comandos de leitura diferentes e ter informações de cache do plano diferentes de outros membros. No entanto, executar o PlanCache.list() em um conjunto de réplica ou um cluster fragmentado obedece as regras normais de preferência de leitura. Ou seja, em um conjunto de réplicas, a operação coleta informações de cache do plano de apenas um membro do conjunto de réplicas e, em um cluster fragmentado, a operação coleta informações de cache do plano de apenas um membro de cada conjunto de réplicas de shard.

Acesso obrigatório

Em sistemas executados com authorization, o usuário deve ter o privilégio planCacheRead para a collection.

Exemplos

Observação

  • Nem todas as queries colocam automaticamente um plano de query no cache. PlanCache.list() retorna uma array vazia se não houver atualmente nenhuma forma de query com planos de query em cache.

  • Para obter detalhes sobre a saída, consulte saída $planCacheStats.

Os exemplos nesta seção usam a seguinte collection orders:

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

Crie os seguintes índices na coleção:

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

Observação

O índice { item: 1, price: 1 } é um índice parcial e indexa apenas documentos com o campo price maior ou igual a NumberDecimal("10").

Execute algumas consultas em relação à coleção:

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

Retornar informações para todas as entradas no cache de query

O seguinte retorna a forma de query que têm planos em cache para a collection orders :

db.orders.getPlanCache().list()

O método retorna uma array das formas de query atualmente no cache. No exemplo, a collection orders tinha plano de query em cache associados com as seguintes formas:

[
   {
      "createdFromQuery" : {
         "query" : { "quantity" : { "$gte" : 5 }, "type" : "apparel" },
         "sort" : { },
         "projection" : { }
      },
      "queryHash" : "4D151C4C",
      "planCacheKey" : "DD67E353",
      "isActive" : false,
      "works" : NumberLong(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,
            "totalKeysExamined" : 3,
            "totalDocsExamined" : 2,
            "executionStages" : {
               "stage" : "FETCH",
               "nReturned" : 2,
               "executionTimeMillisEstimate" : 0,
               "works" : 4,
               ...
            }
         }
      ],
      "candidatePlanScores" : [
         1.5002,
         1.5002
      ],
      "indexFilterSet" : false,
      "estimatedSizeBytes" : NumberLong(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" : { }
      },
      "queryHash" : "23B19B75",
      "planCacheKey" : "6F23F858",
      "isActive" : false,
      "works" : NumberLong(1),
      ...
   },
   {
      "createdFromQuery" : {
         "query" : { "item" : "abc", "price" : { "$gte" : NumberDecimal("5") } },
         "sort" : { },
         "projection" : { }
      },
      "queryHash" : "117A6B10",
      "planCacheKey" : "A1824628",
      "isActive" : false,
      "works" : NumberLong(4),
      ...
   },
   {
      "createdFromQuery" : {
         "query" : { "item" : "abc", "price" : { "$gte" : NumberDecimal("10") } },
         "sort" : { },
         "projection" : { }
      },
      "queryHash" : "117A6B10",
      "planCacheKey" : "2E6E536B",
      "isActive" : false,
      "works" : NumberLong(3),
      ...
   }
]

Para obter detalhes sobre a saída, consulte saída $planCacheStats.

Listar formas de query

Para obter uma lista de todas as formas de query para as quais há um plano em cache, você pode usar o PlanCache.list(). Por exemplo, a operação a seguir passa em um pipeline com um estágio $project para gerar apenas o campo createdFromQuery e o campo queryHash .

db.orders.getPlanCache().list( [ { $project: {createdFromQuery: 1, queryHash: 1 } } ] )

A operação retorna as seguintes formas de query:

[
   { "createdFromQuery" : { "query" : { "quantity" : { "$gte" : 5 }, "type" : "apparel" }, "sort" : { }, "projection" : { } }, "queryHash" : "4D151C4C" },
   { "createdFromQuery" : { "query" : { "quantity" : { "$gte" : 20 } }, "sort" : { }, "projection" : { } }, "queryHash" : "23B19B75" },
   { "createdFromQuery" : { "query" : { "item" : "abc", "price" : { "$gte" : NumberDecimal("5") } }, "sort" : { }, "projection" : { } }, "queryHash" : "117A6B10" },
   { "createdFromQuery" : { "query" : { "item" : "abc", "price" : { "$gte" : NumberDecimal("10") } }, "sort" : { }, "projection" : { } }, "queryHash" : "117A6B10" }
]

Para obter detalhes sobre a saída, consulte saída $planCacheStats.

Encontrar detalhes de entrada de cache para uma forma de query

Para retornar informações do cache do plano para uma forma de query específica, passe um pipeline com um $match no campo planCacheKey .

db.orders.getPlanCache().list([ { $match: { planCacheKey: "DD67E353"} } ] )

A operação retorna o seguinte:

[
   {
      "createdFromQuery" : {
         "query" : {
            "quantity" : {
               "$gte" : 5
            },
            "type" : "apparel"
         },
         "sort" : {
         },
         "projection" : {
         }
      },
      "queryHash" : "4D151C4C",
      "planCacheKey" : "DD67E353",
      "isActive" : false,
      "works" : NumberLong(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,
            "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,
                  "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" : NumberLong(3160),   // Available starting in MongoDB 5.0
      "host" : "mongodb1.example.net:27018",
      "shard" : "shardA"                         // Available if run on sharded cluster
   }
]

Para obter detalhes sobre a saída, consulte saída $planCacheStats.

← PlanCache.help()
Métodos de operação em massa →

Nesta página