$listSearchIndexes (agregação)

Nesta página

Definição

Sintaxe
Campos de comando
Controle de acesso
Saída
Detalhes do status do índice
Detalhes de mapeamento de sinônimos
Status do índice do Atlas Search
Erros
Exemplos
Retornar todos os índices de pesquisa
Retornar um único índice de pesquisa por nome
Retornar um único índice de pesquisa por id
Saiba mais

Definição

$listSearchIndexes

Novidade na versão 7.0: (Disponível também a partir de 6.0.7)

Retorna informações sobre os índices existentes doAtlas Search em uma collection especificada.

Importante

Esse comando só pode ser executado em uma implantação hospedada no MongoDB Atlas e requer uma camada do cluster Atlas de pelo menos M10.

Sintaxe

Sintaxe do comando:

db.<collection>.aggregate(
   [
      {
         $listSearchIndexes:
            {
               id: <indexId>,
               name: <indexName>
            }
      }
   ]
)

Campos de comando

$listSearchIndexes usa um dos seguintes campos:

Campo	Tipo	necessidade	Descrição
`id`	string	Opcional	A ID do índice sobre a qual retornar informações.
`name`	string	Opcional	O nome do índice sobre o qual retornar informações.

Você não pode especificar id e name. Se você omitir os campos id e name , $listSearchIndexes retornará informações sobre todos os índices do Atlas Search na collection.

Controle de acesso

Se a sua implementação impõe controle de acesso, o usuário que executa o $listSearchIndexes deve ter a ação de privilégio listSearchIndexes no banco de dados ou collection:

{
   resource: {
      db : <database>,
      collection: <collection>
   },
   actions: [ "listSearchIndexes" ]
}

A função read incorporada fornece o privilégio listSearchIndexes . O exemplo a seguir concede a função read no banco de dados qa :

db.grantRolesToUser(
   "<user>",
   [ { role: "read", db: "qa" } ]
)

Saída

$listSearchIndexes retorna uma array de documentos. Cada documento no array contém os seguintes campos:

Campo	Tipo	Descrição
`id`	string	Identificador único do índice.
`name`	string	Nome do índice.
`status`	string	Status do índice. Para mais informações, consulte Status do índice do Atlas Search.
`queryable`	booleano	Indica se o índice está pronto para ser consultado.
`latestDefinitionVersion`	documento	Descreve a versão do índice.
`latestDefinitionVersion.version`	inteiro	Número da versão associado à definição do índice. Quando você atualiza uma definição de índice, o número da versão é incrementado automaticamente.
`latestDefinitionVersion.createdAt`	data	Hora em que a definição do índice atual foi criada.
`latestDefinition`	documento	A definição mais recente para o índice. Para obter mais informações, consulte Sintaxe de definição do índice de pesquisa.
`statusDetail`	matriz de documentos	Contém o status do índice em cada host de pesquisa (`mongot`).
`statusDetail.[n].hostname`	string	Nome de host do `mongot` correspondente.
`statusDetail.[n].status`	string	Status do índice no `mongot` correspondente.
`statusDetail.[n].queryable`	booleano	Indica se o índice está pronto para ser consultado no `mongot` correspondente.
`statusDetail.[n].mainIndex`	documento	Contém informações de status sobre o índice ativo no `mongot` correspondente. Para obter detalhes, consulte Detalhes do status do índice.
`statusDetail.[n].stagedIndex`	documento	Contém informações de status sobre um índice que está sendo construído em background no `mongot` correspondente. Este campo aparece somente se você estiver construindo um novo índice para atualizar um índice ativo existente. Para obter detalhes, consulte Detalhes do status do índice.
`synonymMappingStatus`	string	Status dos mapeamentos de sinônimos do índice. Este campo aparece somente se o índice tiver sinônimos definidos. Pode ser um dos seguintes valores: `BUILDING` `FAILED` `READY` O status retornado é um resumo dos mapeamentos de sinônimos em cada `mongot` individual.
`synonymMappingStatusDetail`	matriz de documentos	Contém o status dos mapeamentos de sinônimos do índice em cada host de pesquisa (`mongot`). Este campo (e seus subcampos) aparece somente se o índice tiver sinônimos definidos.
`synonymMappingStatusDetail.[n].status`	string	Status do mapeamento de sinônimos correspondente em todos os processos `mongot` .
`synonymMappingStatusDetail.[n].queryable`	booleano	Indica se o mapeamento de sinônimos correspondente pode suportar queries em todos os processos do `mongot` .
`message`	string	Descreve um erro para o mapeamento de sinônimos, se aplicável. Só aparece se o `status` para esse mapeamento de sinônimo for `FAILED`.

