Menu Docs
Página inicial do Docs
/
Manual do MongoDB
/
Referência
/
Métodos de mongosh
/
Collections

db.collection.explain()

Nesta página

  • Descrição
  • Acesso necessário
  • Comportamento
  • Saída
  • Exemplos

MongoDB com drivers

Esta página documenta um método mongosh. Para ver o método equivalente em um driver MongoDB, consulte a página correspondente da sua linguagem de programação:

C#Java SyncNode.jsPyMongoCC++GoJava RSKotlin CoroutineKotlin SyncPHPMongoidRustScala

Descrição

db.collection.explain()

Retorna informações no plano de query para os seguintes métodos:

  • aggregate()

  • count()

Retorna informações sobre mapReduce().

Para usar db.collection.explain(), acrescente um dos métodos mencionados acima a db.collection.explain():

db.collection.explain().<method(...)>

Por exemplo,

db.products.explain().remove( { category: "apparel" }, { justOne: true } )

Para mais exemplos, consulte Exemplos. Consulte também db.collection.explain().help().

O método db.collection.explain() tem o seguinte parâmetro:

Parâmetro
Tipo
Descrição

verbosity

string

Opcional. Especifica o modo de verbosidade para o resultado de explicação. O modo afeta o comportamento de explain() e determina a quantidade de informações a serem retornadas. Os modos possíveis são:

  • "queryPlanner" (Padrão)

  • "executionStats"

  • "allPlansExecution"

Para compatibilidade com versões anteriores do cursor.explain(), MongoDB interpreta true como "allPlansExecution" e false como "queryPlanner".

Para obter mais informações sobre os modos, consulte Modos de Verbosidade.

Acesso necessário

Para utilizar o explain, você deve ter permissão para executar o comando subjacente.

Comportamento

Observação

Usar explain ignora todas as entradas de cache do plano existentes e evita que o planejador de query do MongoDB crie uma nova entrada de cache do plano.

Modos de Verbosidade

O comportamento de db.collection.explain() e a quantidade de informações retornadas dependem do modo verbosity.

Por padrão, db.collection.explain() é executado no modo de detalhamento queryPlanner.

O MongoDB executa o otimizador de query para escolher o plano vencedor para a operação em avaliação. db.collection.explain() retorna as informações queryPlanner do método avaliado.

O MongoDB executa o otimizador de query para escolher o plano vencedor, executa o plano vencedor até a conclusão e retorna estatísticas que descrevem a execução do plano vencedor.

Para operações de gravação, db.collection.explain() retorna informações sobre as operações de atualização ou exclusão que seriam executadas, mas não aplica as modificações ao banco de dados.

db.collection.explain() retorna as informações queryPlanner e executionStats do método avaliado. No entanto, o executionStats não fornece informações de execução da query para os planos rejeitados.

O MongoDB executa o otimizador de query para escolher o plano vencedor e executar o plano vencedor para conclusão. No modo "allPlansExecution", MongoDB retorna estatísticas descrevendo a execução do plano vencedor, bem como estatísticas para os outros planos candidatos capturados durante a seleção do plano.

Para operações de gravação, db.collection.explain() retorna informações sobre as operações de atualização ou exclusão que seriam executadas, mas não aplica as modificações ao banco de dados.

db.collection.explain() retorna as informações de queryPlanner e executionStats para o método avaliado. O executionStats inclui as informações de execução da query concluída para o plano vencedor.

Se o otimizador de query considerar mais de um plano, as informaçõesexecutionStats também incluirão as informações de execução parcial capturadas durante a fase de seleção do plano para os planos de candidatos vencedores e rejeitados.

Operações de explicação e gravação

Para operações de gravação, db.collection.explain() retorna informações sobre a operação de gravação que seria executada, mas na verdade não modifica o banco de dados.

Restrições

Você não pode executar o comando explain /db.collection.explain() no modo executionStats ou allPlansExecution para um aggregation pipeline que contém o estágio $out. Em vez disso, você pode:

  • executar a explicação no modo queryPlanner ou

  • executar a explicação no modo executionStats ou no modo allPlansExecution, mas sem o estágio $out para retornar informações para os estágios que precedem o estágio $out.

