# Gerenciar índices secundários globais no DynamoDB Esta seção descreve como criar, modificar e excluir índices secundários globais no Amazon DynamoDB. **Topics** + [Criar uma tabela com índices secundários globais](#GSI.Creating) + [Descrever os índices secundários globais em uma tabela](#GSI.Describing) + [Adicionar um índice secundário global a uma tabela](#GSI.OnlineOps.Creating) + [Exclusão de um índice secundário global](#GSI.OnlineOps.Deleting) + [Modificar um índice secundário global durante a criação](#GSI.OnlineOps.Creating.Modify) ## 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](GSI.md)), 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](HowItWorks.NamingRulesDataTypes.md#HowItWorks.DataTypes). 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 obter mais informações, consulte [Considerações sobre throughput provisionado para índices secundários globais](GSI.md#GSI.ThroughputConsiderations). Índices secundários globais herdam o modo de capacidade leitura/gravação da tabela base. Para obter mais informações, consulte [Considerações ao alternar os modos de capacidade no DynamoDB](bp-switching-capacity-modes.md). **nota** 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. Observe as métricas `WriteThrottleEvents`, `ThrottledRequests` e `OnlineIndexPercentageProgress` do CloudWatch 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. `OnlineIndexConsumedWriteCapacity` e `OnlineThrottleEvents` devem mostrar 0 durante o preenchimento de índice. Prepare-se para cancelar a criação do índice, em caso de impacto operacional devido ao controle de utilização de gravação. ## 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. 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 obter mais informações, consulte [Detectar e corrigir violações de chave de índice no DynamoDB](GSI.OnlineOps.ViolationDetection.md). 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. 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 obter mais informações, consulte [Detectar e corrigir violações de chave de índice no DynamoDB](GSI.OnlineOps.ViolationDetection.md). ### 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 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` Para obter mais informações sobre as métricas do CloudWatch relacionadas ao DynamoDB, consulte [Métricas do DynamoDB](metrics-dimensions.md#dynamodb-metrics). **Importante** Talvez seja necessário incluir tabelas muito grandes na lista de permissões antes de criar ou atualizar um índice secundário global. Entre em contato com o AWS Support para incluir tabelas na lista de permissões. 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. ## 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 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 obter mais informações, consulte [Fases da criação de um índice](#GSI.OnlineOps.Creating.Phases).