Detalhes do status do índice

A tabela a seguir descreve os campos incorporados dos seguintes documentos: - statusDetail.[mongot].mainIndex - statusDetail.[mongot].stagedIndex

Os campos descrevem o status do índice em um mongot específico.

Campo	Tipo	Descrição
`status`	string	O estado da geração de índice no `mongot` correspondente.
`queryable`	booleano	Indica se a geração de índice está pronta para ser consultada no `mongot` correspondente.
`synonymMappingStatus`	string	O estado dos mapeamentos de sinônimos da geração de índice no `mongot` correspondente. Somente presente se o índice tiver sinônimos definidos.
`synonymMappingStatusDetails`	documento	Contém o status dos mapeamentos de sinônimos do índice no `mongot` correspondente. Este campo (e seus subcampos) aparece somente se o índice tiver sinônimos definidos. Para obter mais informações, consulte Detalhes de mapeamento de sinônimos.
`definitionVersion`	documento	Descreve a versão de definição de índice com a qual essa geração de índice está sendo construída.
`definitionVersion.version`	inteiro	Número da versão que a geração de índice está usando no `mongot` correspondente. Quando você atualiza uma definição de índice, o índice atualizado é compilado com um número de versão incrementado.
`definitionVersion.createdAt`	data	Hora em que a definição do índice foi criada.
`definition`	documento	A definição com a qual esse índice está sendo construído.

Detalhes de mapeamento de sinônimos

A tabela a seguir descreve os campos embarcados dos seguintes objetos:

statusDetail.mainIndex.synonymMappingStatusDetails.<synonymMapping>
statusDetail.stagedIndex.synonymMappingStatusDetails<synonymMapping>

Campo	Tipo	Descrição
`status`	string	Status do mapeamento de sinônimos no processo `mongot` correspondente.
`queryable`	booleano	Indica se o mapeamento de sinônimos pode suportar queries no processo `mongot` correspondente.
`message`	string	Descreve um erro para o mapeamento de sinônimos, se aplicável. Só aparece se o `status` para esse mapeamento de sinônimo for `FAILED`.

Status do índice do Atlas Search

O campo status na saída $listSearchIndexes pode ser um dos seguintes:

Status	Descrição
`BUILDING`	Os cenários a seguir podem fazer com que um índice esteja no estado `BUILDING` : O Atlas está construindo o índice ou reconstruindo o índice após uma edição. O Atlas Search não consegue acompanhar as alterações de indexação na collection. Neste caso, o Atlas reconstrói o índice em segundo plano. Quando o índice está no estado `BUILDING` : Para um novo índice, o Atlas Search não pode utilizar o índice para queries até que a construção do índice seja concluída. Para um índice existente, o Atlas Search utiliza a definição de índice antiga para queries até que a recriação do índice seja concluída. Um índice no estado `BUILDING` pode ser consultável ou não consultável.
`DOES_NOT_EXIST`	O índice não existe. Um índice no estado `DOES_NOT_EXIST` é sempre não consultável.
`DELETING`	O Atlas está excluindo o índice. Um índice no estado `DELETING` é sempre não consultável.
`FAILED`	A construção do índice falhou. Os índices podem entrar no estado `FAILED` devido a uma definição de índice inválida. Um índice no estado `FAILED` pode ser consultável ou não consultável.
`PENDING`	Atlas ainda não começou a construir o índice. Um índice no estado `PENDING` é sempre não consultável.
`READY`	O índice está pronto e pode suportar queries. Um índice no estado `READY` é sempre consultável.
`STALE`	O índice pode ser consultado, mas parou de replicar dados da coleção indexada. Pesquisas no índice podem retornar dados desatualizados. Os índices podem entrar no estado `STALE` devido a erros de replicação. Um índice no estado `STALE` é sempre consultável.

Erros

Alterado na versão 7.0.3: Este comando lança um erro quando não é executado no Atlas.

