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

O índice se baseia nas coleções preenchidas

Nesta página

Comportamento

Impacto de Construções de Índices no Desempenho do Banco de Dados
Construções dos Índices em Ambientes Replicados
Falha e Recuperação de Construções
Monitorar Construções de Índices em Andamento
Encerrar Construções de Índices em Andamento
Processo de Construção de Índices

As compilações de índice usam um processo de compilação otimizado que mantém um bloqueio exclusivo na coleção no início e no final da compilação do índice. O restante do processo de construção resulta em operações intercaladas de leitura e gravação. Para obter uma descrição detalhada do processo de construção de índice e do comportamento de travas, consulte Processo de construção de índice.

Construir índices em um conjunto de réplicas ou cluster particionado é feito simultaneamente em todos os membros do conjunto de réplicas que contêm dados. O primário requer um número mínimo de membros votantes portadores de dados (ou seja, quórum para a confirmação), incluindo ele mesmo, que deve concluir a construção antes de marcar o índice como pronto para uso. Um membro "votante" é qualquer membro do conjunto de réplicas em que members[n].votes seja maior que 0. Consulte Construção de índice em ambientes replicados para obter mais informações.

Comportamento

Comparação de Construções em Foreground e Background

As versões anteriores do MongoDB suportavam a construção de índices em primeiro plano ou em segundo plano. As compilações de índice em primeiro plano eram rápidas e produziam estruturas de dados de índice mais eficientes, mas exigiam o bloqueio de todo o acesso de leitura-gravação ao banco de dados pai da coleção que estava sendo indexada durante a compilação. As compilações de índices em segundo plano foram mais lentas e tiveram resultados menos eficientes, mas permitiram acesso de leitura e gravação ao banco de dados e suas coleções durante o processo de construção.

As compilações de índice agora obtêm um bloqueio exclusivo somente da coleção que está sendo indexada durante o início e o fim do processo de compilação para proteger as alterações de metadados. O restante do processo de compilação usa o comportamento de produção de compilações de índices em segundo plano para maximizar o acesso de leitura e gravação à coleção durante a compilação. As compilações de índice ainda produzem estruturas de dados de índice eficientes, apesar do comportamento de bloqueio mais permissivo.

O desempenho otimizado da construção de índice está pelo menos no mesmo nível das construções de índice em segundo plano. Para volumes de trabalho com poucas ou nenhuma atualização recebida durante o processo de construção, as compilações de índice otimizadas podem ser tão rápidas quanto uma compilação de índice de primeiro plano nesses mesmos dados.

Use db.currentOp() para monitorar o progresso das construções de índice em andamento.

O MongoDB ignora a opção de construção do índice background se especificada para createIndexes ou seus ajudantes de shellcreateIndex()ecreateIndexes().

Violações de Restrições Durante a Construção de Índices

Para índices que impõem restrições à coleção, como índices exclusivos , o mongod verifica todos os documentos pré-existentes e escritos simultaneamente em busca de violações dessas restrições após a conclusão da criação do índice. Documentos que violam as restrições do índice podem existir durante a construção do índice. Se algum documento violar as restrições de índice no final da compilação, o mongod encerra a compilação e gera um erro.

Por exemplo, considere uma coleção preenchida inventory. Um administrador deseja criar um índice exclusivo no campo product_sku . Se algum documento na coleção tiver valores duplicados para product_sku, a construção do índice ainda poderá ser iniciada com êxito. Se ainda existir alguma violação no final da compilação, o mongod encerra a compilação e gera um erro.

Da mesma forma, um aplicativo pode gravar documentos com êxito na coleção inventory com valores duplicados de product_sku enquanto a compilação do índice está em andamento. Se alguma violação ainda existir no final da compilação, o mongod encerra a compilação e lança um erro.

Para reduzir o risco de falha nas construções de índices devido a violações de restrições:

Valide que nenhum documento na coleção viola as restrições de índices.
Pare todas as gravações na coleção de aplicativos que não podem garantir operações de gravação sem violação.

Coleções partilhadas

Para uma coleção fragmentada distribuída em vários fragmentos, um ou mais fragmentos podem conter um bloco com documentos duplicados. Dessa forma, a operação de criação de índice pode ser bem-sucedida em alguns fragmentos (ou seja, aqueles sem duplicatas), mas não em outros (ou seja, aqueles com duplicatas). Para evitar deixar índices inconsistentes nos fragmentos, você pode emitir o db.collection.dropIndex() de um mongos para remover o índice da coleção.

Para mitigar o risco dessa ocorrência, antes de criar o índice:

Valide que nenhum documento na coleção viola as restrições de índices.
Pare todas as gravações na coleção de aplicativos que não podem garantir operações de gravação sem violação.

Dica

Veja também:

Verificações de Consistência de Índices para Coleções fragmentadas

Máximo de Construções de Índices Simultâneas

Por padrão, o servidor permite até três compilações de índice simultâneas. Para alterar o número de compilações de índice simultâneas permitidas, modifique o parâmetro maxNumActiveUserIndexBuilds.

Se o número de construções de índices simultâneas atingir o limite especificado por maxNumActiveUserIndexBuilds, o servidor bloqueará construções de índices adicionais até que o número de construções de índices simultâneas caia abaixo do limite.

Impacto de Construções de Índices no Desempenho do Banco de Dados

Construções de Índices Durante Volumes de Trabalho com Uso Intenso de Gravação

As construções de índices durante períodos de tempo em que a coleção de destino está sob carga de gravação pesada pode resultar em desempenho de gravação reduzido e construções de índices mais longas.

Considere a possibilidade de designar uma janela de manutenção durante a qual os aplicativos parem ou reduzam as operações de gravação na coleção. Inicie a compilação do índice durante essa janela de manutenção para mitigar o impacto negativo potencial do processo de compilação.

Memória (RAM) Disponível do Sistema Insuficiente

O createIndexes permite criar um ou mais índices em uma collection. createIndexes usa uma combinação de memória e arquivos temporários no disco para concluir as compilações de índice. O limite padrão de uso de memória para createIndexes é 200 megabytes, compartilhados entre todos os índices compilados usando um único comando createIndexes . Após o limite de memória ser alcançado, o createIndexes utiliza arquivos de disco temporários em um subdiretório denominado _tmp dentro do diretório --dbpath para concluir a compilação.

Você pode substituir o limite de memória configurando o parâmetro do servidor maxIndexBuildMemoryUsageMegabytes. A definição de um limite de memória maior pode resultar na conclusão mais rápida das compilações de índices. No entanto, um limite muito alto em relação à RAM não utilizada no seu sistema pode resultar no esgotamento da memória e no desligamento do servidor.

Se a máquina host tiver RAM livre disponível limitada, talvez seja necessário agendar um período de manutenção para aumentar a RAM total do sistema antes de poder modificar o mongod uso da RAM .

Construções dos Índices em Ambientes Replicados

Observação

Exige featureCompatibilityVersion 4.4+

Cada mongod no conjunto de réplica ou agrupamento fragmentado deve ter featureCompatibilityVersion configurado para pelo menos 4.4 para iniciar construções de índice simultaneamente entre membros do conjunto de réplicas.

Construir índices em um conjunto de réplicas ou cluster particionado é feito simultaneamente em todos os membros do conjunto de réplicas que contêm dados. Para clusters fragmentados, a construção de índices ocorre somente em fragmentos que contêm dados para a coleção que está sendo indexada. O primário requer um número mínimo de membros com dados voting (ou seja, quórum para a confirmação), incluindo ele próprio, que deve concluir a compilação antes de marcar o índice como pronto para uso.

O processo de construção é resumido da seguinte forma:

O primário recebe o comando createIndexes e cria imediatamente uma entrada no oplog "startIndexBuild" associada à construção do índice.
Os secundários iniciam a construção de índices após replicarem a entrada oplog "startIndexBuild".
Cada membro "vota" para confirmar a construção assim que terminar de indexar os dados na coleção.
Os membros secundários continuam a processar quaisquer novas operações de gravação no índice enquanto aguardam que os primários confirmem um quórum de votos.
Quando o primário tem um quórum de votos, ele verifica se há violações de restrições de chaves, como erros de chave duplicadas.
- Se não houver violações de restrições de chaves, o principal concluirá a construção de índices, marcará o índice como pronto para uso e criará uma entrada oplog "commitIndexBuild" associada.
- Se houver alguma violação de restrição chave, a construção do índice falhará. A primária cancela a construção do índice e cria uma entrada de oplog "abortIndexBuild" associada.
Os secundários replicam a entrada oplog "commitIndexBuild" e concluem a construção de índices.
Se, em vez disso, os secundários replicarem uma entrada oplog "abortIndexBuild", eles anularão a construção de índices e descartarão o trabalho de construção.

Para clusters fragmentados, a construção de índices ocorre somente em fragmentos que contêm dados para a coleção que está sendo indexada.

Para obter uma descrição mais detalhada do processo de criação de índices, consulte Processo de criação de índices.

