Explicação de resultados

Esta versão da documentação foi arquivada e não é mais suportada. Para atualizar seu sistema do 5.0, consulte osprocedimentos de atualização do MongoDB 6.0 .

Para retornar informações sobre planos de query e estatísticas de execução dos planos de query, o MongoDB fornece:

o método db.collection.explain() ,
o método cursor.explain() e
o comando explain.

Os resultados explain apresentam os planos de query como uma árvore de estágios.

"winningPlan" : {
   "stage" : <STAGE1>,
   ...
   "inputStage" : {
      "stage" : <STAGE2>,
      ...
      "inputStage" : {
         "stage" : <STAGE3>,
         ...
      }
   }
},

Cada estágio passa seus resultados (ou seja, documentos ou chaves de índice) para o nó pai. Os nós da folha acessam a collection ou os índices. Os nós internos manipulam os documentos ou as chaves de índice resultantes dos nós filhos. O nó raiz é o estágio final do qual o MongoDB deriva o conjunto de resultados.

As etapas são descritivas da operação; por exemplo

COLLSCAN para uma verificação de collection
IXSCAN para varredura de chaves de índice
FETCH para recuperar documentos
SHARD_MERGE para mesclar resultados de shards
SHARDING_FILTER para filtrar documentos órfãos de shards

Explicar a saída

As seções a seguir apresentam uma lista de alguns campos-chave retornados pela operação explain .

Observação

A lista de campos não tem a média de ser exaustiva, mas sim de destacar algumas alterações de campo importantes em relação a versões anteriores de explicação.
O formato de saída está sujeito a alterações entre as versões.

`queryPlanner`

queryPlanner as informações detalham o plano selecionado pelo otimizador de query.

Para collections não fragmentadas, explain retorna as seguintes informações queryPlanner:

"queryPlanner" : {
   "plannerVersion" : <int>,
   "namespace" : <string>,
   "indexFilterSet" : <boolean>,
   "parsedQuery" : {
      ...
   },
   "queryHash" : <hexadecimal string>,
   "planCacheKey" : <hexadecimal string>,
   "optimizedPipeline" : <boolean>, // Starting in MongoDB 4.2, only appears if true
   "winningPlan" : {
      "stage" : <STAGE1>,
      ...
      "inputStage" : {
         "stage" : <STAGE2>,
         ...
         "inputStage" : {
            ...
         }
      }
   },
   "rejectedPlans" : [
      <candidate plan 1>,
      ...
   ]
}

Para coleções fragmentadas, explain inclui o planejador de queries principal e as informações do servidor para cada fragmento acessado no campo shards:

"queryPlanner" : {
   "mongosPlannerVersion" : <int>,
   "winningPlan" : {
      "stage" : <STAGE1>,
      "shards" : [
         {
            "shardName" : <string>,
            "connectionString" : <string>,
            "serverInfo" : {
               "host" : <string>,
               "port" : <int>,
               "version" : <string>,
               "gitVersion" : <string>
            },
            "plannerVersion" : <int>,
            "namespace" : <string>,
            "parsedQuery" : <document>,
            "queryHash" : <hexadecimal string>,
            "planCacheKey" : <hexadecimal string>,
            "optimizedPipeline" : <boolean>, // Starting in MongoDB 4.2, only appears if true
            "winningPlan" : {
               "stage" : <STAGE2>,
               "inputStage" : {
                  "stage" : <STAGE3>
                  ...,
               }
            },
            rejectedPlans: [
              <candidate plan1>,
            ]
         }
      ]
   }
}

explain.queryPlanner

Contém informações sobre a seleção do plano de query pelo otimizador de query.

explain.queryPlanner.namespace: Uma string que especifica o namespace com os nomes do banco de dados e a collection acessada pela query. O namespace tem o formato <database>.<collection>.

explain.queryPlanner.indexFilterSet: Um booleano que especifica se o MongoDB aplicou um filtro de índice para a forma de query.

explain.queryPlanner.queryHash

