explicar
Definição
explain
O comando
explain
fornece informações sobre a execução dos seguintes comandos:aggregate
,count
,distinct
,find
,findAndModify
,delete
,mapReduce
eupdate
.Dica
Em
mongosh
, esse comando também pode ser executado por meio dos métodos auxiliaresdb.collection.explain()
ecursor.explain()
.Os métodos auxiliares são práticos para os usuários
mongosh
, mas podem não retornar o mesmo nível de informações que os comandos do banco de dados. Nos casos em que a praticidade não for necessária ou os campos de retorno adicionais forem necessários, use o comando de banco de dados.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.
Compatibilidade
Esse comando 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
Sintaxe
O comando tem a seguinte sintaxe:
db.runCommand( { explain: <command>, verbosity: <string>, comment: <any> } )
Campos de comando
O comando utiliza os seguintes campos:
Campo | Tipo | Descrição |
---|---|---|
explain | documento | |
verbosity | string | Opcional. Uma string que especifica o modo no qual executar Os modos possíveis são:
Para mais informações sobre os modos, consulte explicar comportamento. |
comment | qualquer | Opcional. Um comentário fornecido pelo usuário para anexar a este comando. Depois de definido, esse comentário aparece junto com os registros desse comando nos seguintes locais:
Um comentário pode ser qualquer tipo BSON válido (string, inteiro, objeto, array etc). ObservaçãoSe você especificar |
Comportamento
Modos de Verbosidade
O comportamento de explain
e a quantidade de informações retornadas dependem do modo verbosity
.
O MongoDB executa o otimizador de query para escolher o plano vencedor para a operação em avaliação. explain
retorna as informações queryPlanner
para o <command>
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 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.
explain
retorna as informações queryPlanner
e executionStats
do <command>
avaliado. No entanto, o executionStats
não fornece informações de execução da query para os planos rejeitados.
Por padrão, explain
é executado no modo de detalhamento "allPlansExecution"
.
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 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.
explain
retorna as informações queryPlanner
e executionStats
do <command>
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, o comando explain
retorna informações sobre a operação de gravação que seria executada, mas na verdade não modifica o banco de dados.
Stable API
A API estável V1 aceita os seguintes modos de verbosidade para o comando explain
:
Aviso
O MongoDB não garante nenhum formato de saída específico do comando explain
, mesmo ao usar a stable API.
Restrições
Você não pode executar o comando explain
/db.collection.explain()
no modo executionStats
ou allPlansExecution
para um aggregation pipeline
que contenha o estágio $out
. Em vez disso, você pode:
Saída
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
O comando explain
a seguir é executado no modo de verbosidade "queryPlanner"
para retornar as informações do planejamento de query de um comando count
:
db.runCommand( { explain: { count: "products", query: { quantity: { $gt: 50 } } }, verbosity: "queryPlanner" } )
executionStats
Modo
A operação explain
a seguir é executada no modo de verbosidade "executionStats"
para retornar as informações de planejamento e execução da query para um comando count
:
db.runCommand( { explain: { count: "products", query: { quantity: { $gt: 50 } } }, verbosity: "executionStats" } )
allPlansExecution
Modo
Por padrão, explain
é executado no modo de verbosidade "allPlansExecution"
. O comando explain
a seguir retorna o queryPlanner
e o executionStats
para todos os planos considerados para um comando update
:
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.runCommand( { explain: { update: "products", updates: [ { q: { quantity: 1057, category: "apparel" }, u: { $set: { reorder: true } } } ] } } )