As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Análise do plano de consulta
A análise do plano de consulta por meio do plano de explicação fornece informações essenciais sobre o desempenho das consultas do Amazon DocumentDB. O plano de consulta com ExecutionStats revela as principais métricas, incluindo:
+ Documentos devolvidos por estágio (nReturned)
+ Tempos de execução específicos do estágio (estimativa) executionTimeMillis
+ Duração da geração do plano (planningTimeMillis)
Ao examinar a saída do plano de consulta, os desenvolvedores podem analisar os padrões de execução, avaliar a utilização do índice e identificar possíveis oportunidades de otimização nos estágios do pipeline de consulta.
Para analisar o plano de consulta, você pode usar o comando explain () nos formatos a seguir.
```
db.runCommand({explain: {query document}, verbosity: "executionStats"})
db.collection.find().explain("executionStats");
```
Veja a seguir um exemplo de operação:
```
db.collection.find({ companyname: { '$eq': 'ANYCOMPANY' }, isDeleted: { '$eq': false } }).sort({"createdAt":1}).limit(2).explain("executionStats");
```
A saída dessa operação é semelhante à seguinte:
```
{
queryPlanner: {
plannerVersion: 2,
namespace: 'limit_test.test',
winningPlan: {
stage: 'LIMIT_SKIP',
inputStage: {
stage: 'SORT',
sortPattern: { createdAt: 1 },
inputStage: {
stage: 'IXSCAN',
indexName: 'companyname_1_createdAt_1_isDeleted_1',
direction: 'forward',
indexCond: {
'$and': [
{ companyname: { '$eq': 'ANYCOMPANY' } },
{ isDeleted: { '$eq': false } }
]
}
}
}
}
},
indexFilterSet: false,
indexFilterApplied: false,
executionStats: {
executionSuccess: true,
executionTimeMillis: '4.186',
planningTimeMillis: '3.909',
executionStages: {
stage: 'LIMIT_SKIP',
nReturned: '2',
executionTimeMillisEstimate: '0.199',
inputStage: {
stage: 'SORT',
nReturned: '2',
executionTimeMillisEstimate: '0.197',
sortPattern: { createdAt: 1 },
inputStage: {
stage: 'IXSCAN',
nReturned: '34',
executionTimeMillisEstimate: '0.151',
indexName: 'companyname_1_createdAt_1_isDeleted_1',
direction: 'forward',
indexCond: {
'$and': [
{ companyname: { '$eq': 'ANYCOMPANY' } },
{ isDeleted: { '$eq': false } }
]
}
}
}
}
},
serverInfo: { host: 'demo-cluster', port: 27017, version: '5.0.0' },
ok: 1,
operationTime: Timestamp({ t: 1759915116, i: 1 })
}
```
Abaixo está uma análise detalhada de um plano de execução de consultas do Amazon DocumentDB, detalhando cada componente e suas características de desempenho.
## Cronometragem geral
executionTimeMillis representa o tempo total gasto pela consulta, incluindo o tempo de planejamento.
planningTimeMillis representa o tempo total de planejamento gasto pela consulta.
## Estágios de execução
Ele descreve o step-by-step processo que o Amazon DocumentDB usa para executar uma consulta, mostrando como os dados fluem por meio de diferentes operações.
```
"executionStages": {
"stage": "[STAGE_NAME]",
"nReturned": "[NUMBER_OF_DOCS]",
"executionTimeMillisEstimate": "[TIME]",
"inputStage": {
// Nested stages
}
}
```
### Estágios comuns em um plano de consulta
Abaixo estão os estágios comuns de execução em um plano de consulta. Cada estágio retorna as métricas executionTimeMillis Estimate (tempo de execução) e nReturned (número de documentos) para ajudar a avaliar o desempenho da consulta em cada estágio.
#### COLLSCAN (Digitalização de coleção)
+ Digitaliza todo o documento da coleção por documento
+ nReturned: retorna todos os documentos correspondentes na coleção
+ Pode ser uma operação cara, vista quando nenhum índice está disponível
#### IXSCAN (Digitalização de índice)
+ Usa um índice para encontrar documentos correspondentes
+ nReturned: Somente documentos correspondentes com base no índice
+ Operação eficiente, preferida ao COLLSCAN
#### SORT
+ Classifica documentos com base em campos especificados
+ Se o atributo de classificação na consulta não fizer parte de um índice, esse estágio aparecerá explicitamente
+ nRetornado: Mesmo número dos documentos de entrada
+ Consome muita memória para grandes conjuntos de resultados. Para otimizar, adicione o nome do campo de classificação a um índice
#### LIMIT\_SKIP
+ Controla o número de documentos devolvidos e ignorados
+ nRetornado: Limitado pelo valor LIMITE
+ Usado para operações de paginação ou LIMIT
#### SUBVARREDURA
+ Executa operações de consulta aninhadas
+ nReturned: varia com base nos resultados da subconsulta
+ Usado em consultas complexas com vários estágios
Estágios com alta executionTimeMillis estimativa são bons candidatos para otimização.
**nota**
No momento, o parâmetro ExecutionStats não oferece suporte aos comandos de atualização e exclusão.
## Compreendendo os documentos examinados em Explique as estatísticas de execução do plano
Quando você executa uma consulta com`explain("executionStats")`, o Amazon DocumentDB fornece métricas de exame que ajudam você a entender quantos documentos foram digitalizados para produzir os resultados da consulta. Essas métricas são úteis para identificar planos de consulta ineficientes e otimizar o desempenho.
**nota**
Disponível somente no Amazon DocumentDB 8.0.0\+.
### Campos
| Campo | Description | Nível |
| --- | --- | --- |
| totalDocsExamined | Número total de documentos examinados em todos os estágios de execução. | ExecutionStats de alto nível |
| Documentos examinados | Número de documentos examinados por um estágio específico de execução. | Nível de estágio |
O `docsExamined` campo aparece nos seguintes estágios:
| Estágio | Description |
| --- | --- |
| COLLSCAN | Digitalização da coleção. Todos os documentos da coleção são examinados. |
| IXSCAN | Escaneamento de índice. Somente documentos que correspondam à condição do índice são examinados. |
| FETCH | Quando o otimizador recupera documentos em um estágio separado do IXSCAN, o estágio FETCH relata DocsExamined. Nos planos de escaneamento de índice, os estágios secundários do IXSCAN não relatam DocsExamined. Nos planos $lookup, tanto o estágio FETCH quanto seus estágios secundários podem relatar DocsExamined. |
**nota**
`docsExamined`não aparece nos estágios do IXONLYSCAN porque a consulta é satisfeita inteiramente a partir do índice sem acessar documentos.
### Mostrar documentos examinados na saída do Explain Plan ExecutionStats
Os exemplos a seguir usam uma coleção com 500.000 documentos e demonstram como isso `docsExamined` muda em diferentes estágios de execução da consulta.
Crie dados de amostra:
```
for (let i = 0; i < 500000; i++) {
db.coll.insertOne({ number: i, arr: [i, [i+1]], value: "test", bool: i % 2 === 0 });
}
```
#### Digitalização de coleção (COLLSCAN)
Sem um índice, o Amazon DocumentDB executa uma varredura completa da coleção.
```
db.coll.find({ "number": { "$lt": 500 } }).explain("executionStats").executionStats
```
Saída:
```
{
"executionSuccess" : true,
"nReturned" : "500",
"executionTimeMillis" : "282.055",
"planningTimeMillis" : "0.085",
"totalDocsExamined" : "500000",
"executionStages" : {
"stage" : "COLLSCAN",
"nReturned" : "500",
"executionTimeMillisEstimate" : "281.915",
"docsExamined" : "500000",
"filter" : {
"number" : {
"$lt" : 500
}
}
}
}
```
Todos os 500.000 documentos foram examinados para retornar 500 resultados. Criar um índice no campo numérico melhora isso.
#### Análise de índice (IXSCAN)
```
db.coll.createIndex({ number: 1 });
db.coll.find({ "number": { "$lt": 5000 } }).explain("executionStats").executionStats
```
Saída:
```
{
"executionSuccess" : true,
"nReturned" : "5000",
"executionTimeMillis" : "3.047",
"planningTimeMillis" : "0.296",
"totalDocsExamined" : "5000",
"executionStages" : {
"stage" : "IXSCAN",
"nReturned" : "5000",
"executionTimeMillisEstimate" : "2.576",
"indexName" : "number_1",
"direction" : "forward",
"docsExamined" : "5000",
"indexCond" : {
"$and" : [
{
"number" : {
"$lt" : 5000
}
}
]
}
}
}
```
Com o índice, apenas 5.000 dos 500.000 documentos foram examinados e buscados, correspondendo ao número retornado. A condição do índice filtrou 495.000 documentos que não correspondiam à consulta.
#### Digitalização de índice com filtro residual
```
db.coll.find({ "number": { "$lt": 5000 }, "arr": { "$gt": 4000 } }).explain("executionStats").executionStats
```
Saída:
```
{
"executionSuccess" : true,
"nReturned" : "999",
"executionTimeMillis" : "15.367",
"planningTimeMillis" : "0.115",
"totalDocsExamined" : "5000",
"executionStages" : {
"stage" : "IXSCAN",
"nReturned" : "999",
"executionTimeMillisEstimate" : "15.170",
"indexName" : "number_1",
"direction" : "forward",
"docsExamined" : "5000",
"indexCond" : {
"$and" : [
{
"number" : {
"$lt" : 5000
}
}
]
},
"filter" : {
"arr" : {
"$gt" : 4000
}
}
}
}
```
A condição do índice correspondeu a 5.000 documentos de 500.000 e, em seguida, o filtro residual `arr` reduziu o resultado para 999. O `docsExamined` valor de 5.000 reflete todos os documentos examinados após a condição do índice, mas antes da aplicação do filtro residual.
#### Busque com o IXSCAN
```
db.coll.find({ "$or": [{ "number": { "$lt": 100000 } }, { "number": { "$gt": 400000 } }] }).explain("executionStats").executionStats
```
Saída:
```
{
"executionSuccess" : true,
"nReturned" : "199999",
"executionTimeMillis" : "899.801",
"planningTimeMillis" : "0.183",
"totalDocsExamined" : "199999",
"executionStages" : {
"stage" : "FETCH",
"nReturned" : "199999",
"executionTimeMillisEstimate" : "894.141",
"docsExamined" : "199999",
"inputStage" : {
"stage" : "IXOR",
"nReturned" : "0",
"executionTimeMillisEstimate" : "874.897",
"inputStages" : [
{
"stage" : "IXSCAN",
"nReturned" : "100000",
"executionTimeMillisEstimate" : "462.208",
"indexName" : "number_1",
"indexCond" : {
"$and" : [
{
"number" : {
"$lt" : 100000
}
}
]
}
},
{
"stage" : "IXSCAN",
"nReturned" : "99999",
"executionTimeMillisEstimate" : "412.684",
"indexName" : "number_1",
"indexCond" : {
"$and" : [
{
"number" : {
"$gt" : 400000
}
}
]
}
}
]
}
}
}
```
Quando o otimizador Amazon DocumentDB usa um estágio de busca para recuperar documentos, o estágio FETCH relata. `docsExamined` Os estágios secundários do IXSCAN não relatam `docsExamined` porque eles apenas digitalizam as chaves de índice sem acessar os documentos diretamente.
#### FETCH com pesquisa agregada
```
db.coll.explain("executionStats").aggregate([
{ $match: { "number": { "$lt": 5 } } },
{ $lookup: { from: "coll", pipeline: [{ $match: { "number": { "$lt": 3 } } }], as: "sub" } }
]).executionStats
```
Saída:
```
{
"executionSuccess" : true,
"nReturned" : "5",
"executionTimeMillis" : "0.525",
"planningTimeMillis" : "0.327",
"totalDocsExamined" : "9",
"executionStages" : {
"stage" : "NESTED_LOOP_LOOKUP",
"nReturned" : "5",
"executionTimeMillisEstimate" : "0.163",
"inputStages" : [
{
"stage" : "IXSCAN",
"nReturned" : "5",
"executionTimeMillisEstimate" : "0.039",
"indexName" : "number_1",
"direction" : "forward",
"docsExamined" : "5",
"indexCond" : {
"$and" : [
{
"number" : {
"$lt" : 5
}
}
]
}
},
{
"stage" : "FETCH",
"nReturned" : "1",
"executionTimeMillisEstimate" : "0.009",
"docsExamined" : "1",
"inputStage" : {
"stage" : "AGGREGATE",
"nReturned" : "1",
"executionTimeMillisEstimate" : "0.044",
"inputStage" : {
"stage" : "IXSCAN",
"nReturned" : "3",
"executionTimeMillisEstimate" : "0.013",
"indexName" : "number_1",
"direction" : "forward",
"docsExamined" : "3",
"indexCond" : {
"$and" : [
{
"number" : {
"$lt" : 3
}
}
]
}
}
}
}
]
}
}
```
O IXSCAN externo examinou 5 documentos com números menores que 5. O IXSCAN interno examinou 3 documentos com número < 3, e o estágio FETCH examinou 1 resultado agregado. O `totalDocsExamined` de 9 é a soma de todos os estágios (5 \+ 3 \+ 1).