Por padrão, as compilações de índice usam um quorum de confirmação de "votingMembers"ou todos os membros votantes portadores de dados. Para iniciar uma construção de índice com um commit quorum não padrão, especifique o parâmetro commitQuorum para createIndexes ou seus auxiliares de shell db.collection.createIndex() e db.collection.createIndexes().

Para modificar o quorum de confirmação necessário para uma compilação de índice simultânea em andamento, use o comando setIndexCommitQuorum.

Observação

As compilações de índice podem afetar o desempenho do conjunto de réplicas. Para volumes de trabalho que não toleram a diminuição do desempenho devido a compilações de índices, considere a possibilidade de executar um processo de compilação de índice contínuo. As compilações de índice contínuo retiram no máximo um membro do conjunto de réplicas de cada vez, começando pelos membros secundários, e criam o índice nesse membro como autônomo. As compilações de índice contínuo exigem pelo menos uma eleição de conjunto de réplicas.

Para obter construções de índices contínuas em conjuntos de réplicas, consulte Construções de índices contínuas em conjuntos de réplicas.
Para compilações de índices contínuos em cluster, consulte Compilações de índices contínuos em clusters fragmentados.

Falha e Recuperação de Construções

Construções de Índices Interrompidas em um Primário `mongod`

A partir do MongoDB 5.0, se o mongod primário for desligado corretamente durante a construção do índice e o commitQuorum for definido como votingMembers padrão, o progresso da construção do índice será salvo em disco. O mongod recupera automaticamente a compilação do índice quando é reiniciado e continua a partir do ponto de verificação salvo. Nas versões anteriores, se a construção de índices fosse interrompida, ela teria que ser reiniciada desde o início.

Construções de Índices Interrompidas em um Secundário `mongod`

Iniciando no MongoDB 5.0, se um mongod secundário desligar de forma limpa durante a construção do índice e o commitQuorum estiver configurado para o votingMembers padrão, o progresso da construção do índice será salvo no disco. O mongod recupera automaticamente a compilação do índice quando é reiniciado e continua a partir do ponto de verificação salvo. Nas versões anteriores, se a construção de índices fosse interrompida, ela teria que ser reiniciada desde o início.

mongod pode executar o processo de inicialização enquanto o índice de recuperação é compilado.

Se você reiniciar o mongod como um autônomo (ou seja, removendo ou comentando replication.replSetName ou omitindo --replSetName), o mongod não pode reiniciar a construção de índice. A compilação permanece em um estado pausado até que seja droppedmanualmente.

Construções de Índices Interrompidas em Standalone `mongod`

Se o mongod for encerrado durante a criação do índice, a tarefa de criação do índice e todo o progresso serão perdidos. Reiniciar o mongod não reinicia a construção do índice. Você deve reemitir a operação createIndex() para reiniciar a compilação do índice.

Rollbacks durante o Processo de Construção

A partir do MongoDB 5.0, se um nó for revertido para um estado anterior durante a compilação do índice, o progresso da compilação do índice será salvo no disco. Se ainda houver trabalho a ser feito quando a reversão for concluída, o mongod recuperará automaticamente a compilação do índice e continuará a partir do ponto de verificação salvo.

O MongoDB pode pausar uma construção de índice em andamento para executar uma reversão.

Se o rollback não reverter a construção do índice, o MongoDB reiniciará a construção do índice após concluir o rollback.
Se o rollback reverter a construção de índices, você deverá recriar o(s) índice(s) após a conclusão do rollback.

Verificações de Consistência de Índices para Coleções fragmentadas

Uma collection fragmentada terá um índice inconsistente se a coleção não tiver exatamente os mesmos índices (inclusive as opções de índice) em cada shard que contiver blocos para a coleção. Embora os índices inconsistentes não devam ocorrer durante as operações normais, podem ocorrer, por exemplo:

Quando um usuário está criando um índice com uma restrição de chave unique e um fragmento contém um bloco com documentos duplicados. Nesses casos, a operação de criação do índice pode ser bem-sucedida nos fragmentos sem duplicatas, mas não no fragmento com duplicatas.
Quando um usuário está criando um índice nos fragmentos de maneira contínua (ou seja, criando manualmente o índice um a um nos fragmentos), mas não consegue criar o índice para um fragmento associado ou cria incorretamente um índice com especificação diferente.

O servidor de configuração primário verifica periodicamente se há inconsistências de índice nos fragmentos para collection fragmentadas. Para configurar estas verificações periódicas, consulte enableShardedIndexConsistencyCheck e shardedIndexConsistencyCheckIntervalMS.