db.names.aggregate( [
   { $listSearchIndexes: { } }
] )

MongoServerError: PlanExecutor error during aggregation :: caused by :: Search index commands are only supported with Atlas.

Em versões anteriores, este comando retorna um resultado vazio quando não é executado no Atlas.

Exemplos

Esses exemplos demonstram como:

Retornar todos os índices de pesquisa
Retornar um único índice de pesquisa por nome
Retornar um único índice de pesquisa por id

Retornar todos os índices de pesquisa

O exemplo a seguir retorna todos os índices do Atlas Search na coleção movies :

db.movies.aggregate(
   [
      {
         $listSearchIndexes: { }
      }
   ]
)

Saída de amostra:

[
  {
    id: '6524096020da840844a4c4a7',
    name: 'default',
    status: 'BUILDING',
    queryable: true,
    latestDefinitionVersion: {
      version: 2,
      createdAt: ISODate("2023-10-09T14:51:57.355Z")
    },
    latestDefinition: {
      mappings: { dynamic: true },
      storedSource: { include: [ 'awards.text' ] }
    },
    statusDetail: [
      {
        hostname: 'atlas-n1cm1j-shard-00-02',
        status: 'BUILDING',
        queryable: true,
        mainIndex: {
          status: 'READY',
          queryable: true,
          definitionVersion: {
            version: 0,
            createdAt: ISODate("2023-10-09T14:08:32.000Z")
          },
          definition: { mappings: { dynamic: true, fields: {} } }
        },
        stagedIndex: {
          status: 'PENDING',
          queryable: false,
          definitionVersion: {
            version: 1,
            createdAt: ISODate("2023-10-09T14:51:29.000Z")
          },
          definition: {
            mappings: { dynamic: true, fields: {} },
            storedSource: true
          }
        }
      },
      {
        hostname: 'atlas-n1cm1j-shard-00-01',
        status: 'BUILDING',
        queryable: true,
        mainIndex: {
          status: 'READY',
          queryable: true,
          definitionVersion: {
            version: 0,
            createdAt: ISODate("2023-10-09T14:08:32.000Z")
          },
          definition: { mappings: { dynamic: true, fields: {} } }
        },
        stagedIndex: {
          status: 'PENDING',
          queryable: false,
          definitionVersion: {
            version: 1,
            createdAt: ISODate("2023-10-09T14:51:29.000Z")
          },
          definition: {
            mappings: { dynamic: true, fields: {} },
            storedSource: true
          }
        }
      },
      {
        hostname: 'atlas-n1cm1j-shard-00-00',
        status: 'BUILDING',
        queryable: true,
        mainIndex: {
          status: 'READY',
          queryable: true,
          definitionVersion: {
            version: 0,
            createdAt: ISODate("2023-10-09T14:08:32.000Z")
          },
          definition: { mappings: { dynamic: true, fields: {} } }
        }
      }
    ]
  },
  {
    id: '65240be420da840844a4d077',
    name: 'synonym_mappings',
    status: 'READY',
    queryable: true,
    latestDefinitionVersion: {
      version: 0,
      createdAt: ISODate("2023-10-09T14:19:16.305Z")
    },
    latestDefinition: {
      mappings: {
        dynamic: true,
        fields: {
          fullplot: { type: 'string' }
        }
      },
      synonyms: [
        {
          name: 'synonym_mapping',
          analyzer: 'lucene.english',
          source: { collection: 'synonyms' }
        }
      ]
    },
    synonymMappingStatus: 'READY',
    synonymMappingStatusDetail: [
      {
        synonym_mapping: {
          status: 'READY',
          queryable: true
        }
      }
    ],
    statusDetail: [
      {
        hostname: 'atlas-n1cm1j-shard-00-02',
        status: 'READY',
        queryable: true,
        mainIndex: {
          status: 'READY',
          queryable: true,
          definitionVersion: {
            version: 0,
            createdAt: ISODate("2023-10-09T14:19:16.000Z")
          },
          definition: {
            mappings: {
              dynamic: true,
              fields: {
                fullplot: {
                  type: 'string',
                  indexOptions: 'offsets',
                  store: true,
                  norms: 'include'
                }
              }
            },
            synonyms: [
              {
                name: 'synonym_mapping',
                analyzer: 'lucene.english',
                source: { collection: 'synonyms' }
              }
            ]
          },
          synonymMappingStatus: 'READY',
          synonymMappingStatusDetail: [
            {
              synonym_mapping: {
                status: 'READY',
                queryable: true
              }
            }
          ]
        }
      },
      {
        hostname: 'atlas-n1cm1j-shard-00-01',
        status: 'READY',
        queryable: true,
        mainIndex: {
          status: 'READY',
          queryable: true,
          definitionVersion: {
            version: 0,
            createdAt: ISODate("2023-10-09T14:19:16.000Z")
          },
          definition: {
            mappings: {
              dynamic: true,
              fields: {
                fullplot: {
                  type: 'string',
                  indexOptions: 'offsets',
                  store: true,
                  norms: 'include'
                }
              }
            },
            synonyms: [
              {
                name: 'synonym_mapping',
                analyzer: 'lucene.english',
                source: { collection: 'synonyms' }
              }
            ]
          },
          synonymMappingStatus: 'READY',
          synonymMappingStatusDetail: [
            {
              synonym_mapping: {
                status: 'READY',
                queryable: true
              }
            }
          ]
        }
      },
      {
        hostname: 'atlas-n1cm1j-shard-00-00',
        status: 'READY',
        queryable: true,
        mainIndex: {
          status: 'READY',
          queryable: true,
          definitionVersion: {
            version: 0,
            createdAt: ISODate("2023-10-09T14:19:16.000Z")
          },
          definition: {
            mappings: {
              dynamic: true,
              fields: {
                fullplot: {
                  type: 'string',
                  indexOptions: 'offsets',
                  store: true,
                  norms: 'include'
                }
              }
            },
            synonyms: [
              {
                name: 'synonym_mapping',
                analyzer: 'lucene.english',
                source: { collection: 'synonyms' }
              }
            ]
          },
          synonymMappingStatus: 'READY',
          synonymMappingStatusDetail: [
            {
              synonym_mapping: {
                status: 'READY',
                queryable: true
              }
            }
          ]
        }
      }
    ]
  }
]

