Menu Docs
Página inicial do Docs
/
Manual do MongoDB
/ / /

explicar

Nesta página

  • Definição
  • Compatibilidade
  • Acesso necessário
  • Sintaxe
  • Campos de comando
  • Comportamento
  • Saída
  • Exemplos
explain

O comando explain fornece informações sobre a execução dos seguintes comandos: aggregate, count, distinct, find, findAndModify, delete, mapReduce e update.

Dica

Em mongosh, esse comando também pode ser executado por meio dos métodos auxiliares db.collection.explain() e cursor.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.

Esse comando 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

Para utilizar o explain, você deve ter permissão para executar o comando subjacente.

O comando tem a seguinte sintaxe:

db.runCommand(
{
explain: <command>,
verbosity: <string>,
comment: <any>
}
)

O comando utiliza os seguintes campos:

Campo
Tipo
Descrição

explain

documento

Um documento que especifica o comando para o qual retornar as informações de execução. Para detalhes sobre o documento de comando específico, consulte aggregate, count, distinct, find, findAndModify, delete, mapReduce e update.

verbosity

string

Opcional. Uma string que especifica o modo no qual executar . O modo explain explain afeta o comportamento de e determina a quantidade de informações a serem retornadas.

Os modos possíveis são:

  • "queryPlanner"

  • "executionStats"

  • "allPlansExecution" (Padrão)

Para mais informações sobre os modos, consulte explicar comportamento.

comment

any

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).

Se você especificar explain sem um comment, ele herda qualquer comment no comando especificado para explain.

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, explain retorna informações sobre as operações de atualização ou exclusão que seriam executadas, mas não aplica as modificações ao 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, explain retorna informações sobre as operações de atualização ou exclusão que seriam executadas, mas não aplica as modificações ao 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.

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.

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.

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:

  • 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 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; e

  • 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.

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"
}
)

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"
}
)

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 } }
}
]
}
}
)

Voltar

dbStats