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
  • Compatibilidade
  • Comportamento
  • Saída
  • Exemplos

Descrição

db.collection.explain()

Importante

Método mongosh

Esta página documenta um método mongosh. Esta não é a documentação de comandos de banco de dados nem drivers específicos de linguagem, como Node.js.

Para o comando do banco de dados, consulte o comando explain .

Para drivers de API do MongoDB, consulte a documentação do driver do MongoDB específica da linguagem.

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

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.

Compatibilidade

Esse método está disponível em implantações hospedadas nos seguintes ambientes:

  • MongoDB Atlas: o serviço totalmente gerenciado para implantações MongoDB na nuvem

Observação

Este comando é suportado em todos os clusters do MongoDB Atlas. Para obter informações sobre todos os comandos, consulte Comandos sem suporte.

  • MongoDB Enterprise: a versão autogerenciada e baseada em assinatura do MongoDB

  • MongoDB Community: uma versão com código disponível, de uso gratuito e autogerenciada do MongoDB

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, 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 no 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, 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 no 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 no modo 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 preferido 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 query suportados pelo 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.

  • 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 funciona db.collection.explain() no modo de verbosidade "queryPlanner" para retornar as informações de planejamento de query para a operação count() especificada:

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

executionStats Modo

O exemplo a seguir funciona db.collection.explain() no modo de verbosidade "executionStats" para retornar as informações de planejamento e execução da query para a operação 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 construct db.collection.explain().find() permite o encadeamento de query modifiers. 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.coleção.estimatedDocumentCount

Próximo

db.collection.find

Nesta página