Retornar um único índice de pesquisa por nome

O exemplo a seguir retorna o índice chamado synonym-mappings na coleção movies :

db.movies.aggregate(
   [
      {
         $listSearchIndexes:
            {
               name: "synonym-mappings"
            }
      }
   ]
)

Saída de amostra:

[
  {
    id: '65240be420da840844a4d077',
    name: 'synonym_mappings',
    status: 'READY',
    queryable: true,
    latestDefinitionVersion: {
      version: 0,
      createdAt: ISODate("2023-10-09T14:19:16.305Z")
    },
    latestDefinition: {
      mappings: {
        dynamic: true,
        fields: {
          fullplot: { type: 'string' }
        }
      },
      synonyms: [
        {
          name: 'synonym_mapping',
          analyzer: 'lucene.english',
          source: { collection: 'synonyms' }
        }
      ]
    },
    synonymMappingStatus: 'READY',
    synonymMappingStatusDetail: [
      {
        synonym_mapping: {
          status: 'READY',
          queryable: true
        }
      }
    ],
    statusDetail: [
      {
        hostname: 'atlas-n1cm1j-shard-00-02',
        status: 'READY',
        queryable: true,
        mainIndex: {
          status: 'READY',
          queryable: true,
          definitionVersion: {
            version: 0,
            createdAt: ISODate("2023-10-09T14:19:16.000Z")
          },
          definition: {
            mappings: {
              dynamic: true,
              fields: {
                fullplot: {
                  type: 'string',
                  indexOptions: 'offsets',
                  store: true,
                  norms: 'include'
                }
              }
            },
            synonyms: [
              {
                name: 'synonym_mapping',
                analyzer: 'lucene.english',
                source: { collection: 'synonyms' }
              }
            ]
          },
          synonymMappingStatus: 'READY',
          synonymMappingStatusDetail: [
            {
              synonym_mapping: {
                status: 'READY',
                queryable: true
              }
            }
          ]
        }
      },
      {
        hostname: 'atlas-n1cm1j-shard-00-01',
        status: 'READY',
        queryable: true,
        mainIndex: {
          status: 'READY',
          queryable: true,
          definitionVersion: {
            version: 0,
            createdAt: ISODate("2023-10-09T14:19:16.000Z")
          },
          definition: {
            mappings: {
              dynamic: true,
              fields: {
                fullplot: {
                  type: 'string',
                  indexOptions: 'offsets',
                  store: true,
                  norms: 'include'
                }
              }
            },
            synonyms: [
              {
                name: 'synonym_mapping',
                analyzer: 'lucene.english',
                source: { collection: 'synonyms' }
              }
            ]
          },
          synonymMappingStatus: 'READY',
          synonymMappingStatusDetail: [
            {
              synonym_mapping: {
                status: 'READY',
                queryable: true
              }
            }
          ]
        }
      },
      {
        hostname: 'atlas-n1cm1j-shard-00-00',
        status: 'READY',
        queryable: true,
        mainIndex: {
          status: 'READY',
          queryable: true,
          definitionVersion: {
            version: 0,
            createdAt: ISODate("2023-10-09T14:19:16.000Z")
          },
          definition: {
            mappings: {
              dynamic: true,
              fields: {
                fullplot: {
                  type: 'string',
                  indexOptions: 'offsets',
                  store: true,
                  norms: 'include'
                }
              }
            },
            synonyms: [
              {
                name: 'synonym_mapping',
                analyzer: 'lucene.english',
                source: { collection: 'synonyms' }
              }
            ]
          },
          synonymMappingStatus: 'READY',
          synonymMappingStatusDetail: [
            {
              synonym_mapping: {
                status: 'READY',
                queryable: true
              }
            }
          ]
        }
      }
    ]
  }
]

