Atualizar índices secundários globais

Esta seção descreve como criar, modificar e excluir índices secundários globais no Amazon DynamoDB.

Tópicos

• Criar uma tabela com índices secundários globais
• Descrever os índices secundários globais em uma tabela
• Adicionar um índice secundário global a uma tabela
• Exclusão de um índice secundário global
• Modificar um índice secundário global durante a criação
• Detectar e corrigir violações de chave de índice

Criar uma tabela com índices secundários globais

Para criar uma tabela com um ou mais índices secundários globais, use a operação CreateTable com o parâmetro GlobalSecondaryIndexes. Para obter a flexibilidade máxima de consultas, é possível criar até 20 índices secundários globais (cota padrão) por tabela.

Você deve especificar um atributo que não atue como chave de partição do índice. Como opção, você pode especificar outro atributo para a chave de classificação do índice. Não é necessário que nenhum desses atributos de chave seja o mesmo que um atributo de chave na tabela. Por exemplo, na tabela GameScores (consulte Como usar índices secundários globais no DynamoDB), nem TopScore nem TopScoreDateTime são atributos chave. Você poderia criar um índice secundário global com uma chave de partição TopScore e uma chave de classificação TopScoreDateTime. Um índice desse tipo pode ser usado para determinar se há uma correlação entre pontuações altas e a hora do dia em que um jogo é jogado.

Cada atributo de chave de índice deve ser um escalar do tipo String, Number ou Binary. (Ele não pode ser um documento ou um conjunto.) Você pode projetar atributos de qualquer tipo de dados em um índice secundário global. Isso inclui escalares, documentos e conjuntos. Para obter uma lista completa de tipos de dados, consulte Tipos de dados.

Se estiver usando o modo provisionado, você deve fornecer configurações de ProvisionedThroughput para o índice, formadas por ReadCapacityUnits e WriteCapacityUnits. Essas configurações de throughput provisionado são distintas daquelas na tabela, mas se comportam de forma semelhante. Para mais informações, consulte Considerações sobre throughput provisionado para índices secundários globais.

Índices secundários globais herdam o modo de capacidade leitura/gravação da tabela base. Para mais informações, consulte Considerações ao mudar o modo de capacidade de leitura/gravação.

nota

As operações de provisionamento e as operações de gravação em andamento compartilham o throughput de gravação dentro do índice secundário. Ao criar um novo GSI, pode ser importante conferir se a escolha de chave de partição está gerando uma distribuição desigual ou estreita de dados ou tráfego nos valores de chave de partição do novo índice. Se isso ocorrer, você pode estar vendo operações de provisionamento e de gravação ocorrendo ao mesmo tempo e restringindo as gravações na tabela base. O serviço toma medidas para minimizar o potencial desse caso, mas não tem insights sobre o formato dos dados do cliente em relação à chave de partição de índice, à projeção escolhida ou à dispersão da chave primária do índice.

Se você suspeitar que o novo índice secundário global tenha dados estreitos ou distorcidos ou distribuição de tráfego entre valores de chave de partição, considere o seguinte antes de adicionar novos índices a tabelas operacionalmente importantes.

• Talvez seja mais seguro adicionar o índice no momento em que a aplicação está gerando a menor quantidade de tráfego.

• Considere habilitar o CloudWatch Contributor Insights em sua tabela e índices de base. Isso lhe proporcionará um valioso insight sobre sua distribuição de tráfego.

• Para tabelas e índices base no modo de capacidade provisionada, defina a capacidade de gravação provisionada do novo índice para pelo menos o dobro da tabela base. Observe as métricas do CloudWatch WriteThrottleEvents, ThrottledRequests, OnlineIndexPercentageProgress, OnlineIndexConsumedWriteCapacity e OnlineIndexThrottleEvents em todo o processo. Ajuste a capacidade de gravação provisionada conforme necessário para concluir o provisionamento em tempo razoável, sem efeitos consideráveis de controle de utilização nas operações em andamento.

• Esteja preparado para cancelar a criação do índice, em caso de impacto operacional devido ao controle de utilização de gravação, e caso o aumento de capacidade de gravação provisionada em seu novo GSI não solucione.

Descrever os índices secundários globais em uma tabela

Para ver o status de todos os índices secundários globais em uma tabela, use a operação DescribeTable. A parte GlobalSecondaryIndexes da resposta mostra todos os índices na tabela, juntamente com o status atual de cada (IndexStatus).

O IndexStatus para um índice secundário global será um dos seguintes:

• CREATING: o índice está sendo criado e ainda não está disponível para uso.

• ACTIVE: o índice está pronto para uso e as aplicações podem executar operações Query no índice.

• UPDATING: as configurações de throughput provisionado do índice estão sendo alteradas.

