$listSearchIndexes (agregação)

Nesta página

Definição

Sintaxe
Campos de comando
Controle de acesso
Saída
Detalhes de status do índice
Detalhes de mapeamento de sinônimo
Status do índice do Atlas Search
Errors
Exemplos
Retornar todos os índices de pesquisa
Retornar um índice de pesquisa único por nome
Retornar um índice de pesquisa único 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 qualquer um dos seguintes campos:

Campo	Tipo	necessidade	Descrição
`id`	string	Opcional	O id do índice sobre o 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 coleção.

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 banco de dados ou na collection:

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

A função read integrada 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 exclusivo para o í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 query.
`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 de í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 do 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 criado em segundo plano no `mongot`correspondente. Esse campo só aparece se você estiver criando 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. Esse campo só aparece 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) só aparecem 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 de 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 do índice está pronta para passar por query no `mongot` correspondente.
`synonymMappingStatus`	string	O estado dos mapeamentos de sinônimos da geração de índice no `mongot` correspondente. Presente somente 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) só aparecem 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 da definição de índice com a qual esta geração de índice está sendo construída.
`definitionVersion.version`	inteiro	Número da versão que a geração do índice está usando no `mongot` correspondente. Quando você atualiza uma definição de índice, o índice atualizado é criado com um número de versão incrementado.
`definitionVersion.createdAt`	data	Hora em que a definição de índice foi criada.
`definition`	documento	A definição com a qual esse índice está sendo construído.

Detalhes de mapeamento de sinônimo

A tabela a seguir descreve os campos incorporados 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 dar suporte a consultas 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 coleção. 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 usar o índice para queries até que a criação do índice esteja concluída. Para um índice existente, o Atlas Search usa a definição de índice antiga para query até que a reconstrução do índice seja concluída. Um índice no estado `BUILDING` pode ser consultável ou não.
`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 criaçã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.
`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 tem suporte para queries. Um índice no estado `READY` é sempre consultável.
`STALE`	O índice é consultável, mas parou de replicar dados da coleção indexada. As 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.

Errors

Alterado na versão 7.0.3: Este comando exibe 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, esse comando retorna um resultado vazio quando não é executado no Atlas.

Exemplos

Esses exemplos demonstram como:

Retornar todos os índices de pesquisa
Retornar um índice de pesquisa único por nome
Retornar um índice de pesquisa único 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 índice de pesquisa único 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 índice de pesquisa único 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 usar um método mongosh para visualizar os índices do Atlas Search, consultedb.collection.getSearchIndexes().

Para criar índices do Atlas Search , consulte:

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

Voltar

$listSampledQueries

$listSessions