Uma string hexadecimal que representa o hash da forma de query e depende somente das formas de query. queryHash pode ajudar a identificar queries lentas (incluindo o filtro de query de operações de gravação) com a mesma forma de query.

Observação

Como em qualquer função de hash, duas formas de query diferentes podem resultar no mesmo valor de hash. No entanto, a ocorrência de colisões de hash entre diferentes formas de query é improvável.

Para obter mais informações sobre queryHash e planCacheKey, consulte queryHash e planCacheKey.

Novidades na versão 4.2.

explain.queryPlanner.planCacheKey

Um hash da chave para a entrada de cache do plano associada à query.

Ao contrário de queryHash, planCacheKey é uma função tanto da forma da consulta quanto dos índices atualmente disponíveis para essa forma. Ou seja, se os índices compatíveis com a forma da consulta forem adicionados/descartados, o valor planCacheKey poderá mudar, mas o valor queryHash não mudará.

Para obter mais informações sobre queryHash e planCacheKey, consulte queryHash e planCacheKey.

Novidades na versão 4.2.

explain.queryPlanner.optimizedPipeline

Um booleano que indica que toda a operação de aggregation pipeline foi otimizada e, em vez disso, cumprida por uma árvore de estágios de execução do plano de query.

Por exemplo, a seguinte operação de agregação pode ser realizada pela árvore de execução do plano de query em vez de usar o pipeline de agregação.

db.example.aggregate([ { $match: { someFlag: true } } ] )

O campo só está presente se o valor for true e só se aplica para explicar as operações de aggregation pipeline. Quando true, como o pipeline foi otimizado, nenhuma informação do estágio de aggregation aparece no resultado.

Novidades na versão 4.2.

explain.queryPlanner.winningPlan

Um documento que detalha o plano selecionado pelo otimizador de query. O MongoDB apresenta o plano como uma árvore de estágios; ou seja, um estágio pode ter um inputStage ou, se o estágio tiver vários estágios filhos, inputStages.

explain.queryPlanner.winningPlan.stage

Uma string que indica o nome do estágio.

Cada estágio consiste em informações específicas para o estágio. Por exemplo, um estágio IXSCAN incluirá os limites do índice além de outros dados específicos para sua verificação. Se um estágio tiver um ou vários estágios-filho, o estágio terá um inputStage ou inputStage.

explain.queryPlanner.winningPlan.inputStage: Um documento que descreve o estágio filho, que fornece os documentos ou as chaves de índice para seu pai. O campo estará presente se o estágio pai tiver apenas um filho.

explain.queryPlanner.winningPlan.inputStages: Uma série de documentos que descrevem os estágios filhos. Os estágios filhos fornecem os documentos ou chaves de índice para o estágio pai. O campo está presente se o estágio pai tiver vários nós filhos. Por exemplo, estágios para expressões $or ou interseção de índice consomem entradas de várias fontes.

explain.queryPlanner.rejectedPlans: Array de planos candidatos considerados e rejeitados pelo otimizador de query. A array pode estar vazia se não houver outros planos candidatos.

`executionStats`

As informações executionStats retornadas detalham a execução do plano vencedor. Para incluir executionStats nos resultados, você deve executar a explicação em:

executionStats ou
Modo de detalhamento allPlansExecution . Utilize o modo allPlansExecution para incluir dados de execução parcial capturados durante a seleção de plano.

Para collections não fragmentadas, explain retorna as seguintes informações executionStats:

"executionStats" : {
   "executionSuccess" : <boolean>,
   "nReturned" : <int>,
   "executionTimeMillis" : <int>,
   "totalKeysExamined" : <int>,
   "totalDocsExamined" : <int>,
   "executionStages" : {
      "stage" : <STAGE1>
      "nReturned" : <int>,
      "executionTimeMillisEstimate" : <int>,
      "works" : <int>,
      "advanced" : <int>,
      "needTime" : <int>,
      "needYield" : <int>,
      "saveState" : <int>,
      "restoreState" : <int>,
      "isEOF" : <boolean>,
      ...
      "inputStage" : {
         "stage" : <STAGE2>,
         "nReturned" : <int>,
         "executionTimeMillisEstimate" : <int>,
         ...
         "inputStage" : {
            ...
         }
      }
   },
   "allPlansExecution" : [
      {
         "nReturned" : <int>,
         "executionTimeMillisEstimate" : <int>,
         "totalKeysExamined" : <int>,
         "totalDocsExamined" :<int>,
         "executionStages" : {
            "stage" : <STAGEA>,
            "nReturned" : <int>,
            "executionTimeMillisEstimate" : <int>,
            ...
            "inputStage" : {
               "stage" : <STAGEB>,
               ...
               "inputStage" : {
                 ...
               }
            }
         }
      },
      ...
   ]
}

Para coleções fragmentadas, explain inclui as estatísticas de execução de cada fragmento acessado.

"executionStats" : {
   "nReturned" : <int>,
   "executionTimeMillis" : <int>,
   "totalKeysExamined" : <int>,
   "totalDocsExamined" : <int>,
   "executionStages" : {
      "stage" : <STAGE1>
      "nReturned" : <int>,
      "executionTimeMillis" : <int>,
      "totalKeysExamined" : <int>,
      "totalDocsExamined" : <int>,
      "totalChildMillis" : <NumberLong>,
      "shards" : [
         {
            "shardName" : <string>,
            "executionSuccess" : <boolean>,
            "executionStages" : {
               "stage" : <STAGE2>,
               "nReturned" : <int>,
               "executionTimeMillisEstimate" : <int>,
               ...
               "chunkSkips" : <int>,
               "inputStage" : {
                  "stage" : <STAGE3>,
                  ...
                  "inputStage" : {
                     ...
                  }
               }
            }
         },
         ...
      ]
   }
   "allPlansExecution" : [
      {
         "shardName" : <string>,
         "allPlans" : [
            {
               "nReturned" : <int>,
               "executionTimeMillisEstimate" : <int>,
               "totalKeysExamined" : <int>,
               "totalDocsExamined" :<int>,
               "executionStages" : {
                  "stage" : <STAGEA>,
                  "nReturned" : <int>,
                  "executionTimeMillisEstimate" : <int>,
                  ...
                  "inputStage" : {
                     "stage" : <STAGEB>,
                     ...
                     "inputStage" : {
                       ...
                     }
                  }
               }
            },
            ...
         ]
      },
      {
         "shardName" : <string>,
         "allPlans" : [
          ...
         ]
      },
      ...
   ]
}

explain.executionStats

Contém estatísticas que descrevem a execução da query concluída para o plano vencedor. Para operações de gravação, a execução da query concluída refere-se às modificações que seriam executadas, mas não aplicam as modificações no banco de dados.

explain.executionStats.nReturned: Número de documentos retornados pelo plano de query vencedor. nReturned corresponde ao campo n retornado pelo cursor.explain() em versões anteriores do MongoDB.

explain.executionStats.executionTimeMillis

Tempo total em milissegundos necessário para a seleção do plano de query e a execução da query. Inclui o tempo necessário para executar a parte da fase de avaliação do processo de seleção do plano, mas não inclui o tempo de rede para transmitir os dados de volta ao cliente.

O tempo relatado por explain.executionStats.executionTimeMillis não é necessariamente representativo do tempo real da query. Durante operações de estado estacionário (quando o plano de query é armazenado em cache) ou ao usar cursor.hint() com cursor.explain(), o MongoDB ignora o processo de seleção do plano, resultando em um tempo real mais rápido, levando a um valor explain.executionStats.executionTimeMillis mais baixo.

explain.executionStats.totalKeysExamined: Número de entradas de índices verificadas. totalKeysExamined corresponde ao campo nscanned retornado por cursor.explain() em versões anteriores do MongoDB.