Retornar um único índice de pesquisa por id

O exemplo a seguir retorna o índice de pesquisa com o id fornecido:

db.movies.aggregate(
   [
      {
         $listSearchIndexes:
            {
               id: "6524096020da840844a4c4a7"
            }
      }
   ]
)

Saída de amostra:

[
  {
    id: '6524096020da840844a4c4a7',
    name: 'default',
    status: 'BUILDING',
    queryable: true,
    latestDefinitionVersion: {
      version: 2,
      createdAt: ISODate("2023-10-09T14:51:57.355Z")
    },
    latestDefinition: {
      mappings: { dynamic: true },
      storedSource: { include: [ 'awards.text' ] }
    },
    statusDetail: [
      {
        hostname: 'atlas-n1cm1j-shard-00-02',
        status: 'BUILDING',
        queryable: true,
        mainIndex: {
          status: 'READY',
          queryable: true,
          definitionVersion: {
            version: 0,
            createdAt: ISODate("2023-10-09T14:08:32.000Z")
          },
          definition: { mappings: { dynamic: true, fields: {} } }
        },
        stagedIndex: {
          status: 'PENDING',
          queryable: false,
          definitionVersion: {
            version: 1,
            createdAt: ISODate("2023-10-09T14:51:29.000Z")
          },
          definition: {
            mappings: { dynamic: true, fields: {} },
            storedSource: true
          }
        }
      },
      {
        hostname: 'atlas-n1cm1j-shard-00-01',
        status: 'BUILDING',
        queryable: true,
        mainIndex: {
          status: 'READY',
          queryable: true,
          definitionVersion: {
            version: 0,
            createdAt: ISODate("2023-10-09T14:08:32.000Z")
          },
          definition: { mappings: { dynamic: true, fields: {} } }
        },
        stagedIndex: {
          status: 'PENDING',
          queryable: false,
          definitionVersion: {
            version: 1,
            createdAt: ISODate("2023-10-09T14:51:29.000Z")
          },
          definition: {
            mappings: { dynamic: true, fields: {} },
            storedSource: true
          }
        }
      },
      {
        hostname: 'atlas-n1cm1j-shard-00-00',
        status: 'BUILDING',
        queryable: true,
        mainIndex: {
          status: 'READY',
          queryable: true,
          definitionVersion: {
            version: 0,
            createdAt: ISODate("2023-10-09T14:08:32.000Z")
          },
          definition: { mappings: { dynamic: true, fields: {} } }
        }
      }
    ]
  }
]

Saiba mais

Para utilizar um método mongosh para visualizar índices de Atlas Search, consulte db.collection.getSearchIndexes().

Para criar índices do Atlas Search, consulte:

O método db.collection.createSearchIndex() mongosh
O comando do banco de dados createSearchIndexes

← $listSampledQueries

$listSessions →