cursor.explain()
Definição
cursor.explain(verbosity)
Importante
Método mongosh
Esta página documenta um método
mongosh
. Esta não é a documentação de um driver de idioma específico, como Node.js.Para drivers de API do MongoDB, consulte a documentação do driver do MongoDB específica da linguagem.
Fornece informações sobre o plano de query para o método
db.collection.find()
.O método
explain()
tem o seguinte formulário:db.collection.find().explain() O método
explain()
tem o seguinte parâmetro:ParâmetronecessidadeTipoDescriçãoverbose
OpcionalStringDetermina a quantidade de informações a incluir no resultado de explicação. Os possíveis modos de verbosidade são:
allPlansExecution
executionStats
queryPlanner
(Padrão)
Para compatibilidade com versões anteriores do
explain()
, MongoDB interpretatrue
comoallPlansExecution
efalse
comoqueryPlanner
.Para obter mais informações sobre os modos, consulte Modos de detalhamento.
O método
explain()
retorna um documento com o plano de query e, opcionalmente, as estatísticas de execução.
Compatibilidade
Esse método está disponível em implantações hospedadas nos seguintes ambientes:
MongoDB Atlas: o serviço totalmente gerenciado para implantações do MongoDB na nuvem
Observação
Este comando é aceito em todos os clusters do MongoDB Atlas. Para obter informações sobre o suporte do Atlas a todos os comandos, consulte Comandos não suportados.
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 cursor.explain()
e a quantidade de informações retornadas dependem do modo verbosity
.
queryPlanner
Modo
Por padrão, cursor.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. cursor.explain()
retorna as informações queryPlanner
do método avaliado.
executionStats
Modo
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.
cursor.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.
allPlansExecution
Modo
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.
cursor.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.
db.collection.explain().find()
db.collection.explain().find()
é semelhante ao db.collection.find().explain()
com as seguintes diferenças principais:
A construção
db.collection.explain().find()
permite o sequenciamento adicional de modificadores de consulta. Para ver a lista de modificadores de consulta, consulte db.collection.explain().find().help().O
db.collection.find().explain()
retorna um cursor, que requer uma chamada para.next()
, ou seu alias.finish()
, para retornar os resultadosexplain()
. Se executado interativamente 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().
Consulte db.collection.explain()
para mais informações.
Saída
cursor.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.queryShapeHash
, começando no MongoDB 8.0, que é uma string hexadecimal com o hash de uma forma de consulta. Para obter detalhes, consulte Formas de consulta, Hash de forma de consulta eexplain.queryShapeHash
.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.
Exemplo
O exemplo a seguir é executado cursor.explain()
no modo de detalhamento "executionStats" para retornar as informações de planejamento e execução da query para a operação de db.collection.find()
especificada:
db.products.find( { quantity: { $gt: 50 }, category: "apparel" } ).explain("executionStats")