Menu Docs

Página inicial do Docs → Desenvolver aplicações → Manual do MongoDB

explicar

Nesta página

  • Definição
  • Compatibilidade
  • Sintaxe
  • Campos de comando
  • Comportamento
  • Saída
  • Exemplos

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 db.collection.explain() e cursor.explain() auxiliar.

Os métodos auxiliares são convenientes 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 conveniência não for necessária ou os campos de retorno adicionais forem necessários, use o comando de banco de dados.

Observação

O uso do explain ignora todas as entradas de cache do plano existentes e impede que o planejador de query do MongoDB crie uma nova entrada de cache do plano.

Compatibilidade

Este comando está disponível em sistemas hospedados 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 não suportados.

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
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 explain. O modo afeta o comportamento de explain 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
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ção

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

Comportamento

Modos de Verbosidade

O comportamento de explain e a quantidade de informações retornadas dependem do modo verbosity .

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 API estável.

Restrições

A partir do MongoDB 4.2, 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:

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

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

Exemplos

queryPlanner Modo

O commando explain a seguir é executado no verbosity mode "queryPlanner" para retornar as query planning information para um commando count :

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

executionStats Modo

A operation a seguir explain é executada no "executionStats" verbosidade para retornar as de da count para um :

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

allPlansExecution Modo

Por padrão, o explain executa no modo de verbosidade do "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 } }
           }
        ]
     }
   }
)
← driverOIDTest
características →

Nesta página