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

$planCacheStats

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 estágio 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 .

  • mongo shell fornece o método PlanCache.list() como um wrapper 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

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

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

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

Dica

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

creationExecStats

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.

candidatePlanScores

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.

Anfitrião

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.

estilhaço

O nome do fragmento do qual recuperou a entrada de $planCacheStats 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" : 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" }
] )

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: Decimal128("10")} } }
);

Observação

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

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

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" } )

As queries anteriores são concluídas usando o mecanismo de execução de queries baseado em slots.

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

O agregação pipeline a seguir usa $planCacheStats para retornar informações sobre as entradas de cache do plano para a collection:

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

Saída:

[
  {                                             // 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 também planCacheKey.

Encontrar detalhes de entrada do cache para uma query com hash

Para retornar informações do cache do plano para um hash de query específico, o estágio $planCacheStats pode ser seguido por um $match no campo planCacheKey .

O pipeline de agregação a seguir usa $planCacheStats seguido de um estágio $match para retornar informações específicas de um determinado hash de query:

db.orders.aggregate( [
    { $planCacheStats: { } },
    { $match: { planCacheKey: "B1435201"} }
] )

Saída:

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

Consulte também planCacheKey e queryHash.

Para usar o driver Node.js do MongoDB para adicionar um estágio $planCacheStats a um pipeline de agregação , use o operador $planCacheStats em um objeto de pipeline.

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

O exemplo a seguir cria um estágio de pipeline que retorna informações sobre as entradas de cache do plano para a collection. Em seguida, o exemplo executa o agregação pipeline:

const pipeline = [{ $planCacheStats: {} }];
const cursor = collection.aggregate(pipeline);
return cursor;

Encontrar detalhes de entrada do cache para uma query com hash

Para retornar informações do cache do plano para um hash de query específico, inclua um estágio $match que verifique se há um hash de query específico no campo planCacheKey.

O exemplo a seguir cria um pipeline que retorna informações para um valor de hash de query de "B1435201". Em seguida, o exemplo executa o agregação pipeline:

const pipeline = [
 $planCacheStats: {} },
  { $match: { planCacheKey: "B1435201"} }
];
const cursor = collection.aggregate(pipeline);
return cursor;

Voltar

$out

Próximo

$project

Nesta página