• DELETING: o índice está sendo excluído e não pode mais ser usado.

Quando o DynamoDB tiver terminado de criar um índice secundário global, o status do índice mudará de CREATING para ACTIVE.

Adicionar um índice secundário global a uma tabela

Para adicionar um índice secundário global a uma tabela existente, use a operação UpdateTable com o parâmetro GlobalSecondaryIndexUpdates. Você deve fornecer o seguinte:

• Um nome de índice. O nome deve ser exclusivo entre todos os índices na tabela.

• O esquema de chave do índice. É necessário especificar um atributo para a chave da partição de índice, mas existe a opção de especificar outro atributo para a chave de classificação de índice. Não é necessário que nenhum desses atributos de chave seja o mesmo que um atributo de chave na tabela. Os tipos de dados de cada atributo de esquema devem ser escalares: String, Number ou Binary.

• Os atributos a serem projetados da tabela para o índice:

  • KEYS_ONLY: cada item do índice consiste apenas nos valores de chaves de partição e nas chaves de classificação da tabela, além dos valores de chaves do índice.

  • INCLUDE: além dos atributos descritos em KEYS_ONLY, o índice secundário inclui outros atributos não chave que você especificar.

  • ALL:  o índice inclui todos os atributos da tabela de origem.

• As configurações do throughput provisionado para o índice, formadas por ReadCapacityUnits e WriteCapacityUnits. Essas configurações de throughput provisionado são distintas daquelas na tabela.

Você pode criar somente um índice secundário global por operação UpdateTable.

Fases da criação de um índice

Quando você adiciona um novo índice secundário global a uma tabela existente, ela continua a estar disponível enquanto o índice está sendo construído. No entanto, o novo índice apenas estará disponível para operações de consulta quando seu status mudar de CREATING para ACTIVE.

nota

A criação do índice secundário global não usa o Application Auto Scaling. Aumentar a capacidade MIN do Application Auto Scaling não diminuirá o tempo de criação do índice secundário global.

Nos bastidores, o DynamoDB constrói o índice em duas fases:

Alocação de recursos

O DynamoDB aloca os recursos de computação e de armazenamento que são necessários para a construção do índice.

Durante a fase de alocação de recursos, o atributo IndexStatus é CREATING, enquanto o atributo Backfilling é false. Use a operação DescribeTable para recuperar o status de uma tabela e todos os índices secundários dela.

Enquanto o índice estiver na fase de alocação de recurso, você poderá excluí-lo ou a apagar a tabela principal dele. Você também não pode modificar o throughput provisionado do índice ou da tabela. Não é possível adicionar ou excluir outros índices na tabela. No entanto, você pode modificar o throughput provisionado desses outros índices.

Aterramento

Para cada item na tabela, o DynamoDB determina qual conjunto de atributos deve ser gravado no índice com base em sua projeção (KEYS_ONLY, INCLUDE ou ALL). Em seguida, ele grava esses atributos no índice. Durante a fase de preenchimento, o DynamoDB rastreia os itens que estão sendo adicionados, excluídos ou atualizados na tabela. Os atributos desses itens também são adicionados, excluídos ou atualizados no índice conforme apropriado.

Durante a fase de preenchimento, o atributo IndexStatus é definido como CREATING, e o atributo Backfilling é verdadeiro. Use a operação DescribeTable para recuperar o status de uma tabela e todos os índices secundários dela.

Enquanto o índice está em processo de aterramento, não é possível excluir a tabela principal. No entanto, ainda é possível excluir o índice ou modificar o throughput provisionado da tabela e de qualquer um dos seus índices secundários globais.

nota

Durante a fase de aterramento, algumas gravações de itens infratores podem ter sucesso, enquanto outras serão rejeitadas. Após o aterramento, todas as gravações de itens que violarem o esquema de chaves do novo índice serão rejeitadas. Recomendamos executar a ferramenta Violation Detector após a conclusão da fase de preenchimento em segundo plano, para detectar e resolver qualquer infração de chave que possa ter ocorrido. Para mais informações, consulte Detectar e corrigir violações de chave de índice.

Enquanto as fases de alocação de recurso e aterramento estão em andamento, o índice permanece no estado CREATING. Enquanto isso, o DynamoDB executa operações de leitura na tabela. Você não é cobrado pelas operações de leitura da tabela-base para preencher o índice secundário global. No entanto, você será cobrado pelas operações de gravação para preencher o índice secundário global recém-criado.

Quando a construção do índice estiver concluída, seu status mudará para ACTIVE. Você não pode executar Query ou Scan no índice até que ele esteja no modo ACTIVE.

nota

Em alguns casos, o DynamoDB não pode gravar dados da tabela no índice devido a violações de chaves de índice. Isso poderá ocorrer se:

• O tipo de dados de um valor de atributo não corresponder ao tipo de dados de um esquema de chaves de índice.

• O tamanho de um atributo excede o tamanho máximo de um atributo de chave de índice.

• Um atributo de chave de índice tem um valor binários ou de string vazio.

Violações de chaves de índice não interferem na criação do índice secundário global. No entanto, quando o índice ficar ACTIVE, as chaves infratoras não estarão presentes no índice.

O DynamoDB fornece uma ferramenta autônoma para localizar e resolver esses problemas. Para mais informações, consulte Detectar e corrigir violações de chave de índice.

Adicionar um índice secundário global a uma tabela grande

O tempo necessário para a construção de um índice secundário global depende de vários fatores, entre eles:

• O tamanho da tabela

• O número de itens na tabela que se qualificam para inclusão no índice

• O número de atributos projetados no índice

• A capacidade de gravação provisionada do índice

• A atividade de gravação na tabela principal durante a criação dos índices

Se você estiver adicionando um índice secundário global a uma tabela muito grande, a conclusão do processo de criação poderá ser demorada. Para monitorar o progresso e determinar se o índice tem capacidade de gravação suficiente, consulte as seguintes métricas do Amazon CloudWatch:

• OnlineIndexPercentageProgress

• OnlineIndexConsumedWriteCapacity

• OnlineIndexThrottleEvents

nota

Para obter mais informações sobre as métricas do CloudWatch relacionadas ao DynamoDB, consulte Métricas do DynamoDB.

Se a configuração do throughput provisionado de gravação no índice for muito baixa, a compilação do índice levará mais tempo para ser concluída. Para reduzir o tempo necessário para construir um novo índice secundário global, você pode aumentar sua capacidade de gravação provisionada temporariamente.

nota

Como regra geral, recomendamos definir a capacidade de gravação provisionada do índice como 1,5 vezes maior que a capacidade de gravação da tabela. Essa é uma boa configuração para muitos casos de uso. No entanto, seus requisitos reais podem ser maiores ou menores.

Enquanto um índice está sendo preenchido em segundo plano, o DynamoDB usa a capacidade do sistema interno para fazer leituras na tabela. Isso é feito para minimizar o impacto da criação do índice e garantir que sua tabela não fique sem capacidade de leitura.

No entanto, é possível que o volume de atividades de gravação recebidas exceda a capacidade de gravação provisionada do índice. Este é um cenário de afunilamento, no qual a criação do índice é mais demorada porque a atividade de gravação no índice é limitada. Durante a criação do índice, é recomendável monitorar as métricas do Amazon CloudWatch para o índice a fim de determinar se a capacidade de gravação consumida está excedendo sua capacidade provisionada. Em um cenário de afunilamento, é necessário aumentar a capacidade de gravação provisionada no índice para evitar o controle de utilização de gravações durante a fase de aterramento.

Depois que o índice tiver sido criado, você deverá definir sua capacidade de gravação provisionada para refletir o uso normal de sua aplicação.

Exclusão de um índice secundário global

Se você não precisa mais de um índice secundário global, pode excluí-lo usando a operação UpdateTable.

É possível excluir somente um índice secundário global por operação UpdateTable.

Enquanto o índice secundário global está sendo excluído, não há efeitos sobre atividades de leitura ou de gravação na tabela principal. Enquanto a exclusão está em andamento, você ainda pode modificar o throughput provisionado em outros índices.

nota

• Quando você exclui uma tabela usando a ação DeleteTable, todos os índices secundários globais nessa tabela também são excluídos.

• Sua conta não será cobrada pela operação de exclusão do índice secundário global.

Modificar um índice secundário global durante a criação

Enquanto um índice está sendo construído, é possível usar a operação DescribeTable para determinar em qual fase ele se encontra. A descrição do índice inclui um atributo booleano, Backfilling, para indicar se o DynamoDB está carregando o índice com itens da tabela no momento. Se Backfilling for verdadeiro, a fase de alocação de recursos estará concluída, e o índice agora estará sendo preenchido.

Durante o aterramento, é possível atualizar os parâmetros de throughput provisionado do índice. Você pode optar por fazer isso para acelerar a construção do índice: é possível aumentar a capacidade de gravação do índice enquanto ele está sendo construído e, em seguida, reduzi-la. Para modificar as configurações de throughput provisionado do índice, use a operação UpdateTable. O status do índice muda para UPDATING, e Backfilling é true até o índice estar pronto para uso.

Durante a fase de aterramento, é possível excluir o índice que está sendo criado. Durante essa fase, não é possível adicionar ou excluir outros índices na tabela.

nota

Para índices que foram criados como parte de uma operação CreateTable, o atributo Backfilling não aparece na saída de DescribeTable. Para mais informações, consulte Fases da criação de um índice.