explain.executionStats.totalDocsExamined: Número de documentos examinados durante a execução da query. As etapas comuns de execução de query que examinam documentos são COLLSCAN e FETCH.
Observação
totalDocsExamined refere-se ao número total de documentos examinados e não ao número de documentos devolvidos. Por exemplo, um estágio pode examinar um documento para aplicar um filtro. Se o documento for filtrado, ele foi examinado, mas não será retornado como parte do conjunto de resultados da query.
Se um documento for analisado várias vezes durante a execução da consulta, totalDocsExamined contará cada análise. Ou seja, totalDocsExamined não é uma contagem do número total de documentos exclusivos analisados.

explain.executionStats.executionStages

Detalha a execução completa do plano vencedor como uma árvore de estágios; ou seja, um estágio pode ter um inputStage ou vários inputStages.

Cada estágio consiste em informações de execução específicas do estágio.

explain.executionStats.executionStages.executionTimeMillisEstimate: O tempo estimado em milissegundos para a execução da query.

explain.executionStats.executionStages.works: Especifica o número de "unidades de trabalho" executadas pelo estágio de execução da query. A execução da query divide seu trabalho em pequenas unidades. Uma "unidade de trabalho" pode consistir em examinar uma única chave de índice, buscar um único documento da collection, aplicar uma projeção a um único documento ou fazer uma contabilidade interna.

explain.executionStats.executionStages.advanced: O número de resultados intermediários retornados, ou avançados, por esse estágio em relação ao estágio pai.

explain.executionStats.executionStages.needTime: O número de ciclos de trabalho que não avançaram um resultado intermediário para o estágio pai (consulte explain.executionStats.executionStages.advanced). Por exemplo, um estágio de varredura de índice pode passar um ciclo de trabalho buscando uma nova posição no índice em vez de retornar uma chave de índice; esse ciclo de trabalho contaria para explain.executionStats.executionStages.needTime em vez de explain.executionStats.executionStages.advanced.

explain.executionStats.executionStages.needYield: O número de vezes que a camada de armazenamento solicitou que o estágio de query suspendesse o processamento e gerasse suas travas.

explain.executionStats.executionStages.saveState: O número de vezes que o estágio da query suspendeu o processamento e salvou seu estado de execução atual, por exemplo, na preparação para gerar travas.

explain.executionStats.executionStages.restoreState: O número de vezes que o estágio da query restaurou um estado de execução salvo, por exemplo, depois de recuperar travas que ele havia gerado anteriormente.

explain.executionStats.executionStages.isEOF

Especifica se o estágio de execução atingiu o fim do fluxo:

Se true ou 1, o estágio de execução chegou ao fim do fluxo.
Se false ou 0, o estágio ainda pode ter resultados para retornar. Por exemplo, considere uma query com um limite cujos estágios de execução consistem em um estágio LIMIT com um estágio de entrada de IXSCAN para a query. Se a query retornar mais do que o limite especificado, o estágio LIMIT informará isEOF: 1, mas o estágio IXSCAN subjacente informará isEOF: 0.

explain.executionStats.executionStages.inputStage.keysExamined

Para estágios de execução de queries que analisam um índice (por exemplo, IXSCAN), keysExamined é o número total de chaves dentro e fora dos limites que são examinadas no processo de varredura do índice. Se a varredura do índice consistir em uma única faixa contígua de chaves, somente as chaves dentro dos limites precisarão ser examinadas. Se os limites do índice consistirem em várias faixas de chaves, o processo de execução de varredura do índice poderá examinar chaves fora dos limites para pular do final de uma faixa para o início da próxima.

Considere o exemplo a seguir, onde há um índice do campo x e a coleção contém 100 documentos com x valores 1 a 100:

db.keys.find( { x : { $in : [ 3, 4, 50, 74, 75, 90 ] } } ).explain( "executionStats" )

A query verificará as chaves 3 e 4. Em seguida, ele verificará a chave 5, detectará que está fora dos limites e pulará para a próxima chave 50.

