Menu Docs
Página inicial do Docs
/
Manual do MongoDB
/
Referência
/
Operadores
/
Estágios do pipeline de agregação

$planCacheStats

Nesta página

  • Definição
  • Considerações
  • Saída
  • Exemplos

Definição

$planCacheStats

Novidades na versão 4.2.

Retorna informações decache 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,

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

Controle de acesso

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

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 várias estatísticas de execução, inclusive:

Campo
Descrição

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

  • Se estiver inativo, o planejador de query não está usando a entrada para gerar plano de query no momento.

Dica

Veja também:

Planejar o estado de entrada do cache

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

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

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 de criação da entrada.

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

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

Uma série de pontuações para os planos candidatos listados na array 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.

O nome do host e a porta da instância do 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.

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

Disponível somente se executado em um cluster fragmentado.

Novidades na versão 4.4.

Exemplos

Os exemplos nesta seção usam a seguinte coleção 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 indexado com 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 consulta

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.

Voltar

$out

Próximo

$project