explain() Mecânica

O método db.collection.explain() envolve o comando explain e é o caminho preferencial para executar explain.

db.collection.explain().find() é semelhante a db.collection.find().explain() com as seguintes diferenças principais:

db.collection.explain().aggregate() é equivalente a passar a opção de explicação para o método db.collection.aggregate().

help()

Para visualizar a lista de operações suportadas pelo db.collection.explain(), execute:

db.collection.explain().help()

db.collection.explain().find() retorna um cursor, que permite a cadeia de modificadores de query. Para ver a lista de modificadores de consulta suportados por db.collection.explain().find(), bem como os métodos relacionados ao cursor, execute:

db.collection.explain().find().help()

Você pode encadear vários modificadores para db.collection.explain().find(). Para ver um exemplo, consulte Explicar find() com modificadores.

Saída

db.collection.explain() as operações podem retornar informações sobre:

  • explainVersion, a versão do formato de saída (por exemplo, "1");

  • command, que detalha o comando a ser explicado;

  • queryPlanner, que detalha o plano selecionado pelo otimizador de query e lista os planos rejeitados;

  • executionStats, que detalha a execução do plano vencedor e os planos rejeitados;

  • serverInfo, que fornece informações sobre a instância MongoDB; e

  • serverParameters, que detalha os parâmetros internos.

O modo de verbosidade (ou seja, queryPlanner, executionStats, allPlansExecution) determina se os resultados incluem executionStats e se executionStats inclui dados capturados durante a seleção do plano.

A saída de explicação é limitada pela profundidade máxima aninhada para documentos BSON, que é de 100 níveis de aninhamento. A saída de explicações que excede o limite é truncada.

Para obter detalhes sobre o resultado, consulte Explicar os resultados.

Exemplos

queryPlanner Modo

Por padrão, db.collection.explain() é executado no modo de detalhamento "queryPlanner".

O exemplo a seguir é executado db.collection.explain() no modo de detalhamento "queryPlanner" para retornar as informações de planejamento de consulta para a operação de count() especificada:

db.products.explain().count( { quantity: { $gt: 50 } } )

executionStats Modo

O exemplo a seguir executa db.collection.explain() no modo de detalhamento "executionStats" para retornar as informações de planejamento e execução da query para a operação de find() especificada:

db.products.explain("executionStats").find(
   { quantity: { $gt: 50 }, category: "apparel" }
)

allPlansExecution Modo

O exemplo a seguir executa db.collection.explain() no modo de verbosidade "allPlansExecution". db.collection.explain() retorna queryPlanner e executionStats para todos os planos considerados para a operação findAndModify() especificada:

Observação

A execução desta explicação não modificará os dados, mas executará o predicado de query da operação de atualização. Para planos candidatos, o MongoDB retorna as informações de execução capturadas durante a fase de seleção do plano.

db.products.explain( "allPlansExecution" ).findAndModify( {
   query: { name: "Tom", state: "active", rating: { $gt: 10 } },
   sort: { rating: 1 },
   update: { $inc: { score: 1 } }
} )

Explique find() com modificadores

A construção db.collection.explain().find() permite o encadeamento de modificadores de query. Por exemplo, a operação a seguir fornece informações sobre o método find() com modificadores de query sort() e hint().

db.products.explain("executionStats").find(
   { quantity: { $gt: 50 }, category: "apparel" }
).sort( { quantity: -1 } ).hint( { category: 1, quantity: -1 } )

Para uma lista de modificadores de query disponíveis, execute o seguinte em mongosh:

db.collection.explain().find().help()

Iterar o explain().find() cursor de retorno

db.collection.explain().find() retorna um cursor para os resultados de explicação. Se executado de forma interativa no mongosh, mongosh itera automaticamente o cursor utilizando o método .next(). No entanto, para scripts, você deve chamar explicitamente .next() (ou seu nome alternativo .finish()) para retornar os resultados:

var explainResult = db.products.explain().find( { category: "apparel" } ).next();

Voltar

db.collection.estimatedDocumentCount

Próximo

db.collection.find