Continuando esse processo, a query verifica as chaves 3, 4, 5, 50, 51, 74, 75, 76, 90 e 91. Chaves 5, 51, 76 e 91 são chaves fora dos limites que ainda são examinadas. O valor de keysExamined é 10.

explain.executionStats.executionStages.inputStage.docsExamined

Especifica o número de documentos verificados durante o estágio de execução da query.

Presente para o estágio COLLSCAN , bem como para os estágios que recuperam documentos da coleção (por exemplo FETCH)

explain.executionStats.executionStages.inputStage.seeks: Novidades na versão 3.4: Somente para estágios de verificação de índice (IXSCAN).
O número de vezes que tivemos que buscar o cursor do índice para uma nova posição para concluir a varredura do índice.

explain.executionStats.allPlansExecution: Contém informações de execução parcial capturadas durante a fase de seleção do plano para os planos vencedores e rejeitados. O campo está presente somente se o explain executar no modo de detalhamentoallPlansExecution.

Estatística do plano de execução da query com `$lookup` estágio de pipeline

Novidades na versão 5.0.

Os resultados da explicação podem incluir estatísticas de execução para consultas que usam um estágio de pipeline $lookup. Para incluir essas estatísticas de execução, você deve executar a operação de explicação em um destes modos de detalhamento de execução:

Os seguintes campos são incluídos nos resultados explicativos para uma query $lookup:

'$lookup': {
   from: <string>,
   as: <string>,
   localField: <string>,
   foreignField: <string>
},
totalDocsExamined: <long>,
totalKeysExamined: <long>,
collectionScans: <long>,
indexesUsed: [ <string_1>, <string_2>, ..., <string_n> ],
executionTimeMillisEstimate: <long>

Para ver as descrições dos campos na seção $lookup, consulte a página $lookup.

Os outros campos são:

explain.totalDocsExamined: Número de documentos examinados durante a execução da query.

explain.totalKeysExamined: Número de chaves de índice examinadas.

explain.collectionScans: Número de vezes em que ocorreu uma análise de collection durante a execução da query. Durante uma análise de collection, cada documento em uma collection é comparado ao predicado da query. As análises de collection ocorrem se não houver um índice apropriado que cubra a query.

explain.indexesUsed: Array de strings com os nomes dos índices utilizados pela query.

explain.executionTimeMillisEstimate: Tempo estimado em milissegundos para execução da query.

`serverInfo`

Para collections não fragmentadas, explain retorna as seguintes informações serverInfo para a instância MongoDB:

"serverInfo" : {
   "host" : <string>,
   "port" : <int>,
   "version" : <string>,
   "gitVersion" : <string>
}

Para coleções fragmentadas, explain retorna serverInfo para cada fragmento acessado e um objeto serverInfo de nível superior para mongos.

"queryPlanner" : {
   ...
   "winningPlan" : {
      "stage" : <STAGE1>,
      "shards" : [
         {
            "shardName" : <string>,
            "connectionString" : <string>,
            "serverInfo" : {
               "host" : <string>,
               "port" : <int>,
               "version" : <string>,
               "gitVersion" : <string>
            },
            ...
         }
         ...
      ]
   }
 },
 "serverInfo" : {      // serverInfo for mongos
   "host" : <string>,
   "port" : <int>,
   "version" : <string>,
   "gitVersion" : <string>
 }
 ...

3.0 Alteração de formato

A partir do MongoDB 3.0, o formato e os campos dos resultados explain foram alterados em relação às versões anteriores. A seguir, listamos algumas diferenças importantes.

Varredura de collection versus uso de índice

Se o planejador de queries selecionar uma varredura de collection, o resultado da explicação incluirá um estágio COLLSCAN.

Se o planejador de query selecionar um índice, o resultado de explicação incluirá um estágio IXSCAN. O estágio inclui informações como o padrão da chave do índice, a direção da travessia e os limites do índice.

Em versões anteriores do MongoDB, cursor.explain() retornou o campo cursor com o valor de:

BasicCursor para verificações de collection e
BtreeCursor <index name> [<direction>] para verificações de índice.

Para obter mais informações sobre estatística de execução de verificações de coleção versus verificações de índice, consulte Analisar o desempenho da consulta.

Queries cobertas

Quando um índice cobre uma query, o MongoDB pode corresponder as condições da query e retornar os resultados usando apenas as chaves de índice. O MongoDB não precisa examinar documentos da coleção para executar qualquer parte da query.

Quando um índice abrange uma consulta, o resultado de explicação tem um estágio IXSCAN que não é descendente de um estágio FETCH e, no executionStats, o totalDocsExamined é 0.

Em versões anteriores do MongoDB, o cursor.explain() retornou o campo indexOnly para indicar se o índice cobriu uma query.

Interseção de índice

Para um plano de interseção de índice, o resultado incluirá um estágio AND_SORTED ou um estágio AND_HASH com uma array inputStages que detalha os índices; por exemplo:

{
   "stage" : "AND_SORTED",
   "inputStages" : [
      {
         "stage" : "IXSCAN",
         ...
      },
      {
         "stage" : "IXSCAN",
         ...
      }
   ]
}

Em versões anteriores do MongoDB, o cursor.explain() retornou o campo cursor com o valor de Complex Plan para interseções de índice.

`$or` Expressão

Se o MongoDB utilizar índices para uma expressão $or, o resultado incluirá o estágio OR com uma array inputStages que detalha os índices. Ex.:

{
   "stage" : "OR",
   "inputStages" : [
      {
         "stage" : "IXSCAN",
         ...
      },
      {
         "stage" : "IXSCAN",
         ...
      },
      ...
   ]
}

Em versões anteriores do MongoDB, o cursor.explain() retornou a array clauses que detalhou os índices.

`$sort` e `$group` estágios

Quando explain é executado no modo de detalhamento executionStats ou allPlansExecution, os estágios $sort e $group têm saída adicional.

Estágio	Campo	Tipo	Descrição
`$sort`	`totalDataSizeSortedBytesEstimate`	long	Um número estimado de bytes processados no estágio `$sort`.
`$sort`	`usedDisk`	booleano	Se o estágio `$sort` foi gravado em disco.
`$group`	`totalOutputDataSizeBytes`	long	Uma estimativa do tamanho total de todos os documentos gerados pelo estágio `$group` em bytes.
`$group`	`usedDisk`	booleano	Se o estágio `$group` foi gravado em disco.

Estágio de classificação

Se o MongoDB não puder usar um ou mais índices para obter a ordem de classificação, os resultados incluirão um estágio SORT indicando uma operação do ordenador bloqueante. Os ordenadores bloqueantes não bloqueiam operações concomitantes na collection ou no banco de dados. O nome refere-se ao requisito de que o estágio SORT leia todos os documentos de entrada antes de retornar documentos de saída, bloqueando o fluxo de dados para essa query específica.

Se o MongoDB exigir o uso de mais de 100 megabytes de memória do sistema para a operação de block sort, o MongoDB retornará um erro a menos que a query especifique cursor.allowDiskUse(). cursor.allowDiskUse() permite que o MongoDB use arquivos temporários em disco para armazenar dados que excedam o limite de 100 megabytes de memória do sistema durante o processamento de uma operação de block sort. Se o plano de explicação não contiver um estágio SORT explícito, o MongoDB poderá usar um índice para obter a ordem de classificação.

Voltar

Analisar o desempenho

Database Profiler

Explicar a saída

Observação

queryPlanner

Observação

executionStats

Observação

Estatística do plano de execução da query com $lookup estágio de pipeline

serverInfo

3.0 Alteração de formato

Varredura de collection versus uso de índice

Queries cobertas

Interseção de índice

$or Expressão

$sort e $group estágios

Estágio de classificação

`queryPlanner`

`executionStats`

Estatística do plano de execução da query com `$lookup` estágio de pipeline

`serverInfo`

`$or` Expressão

`$sort` e `$group` estágios