$planCacheStats

Nesta página

Definição

Considerações
Pipeline
Restrições
Controle de acesso
Redação
readPreference
Saída
Exemplos
Retornar informações para todas as entradas no cache de consulta
Encontrar detalhes de entrada do cache para uma query com hash

Definição

$planCacheStats

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 tem a seguinte sintaxe:

{
   $planCacheStats: {
      allHosts: <boolean>
   }
}

O estágio de agregação $planCacheStats tem as seguintes opções:

Opção

Descrição

allHosts

Configura como o estágio de agregação $planCacheStats direciona os nós em um cluster fragmentado.

Se true, mongos transmite o estágio de agregação $planCacheStats para todos os nós (primary e secundários) para cada shard afetado que contém uma ou mais parte da collection de destino.
Se false, o estágio de aggregation $planCacheStats segue a preferência de leitura e recupera apenas o cache do plano do conjunto de réplicas direcionado primário.

Os conjuntos de réplicas e servidores autônomos retornam um erro durante a análise do pipeline se allHosts estiver definido como true. A opção está disponível apenas para clusters fragmentados.

Padrão: false

Novidade na versão 7.1.

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 referência de leitura "local".

Controle de acesso

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

Redação

Se utilizar a Queryable Encryption, o estágio $planCacheStats omite as operações em coleções criptografadas, mesmo que as operações sejam armazenadas em cache normalmente.

readPreference

Quando a opção allHosts é definida como false, $planCacheStats segue a preferência de leitura ao selecionar o(s) host(s) a partir do qual retornar as informações do cache do plano.

Os aplicativos podem focar diferentes nós de um conjunto de réplicas. Assim, cada nó do conjunto de réplicas pode receber comandos de leitura diferentes e pode ter informações de cache do plano diferentes de outros nós. No entanto, executar $planCacheStats em um conjunto de réplicas ou em um cluster fragmentado obedece às regras normais de preferência de leitura. Ou seja, em um conjunto de réplicas, a operação reúne informações de cache do plano de apenas um nó do conjunto de réplicas e, em um cluster fragmentado, a operação reúne informações de cache do plano de apenas um nó de cada conjunto de réplicas de fragmentos.

Saída

Alterado na versão 7.0.

A saída de $planCacheStats depende do mecanismo de query usado para concluir a query. O valor do campo version do $planCacheStats indica qual mecanismo de query foi usado:

1 indica que o mecanismo clássico foi usado.
2 indica que o mecanismo de execução de query baseado em slot foi usado.

Para queries que utilizam o mecanismo de execução clássico, o $planCacheStats retorna um documento semelhante ao seguinte:

{
   "version" : 1,
   "createdFromQuery" : <document>,
   "planCacheShapeHash" : <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>,
   "querySettings" : <document>,
   "host" : <string>,
   "shard" : <string>
}

Cada documento inclui vários planos de query e várias estatísticas de execução, inclusive:

Campo

Descrição

version

Um número que indica o mecanismo de query usado para concluir a query.

1 indica que o mecanismo clássico foi usado.
2 indica que o mecanismo de execução de query baseado em slot foi usado.

createdFromQuery

Um documento que contém a query específica que resultou nessa entrada de cache. Por exemplo:

{
  "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.

Consulte Planejar o estado de entrada do cache.

planCacheShapeHash

Uma string hexadecimal que representa o hash da forma de query. Consulte explain.queryPlanner.planCacheShapeHash.

A partir do MongoDB 8.0, o campo queryHash pré-existente é renomeado para planCacheShapeHash. Se você estiver usando uma versão anterior do MongoDB , verá queryHash em vez de planCacheShapeHash.

planCacheKey

Uma string hexadecimal que representa o hash da chave usada para localizar a entrada de cache do plano associada a essa query. A chave do cache do plano é uma função da forma de query do cache do plano e dos índices atualmente disponíveis para essa forma. Consulte explain.queryPlanner.planCacheKey.

cachedPlan

Os detalhes do plano em cache. Os campos incluídos no cachedPlan variam dependendo se a query foi concluída usando o mecanismo clássico ou o mecanismo de execução de query baseado em slots. Para obter mais informações sobre planos de query, consulte explain.queryPlanner.

works

O número de "unidades de trabalho" executadas pelo plano de execução da query durante o período de teste quando o planejador de query avalia os planos candidatos. Para mais informações, consulte 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 do cache do plano.

estimatedSizeBytes

O tamanho estimado em bytes de uma entrada de cache do plano.

querySettings

Novidades na versão 8.0.

Um documento que contém configurações de query definidas anteriormente usando setQuerySettings:

querySettings: {
   indexHints: [ {
      ns: { db: <string>, coll: <string> },
      allowedIndexes: <array>
   }, ... ],
   queryFramework: <string>
}

querySettings campos:

Campo

Tipo

Descrição

indexHints.ns

documento

Namespace para dicas de índice.

`db`	string	Nome do banco de banco de dados para dicas de índice.
`coll`	string	Nome da coleção para dicas de índice.

indexHints.allowedIndexes

array

Array de índices para dicas de índice. Para obter mais detalhes, consulte Índices e hint().

queryFramework

string

A string da estrutura da query pode ser:

classic para o mecanismo clássico.
sbe para mecanismo de execução de query baseado em slot. Para obter detalhes, consulte Mecanismo de execução de query baseado em slot.

host

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 Redação.

shard

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

Disponível somente se executado em um cluster fragmentado.

Para queries que usam o mecanismo de execução de queries baseado em slots, $planCacheStats retorna um documento semelhante ao seguinte:

{
   "version" : 2,
   "planCacheShapeHash" : <hexadecimal string>,
   "planCacheKey" : <hexadecimal string>,
   "isActive" :  <boolean>,
   "works" : <NumberLong>,
   "cachedPlan" : {
      "slots" : <string>,
      "stages": <string>
   },
   "indexFilterSet" : <boolean>,
   "estimatedSizeBytes" : <num>,
   "querySettings" : <document>,
   "host" : <string>
}

Cada documento inclui vários planos de query e várias estatísticas de execução, inclusive:

Campo

Descrição

version

Um número que indica o mecanismo de query usado para concluir a query.

1 indica que o mecanismo clássico foi usado.
2 indica que o mecanismo de execução de query baseado em slot foi usado.

planCacheShapeHash

Uma string hexadecimal que representa o hash da forma de query. Consulte explain.queryPlanner.planCacheShapeHash.

planCacheKey

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.

Consulte Planejar o estado de entrada do cache.

works

cachedPlan

indexFilterSet

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

estimatedSizeBytes

O tamanho estimado em bytes de uma entrada de cache do plano.

querySettings

Novidades na versão 8.0.

Um documento que contém configurações de query definidas anteriormente usando setQuerySettings:

querySettings: {
   indexHints: [ {
      ns: { db: <string>, coll: <string> },
      allowedIndexes: <array>
   }, ... ],
   queryFramework: <string>
}

querySettings campos:

Campo

Tipo

Descrição

indexHints.ns

documento

Namespace para dicas de índice.

`db`	string	Nome do banco de banco de dados para dicas de índice.
`coll`	string	Nome da coleção para dicas de índice.

indexHints.allowedIndexes

array

Array de índices para dicas de índice. Para obter mais detalhes, consulte Índices e hint().

queryFramework

string

A string da estrutura da query pode ser:

classic para o mecanismo clássico.
sbe para mecanismo de execução de query baseado em slot. Para obter detalhes, consulte Mecanismo de execução de query baseado em slot.

host

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

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

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

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'
     }
   ],

Aviso

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

Aviso

Consulte também planCacheKey e planCacheShapeHash.

Voltar

$out

$project