O comando serverStatus retorna o campo shardedIndexConsistency para relatar inconsistências de índice quando executado no servidor de configuração primário.

Para verificar se uma collection fragmentada tem índices inconsistentes, consulte Localizar índices inconsistentes em shards.

Monitorar Construções de Índices em Andamento

Para ver o status de uma operação de compilação de índice, você pode usar o método db.currentOp() em mongosh. Para filtrar as operações atuais para operações de criação de índice, consulte Operações de Indexação Ativa para obter um exemplo.

O campo msg inclui uma medição da porcentagem completa do estágio atual do processo de criação do índice.

Observe as Construções de Índices Interrompidas e Retomadas nos Registros

Enquanto um índice está sendo construído, o progresso é escrito no registro do MongoDB. Se uma compilação de índice for interrompida e retomada, haverá mensagens de registro com campos como estes:

 "msg":"Index build: wrote resumable state to disk",
 "msg":"Found index from unfinished build",

Encerrar Construções de Índices em Andamento

Use o comando dropIndexes ou seu assistente de shell dropIndex() ou dropIndexes() para encerrar uma construção de índice em andamento. Consulte Abortar Construções de Índices em Andamento para obter mais informações.

Não use killOp para encerrar compilações de índice em andamento em conjuntos de réplicas ou clusters fragmentados.

Processo de Construção de Índices

A tabela a seguir descreve cada estágio do processo de construção de índices:

Estágio	Descrição
Bloqueio	O `mongod` obtém um bloqueio `X` exclusivo na coleção que está sendo indexada. Isso bloqueia todas as operações de leitura e gravação na coleção, incluindo a aplicação de quaisquer operações de gravação replicadas ou comandos de metadados destinados à coleção. O `mongod` não gera esse bloqueio.
Inicialização	O `mongod` cria três estruturas de dados neste estado inicial: A entrada inicial de metadados do índice. Uma tabela temporária ("tabela de gravações laterais"), que armazena chaves geradas a partir de gravações na coleção que está sendo indexada durante o processo de construção. Uma tabela temporária ("tabela de violações de restrições") para todos os documentos que possam causar um erro de geração de chave. Os erros de geração de chaves ocorrem quando um documento tem chaves inválidas para os campos indexados. Por exemplo, um documento com valores de campo duplicados ao criar um índice índice único ou objetos GeoJSON malformados ao criar um índice 2dsphere.
Bloqueio	O `mongod` rebaixa o bloqueio exclusivo da coleção `X` para um bloqueio de `IX` exclusivo com intenção. O `mongod` periodicamente produz esse bloqueio para intercalar operações de leitura e gravação.
Verificar Coleção	Para cada documento na coleção, o `mongod` gera uma chave para esse documento e transfere a chave para uma classificadora externa. Se o `mongod`encontrar um erro de geração de chave ao gerar uma chave durante a verificação da coleção, ele armazenará essa chave na tabela de violações de restrições para processamento posterior. Se o `mongod` encontrar qualquer outro erro ao gerar uma chave, a construção falhará com um erro. Depois que o `mongod` concluir a verificação da coleção, ele despejará as chaves classificadas no índice.
Tabela de gravações do lado do processo	O `mongod` drena a tabela de gravação lateral usando a prioridade primeiro a entrar, primeiro a sair. Se o `mongod` encontrar um erro de geração de chave durante o processamento de uma chave na tabela de gravação lateral, ele armazenará essa chave na tabela de violação de restrição para processamento posterior. Se o `mongod` encontrar qualquer outro erro durante o processamento de uma chave, a construção falhará com um erro. Para cada documento gravado na coleção durante o processo de compilação, o `mongod` gera uma chave para esse documento e a armazena na tabela de gravação lateral para processamento posterior. O `mongod` usa um sistema de snapshot para definir um limite para o número de chaves a serem processadas.
Votar e Aguardar o Quorum para o Commit	Um `mongod` que não faz parte de um conjunto de réplicas pula esse estágio. O `mongod` envia um "voto" para o primary para cometer o índice. Especificamente, ele grava o "voto" em uma collection replicada interna no primário. Se o `mongod` for o principal, ele espera até ter um quórum de votos confirmados (todos os membros portadores de dados de votação, por padrão) antes de continuar o processo de criação do índice. Se o `mongod` for um secundário, ele aguardará até replicar uma entrada no oplog "commitIndexBuild" ou "abortIndexBuild": Se o `mongod` replicar uma entrada de oplog " commitIndexBuild ", ele terminará de drenar a tabela de gravações laterais e passará para o próximo estágio no processo de criação do índice. Se o `mongod` replica uma entrada oplog "abortIndexBuild", ele aborta a compilação de índice e descarta o trabalho de compilação. Enquanto aguarda o quorum para o commit, o `mongod` acrescenta quaisquer chaves adicionais geradas a partir de operações de gravação à coleção que está sendo indexada na tabela de gravações laterais e drena periodicamente a tabela.
Bloqueio	O `mongod` atualiza o bloqueio de `IX` exclusivo de intenção na coleção para um bloqueio de `S` compartilhado. Isso bloqueia todas as operações de gravação na coleção, incluindo a aplicação de quaisquer operações de gravação replicadas ou comandos de metadados destinados à coleção.
Concluir o Processamento da Tabela de Gravações Laterais Temporárias	O `mongod` continua drenando os registros restantes na tabela lateral de gravações. O `mongod` pode pausar a replicação durante esse estágio. Se o `mongod` encontrar um erro de geração de chave durante o processamento de uma chave na tabela de gravação lateral, ele armazenará essa chave na tabela de violação de restrição para processamento posterior. Se o `mongod` encontrar qualquer outro erro durante o processamento de uma chave, a construção falhará com um erro.
Bloqueio	O `mongod` atualiza o bloqueio de `S` compartilhado na coleção para um bloqueio de `X` exclusivo na coleção. Isso bloqueia todas as operações de leitura e gravação na coleção, incluindo a aplicação de quaisquer operações de gravação replicadas ou comandos de metadados destinados à coleção. O `mongod` não gera essa trava.
Descartar Tabela de Gravações Laterais	O `mongod` aplica todas as operações restantes na tabela de gravações laterais antes de soltá-la. Se o `mongod` encontrar um erro de geração de chave durante o processamento de uma chave na tabela de gravação lateral, ele armazenará essa chave na tabela de violação de restrição para processamento posterior. Se o `mongod` encontrar qualquer outro erro durante o processamento de uma chave, a construção falhará com um erro. Neste ponto, o índice inclui todos os dados gravados na coleção.
Tabela de Violações de Restrições do Processo	Se o `mongod` for o principal, ele drenará a tabela de violação de restrição usando a prioridade primeiro a entrar, primeiro a sair. Se nenhuma chave na tabela de violação de restrição produzir um erro de geração de chave ou se a tabela estiver vazia, o `mongod` soltará a tabela e criará uma entrada de oplog "commitIndexBuild". Os secundários podem concluir a construção do índice associado após replicar a entrada do oplog. Se alguma chave na tabela de violação de restrição ainda produzir um erro de geração de chave, o `mongod` interromperá a compilação e lançará um erro. O `mongod` cria uma entrada associada no oplog "abortIndexBuild" para indicar que os secundários devem abortar e descartar o trabalho de criação de índice. Se o `mongod` for secundário, ele descarta a tabela de violação de restrições. Como o primário deve drenar com êxito a tabela de violações de restrições antes de criar a entrada oplog " CommitopLogEntry ", o secundário pode presumir com segurança que não existem violações.
Marcar o Índice como Pronto	O `mongod` atualiza os metadados do índice para marcar o índice como pronto para uso.
Bloqueio	O `mongod` libera o bloqueio `X` na coleção.

