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

$planCacheStats

Nesta página

Definição

Considerações
Saída
Exemplos

Definição

$planCacheStats

Novidades na versão 4.2.

Retorna informações de cache do plano para uma coleção. O estágio retorna um documento para cada entrada do cache do plano.

O estágio $planCacheStats deve ser o primeiro no pipeline. O estágio usa um documento vazio como parâmetro e tem a seguinte sintaxe:

{ $planCacheStats: { } }

Observação

4.4 Mudanças

A partir da versão 4.4,

O estágio $planCacheStats pode ser executado em instâncias mongos e também em instâncias mongod . Em 4.2, o estágio $planCacheStats só pode ser executado em instâncias mongod .
$planCacheStats inclui novos campos: o campo de host e, quando executado em um mongos, o campo de shard .
O shell mongo fornece o método PlanCache.list() como invólucro para o estágio de agregação $planCacheStats .
O MongoDB remove o seguinte:
- planCacheListPlans e planCacheListQueryShapes comandos, e
- PlanCache.getPlansByQuery() e métodos PlanCache.listQueryShapes() .
Em vez disso , use $planCacheStats ou PlanCache.list() .

Dica

Veja também:

Planos de query

Considerações

Pipeline

$planCacheStats deve ser o primeiro estágio em um pipeline de agregação.

Restrições

$planCacheStats não é permitido em:
- transações
- $facet estágio de agregação
$planCacheStats requer nível de read concern "local".

Controle de acesso

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

readPreference

$planCacheStats 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 $planCacheStats 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.

Saída

Para cada entrada do cache do plano, o estágio $planCacheStats retorna um documento semelhante ao seguinte:

{
   "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 inclui vários planos de query e estatísticas de execução, incluindo:

Campo

Descrição

createdFromQuery

Um documento que contém a query específica que resultou nesta entrada de cache; isto é,

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

isActive

Um booleano que indica se a entrada está ativa ou inativa.

Se ativo, o planejador de query está usando a entrada para gerar planos de query.
Se inativo, o planejador de query não está usando a entrada para gerar planos de query.

Dica

Veja também:

Planejar o estado de entrada do cache

queryHash

Uma string hexadecimal que representa o hash da forma de query. Para obter mais informações, consulte explain.queryPlanner.queryHash

planCacheKey

Uma sequência hexadecimal que representa o hash da chave usada para localizar a entrada de cache do plano associada a esta query. A chave de cache do plano é uma função da forma de query e dos índices atualmente disponíveis para essa forma. Para mais informações, veja explain.queryPlanner.planCacheKey

cachedPlan

Os detalhes do plano em cache. Consulte explain.queryPlanner.

works

O número de "unidades de trabalho" realizadas pelo plano de execução da query durante o período de teste em que o planejador de query avalia os planos candidatos. Para mais informações, veja explain.executionStats.executionStages.works

timeOfCreation

Hora da criação da entrada.

creationExecStats

Uma array de documentos de estatísticas de execução. O array contém um documento para cada plano candidato.

Para detalhes sobre as estatísticas de execução, consulte explain.executionStats.

candidatePlanScores

Uma série de pontuações para os planos candidatos listados na matriz creationExecStats .

indexFilterSet

Um booleano que indica se existe um filtro de índice para a forma de query.

estimatedSizeBytes

Um número que descreve o tamanho estimado em bytes de uma entrada de cache do plano.

Novidades na versão 5,0.

A partir do MongoDB 5.0, 4.4.3 e 4.2.12, este campo está disponível.

Anfitrião

O nome do host e a porta da instância mongod da qual as informações do cache do plano foram retornadas.

Quando executada em um cluster fragmentado, a operação 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.

Novidades na versão 4.4.

estilhaço

O nome do fragmento do qual $planCacheStats recuperou a entrada de cache.

Disponível apenas se executado em um cluster fragmentado.

Novidades na versão 4.4.

Exemplos

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( { quantity: 1 } );
db.orders.createIndex( { quantity: 1, type: 1 } );
db.orders.createIndex(
   { item: 1, price: 1 },
   { partialFilterExpression: { price: { $gte: NumberDecimal("10")} } }
);

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 aggregation pipeline a seguir usa $planCacheStats para retornar informações sobre as entradas de cache do plano para a collection:

db.orders.aggregate( [
   { $planCacheStats: { } }
] )

A operação retorna todas as entradas no cache:

{                                               // Plan Cache Entry 1
   "createdFromQuery" : {
      "query" : { "quantity" : { "$gte" : 5 }, "type" : "apparel" },
      "sort" : { },
      "projection" : { }
   },
   "queryHash" : "4D151C4C",
   "planCacheKey" : "DD67E353",
   "isActive" : false,
   "works" : NumberLong(4),
   "cachedPlan" : {
      ...
   },
   "timeOfCreation" : ISODate("2020-02-06T18:15:44.849Z"),
   "creationExecStats" : [
      {
         ... // Exec Stats for Candidate 1
      },
      {
         ... // Exec Stats for Candidate 2
      }
   ],
   "candidatePlanScores" : [
      1.5002,
      1.5002
   ],
   "indexFilterSet" : false,
   "estimatedSizeBytes" : NumberLong(3160),     // Available starting in MongoDB 5.0, 4.4.3, 4.2.12
   "host" : "mongodb1.example.net:27018",       // Available starting in MongoDB 4.4
   "shard" : "shardA"                           // Available starting in MongoDB 4.4 if run on sharded cluster
}
{                                               // Plan Cache Entry 2
   "createdFromQuery" : {
      "query" : { "quantity" : { "$gte" : 20 } },
      "sort" : { },
      "projection" : { }
   },
   "queryHash" : "23B19B75",
   "planCacheKey" : "6F23F858",
   "isActive" : false,
   "works" : NumberLong(1),
   "cachedPlan" : {
      ...
   },
   "timeOfCreation" : ISODate("2020-02-06T18:15:44.454Z"),
   "creationExecStats" : [
      {
         ... // Exec Stats for Candidate 1
      },
      {
         ... // Exec Stats for Candidate 2
      }
   ],
   "candidatePlanScores" : [
      1.0002,
      1.0002
   ],
   "indexFilterSet" : false,
   "estimatedSizeBytes" : NumberLong(2539),     // Available starting in MongoDB 5.0, 4.4.3, 4.2.12
   "host" : "mongodb1.example.net:27018",       // Available starting in MongoDB 4.4
   "shard" : "shardA"                           // Available starting in MongoDB 4.4 if run on sharded cluster
}
{                                               // Plan Cache Entry 3
   "createdFromQuery" : {
      "query" : { "item" : "abc", "price" : { "$gte" : NumberDecimal("5") } },
      "sort" : { },
      "projection" : { }
   },
   "queryHash" : "117A6B10",
   "planCacheKey" : "A1824628",
   "isActive" : true,
   "works" : NumberLong(4),
   "cachedPlan" : {
      ...
   },
   "timeOfCreation" : ISODate("2020-02-06T18:15:44.452Z"),
   "creationExecStats" : [
      {
         ... // Exec Stats for Candidate 1
      },
      {
         ... // Exec Stats for Candidate 2
      }
   ],
   "candidatePlanScores" : [
      1.7502,
      1.7502
   ],
   "indexFilterSet" : false,
   "estimatedSizeBytes" : NumberLong(3183),     // Available starting in MongoDB 5.0, 4.4.3, 4.2.12
   "host" : "mongodb1.example.net:27018",       // Available starting in MongoDB 4.4
   "shard" : "shardA"                           // Available starting in MongoDB 4.4 if run on sharded cluster
}
{                                               // Plan Cache Entry 4
   "createdFromQuery" : {
      "query" : { "item" : "abc", "price" : { "$gte" : NumberDecimal("10") } },
      "sort" : { },
      "projection" : { }
   },
   "queryHash" : "117A6B10",
   "planCacheKey" : "2E6E536B",
   "isActive" : true,
   "works" : NumberLong(3),
   "cachedPlan" : {
      ...
   },
   "timeOfCreation" : ISODate("2020-02-06T18:15:44.449Z"),
   "creationExecStats" : [
      {
         ... // Exec Stats for Candidate 1
      },
      {
         ... // Exec Stats for Candidate 2
      },
      {
         ... // Exec Stats for Candidate 3
      }
   ],
   "candidatePlanScores" : [
      1.6668666666666665,
      1.6668666666666665,
      1.6668666666666665
   ],
   "indexFilterSet" : false,
   "estimatedSizeBytes" : NumberLong(4653),     // Available starting in MongoDB 5.0, 4.4.3, 4.2.12
   "host" : "mongodb1.example.net:27018",       // Available starting in MongoDB 4.4
   "shard" : "shardA"                           // Available starting in MongoDB 4.4 if run on sharded cluster
}

Consulte também planCacheKey.

Listar formas de query

O MongoDB 4.4 remove o comando planCacheListQueryShapes obsoleto e seu método auxiliar PlanCache.listQueryShapes().

Como alternativa, você pode usar o estágio $planCacheStats para obter uma lista de todas as formas de query para as quais há um plano em cache.

Por exemplo, o seguinte utiliza o estágio $project para produzir somente o campo createdFromQuery e o campo queryHash .

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

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

{ "createdFromQuery" : { "query" : { "item" : "abc", "price" : { "$gte" : NumberDecimal("5") } }, "sort" : {  }, "projection" : {  } }, "queryHash" : "117A6B10" }
{ "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("10") } }, "sort" : {  }, "projection" : {  } }, "queryHash" : "117A6B10" }

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, o estágio $planCacheStats pode ser seguido por um $match no campo planCacheKey .

O pipeline de agregação a seguir usa $planCacheStats seguido por $match e $project para retornar informações específicas para uma forma de query específica:

db.orders.aggregate( [
   { $planCacheStats: { } },
   { $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-06T18:15:44.849Z"),
   "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, 4.4.3, 4.2.12
   "host" : "mongodb1.example.net:27018",       // Available starting in MongoDB 4.4
   "shard" : "shardA"                           // Available starting in MongoDB 4.4 if run on sharded cluster
}

Consulte também planCacheKey e queryHash.

← $out (agregação)

$project (agregação) →

$planCacheStats.css-134mg1q{-webkit-align-self:center;-ms-flex-item-align:center;align-self:center;padding:0 10px;visibility:hidden;}.css-6vrlzm{border-radius:0!important;display:initial!important;margin:initial!important;}.css-1l4s55v{margin-top:-175px;position:absolute;padding-bottom:2px;}

Definição

Observação

4.4 Mudanças

Dica

Veja também:

Considerações

Pipeline

Restrições

Controle de acesso

readPreference

Saída

Dica

Veja também:

Exemplos

Observação

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

Listar formas de query

Encontrar detalhes de entrada de cache para uma forma de query

$planCacheStats