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

db.collection.explain()

Nesta página

  • Descrição
  • 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 para comandos de banco de dados ou drivers específicos de idioma, 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 MongoDB específica do idioma.

Para a documentação de shell legada do mongo, consulte a documentação para a versão correspondente do MongoDB Server:

mongo shell v4.4

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.

Comportamento

Observação

O uso do explain ignora todas as entradas de cache do plano existentes e impede 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 .

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

Para operações de gravação, 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, o db.collection.explain() executa no modo de verbosidade do "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 cursor de retorno explain().find()

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

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

Nesta página