Explicação de resultados
Nesta página
Para obter informações sobre os planos de query e sobre as estatísticas de execução dos planos de query, o MongoDB oferece os seguintes métodos:
Para saber mais sobre campos de resultados explicativos importantes e como interpretá-los, consulte a página Interpretar os resultados do plano de explicação.
Importante
explain
ignora o cache do plano. Em vez disso, um conjunto de planos candidatos é gerado, e um vencedor é escolhido sem consultar o cache do plano. Além disso, explain
impede que o planejador de consultas do MongoDB armazene em cache o plano vencedor.
Observação
Somente os campos de saída mais importantes são mostrados nesta página, e os campos para uso interno não estão documentados. Os campos listados na saída estão sujeitos a alterações.
Explicar estrutura de saída
Os resultados explain
apresentam os planos de query como uma árvore de estágios. A estrutura de saída pode diferir com base em qual mecanismo de query a operação utiliza. As operações podem usar o mecanismo de query clássico ou o mecanismo de query de execução baseado em slots.
Para ver como a estrutura de saída pode diferir entre os dois mecanismos de execução, consulte os seguintes exemplos:
winningPlan: { stage: <STAGE1>, ... inputStage: { stage: <STAGE2>, ... inputStage: { stage: <STAGE3>, ... } } },
winningPlan: { queryPlan: { stage: <STAGE1>, ... inputStage: { stage: <STAGE2>, ... inputStage: { stage: <STAGE3>, ... } } } slotBasedPlan: { ... } },
Cada estágio passa seus documentos resultantes ou chaves de índice para o nó pai. Os nós da folha acessam a collection ou os índices. Os nós internos usam os documentos ou as chaves de índice resultantes dos nós filhos. O nó raiz indica o estágio 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 collectionIXSCAN
para varredura de chaves de índiceFETCH
para recuperar documentosGROUP
para agrupar documentosSHARD_MERGE
para mesclar resultados de shardsSHARDING_FILTER
para filtrar documentos órfãos de shardsBATCHED_DELETE
para exclusões de vários documentos agrupados internamente (a partir do MongoDB 6.1)
Explicar a saída para MongoDB 5.1 e posterior
Esta seção mostra a saída explain
para MongoDB 5.1 e versões posteriores. Para ver a saída de explicação para versões mais antigas do MongoDB, consulte a documentação dessa versão.
explain.explainVersion
Campo inteiro.
explainVersion
é a versão do formato de saída do plano, como"1"
ou"2"
.Novidades na versão 5.1.
queryPlanner
explain.queryPlanner
as informações detalham o plano selecionado pelo otimizador de query.
Esses exemplos podem combinar as estruturas de saída dos mecanismos de execução clássicos e baseados em slots do MongoDB. Eles não pretendem ser representativos. Sua saída pode diferir significativamente.
Para collections não fragmentadas, explain
retorna as seguintes informações queryPlanner
:
queryPlanner: { namespace: <string>, indexFilterSet: <boolean>, parsedQuery: { ... }, queryHash: <hexadecimal string>, planCacheKey: <hexadecimal string>, maxIndexedOrSolutionsReached: <boolean>, maxIndexedAndSolutionsReached: <boolean>, maxScansToExplodeReached: <boolean>, winningPlan: { stage: <STAGE1>, inputStage: { stage: <string>, ... } }, rejectedPlans: [ <candidate plan1>, ] }
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: { ... }, namespace: <string>, indexFilterSet: <boolean>, parsedQuery: { ... }, queryHash: <hexadecimal string>, planCacheKey: <hexadecimal string>, maxIndexedOrSolutionsReached: <boolean>, maxIndexedAndSolutionsReached: <boolean>, maxScansToExplodeReached: <boolean>, winningPlan: { stage: <STAGE1>, inputStage: { stage: <string>, ... } }, 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
eplanCacheKey
, consultequeryHash
eplanCacheKey
.
explain.queryPlanner.planCacheKey
Um hash da chave para a entrada de cache do plano associada à query.
Ao contrário de
explain.queryPlanner.queryHash
,explain.queryPlanner.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 valorplanCacheKey
poderá mudar, mas o valorqueryHash
não mudará.Para obter mais informações sobre
queryHash
eplanCacheKey
, consultequeryHash
eplanCacheKey
.
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. Quandotrue
, como o pipeline foi otimizado, nenhuma informação do estágio de aggregation aparece no resultado.
explain.queryPlanner.winningPlan
Um documento que detalha o plano selecionado pelo otimizador de query.
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
inclui 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áinputStage
ouinputStages
.Este campo aparece se a operação utilizou o mecanismo de execução de query clássico.
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 podem consumir entradas de várias fontes.
Este campo aparece se a operação utilizou o mecanismo de execução de query clássico.
explain.queryPlanner.winningPlan.queryPlan
Um documento que detalha o plano selecionado pelo otimizador de query. O MongoDB apresenta o plano como uma árvore de estágios.
Esse documento aparece se a query tiver usado o mecanismo de query de execução baseado em slots.
Novidades na versão 5.1.
explain.queryPlanner.winningPlan.queryPlan.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
inclui os limites do índice além de outros dados específicos para sua verificação.
explain.queryPlanner.winningPlan.queryPlan.planNodeId
Campo inteiro exclusivo que identifica cada estágio do plano de execução. O campo está incluído em todos os estágios dos resultados
explain
.Novidades na versão 5.1.
executionStats
As informações explain.executionStats
retornadas detalham a execução do plano vencedor. Para incluir executionStats
nos resultados, você deve executar a explicação em:
Modo de detalhamento allPlansExecution . Utilize o modo
allPlansExecution
para incluir dados de execução parcial capturados durante a seleção de plano.
Esses exemplos podem combinar as estruturas de saída dos mecanismos de execução clássicos e baseados em slots do MongoDB. Eles não pretendem ser representativos. Sua saída pode diferir significativamente.
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>, opens: <int>, // Starting in MongoDB 5.1 closes: <int>, // Starting in MongoDB 5.1 works: <int>, advanced: <int>, needTime: <int>, needYield: <int>, saveState: <int>, restoreState: <int>, isEOF: <boolean>, ... inputStage: { stage: <STAGE2>, nReturned: <int>, ... numReads: <int>, // Starting in MongoDB 5.1 ... executionTimeMillisEstimate: <int>, ... inputStage: { ... } } }, allPlansExecution: [ { nReturned: <int>, executionTimeMillisEstimate: <int>, totalKeysExamined: <int>, totalDocsExamined:<int>, executionStages: { stage: <STAGEA>, nReturned: <int>, executionTimeMillisEstimate: <int>, ... inputStage: { stage: <STAGEB>, ... inputStage: { ... } } } }, ... ] operationMetrics: { cpuNanos: <int>, cursorSeeks: <int>, docBytesRead: <int>, docBytesWritten: <int>, docUnitsRead: <int>, docUnitsReturned: <int>, docUnitsWritten: <int>, idxEntryBytesRead: <int>, idxEntryBytesWritten: <int>, idxEntryUnitsRead: <int>, idxEntryUnitsWritten: <int>, totalUnitsWritten: <int>, keysSorted: <int>, sorterSpills: <int> } }
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>, opens: <int>, // Starting in MongoDB 5.1 closes: <int>, // Starting in MongoDB 5.1 totalKeysExamined: <int>, totalDocsExamined: <int>, totalChildMillis: <NumberLong>, shards: [ { shardName: <string>, executionSuccess: <boolean>, executionStages: { stage: <STAGE2>, nReturned: <int>, executionTimeMillisEstimate: <int>, ... chunkSkips: <int>, inputStage: { stage: <STAGE3>, ... numReads: <int>, // Starting in MongoDB 5.1 ... 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 campon
retornado pelocursor.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 usarcursor.hint()
comcursor.explain()
, o MongoDB ignora o processo de seleção do plano, resultando em um tempo real mais rápido, levando a um valorexplain.executionStats.executionTimeMillis
mais baixo.
explain.executionStats.totalKeysExamined
Número de entradas de índices verificadas.
explain.executionStats.totalKeysExamined
corresponde ao camponscanned
retornado porcursor.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
eFETCH
.Observação
explain.executionStats.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,
explain.executionStats.totalDocsExamined
contará cada análise. Ou seja,explain.executionStats.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áriosinputStages
.A partir do MongoDB 5.1, um estágio pode ter estes estágios de entrada:
thenStage
elseStage
innerStage
outerStage
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.opens
A partir do MongoDB 5.1, o número de vezes que um estágio foi aberto durante a execução de query
explain.executionStats.executionStages.closes
A partir do MongoDB 5.1, o número de vezes que um estágio foi fechado durante a execução de 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.
Este campo aparece se a operação utilizou o mecanismo de execução de query clássico.
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
ou1
, o estágio de execução chegou ao fim do fluxo.Se
false
ou0
, 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ágioLIMIT
com um estágio de entrada deIXSCAN
para a query. Se a query retornar mais do que o limite especificado, o estágioLIMIT
informaráisEOF: 1
, mas o estágioIXSCAN
subjacente informaráisEOF: 0
.
explain.executionStats.executionStages.inputStage
Cada
inputStage
pode ter campos diferentes dependendo do valor deinputStage.stage
. A tabela a seguir descreve possíveis campos e em quais estágios eles podem aparecer.Cada
inputStage
pode ter outroinputStage
como um campo. Consulte Explicar estrutura de saída.CampoDescriçãoEstágios aplicáveisdocsExamined
Especifica o número de documentos verificados durante o estágio de execução da query.COLLSCAN
,FETCH
keysExamined
Para estágios de execução de queries que analisam um índicekeysExamined
é 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.IXSCAN
numReads
O número de documentos verificados ou chaves de índice examinadas durante o estágio de execução da query.
Novidades na versão 5.1.
COLLSCAN
,IXSCAN
seeks
O número de vezes que tivemos que buscar o cursor do índice para uma nova posição para concluir a varredura do índice.IXSCAN
spilledBytesApprox
O número aproximado de bytes na memória distribuídos no disco no estágio.
Novidades na versão 5.3.
GROUP
spilledRecords
O número de registros produzidos transferidos para o disco no estágio.
Novidades na versão 5.3.
GROUP
usedDisk
Se o estágio foi gravado em disco.
Novidades na versão 5.3.
GROUP
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
.
explain.executionStats.operationMetrics
Contém estatísticas de consumo de recursos, desde que não sejam zero. O campo estará presente somente se
explain
for executado no modo de detalhamentoexecutionStats
ou superior e seprofileOperationResourceConsumptionMetrics
estiver ativo.
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> } ...
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:
Varredura de collection
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.
A partir do MongoDB 5.3, se o planejador de consulta selecionar um índice clusterizado para uma coleção clusterizada e a consulta contiver limites que definem a parte do índice a ser pesquisada, o resultado da explicação incluirá um estágio CLUSTERED_IXSCAN
. O estágio inclui informações sobre a chave de índice agrupada e os limites do índice.
Se o planejador de queries selecionar um índice clusterizado para uma coleção clusterizada e a query não contiver limites, a query executará uma varredura de coleção não limitada e o resultado da explicação incluirá um estágio COLLSCAN
.
Observação
O parâmetro notablescan
não permite queries ilimitadas que usam um índice clusterizado porque as queries exigem uma varredura completa da collection.
Para obter mais informações sobre estatística de execução de verificações de coleção, consulte Interpretar resultados do plano de explicação.
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 collection 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 explain.executionStats.totalDocsExamined
é 0
.
$or
Expressão
Se o MongoDB utilizar índices para uma expressão $or
, o resultado incluirá o estágio OR
com uma array explain.queryPlanner.winningPlan.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 |
---|---|---|---|
totalDataSizeSortedBytesEstimate | long | Um número estimado de bytes processados no estágio $sort . | |
usedDisk | booleano | Se o estágio $sort foi gravado em disco. | |
totalOutputDataSizeBytes | long | Uma estimativa do tamanho total de todos os documentos gerados pelo estágio $group em bytes. | |
usedDisk | booleano | Se o estágio $group foi gravado em disco. | |
spillFileSizeBytes | long | Tamanho do arquivo gravado no disco no estágio $group . Devido à compressão, o valor de spillFileSizeBytes deve ser menor ou igual a numBytesSpilledEstimate . | |
numBytesSpilledEstimate | long | Uma estimativa do número de bytes gravados no disco no estágio $group antes da compressão. |
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.