/ /

Estágios de aggregation

Página inicial do Docs

/ /

Linguagem de query

Estágios de aggregation

Página inicial do Docs

Desenvolvimento

Referência

Linguagem de query

Estágios de aggregation

$planCacheStats

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 do pipeline. ele toma um documento vazio como parâmetro e tem a seguinte sintaxe:

{ $planCacheStats: { } }

Dica

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

$planCacheStats observa a preferência de leitura ao selecionar o(s) host(s) 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.

Observação

A partir da versão 7.0.17, o mecanismo de execução de queries baseado em slots não está mais ativado por padrão para versões de patch do 7.0. Se você deseja que suas queries usem o mecanismo de execução de queries baseado em slots, atualize para a versão 8.0, onde está habilitado por padrão.

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

{
   "version" : 1,
   "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>,
   "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.

queryHash

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

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

estimatedSizeBytes

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

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

shard

O nome do fragmento do qual recuperou a entrada de $planCacheStats 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,
   "queryHash" : <hexadecimal string>,
   "planCacheKey" : <hexadecimal string>,
   "isActive" :  <boolean>,
   "works" : <NumberLong>,
   "cachedPlan" : {
      "slots" : <string>,
      "stages": <string>
   },
   "indexFilterSet" : <boolean>,
   "estimatedSizeBytes" : <num>,
   "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.
`queryHash`	Uma string hexadecimal que representa o hash da forma de query. Consulte `explain.queryPlanner.queryHash`.
`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 e dos índices atualmente disponíveis para essa forma. Consulte `explain.queryPlanner.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`	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`.
`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`.
`indexFilterSet`	Um booleano que indica se existe um filtro de índice para a forma de query.
`estimatedSizeBytes`	O tamanho estimado em bytes de uma entrada de cache do plano.
`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. Consultetambém Redação.

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

$project