explicar

Definição

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.

Compatibilidade

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

• 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

Acesso necessário

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

Sintaxe

O comando tem a seguinte sintaxe:

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

Campos de comando

O comando utiliza os seguintes campos:

Comportamento

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.

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

Exemplos

db.runCommand(
   {
     explain: { count: "products", query: { quantity: { $gt: 50 } } },
     verbosity: "queryPlanner"
   }
)

db.runCommand(
   {
      explain: { count: "products", query: { quantity: { $gt: 50 } } },
      verbosity: "executionStats"
   }
)

db.runCommand(
   {
     explain: {
        update: "products",
        updates: [
           {
               q: { quantity: 1057, category: "apparel" },
               u: { $set: { reorder: true } }
           }
        ]
     }
   }
)