db.collection.explain()
Nesta página
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 adb.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âmetroTipoDescriçãoverbosity
stringOpcional. 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 interpretatrue
como"allPlansExecution"
efalse
como"queryPlanner"
.Para obter mais informações sobre os modos, consulte Modos de Verbosidade.
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:
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:
A construção
db.collection.explain().find()
permite o sequenciamento adicional de modificadores de query. Para ver a lista de modificadores de query, consulte db.coleção.explain().find().help().O
db.collection.find().explain()
retorna um cursor, o que exige uma chamada a.next()
, ou seu alias.finish()
, para retornar os resultadosexplain()
. Se executado de forma interativa emmongosh
,mongosh
chama automaticamente.finish()
para retornar os resultados. No entanto, para scripts, você deve chamar explicitamente.next()
ou.finish()
para retornar os resultados. Para ver a lista de métodos relacionados ao cursor, consulte db.collection.explain().find().help()..
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();