Dica

Veja também:

Perguntas frequentes: simultaneidade

← Índices esparsos

Construção contínua de índices em conjuntos réplicas →

Comportamento

Comparação de Construções em Foreground e Background

Violações de Restrições Durante a Construção de Índices

Coleções partilhadas

Dica

Veja também:

Máximo de Construções de Índices Simultâneas

Impacto de Construções de Índices no Desempenho do Banco de Dados

Construções de Índices Durante Volumes de Trabalho com Uso Intenso de Gravação

Memória (RAM) Disponível do Sistema Insuficiente

Construções dos Índices em Ambientes Replicados

Observação

Exige featureCompatibilityVersion 4.4+

Observação

Falha e Recuperação de Construções

Construções de Índices Interrompidas em um Primário mongod

Construções de Índices Interrompidas em um Secundário mongod

Construções de Índices Interrompidas em Standalone mongod

Rollbacks durante o Processo de Construção

Verificações de Consistência de Índices para Coleções fragmentadas

Monitorar Construções de Índices em Andamento

Observe as Construções de Índices Interrompidas e Retomadas nos Registros

Encerrar Construções de Índices em Andamento

Processo de Construção de Índices

Dica

Veja também:

Construções de Índices Interrompidas em um Primário `mongod`

Construções de Índices Interrompidas em um Secundário `mongod`

Construções de Índices Interrompidas em Standalone `mongod`