kvp in attributeList)
{
string attributeName = kvp.Key;
AttributeValue value = kvp.Value;
Console.WriteLine(
attributeName + " " +
(value.S == null ? "" : "S=[" + value.S + "]") +
(value.N == null ? "" : "N=[" + value.N + "]") +
(value.SS == null ? "" : "SS=[" + string.Join(",", value.SS.ToArray()) + "]") +
(value.NS == null ? "" : "NS=[" + string.Join(",", value.NS.ToArray()) + "]") +
(value.B == null ? "" : "B=[" + FromGzipMemoryStream(value.B) + "]")
);
}
Console.WriteLine("************************************************");
}
private static MemoryStream ToGzipMemoryStream(string value)
{
MemoryStream output = new MemoryStream();
using (GZipStream zipStream = new GZipStream(output, CompressionMode.Compress, true))
using (StreamWriter writer = new StreamWriter(zipStream))
{
writer.Write(value);
}
return output;
}
private static string FromGzipMemoryStream(MemoryStream stream)
{
using (GZipStream zipStream = new GZipStream(stream, CompressionMode.Decompress))
using (StreamReader reader = new StreamReader(zipStream))
{
return reader.ReadToEnd();
}
}
}
}
```
# Melhorar o acesso aos dados com índices secundários no DynamoDB
O Amazon DynamoDB dá acesso rápido a itens em uma tabela ao especificar valores de chave primária. No entanto, muitos aplicativos podem se beneficiar por terem uma ou mais chaves secundárias (ou alternativas) disponíveis, para permitir acesso eficiente aos dados com atributos que não sejam a chave primária. Para resolver isso, você pode criar um ou mais índices secundários em uma tabela e emitir solicitações de `Query` ou de `Scan` nesses índices.
Um *índice secundário* é uma estrutura de dados que contém um subconjunto de atributos de uma tabela, juntamente com uma chave alternativa para oferecer suporte a operações `Query`. Você pode recuperar dados do índice usando uma `Query`, de maneira muito semelhante ao uso de uma `Query` com uma tabela. Uma tabela pode ter vários índices secundários, o que permite que seus aplicativos tenham acesso a muitos padrões de consulta diferentes.
**nota**
Você também pode `Scan` um índice, da mesma forma como poderia `Scan` uma tabela.
Atualmente, o acesso entre contas para operações de verificação de índice secundário não é aceito em [políticas baseadas em recursos](access-control-resource-based.md).
Cada índice secundário está associado a exatamente uma tabela, da qual ele obtém seus dados. Ela é chamada de *tabela base* para o índice. Ao criar um índice, você define uma chave alternativa para ele (chave de partição e chave de classificação). Você também define os atributos a serem *projetados*, ou copiados, da tabela-base para o índice. O DynamoDB copia esses atributos para o índice, juntamente com os atributos de chave primária da tabela-base. Você pode consultar ou verificar o índice como faria com qualquer tabela.
Cada índice secundário é automaticamente mantido pelo DynamoDB. Quando você adiciona, modifica ou exclui itens na tabela base, todos os índices dessa tabela também são atualizados para refletir essas alterações.
O DynamoDB oferece suporte a dois tipos de índices secundários:
+ **[Índice secundário global](GSI.html)**: um índice com uma chave de partição e uma chave de classificação que podem ser diferentes daquelas contidas na tabela-base. Um índice secundário global é considerado “global” porque as consultas no índice podem abranger todos os dados em uma tabela base, além de todas as partições. O índice secundário global é armazenado em seu próprio espaço de partição longe da tabela-base e é dimensionado separadamente da tabela-base.
+ **[Índice secundário local](LSI.html)**: um índice que tem a mesma chave de partição que a tabela-base, mas uma chave de classificação diferente. Um índice secundário local é “local” no sentido de que cada partição de um índice secundário local tem a determinação de escopo para uma partição de tabela base com o mesmo valor de chave de partição.
Para ver uma comparação entre índices secundários globais e índices secundários locais, assista a este vídeo.
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/BkEu7zBWge8)
**Topics**
+ [Como usar índices secundários globais no DynamoDB](GSI.md)
+ [Índices secundários locais](LSI.md)
Você deve considerar os requisitos do seu aplicativo ao determinar qual tipo de índice usar. A tabela a seguir mostra as principais diferenças entre um índice secundário global e um índice secundário local.
****
| Característica | Índice secundário global | Índice secundário local |
| --- | --- | --- |
| Esquema de chaves | A chave primária de um índice secundário global pode ser simples (chave de partição) ou composta (chave de partição e chave de classificação). | A chave primária de um índice secundário local deve ser composta (chave de partição e chave de classificação). |
| Atributos de chaves | A chave de partição e a chave de classificação (se presente) do índice podem ser qualquer atributo da tabela base do tipo String, Número ou Binário. | A chave de partição do índice é o mesmo atributo que a chave de partição da tabela base. A chave de classificação pode ser qualquer atributo da tabela base do tipo String, Número ou Binário. |
| Restrições de tamanho por valor de chave de partição | Não há restrições de tamanho para índices secundários globais. | Para cada valor de chave de partição, o tamanho total de todos os itens indexados deve ser 10 GB ou menos. |
| Operações de índice online | Você pode criar índices secundários globais ao mesmo tempo que cria uma tabela. Você também pode adicionar um novo índice secundário global a uma tabela ou então excluí-lo. Para obter mais informações, consulte [Gerenciar índices secundários globais no DynamoDB](GSI.OnlineOps.md). | Você pode criar índices secundários locais ao mesmo tempo que cria uma tabela. Não é possível adicionar um índice secundário local a uma tabela existente nem excluir índices secundários existentes. |
| Consultas e partições | Um índice secundário global permite que você consulte a tabela inteira, em todas as partições. | Um índice secundário local permite consultar uma única partição, conforme especificado pelo valor da chave de partição na consulta. |
| Consistência de leituras | As consultas em índices secundários globais oferecem suporte somente à consistência final. | Ao consultar um índice secundário local, você pode escolher consistência final ou coerência forte. |
| Consumo de throughput provisionado | Cada índice secundário global tem suas próprias configurações de throughput provisionado para atividades de leitura e gravação. Consultas ou verificações em um índice secundário global consumem unidades de capacidade do índice, e não da tabela-base. O mesmo vale para atualizações de índices secundários globais devido a gravações de tabelas. Um índice secundário global associado a tabelas globais consome unidades de capacidade de gravação. | Consultas ou verificações em um índice secundário local consomem unidades de capacidade de leitura da tabela-base. Quando você grava em uma tabela, seus índices secundários locais também são atualizados. Essas atualizações consomem unidades de capacidade de gravação da tabela-base. Um índice secundário local associado a tabelas globais consome unidades de capacidade de gravação replicadas. |
| Atributos projetados | Com consultas ou verificações em um índice secundário global, você pode solicitar somente os atributos que estão projetados no índice. O DynamoDB não busca atributos da tabela. | Se você consultar ou verificar um índice secundário local, poderá solicitar atributos que não estão projetados no índice. O DynamoDB buscará automaticamente os atributos da tabela. |
Se quiser criar mais de uma tabela com índices secundários, você deverá fazer isso sequencialmente. Por exemplo, você poderia criar a primeira tabela e esperar até que ela entrasse no estado `ACTIVE`. Em seguida, você criaria a seguinte tabela e esperaria até que ela entrasse no estado `ACTIVE` e assim por diante. Se você tentar criar mais de uma tabela ao mesmo tempo com um índice secundário, o DynamoDB retornará uma `LimitExceededException`.
Cada índice secundário usa a mesma [classe de tabela](HowItWorks.TableClasses.html) e [modo de capacidade](capacity-mode.md) da tabela-base à qual está associado. Para cada índice secundário, é necessário especificar o seguinte:
+ O tipo de índice a ser criado: índice secundário global ou índice secundário local.
+ Um nome para o índice. As regras de nomenclatura de índices são iguais às de tabelas, conforme listado em [Cotas no Amazon DynamoDB](ServiceQuotas.md). O nome deve ser exclusivo para a tabela-base à qual ele está associado, mas você pode usar o mesmo nome para índices que estão associados a diferentes tabelas-base.
+ O esquema de chaves do índice. Cada atributo no esquema de chaves do índice deve ser um atributo de nível superior do tipo `String`. `Number` ou `Binary`. Outros tipos de dados, incluindo documentos e conjuntos, não são permitidos. Outros requisitos para o esquema de chaves dependem do tipo de índice:
+ Para um índice secundário global, a chave de partição pode ser qualquer atributo escalar da tabela-base. Uma chave de classificação é opcional e também pode ser qualquer atributo escalar da tabela-base.
+ Para um índice secundário local, a chave de partição deve igual à chave de partição da tabela-base, e a chave de classificação deve ser um atributo da tabela-base não relacionado a chaves.
+ Atributos adicionais, se houver, a serem projetados da tabela-base no índice. Esses atributos são adicionais aos atributos de chave da tabela, que são automaticamente projetados em cada índice. Você pode projetar atributos de qualquer tipo de dados, incluindo escalares, documentos e conjuntos.
+ As configurações de throughput provisionado para o índice, se necessário:
+ Para um índice secundário global, você deve especificar configurações de unidades de capacidade de gravação. Essas configurações de throughput provisionado são independentes das configurações da tabela-base.
+ Para um índice secundário local, não é necessário especificar configurações de unidades de capacidade de gravação. Qualquer operação de leitura e gravação em um índice secundário extrai das configurações de throughput provisionado de sua tabela-base.
Para obter a flexibilidade máxima nas consultas, é possível criar até 20 índices secundários globais (cota padrão) e até 5 índices secundários locais por tabela.
Para obter uma listagem detalhada de índices secundários em uma tabela, use a operação `DescribeTable`. `DescribeTable` retorna o nome, o tamanho de armazenamento e as contagens de itens de cada índice secundário na tabela. Esses valores não são atualizados em tempo real, mas aproximadamente a cada seis horas.
Você pode acessar os dados em um índice secundário usando a operação `Query` ou `Scan`. Você deve especificar o nome da tabela-base e o nome do índice que deseja usar, os atributos a serem retornados nos resultados e qualquer expressão de condição a ser aplicada. O DynamoDB pode retornar os resultados em ordem crescente ou decrescente.
Quando uma tabela é excluída, todos os índices associados a ela também são excluídos.
Para ver as práticas recomendadas, consulte [Práticas recomendadas para uso de índices secundários no DynamoDB](bp-indexes.md).
# Como usar índices secundários globais no DynamoDB
Alguns aplicativos talvez precisem executar muitos tipos de consultas, usando uma variedade de atributos diferentes como critérios de consulta. Para oferecer suporte a esses requisitos, você pode criar um ou mais *índices secundários globais* e emitir solicitações `Query` para esses índices no Amazon DynamoDB.
**Topics**
+ [Cenário: Uso de um índice secundário global](#GSI.scenario)
+ [Projeções de atributo](#GSI.Projections)
+ [Esquema de chave de vários atributos](#GSI.MultiAttributeKeys)
+ [Ler dados de um índice secundário global](#GSI.Reading)
+ [Sincronização de dados entre tabelas e índices secundários globais](#GSI.Writes)
+ [Classes de tabela com índice secundário global](#GSI.tableclasses)
+ [Considerações sobre throughput provisionado para índices secundários globais](#GSI.ThroughputConsiderations)
+ [Considerações sobre armazenamento para índices secundários globais](#GSI.StorageConsiderations)
+ [Padrões de design](GSI.DesignPatterns.md)
+ [Gerenciar índices secundários globais no DynamoDB](GSI.OnlineOps.md)
+ [Detectar e corrigir violações de chave de índice no DynamoDB](GSI.OnlineOps.ViolationDetection.md)
+ [Como trabalhar com índices secundários globais: Java](GSIJavaDocumentAPI.md)
+ [Como trabalhar com índices secundários globais: .NET](GSILowLevelDotNet.md)
+ [Trabalhar com índices secundários globais no DynamoDB usando a AWS CLI](GCICli.md)
## Cenário: Uso de um índice secundário global
Para ilustrar, considere uma tabela chamada `GameScores` que controla os usuários e os placares de um aplicativo de jogo móvel. Cada item em `GameScores` é identificado por uma chave de partição (`UserId`) e por uma chave de classificação (`GameTitle`). O diagrama a seguir mostra como os itens da tabela seriam organizados. (Nem todos os atributos são mostrados.)
![\[A tabela GameScores que contém uma lista de ID de usuários, títulos, pontuações, datas e vitórias/derrotas.\]](http://docs.aws.amazon.com/pt_br/amazondynamodb/latest/developerguide/images/GSI_01.png)
Agora, vamos supor que você quisesse gravar um aplicativo de placar para exibir as pontuações máximas de cada jogo. Uma consulta que especificasse os atributos chave (`UserId` e `GameTitle`) seria muito eficaz. No entanto, se o aplicativo precisasse recuperar dados de `GameScores` com base no `GameTitle` apenas, ele precisaria usar uma operação `Scan`. À medida que mais itens são adicionados à tabela, as verificações de todos os dados se tornam lentas e ineficientes. Isso dificulta responder a questões como as seguintes:
+ Qual é a pontuação máxima já registrada no jogo Meteor Blasters?
+ Qual usuário tinha a maior pontuação no Galaxy Invaders?
+ Qual era a maior proporção de vitórias versus derrotas?
Para acelerar as consultas em atributos que não são chave, você pode criar um índice secundário global. Um índice secundário global contém uma seleção de atributos da tabela-base, mas eles são organizados por uma chave primária que é diferente daquela da região da tabela. A chave do índice não precisa ter nenhum dos atributos de chaves da tabela. Ela não precisa nem ter o mesmo esquema de chaves que a tabela.
Por exemplo, você poderia criar um índice secundário global chamado `GameTitleIndex` com uma chave de partição `GameTitle` e uma chave de classificação `TopScore`. Os atributos de chave primária da tabela base são sempre projetados em um índice, portanto, o atributo `UserId` também está presente. O diagrama a seguir mostra qual é a aparência do índice `GameTitleIndex`.
![\[A tabela GameTitleIndex que contém uma lista de títulos, pontuações e IDs de usuários.\]](http://docs.aws.amazon.com/pt_br/amazondynamodb/latest/developerguide/images/GSI_02.png)
Agora você pode consultar `GameTitleIndex` e obter as pontuações do jogo Meteor Blasters com facilidade. Os resultados são ordenados por valores de chave de classificação, `TopScore`. Se você definir o parâmetro `ScanIndexForward` como falso, os resultados serão retornados em ordem decrescente, de modo que a maior pontuação é retornada primeiro.
Cada índice secundário global deve ter uma chave de partição e pode ter uma chave de classificação opcional. O esquema da chave de índice pode ser diferente do esquema da tabela base. Você poderia ter uma tabela com uma chave primária simples (chave de partição) e criar um índice secundário global com uma chave primária composta (chave de partição e chave de classificação), ou vice versa. Os atributos de chaves do índice podem consistir em quaisquer atributos de nível superior, `String`, `Number` ou `Binary` da tabela base. Outros tipos escalares, tipos de documento e tipos de conjunto não são permitidos.
Você pode projetar outros atributos da tabela-base para o índice, se quisesse. Quando você consultar o índice, o DynamoDB poderá recuperar esses atributos projetados com eficiência. No entanto, as consultas do índice secundário global buscam atributos da tabela-base. Por exemplo, se você consultar `GameTitleIndex` conforme mostrado no diagrama anterior, a consulta poderá não acessar nenhum atributo que não seja de chave além de `TopScore` (embora os atributos de chave `GameTitle` e `UserId` sejam projetados automaticamente).
Em uma tabela do DynamoDB, cada valor de chave deve ser exclusivo. No entanto, os valores de chave em um índice secundário global não precisam ser exclusivos. Para ilustrar, suponhamos que um jogo chamado Comet Quest seja muito difícil. Há vários novos usuários tentando obter uma pontuação acima de zero, mas não conseguem. Veja a seguir alguns dos dados que podem representar isso.
****
| UserId | GameTitle | TopScore |
| --- | --- | --- |
| 123 | Comet Quest | 0 |
| 201 | Comet Quest | 0 |
| 301 | Comet Quest | 0 |
Quando esses dados são adicionados à tabela `GameScores`, o DynamoDB os propaga para o `GameTitleIndex`. Se consultarmos o índice usando Comet Quest para `GameTitle` e 0 para `TopScore`, os seguintes dados serão retornados.
![\[A tabela que contém uma lista de títulos, pontuações superiores e IDs de usuários.\]](http://docs.aws.amazon.com/pt_br/amazondynamodb/latest/developerguide/images/GSI_05.png)
Apenas os itens com os valores de chaves especificados aparecem na resposta. Nesse conjunto de dados, os itens não estão em nenhuma ordem específica.
Um índice secundário global controla apenas os itens de dados em que seus atributos de chave realmente existem. Por exemplo, suponha que você tenha adicionado um novo item à tabela `GameScores`, mas forneceu somente os atributos de chave primária necessários.
****
| UserId | GameTitle |
| --- | --- |
| 400 | Comet Quest |
Como você não especificou o atributo `TopScore`, o DynamoDB não propagará esse item para `GameTitleIndex`. Portanto, se você tivesse consultado `GameScores` para obter todos os itens do Comet Quest, obteria os quatro itens a seguir.
![\[A tabela que contém uma lista de 4 títulos, pontuações superiores e IDs de usuários.\]](http://docs.aws.amazon.com/pt_br/amazondynamodb/latest/developerguide/images/GSI_04.png)
Uma consulta semelhante em `GameTitleIndex` ainda retornaria três itens, em vez de quatro. Isso acontece porque o item com `TopScore` inexistente não é propagado para o índice.
![\[A tabela que contém uma lista de 3 títulos, pontuações superiores e IDs de usuários.\]](http://docs.aws.amazon.com/pt_br/amazondynamodb/latest/developerguide/images/GSI_05.png)
## Projeções de atributo
Uma *projeção* é o conjunto de atributos que é copiado de uma tabela para um índice secundário. A chave de partição e a chave de classificação da tabela são sempre projetadas no índice; você pode projetar outros atributos para suportar os requisitos de consulta da sua aplicação. Quando você consulta um índice, o Amazon DynamoDB pode acessar quaisquer atributos na projeção como se estivessem em uma tabela própria.
Quando você cria um índice secundário, é necessário especificar os atributos que serão projetados no índice. O DynamoDB proporciona três opções diferentes para fazer isso:
+ *KEYS\$1ONLY*: 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. A opção `KEYS_ONLY` resulta no menor índice secundário possível.
+ *INCLUDE*: além dos atributos descritos em `KEYS_ONLY`, o índice secundário incluirá outros atributos não chave que você especificar.
+ *ALL*: o índice secundário inclui todos os atributos da tabela de origem. Como todos os dados da tabela são duplicados no índice, uma projeção `ALL` resulta no maior índice secundário possível.
No diagrama anterior, `GameTitleIndex` tem apenas um atributo projetado: `UserId` Portanto, embora um aplicativo possa determinar eficientemente o `UserId` dos melhores marcadores para cada jogo usando `GameTitle` e `TopScore` nas consultas, ele não pode determinar com eficiência a maior proporção de vitórias versus derrotas dos maiores marcadores. Para fazer isso, a aplicação teria que realizar uma consulta adicional na tabela base para buscar os ganhos e perdas de cada um dos maiores artilheiros. A maneira mais eficiente de oferecer suporte a consultas nesses dados seria projetar esses atributos da tabela-base no índice secundário global, conforme mostrado neste diagrama.
![\[Descrição da projeção de atributos não essenciais em um GSI para oferecer suporte a consultas eficientes.\]](http://docs.aws.amazon.com/pt_br/amazondynamodb/latest/developerguide/images/GSI_06.png)
Como os atributos não são de chave `Wins` e `Losses` são projetados no índice, um aplicativo pode determinar a proporção de vitórias versus derrotas de qualquer jogo ou de qualquer combinação de jogo e ID do usuário.
Ao escolher os atributos para projetar em um índice secundário global, você deve considerar a desvantagem entre os custos de throughput provisionado e os custos de armazenamento:
+ Se você precisar acessar apenas alguns atributos com a latência mais baixa possível, considere projetar apenas os atributos em um índice secundário global. Quanto menor o índice, menores serão os custos de armazenamento e de gravação.
+ Se sua aplicação acessar frequentemente alguns atributos não chave, considere projetar esses atributos em um índice secundário global. Os custos adicionais de armazenamento do índice secundário global compensarão o custo de executar verificações de tabelas frequentes.
+ Se precisar acessar a maioria dos atributos não chave com frequência, você poderá projetar esses atributos, inclusive a tabela-base inteira, em um índice secundário global. Isso dá flexibilidade máxima a você. No entanto, o custo do armazenamento aumentará ou até dobrará.
+ Se o aplicativo precisar consultar uma tabela com pouca frequência, mas precisar executar muitas gravações ou atualizações nos dados da tabela, considere projetar `KEYS_ONLY`. O índice secundário global seria de tamanho mínimo, mas ainda estaria disponível quando necessário para a atividade de consulta.
## Esquema de chave de vários atributos
Os índices secundários globais são compatíveis com chaves de vários atributos, permitindo que você componha chaves de partição e chaves de classificação com base em vários atributos. Com chaves de vários atributos, você pode criar uma chave de partição com até quatro atributos e uma chave de classificação com até quatro atributos, totalizando até oito atributos por esquema de chave.
As chaves de vários atributos simplificam seu modelo de dados, eliminando a necessidade de concatenar manualmente os atributos em chaves sintéticas. Em vez de criar strings compostas, como `TOURNAMENT#WINTER2024#REGION#NA-EAST`, você pode usar diretamente os atributos naturais do seu modelo de domínio. O DynamoDB processa a lógica da chave composta automaticamente, unindo vários atributos da chave de partição para distribuição de dados e mantendo a ordem de classificação hierárquica em vários atributos da chave de classificação.
Por exemplo, considere um sistema de torneios de jogos em que você deseja organizar partidas por torneio e região. Com chaves de vários atributos, você pode definir sua chave de partição como dois atributos separados: `tournamentId` e `region`. Da mesma forma, você pode definir sua chave de classificação usando vários atributos, como `round`, `bracket` e `matchId`, para criar uma hierarquia natural. Essa abordagem mantém seus dados tipados e seu código limpo, sem manipulação nem análise de strings.
Quando você consulta um índice secundário global com chaves de vários atributos, deve especificar todos os atributos da chave de partição usando condições de igualdade. Em relação a atributos de chave de classificação, é possível consultá-los da esquerda para a direita na ordem em que estão definidos no esquema de chaves. Isso significa que você pode consultar o primeiro atributo da chave de classificação sozinho, os dois primeiros atributos juntos ou todos os atributos juntos, mas não pode ignorar os atributos no meio. Condições de desigualdade, como `>`, `<`, `BETWEEN` ou `begins_with()`, devem ser a última condição em sua consulta.
As chaves de vários atributos funcionam particularmente bem quando você cria índices secundários globais em tabelas existentes. Você pode usar atributos que já existem na sua tabela sem precisar preencher chaves sintéticas em todos os seus dados. Isso facilita a inclusão de novos padrões de consulta à sua aplicação criando índices que reorganizam seus dados usando diferentes combinações de atributos.
Cada atributo em uma chave de vários atributos pode ter seu próprio tipo de dados: `String` (S), `Number` (N) ou `Binary` (B). Quando você escolhe os tipos de dados, pense que os atributos `Number` são classificados numericamente sem exigir preenchimento zero, enquanto os atributos `String` são classificados de modo lexicográfico. Por exemplo, se você usar um tipo `Number` para um atributo de pontuação, os valores 5, 50, 500 e 1000 serão classificados em ordem numérica natural. Os mesmos valores, se fossem do tipo `String`, seriam ordenados como “1000”, “5”, “50”, “500”, a menos que você os preenchesse com zeros à esquerda.
Ao criar chaves de vários atributos, ordene seus atributos do mais geral para o mais específico. Para chaves de partição, combine atributos que são sempre consultados juntos e que oferecem uma boa distribuição de dados. Para chaves de classificação, coloque os atributos frequentemente consultados em primeiro lugar na hierarquia para maximizar a flexibilidade da consulta. Essa ordenação permite que você consulte em qualquer nível de granularidade que corresponda aos seus padrões de acesso.
Consulte exemplos de implementação em [Chaves de vários atributos](GSI.DesignPattern.MultiAttributeKeys.md).
## Ler dados de um índice secundário global
Você pode recuperar itens de um índice secundário global usando as operações `Query` e `Scan`. As operações `GetItem` e `BatchGetItem` não podem ser usadas em um índice secundário global.
### Como consultar um índice secundário global
Você pode usar a operação `Query` para acessar um ou mais itens em um índice secundário global. A consulta deve especificar o nome da tabela-base e o nome do índice que você deseja usar, os atributos a serem retornados nos resultados de consulta e quaisquer condições que você deseja aplicar. O DynamoDB pode retornar os resultados em ordem crescente ou decrescente.
Considere os seguintes dados retornados de uma `Query` que solicita dados de jogos para um aplicativo de placar.
```
{
"TableName": "GameScores",
"IndexName": "GameTitleIndex",
"KeyConditionExpression": "GameTitle = :v_title",
"ExpressionAttributeValues": {
":v_title": {"S": "Meteor Blasters"}
},
"ProjectionExpression": "UserId, TopScore",
"ScanIndexForward": false
}
```
Nesta consulta:
+ O DynamoDB acessa *GameTitleIndex* usando a chave de partição *GameTitle* para localizar os itens de índice do Meteor Blasters. Todos os itens do índice com essa chave são armazenados lado a lado para rápida recuperação.
+ Nesse jogo, o DynamoDB usa o índice para acessar todos os IDs de usuário e as pontuações máximas.
+ Os resultados são retornados, classificados em ordem decrescente, pois o parâmetro `ScanIndexForward` está definido como falso.
### Como verificar um índice secundário global
Você pode usar a operação `Scan` para recuperar todos os dados de um índice secundário global. Você deve fornecer o nome da tabela-base e o nome de índice na solicitação. Com uma operação `Scan`, o DynamoDB lê todos os dados do índice e os retorna para a aplicação. Você também pode solicitar que apenas alguns dos dados sejam retornados, e que os dados restantes sejam descartados. Para fazer isso, use o parâmetro `FilterExpression` da operação `Scan`. Para obter mais informações, consulte [Expressões de filtro para verificação](Scan.md#Scan.FilterExpression).
## Sincronização de dados entre tabelas e índices secundários globais
O DynamoDB sincroniza automaticamente cada índice secundário global com sua tabela-base. Quando uma aplicação grava ou exclui itens em uma tabela, quaisquer índices secundários globais nessa tabela são atualizados de forma assíncrona usando um modelo final consistente. Os aplicativos nunca gravam diretamente em um índice. No entanto, é importante compreender as implicações de como o DynamoDB mantém esses índices.
Í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).
Ao criar um índice secundário global, você especifica um ou mais atributos de chave de índice e seus tipos de dados. Isso significa que sempre que você grava um item na tabela-base, os tipos de dados desses atributos devem corresponder aos tipos de dados do esquema de chaves do índice. No caso de `GameTitleIndex`, a chave de partição `GameTitle` no índice é definida como um tipo de dados `String`. A chave de classificação `TopScore` no índice é do tipo `Number`. Se você tentar adicionar um item à tabela `GameScores` e especificar um tipo de dados diferente para `GameTitle` ou `TopScore`, o DynamoDB retornará uma `ValidationException` devido à inconsistência do tipo de dados.
Quando você insere ou exclui itens em uma tabela, os índices secundários globais dessa tabela são atualizados de uma forma eventualmente consistente. As alterações na tabela são propagadas para os índices secundários globais em uma fração de segundo, sob condições normais. No entanto, em alguns cenários improváveis de falha, podem ocorrer atrasos de propagação mais longos. Consequentemente, as aplicações precisam prever e lidar com situações em que uma consulta em um índice secundário global retorna resultados que não estão atualizados.
Se você gravar um item em uma tabela, não será necessário especificar os atributos para qualquer chave de classificação do índice secundário global. Usando `GameTitleIndex` como um exemplo, você não precisa especificar um valor para o atributo `TopScore` para gravar um novo item na tabela `GameScores`. Neste caso, o DynamoDB não grava todos os dados no índice deste item específico.
Os custos das atividades de gravação em uma tabela com muitos índices secundários serão mais altos do que em uma tabela com um número menor de índices. Para obter mais informações, consulte [Considerações sobre throughput provisionado para índices secundários globais](#GSI.ThroughputConsiderations).
## Classes de tabela com índice secundário global
Um índice secundário global sempre usará a mesma classe de tabela que sua tabela-base. Sempre que um novo índice secundário global for adicionado para uma tabela, o novo índice usará a mesma classe de tabela que sua tabela base. Quando a classe de tabela de uma tabela é atualizada, todos os índices secundários globais associados também são atualizados.
## Considerações sobre throughput provisionado para índices secundários globais
Ao criar um índice secundário global em uma tabela de modo provisionado, você deve especificar unidades de capacidade de leitura e gravação para a workload esperada no índice. As configurações de throughput provisionado de um índice secundário global são separadas daquelas de sua tabela-base. Uma operação `Query` em um índice secundário global consome unidades de capacidade de leitura do índice, não da tabela-base. Quando você insere ou exclui itens em uma tabela, os índices secundários globais dessa tabela também são atualizados. Essas atualizações de índice consomem unidades de capacidade do índice, não da tabela base.
Por exemplo, se você usar a operação `Query` em um índice secundário global e exceder sua capacidade de leitura provisionada, sua solicitação será limitada. Se você executar atividades de gravação pesadas na tabela, mas um índice secundário global da tabela tiver capacidade de gravação insuficiente, a atividade de gravação na tabela será limitada.
**Importante**
Para evitar o controle de utilização potencial, a capacidade de gravação provisionada para um índice secundário global deve ser igual ou maior que a capacidade de gravação da tabela base, porque as novas atualizações gravarão na tabela base e no índice secundário global.
Para visualizar as configurações de throughput provisionado de um índice secundário global, use a operação `DescribeTable`. Informações detalhadas sobre todos os índices secundários globais da tabela são retornados.
### Unidades de capacidade de leitura
Os índices secundários globais oferecem suporte a leituras eventualmente consistentes, cada uma delas consome metade de uma unidade de capacidade de leitura. Isso significa que uma única consulta de índice secundário global pode recuperar até 2 × 4 KB = 8 KB por unidade de capacidade de leitura.
Para consultas de índice secundário global, o DynamoDB calcula a atividade de leitura provisionada da mesma forma que para consultas em tabelas. A única diferença é que o cálculo é baseado no tamanho das entradas de índice, em vez do tamanho do item na tabela-base. O número de unidades de capacidade de leitura é a soma de todos os tamanhos de atributos projetados em todos os itens retornados. O resultado é arredondado para o próximo limite de 4 KB. Para obter mais informações sobre como o DynamoDB calcula a utilização de throughput provisionado, consulte [Modo de capacidade provisionada do DynamoDB](provisioned-capacity-mode.md).
O tamanho máximo dos resultados retornados por uma operação `Query` é 1 MB. Isso inclui os tamanhos de todos os nomes e valores de atributos de todos os itens retornados.
Por exemplo, considere um índice secundário global em que cada item contém 2.000 bytes de dados. Agora vamos supor que você use a operação `Query` nesse índice e que `KeyConditionExpression` da consulta retorne oito itens. O tamanho total dos itens correspondentes é 2.000 bytes × 8 itens = 16.000 bytes. O resultado é arredondado para o próximo limite de 4 KB. Como as consultas do índice secundário global são finais consistentes, o custo total é 0,5 × (16 KB / 4 KB), ou 2 unidades de capacidade de leitura.
### Unidades de capacidade de gravação
Quando um item é adicionado, atualizado ou excluído em uma tabela, e um índice secundário global é afetado por isso, o índice secundário global consome unidades de capacidade de gravação provisionadas para a operação. O custo total do throughput provisionado para uma gravação consiste na soma das unidades de capacidade de gravação consumidas pela gravação na tabela base e pela atualização dos índices secundários globais. Se uma gravação em uma tabela não exigir uma atualização do índice secundário global, nenhuma capacidade de gravação será consumida no índice.
Para que uma gravação de tabela seja bem-sucedida, as configurações do throughput provisionado e todos os seus índices secundários globais devem ter capacidade de gravação suficiente para acomodar a gravação. Caso contrário, a gravação na tabela será limitada.
**Importante**
Ao criar um índice secundário global (GSI), as operações de gravação na tabela base poderão sofrer controle de utilização se a atividade do GSI resultante das gravações na tabela base exceder a capacidade de gravação provisionada do GSI. Esse controle de utilização afeta todas as operações de gravação, desde o processo de indexação até a possível interrupção de suas workloads de produção. Para ter mais informações, consulte [Problemas de controle de utilização no Amazon DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/TroubleshootingThrottling.html).
O custo de gravar um item em um índice secundário global depende de vários fatores:
+ Se você gravar um novo item na tabela que define um atributo indexado, ou atualizar um item existente para definir um atributo indexado indefinido anteriormente, uma operação de gravação é necessária para inserir o item no índice.
+ Se uma atualização na tabela alterar o valor de um atributo de chave indexado (de A para B), duas gravações serão necessárias, uma para excluir o item anterior do índice e outra gravação para inserir o novo item no índice.
+ Se um item estava presente no índice, mas uma gravação na tabela fez com que o atributo indexado fosse excluído, uma gravação é necessária para excluir a projeção do item antigo do índice.
+ Se um item não estiver presente no índice antes ou depois que o item é atualizado, não haverá custo de gravação adicionais para o índice.
+ Se uma atualização na tabela alterar somente o valor dos atributos projetados no esquema de chaves do índice, mas não alterar o valores de qualquer atributo de chave indexado, uma gravação será necessária para atualizar os valores dos atributos projetados no índice.
Todos esses fatores supõem que o tamanho de cada item no índice seja menor ou igual ao tamanho de item de 1 KB para calcular unidades de capacidade de gravação. Entradas de índice maiores exigirão unidades adicionais de capacidade de gravação. Você pode minimizar os custos de gravação, considerando quais atributos suas consultas precisarão retornar e projetar apenas esses atributos no índice.
## Considerações sobre armazenamento para índices secundários globais
Quando uma aplicação grava um item em uma tabela, o DynamoDB copia automaticamente o subconjunto de atributos corretos para qualquer índice secundário global no qual esses atributos devem aparecer. Sua conta da AWS é cobrada pelo armazenamento do item na tabela-base e também pelo armazenamento de atributos em qualquer índice secundário global dessa tabela.
A quantidade de espaço usada por um item do índice é a soma do seguinte:
+ O tamanho em bytes da chave primária da tabela-base (chave de partição e chave de classificação)
+ O tamanho em bytes do atributo de chave do índice
+ O tamanho em bytes dos atributos projetados (se houver)
+ 100 bytes de sobrecarga por item de índice
Para estimar os requisitos de armazenamento de um índice secundário global, você pode estimar o tamanho médio de um item no índice e multiplicar pelo número de itens da tabela-base que têm os atributos de chave do índice secundário global.
Se uma tabela contiver um item em que determinado atributo não esteja definido, mas esteja configurado como uma chave de partição ou chave de classificação do índice, o DynamoDB não gravará nenhum dado desse item no índice.
# Padrões de design
Os padrões de design fornecem soluções comprovadas para desafios comuns quando você trabalha com índices secundários globais. Esses padrões ajudam você a criar aplicações eficientes e escaláveis, mostrando como estruturar seus índices para casos de uso específicos.
Cada padrão inclui um guia de implementação completo com exemplos de código, práticas recomendadas e casos de uso reais para ajudar você a aplicar o padrão em suas próprias aplicações.
**Topics**
+ [Chaves de vários atributos](GSI.DesignPattern.MultiAttributeKeys.md)
# Padrão de chaves de vários atributos
## Visão geral
As chaves de vários atributos permitem criar partições de Índice Secundário Global (GSI) e chaves de classificação compostas por até quatro atributos cada. Isso reduz o código do lado do cliente e facilita a modelagem inicial dos dados e a adição posterior de novos padrões de acesso.
Pense em um cenário comum: para criar um GSI que consulte itens por vários atributos hierárquicos, você tradicionalmente precisaria criar chaves sintéticas concatenando valores. Por exemplo, em uma aplicação de jogos, para consultar partidas de torneios por torneio, região e rodada, você pode criar uma chave de partição de GSI sintética, como TOURNAMENT\$1WINTER2024\$1REGION\$1NA-EAST, e uma chave de classificação sintética, como ROUND\$1SEMIFINALS\$1BRACKET\$1UPPER. Essa abordagem funciona, mas requer concatenação de strings ao gravar dados, analisar durante a leitura e preencher chaves sintéticas em todos os itens existentes se você estiver adicionando o GSI a uma tabela existente. Isso torna o código mais confuso e desafiador para manter a segurança de tipos em componentes de chave individuais.
As chaves de vários atributos resolvem esse problema para GSIs. Você define sua chave de partição de GSI usando vários atributos existentes, como tournamentId e region. O DynamoDB processa a lógica da chave composta automaticamente, juntando-as para distribuição de dados. Você grava itens usando atributos naturais do seu modelo de domínio e o GSI os indexa automaticamente. Sem concatenação, sem análise, sem preenchimento. Seu código permanece limpo, seus dados permanecem tipados e suas consultas permanecem simples. Essa abordagem é particularmente útil quando você tem dados hierárquicos com agrupamentos de atributos naturais (como torneio → região → rodada ou organização → departamento → equipe).
## Aplicação de exemplo
Este guia explica a criação de um sistema de rastreamento de partidas de torneios para uma plataforma de esportes eletrônicos. A plataforma precisa consultar partidas de forma eficiente em várias dimensões: por torneio e região para gerenciamento de chaves, por jogador para o histórico de partidas e por data para agendamento.
## Modelo de dados
Neste passo a passo, o sistema de rastreamento de partidas do torneio comporta três padrões de acesso primários, cada um exigindo uma estrutura de chave diferente:
**Padrão de acesso 1:** procure uma correspondência específica por seu ID exclusivo.
+ **Solução:** tabela base com `matchId` como chave de partição.
**Padrão de acesso 2:** consulte todas as partidas de um torneio e região específicos, opcionalmente filtrando por rodada, chave ou partida.
+ **Solução:** índice secundário global com chave de partição de vários atributos (`tournamentId` \$1 `region`) e chave de classificação de vários atributos (`round` \$1 `bracket` \$1 `matchId`).
+ **Consultas de exemplo:** “Todas as partidas WINTER2024 na região NA-EAST” ou “Todas as partidas de SEMIFINALS na chave UPPER de WINTER2024/NA-EAST”.
**Padrão de acesso 3:** consulte o histórico de partidas de um jogador, opcionalmente filtrando por intervalo de datas ou rodada do torneio.
+ **Solução:** índice secundário global com uma chave de partição (`player1Id`) e uma chave de classificação de vários atributos (`matchDate` \$1 `round`).
+ **Consultas de exemplo:** “Todas as partidas do jogador 101" ou “Partidas do jogador 101 em janeiro de 2024".
A principal diferença entre as abordagens tradicional e de vários atributos fica clara ao examinar a estrutura do item:
**Abordagem tradicional do Índice Secundário Global (chaves concatenadas):**
```
// Manual concatenation required for GSI keys
const item = {
matchId: 'match-001', // Base table PK
tournamentId: 'WINTER2024',
region: 'NA-EAST',
round: 'SEMIFINALS',
bracket: 'UPPER',
player1Id: '101',
// Synthetic keys needed for GSI
GSI_PK: `TOURNAMENT#${tournamentId}#REGION#${region}`, // Must concatenate
GSI_SK: `${round}#${bracket}#${matchId}`, // Must concatenate
// ... other attributes
};
```
**Abordagem de Índice Secundário Global de vários atributos (chaves nativas):**
```
// Use existing attributes directly - no concatenation needed
const item = {
matchId: 'match-001', // Base table PK
tournamentId: 'WINTER2024',
region: 'NA-EAST',
round: 'SEMIFINALS',
bracket: 'UPPER',
player1Id: '101',
matchDate: '2024-01-18',
// No synthetic keys needed - GSI uses existing attributes directly
// ... other attributes
};
```
Com chaves de vários atributos, você grava itens uma vez com atributos de domínio naturais. O DynamoDB os indexa automaticamente em vários GSIs sem exigir chaves concatenadas sintéticas.
**Esquema da tabela base:**
+ Chave de partição: `matchId` (1 atributo)
**Esquema de Índice Secundário Global (TournamentRegionIndex com chaves de vários atributos):**
+ Chave de partição: `tournamentId`, `region` (2 atributos)
+ Chave de classificação: `round`, `bracket`, `matchId` (3 atributos)
**Esquema de Índice Secundário Global (PlayerMatchHistoryIndex com chaves de vários atributos):**
+ Chave de partição: `player1Id` (1 atributo)
+ Chave de classificação: `matchDate`, `round` (2 atributos)
### Tabela base: TournamentMatches
| matchId (PK) | tournamentId | região | round | bracket | player1Id | player2Id | matchDate | winner | pontuação |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| match-001 | WINTER2024 | NA-EAST | FINALS | CHAMPIONSHIP | 101 | 103 | 2024-01-20 | 101 | 3-1 |
| match-002 | WINTER2024 | NA-EAST | SEMIFINALS | UPPER | 101 | 105 | 2024-01-18 | 101 | 3-2 |
| match-003 | WINTER2024 | NA-EAST | SEMIFINALS | UPPER | 103 | 107 | 2024-01-18 | 103 | 3-0 |
| match-004 | WINTER2024 | NA-EAST | QUARTERFINALS | UPPER | 101 | 109 | 2024-01-15 | 101 | 3-1 |
| match-005 | WINTER2024 | NA-WEST | FINALS | CHAMPIONSHIP | 102 | 104 | 2024-01-20 | 102 | 3-2 |
| match-006 | WINTER2024 | NA-WEST | SEMIFINALS | UPPER | 102 | 106 | 2024-01-18 | 102 | 3-1 |
| match-007 | SPRING2024 | NA-EAST | QUARTERFINALS | UPPER | 101 | 108 | 2024-03-15 | 101 | 3-0 |
| match-008 | SPRING2024 | NA-EAST | QUARTERFINALS | LOWER | 103 | 110 | 2024-03-15 | 103 | 3-2 |
### GSI: TournamentRegionIndex (chaves de vários atributos)
| tournamentId (PK) | region (PK) | round (SK) | bracket (SK) | matchId (SK) | player1Id | player2Id | matchDate | winner | pontuação |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| WINTER2024 | NA-EAST | FINALS | CHAMPIONSHIP | match-001 | 101 | 103 | 2024-01-20 | 101 | 3-1 |
| WINTER2024 | NA-EAST | QUARTERFINALS | UPPER | match-004 | 101 | 109 | 2024-01-15 | 101 | 3-1 |
| WINTER2024 | NA-EAST | SEMIFINALS | UPPER | match-002 | 101 | 105 | 2024-01-18 | 101 | 3-2 |
| WINTER2024 | NA-EAST | SEMIFINALS | UPPER | match-003 | 103 | 107 | 2024-01-18 | 103 | 3-0 |
| WINTER2024 | NA-WEST | FINALS | CHAMPIONSHIP | match-005 | 102 | 104 | 2024-01-20 | 102 | 3-2 |
| WINTER2024 | NA-WEST | SEMIFINALS | UPPER | match-006 | 102 | 106 | 2024-01-18 | 102 | 3-1 |
| SPRING2024 | NA-EAST | QUARTERFINALS | LOWER | match-008 | 103 | 110 | 2024-03-15 | 103 | 3-2 |
| SPRING2024 | NA-EAST | QUARTERFINALS | UPPER | match-007 | 101 | 108 | 2024-03-15 | 101 | 3-0 |
### GSI: PlayerMatchHistoryIndex (chaves de vários atributos)
| player1Id (PK) | matchDate (SK) | round (SK) | tournamentId | região | bracket | matchId | player2Id | winner | pontuação |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 101 | 2024-01-15 | QUARTERFINALS | WINTER2024 | NA-EAST | UPPER | match-004 | 109 | 101 | 3-1 |
| 101 | 2024-01-18 | SEMIFINALS | WINTER2024 | NA-EAST | UPPER | match-002 | 105 | 101 | 3-2 |
| 101 | 2024-01-20 | FINALS | WINTER2024 | NA-EAST | CHAMPIONSHIP | match-001 | 103 | 101 | 3-1 |
| 101 | 2024-03-15 | QUARTERFINALS | SPRING2024 | NA-EAST | UPPER | match-007 | 108 | 101 | 3-0 |
| 102 | 2024-01-18 | SEMIFINALS | WINTER2024 | NA-WEST | UPPER | match-006 | 106 | 102 | 3-1 |
| 102 | 2024-01-20 | FINALS | WINTER2024 | NA-WEST | CHAMPIONSHIP | match-005 | 104 | 102 | 3-2 |
| 103 | 2024-01-18 | SEMIFINALS | WINTER2024 | NA-EAST | UPPER | match-003 | 107 | 103 | 3-0 |
| 103 | 2024-03-15 | QUARTERFINALS | SPRING2024 | NA-EAST | LOWER | match-008 | 110 | 103 | 3-2 |
## Pré-requisitos
Antes de começar, verifique se você tem:
### Conta e permissões
+ Uma conta da AWS ativa ([crie uma aqui](https://aws.amazon.com/free/), se necessário)
+ Permissões do IAM para operações do DynamoDB:
+ `dynamodb:CreateTable`
+ `dynamodb:DeleteTable`
+ `dynamodb:DescribeTable`
+ `dynamodb:PutItem`
+ `dynamodb:Query`
+ `dynamodb:BatchWriteItem`
**nota**
**Nota de segurança:** para uso em produção, crie uma política do IAM personalizada com apenas as permissões necessárias. Para este tutorial, você pode usar a política gerenciada pela AWS `AmazonDynamoDBFullAccessV2`.
### Ambiente de desenvolvimento
+ Node.js instalado em sua máquina
+ Credenciais da AWS configuradas usando um dos seguintes métodos:
**Opção 1: AWS CLI**
```
aws configure
```
**Opção 2: Variáveis de ambiente**
```
export AWS_ACCESS_KEY_ID=your_access_key_here
export AWS_SECRET_ACCESS_KEY=your_secret_key_here
export AWS_DEFAULT_REGION=us-east-1
```
### Instalar os pacotes obrigatórios
```
npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
```
## Implementação
### Etapa 1: criar tabela com GSIs usando chaves de vários atributos
Crie uma tabela com uma estrutura de chave básica simples e GSIs que usam chaves de vários atributos.
#### Exemplo de código
```
import { DynamoDBClient, CreateTableCommand } from "@aws-sdk/client-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const response = await client.send(new CreateTableCommand({
TableName: 'TournamentMatches',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'matchId', KeyType: 'HASH' } // Simple PK
],
AttributeDefinitions: [
{ AttributeName: 'matchId', AttributeType: 'S' },
{ AttributeName: 'tournamentId', AttributeType: 'S' },
{ AttributeName: 'region', AttributeType: 'S' },
{ AttributeName: 'round', AttributeType: 'S' },
{ AttributeName: 'bracket', AttributeType: 'S' },
{ AttributeName: 'player1Id', AttributeType: 'S' },
{ AttributeName: 'matchDate', AttributeType: 'S' }
],
// GSIs with multi-attribute keys
GlobalSecondaryIndexes: [
{
IndexName: 'TournamentRegionIndex',
KeySchema: [
{ AttributeName: 'tournamentId', KeyType: 'HASH' }, // GSI PK attribute 1
{ AttributeName: 'region', KeyType: 'HASH' }, // GSI PK attribute 2
{ AttributeName: 'round', KeyType: 'RANGE' }, // GSI SK attribute 1
{ AttributeName: 'bracket', KeyType: 'RANGE' }, // GSI SK attribute 2
{ AttributeName: 'matchId', KeyType: 'RANGE' } // GSI SK attribute 3
],
Projection: { ProjectionType: 'ALL' }
},
{
IndexName: 'PlayerMatchHistoryIndex',
KeySchema: [
{ AttributeName: 'player1Id', KeyType: 'HASH' }, // GSI PK
{ AttributeName: 'matchDate', KeyType: 'RANGE' }, // GSI SK attribute 1
{ AttributeName: 'round', KeyType: 'RANGE' } // GSI SK attribute 2
],
Projection: { ProjectionType: 'ALL' }
}
],
BillingMode: 'PAY_PER_REQUEST'
}));
console.log("Table with multi-attribute GSI keys created successfully");
```
**Principais decisões de design:**
**Tabela base:** a tabela base usa uma chave de partição `matchId` simples para pesquisas diretas de correspondência, mantendo a estrutura da tabela base simples, enquanto os GSIs fornecem padrões de consulta complexos.
**Índice Secundário Global TournamentRegionIndex:** o Índice Secundário Global `TournamentRegionIndex` usa `tournamentId` \$1 `region` como uma chave de partição de vários atributos, criando um isolamento da região do torneio em que os dados são distribuídos pelo hash de ambos os atributos combinados, permitindo consultas eficientes dentro de um contexto específico da região do torneio. A chave de classificação de vários atributos (`round` \$1 `bracket` \$1`matchId`) fornece classificação hierárquica que comporta consultas em qualquer nível da hierarquia com ordenação natural do geral (redondo) ao específico (ID de correspondência).
**Índice secundário global PlayerMatchHistoryIndex:** o Índice Secundário Global `PlayerMatchHistoryIndex` reorganiza os dados por jogador usando `player1Id` como chave de partição, permitindo consultas entre torneios para um jogador específico. A chave de classificação de vários atributos (`matchDate` \$1 `round`) fornece ordem cronológica com a capacidade de filtrar por intervalos de datas ou rodadas específicas do torneio.
### Etapa 2: inserir dados com atributos nativos
Adicione dados da partida do torneio usando atributos naturais. O GSI indexará automaticamente esses atributos sem exigir chaves sintéticas.
#### Exemplo de código
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);
// Tournament match data - no synthetic keys needed for GSIs
const matches = [
// Winter 2024 Tournament, NA-EAST region
{
matchId: 'match-001',
tournamentId: 'WINTER2024',
region: 'NA-EAST',
round: 'FINALS',
bracket: 'CHAMPIONSHIP',
player1Id: '101',
player2Id: '103',
matchDate: '2024-01-20',
winner: '101',
score: '3-1'
},
{
matchId: 'match-002',
tournamentId: 'WINTER2024',
region: 'NA-EAST',
round: 'SEMIFINALS',
bracket: 'UPPER',
player1Id: '101',
player2Id: '105',
matchDate: '2024-01-18',
winner: '101',
score: '3-2'
},
{
matchId: 'match-003',
tournamentId: 'WINTER2024',
region: 'NA-EAST',
round: 'SEMIFINALS',
bracket: 'UPPER',
player1Id: '103',
player2Id: '107',
matchDate: '2024-01-18',
winner: '103',
score: '3-0'
},
{
matchId: 'match-004',
tournamentId: 'WINTER2024',
region: 'NA-EAST',
round: 'QUARTERFINALS',
bracket: 'UPPER',
player1Id: '101',
player2Id: '109',
matchDate: '2024-01-15',
winner: '101',
score: '3-1'
},
// Winter 2024 Tournament, NA-WEST region
{
matchId: 'match-005',
tournamentId: 'WINTER2024',
region: 'NA-WEST',
round: 'FINALS',
bracket: 'CHAMPIONSHIP',
player1Id: '102',
player2Id: '104',
matchDate: '2024-01-20',
winner: '102',
score: '3-2'
},
{
matchId: 'match-006',
tournamentId: 'WINTER2024',
region: 'NA-WEST',
round: 'SEMIFINALS',
bracket: 'UPPER',
player1Id: '102',
player2Id: '106',
matchDate: '2024-01-18',
winner: '102',
score: '3-1'
},
// Spring 2024 Tournament, NA-EAST region
{
matchId: 'match-007',
tournamentId: 'SPRING2024',
region: 'NA-EAST',
round: 'QUARTERFINALS',
bracket: 'UPPER',
player1Id: '101',
player2Id: '108',
matchDate: '2024-03-15',
winner: '101',
score: '3-0'
},
{
matchId: 'match-008',
tournamentId: 'SPRING2024',
region: 'NA-EAST',
round: 'QUARTERFINALS',
bracket: 'LOWER',
player1Id: '103',
player2Id: '110',
matchDate: '2024-03-15',
winner: '103',
score: '3-2'
}
];
// Insert all matches
for (const match of matches) {
await docClient.send(new PutCommand({
TableName: 'TournamentMatches',
Item: match
}));
console.log(`Added: ${match.matchId} - ${match.tournamentId}/${match.region} - ${match.round} ${match.bracket}`);
}
console.log(`\nInserted ${matches.length} tournament matches`);
console.log("No synthetic keys created - GSIs use native attributes automatically");
```
**Estrutura de dados explicada:**
**Uso de atributos naturais:** cada atributo representa um conceito real de torneio sem necessidade de concatenação ou análise de strings, fornecendo mapeamento direto para o modelo de domínio.
**Indexação automática do Índice Secundário Global:** os GSIs indexam itens automaticamente usando os atributos existentes (`tournamentId`, `region`, `round`, `bracket`, `matchId` para TournamentRegionIndex e `player1Id`, `matchDate`, `round` para PlayerMatchHistoryIndex) sem exigir chaves concatenadas sintéticas.
**Sem necessidade de preenchimento:** quando você adiciona um novo Índice Secundário Global com chaves de vários atributos a uma tabela existente, o DynamoDB indexa automaticamente todos os itens existentes usando seus atributos naturais, sem a necessidade de atualizar os itens com chaves sintéticas.
### Etapa 3: consultar o Índice Secundário Global TournamentRegionIndex com todos os atributos da chave de partição
Este exemplo consulta o Índice Secundário Global TournamentRegionIndex, que tem uma chave de partição de vários atributos (`tournamentId` \$1 `region`). Todos os atributos da chave de partição devem ser especificados com condições de igualdade nas consultas, ou seja, você não pode fazer consultas com apenas `tournamentId` sozinho ou usar operadores de desigualdade nos atributos da chave de partição.
#### Exemplo de código
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);
// Query GSI: All matches for WINTER2024 tournament in NA-EAST region
const response = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region',
ExpressionAttributeNames: {
'#region': 'region', // 'region' is a reserved keyword
'#tournament': 'tournament'
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST'
}
}));
console.log(`Found ${response.Items.length} matches for WINTER2024/NA-EAST:\n`);
response.Items.forEach(match => {
console.log(` ${match.round} | ${match.bracket} | ${match.matchId}`);
console.log(` Players: ${match.player1Id} vs ${match.player2Id}`);
console.log(` Winner: ${match.winner}, Score: ${match.score}\n`);
});
```
**Saída esperada:**
```
Found 4 matches for WINTER2024/NA-EAST:
FINALS | CHAMPIONSHIP | match-001
Players: 101 vs 103
Winner: 101, Score: 3-1
QUARTERFINALS | UPPER | match-004
Players: 101 vs 109
Winner: 101, Score: 3-1
SEMIFINALS | UPPER | match-002
Players: 101 vs 105
Winner: 101, Score: 3-2
SEMIFINALS | UPPER | match-003
Players: 103 vs 107
Winner: 103, Score: 3-0
```
**Consultas inválidas:**
```
// Missing region attribute
KeyConditionExpression: 'tournamentId = :tournament'
// Using inequality on partition key attribute
KeyConditionExpression: 'tournamentId = :tournament AND #region > :region'
```
**Performance:** as chaves de partição de vários atributos são combinadas por meio de uma função hash, fornecendo a mesma performance de pesquisa O(1) como chaves de atributo único.
### Etapa 4: consultar as chaves de classificação do Índice Secundário Global da esquerda para a direita
Os atributos da chave de classificação devem ser consultados da esquerda para a direita na ordem em que estão definidos no Índice Secundário Global. Este exemplo demonstra a consulta do TournamentRegionIndex em diferentes níveis hierárquicos: filtrando por apenas `round`, por `round` \$1 `bracket` ou por todos os três atributos da chave de classificação. Você não pode ignorar atributos no meio, por exemplo, você não pode consultar por `round` e `matchId` e ignorar `bracket`.
#### Exemplo de código
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);
// Query 1: Filter by first sort key attribute (round)
console.log("Query 1: All SEMIFINALS matches");
const query1 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round = :round',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':round': 'SEMIFINALS'
}
}));
console.log(` Found ${query1.Items.length} matches\n`);
// Query 2: Filter by first two sort key attributes (round + bracket)
console.log("Query 2: SEMIFINALS UPPER bracket matches");
const query2 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round = :round AND bracket = :bracket',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':round': 'SEMIFINALS',
':bracket': 'UPPER'
}
}));
console.log(` Found ${query2.Items.length} matches\n`);
// Query 3: Filter by all three sort key attributes (round + bracket + matchId)
console.log("Query 3: Specific match in SEMIFINALS UPPER bracket");
const query3 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round = :round AND bracket = :bracket AND matchId = :matchId',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':round': 'SEMIFINALS',
':bracket': 'UPPER',
':matchId': 'match-002'
}
}));
console.log(` Found ${query3.Items.length} matches\n`);
// Query 4: INVALID - skipping round
console.log("Query 4: Attempting to skip first sort key attribute (WILL FAIL)");
try {
const query4 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND bracket = :bracket',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':bracket': 'UPPER'
}
}));
} catch (error) {
console.log(` Error: ${error.message}`);
console.log(` Cannot skip sort key attributes - must query left-to-right\n`);
}
```
**Saída esperada:**
```
Query 1: All SEMIFINALS matches
Found 2 matches
Query 2: SEMIFINALS UPPER bracket matches
Found 2 matches
Query 3: Specific match in SEMIFINALS UPPER bracket
Found 1 matches
Query 4: Attempting to skip first sort key attribute (WILL FAIL)
Error: Query key condition not supported
Cannot skip sort key attributes - must query left-to-right
```
**Regras de consulta da esquerda para a direita:** você deve consultar os atributos na ordem da esquerda para a direita, sem ignorar nenhum.
**Padrões válidos:**
+ Somente o primeiro atributo: `round = 'SEMIFINALS'`
+ Primeiros dois atributos: `round = 'SEMIFINALS' AND bracket = 'UPPER'`
+ Todos os três atributos: `round = 'SEMIFINALS' AND bracket = 'UPPER' AND matchId = 'match-002'`
**Padrões inválidos:**
+ Ignorando o primeiro atributo: `bracket = 'UPPER'` (ignora uma rodada)
+ Consulta fora de ordem: `matchId = 'match-002' AND round = 'SEMIFINALS'`
+ Deixando lacunas: `round = 'SEMIFINALS' AND matchId = 'match-002'` (ignora a chave)
**nota**
**Dica de design:** ordene os atributos da chave de classificação do mais geral para o mais específico para maximizar a flexibilidade da consulta.
### Etapa 5: usar condições de desigualdade nas chaves de classificação do Índice Secundário Global
Condições de desigualdade devem ser a última condição em sua consulta. Este exemplo demonstra o uso de operadores de comparação (`>=`, `BETWEEN`) e correspondência de prefixo (`begins_with()`) nos atributos da chave de classificação. Depois de usar um operador de desigualdade, você não pode adicionar nenhuma condição adicional de chave de classificação depois dele, ou seja, a desigualdade deve ser a condição final em sua expressão de condição de chave.
#### Exemplo de código
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);
// Query 1: Round comparison (inequality on first sort key attribute)
console.log("Query 1: Matches from QUARTERFINALS onwards");
const query1 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round >= :round',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':round': 'QUARTERFINALS'
}
}));
console.log(` Found ${query1.Items.length} matches\n`);
// Query 2: Round range with BETWEEN
console.log("Query 2: Matches between QUARTERFINALS and SEMIFINALS");
const query2 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round BETWEEN :start AND :end',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':start': 'QUARTERFINALS',
':end': 'SEMIFINALS'
}
}));
console.log(` Found ${query2.Items.length} matches\n`);
// Query 3: Prefix matching with begins_with (treated as inequality)
console.log("Query 3: Matches in brackets starting with 'U'");
const query3 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round = :round AND begins_with(bracket, :prefix)',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':round': 'SEMIFINALS',
':prefix': 'U'
}
}));
console.log(` Found ${query3.Items.length} matches\n`);
// Query 4: INVALID - condition after inequality
console.log("Query 4: Attempting condition after inequality (WILL FAIL)");
try {
const query4 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region AND round > :round AND bracket = :bracket',
ExpressionAttributeNames: {
'#region': 'region' // 'region' is a reserved keyword
},
ExpressionAttributeValues: {
':tournament': 'WINTER2024',
':region': 'NA-EAST',
':round': 'QUARTERFINALS',
':bracket': 'UPPER'
}
}));
} catch (error) {
console.log(` Error: ${error.message}`);
console.log(` Cannot add conditions after inequality - it must be last\n`);
}
```
**Regras do operador de desigualdade:** você pode usar operadores de comparação (`>`, `>=`, `<`, `<=`) `BETWEEN` para consultas de intervalo e `begins_with()` para correspondência de prefixos. A desigualdade deve ser a última condição em sua consulta.
**Padrões válidos:**
+ Condições de igualdade seguidas de desigualdade: `round = 'SEMIFINALS' AND bracket = 'UPPER' AND matchId > 'match-001'`
+ Desigualdade no primeiro atributo: `round BETWEEN 'QUARTERFINALS' AND 'SEMIFINALS'`
+ Correspondência de prefixo como condição final: `round = 'SEMIFINALS' AND begins_with(bracket, 'U')`
**Padrões inválidos:**
+ Adicionando condições após uma desigualdade: `round > 'QUARTERFINALS' AND bracket = 'UPPER'`
+ Usando várias desigualdades: `round > 'QUARTERFINALS' AND bracket > 'L'`
**Importante**
`begins_with()` é tratada como uma condição de desigualdade, portanto, nenhuma condição adicional de chave de classificação pode segui-la.
### Etapa 6: consultar o Índice Secundário Global PlayerMatchHistoryIndex com chaves de classificação vários atributos
Este exemplo consulta o PlayerMatchHistoryIndex, que tem uma única chave de partição (`player1Id`) e uma chave de classificação de vários atributos (`matchDate` \$1 `round`). Isso permite a análise de vários torneios consultando todas as partidas de um jogador específico sem saber os IDs do torneio, enquanto a tabela base exigiria consultas separadas por combinação de torneio e região.
#### Exemplo de código
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);
// Query 1: All matches for Player 101 across all tournaments
console.log("Query 1: All matches for Player 101");
const query1 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'PlayerMatchHistoryIndex',
KeyConditionExpression: 'player1Id = :player',
ExpressionAttributeValues: {
':player': '101'
}
}));
console.log(` Found ${query1.Items.length} matches for Player 101:`);
query1.Items.forEach(match => {
console.log(` ${match.tournamentId}/${match.region} - ${match.matchDate} - ${match.round}`);
});
console.log();
// Query 2: Player 101 matches on specific date
console.log("Query 2: Player 101 matches on 2024-01-18");
const query2 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'PlayerMatchHistoryIndex',
KeyConditionExpression: 'player1Id = :player AND matchDate = :date',
ExpressionAttributeValues: {
':player': '101',
':date': '2024-01-18'
}
}));
console.log(` Found ${query2.Items.length} matches\n`);
// Query 3: Player 101 SEMIFINALS matches on specific date
console.log("Query 3: Player 101 SEMIFINALS matches on 2024-01-18");
const query3 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'PlayerMatchHistoryIndex',
KeyConditionExpression: 'player1Id = :player AND matchDate = :date AND round = :round',
ExpressionAttributeValues: {
':player': '101',
':date': '2024-01-18',
':round': 'SEMIFINALS'
}
}));
console.log(` Found ${query3.Items.length} matches\n`);
// Query 4: Player 101 matches in date range
console.log("Query 4: Player 101 matches in January 2024");
const query4 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'PlayerMatchHistoryIndex',
KeyConditionExpression: 'player1Id = :player AND matchDate BETWEEN :start AND :end',
ExpressionAttributeValues: {
':player': '101',
':start': '2024-01-01',
':end': '2024-01-31'
}
}));
console.log(` Found ${query4.Items.length} matches\n`);
```
## Variações de padrões
### Dados de séries temporais com chaves de vários atributos
Otimizar para consultas de séries temporais com atributos de tempo hierárquicos
#### Exemplo de código
```
{
TableName: 'IoTReadings',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'readingId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'readingId', AttributeType: 'S' },
{ AttributeName: 'deviceId', AttributeType: 'S' },
{ AttributeName: 'locationId', AttributeType: 'S' },
{ AttributeName: 'year', AttributeType: 'S' },
{ AttributeName: 'month', AttributeType: 'S' },
{ AttributeName: 'day', AttributeType: 'S' },
{ AttributeName: 'timestamp', AttributeType: 'S' }
],
// GSI with multi-attribute keys for time-series queries
GlobalSecondaryIndexes: [{
IndexName: 'DeviceLocationTimeIndex',
KeySchema: [
{ AttributeName: 'deviceId', KeyType: 'HASH' },
{ AttributeName: 'locationId', KeyType: 'HASH' },
{ AttributeName: 'year', KeyType: 'RANGE' },
{ AttributeName: 'month', KeyType: 'RANGE' },
{ AttributeName: 'day', KeyType: 'RANGE' },
{ AttributeName: 'timestamp', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
}],
BillingMode: 'PAY_PER_REQUEST'
}
// Query patterns enabled via GSI:
// - All readings for device in location
// - Readings for specific year
// - Readings for specific month in year
// - Readings for specific day
// - Readings in time range
```
**Benefícios:** a hierarquia de tempo natural (ano → mês → dia → carimbo de data/hora) permite consultas eficientes em qualquer momento, granularidade, sem análise ou manipulação de datas. O Índice Secundário Global indexa automaticamente todas as leituras usando seus atributos de tempo natural.
### Pedidos de comércio eletrônico com chaves de vários atributos
Monitorar pedidos com várias dimensões
#### Exemplo de código
```
{
TableName: 'Orders',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'orderId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'orderId', AttributeType: 'S' },
{ AttributeName: 'sellerId', AttributeType: 'S' },
{ AttributeName: 'region', AttributeType: 'S' },
{ AttributeName: 'orderDate', AttributeType: 'S' },
{ AttributeName: 'category', AttributeType: 'S' },
{ AttributeName: 'customerId', AttributeType: 'S' },
{ AttributeName: 'orderStatus', AttributeType: 'S' }
],
GlobalSecondaryIndexes: [
{
IndexName: 'SellerRegionIndex',
KeySchema: [
{ AttributeName: 'sellerId', KeyType: 'HASH' },
{ AttributeName: 'region', KeyType: 'HASH' },
{ AttributeName: 'orderDate', KeyType: 'RANGE' },
{ AttributeName: 'category', KeyType: 'RANGE' },
{ AttributeName: 'orderId', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
},
{
IndexName: 'CustomerOrdersIndex',
KeySchema: [
{ AttributeName: 'customerId', KeyType: 'HASH' },
{ AttributeName: 'orderDate', KeyType: 'RANGE' },
{ AttributeName: 'orderStatus', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
}
],
BillingMode: 'PAY_PER_REQUEST'
}
// SellerRegionIndex GSI queries:
// - Orders by seller and region
// - Orders by seller, region, and date
// - Orders by seller, region, date, and category
// CustomerOrdersIndex GSI queries:
// - Customer's orders
// - Customer's orders by date
// - Customer's orders by date and status
```
### Dados de organizações hierárquicas
Hierarquias organizacionais de modelos
#### Exemplo de código
```
{
TableName: 'Employees',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'employeeId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'employeeId', AttributeType: 'S' },
{ AttributeName: 'companyId', AttributeType: 'S' },
{ AttributeName: 'divisionId', AttributeType: 'S' },
{ AttributeName: 'departmentId', AttributeType: 'S' },
{ AttributeName: 'teamId', AttributeType: 'S' },
{ AttributeName: 'skillCategory', AttributeType: 'S' },
{ AttributeName: 'skillLevel', AttributeType: 'S' },
{ AttributeName: 'yearsExperience', AttributeType: 'N' }
],
GlobalSecondaryIndexes: [
{
IndexName: 'OrganizationIndex',
KeySchema: [
{ AttributeName: 'companyId', KeyType: 'HASH' },
{ AttributeName: 'divisionId', KeyType: 'HASH' },
{ AttributeName: 'departmentId', KeyType: 'RANGE' },
{ AttributeName: 'teamId', KeyType: 'RANGE' },
{ AttributeName: 'employeeId', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
},
{
IndexName: 'SkillsIndex',
KeySchema: [
{ AttributeName: 'skillCategory', KeyType: 'HASH' },
{ AttributeName: 'skillLevel', KeyType: 'RANGE' },
{ AttributeName: 'yearsExperience', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'INCLUDE', NonKeyAttributes: ['employeeId', 'name'] }
}
],
BillingMode: 'PAY_PER_REQUEST'
}
// OrganizationIndex GSI query patterns:
// - All employees in company/division
// - Employees in specific department
// - Employees in specific team
// SkillsIndex GSI query patterns:
// - Employees by skill and experience level
```
### Chaves esparsas de vários atributos
Combinar chaves de vários atributos para criar um GSI esparso
#### Exemplo de código
```
{
TableName: 'Products',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'productId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'productId', AttributeType: 'S' },
{ AttributeName: 'categoryId', AttributeType: 'S' },
{ AttributeName: 'subcategoryId', AttributeType: 'S' },
{ AttributeName: 'averageRating', AttributeType: 'N' },
{ AttributeName: 'reviewCount', AttributeType: 'N' }
],
GlobalSecondaryIndexes: [
{
IndexName: 'CategoryIndex',
KeySchema: [
{ AttributeName: 'categoryId', KeyType: 'HASH' },
{ AttributeName: 'subcategoryId', KeyType: 'HASH' },
{ AttributeName: 'productId', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
},
{
IndexName: 'ReviewedProductsIndex',
KeySchema: [
{ AttributeName: 'categoryId', KeyType: 'HASH' },
{ AttributeName: 'averageRating', KeyType: 'RANGE' }, // Optional attribute
{ AttributeName: 'reviewCount', KeyType: 'RANGE' } // Optional attribute
],
Projection: { ProjectionType: 'ALL' }
}
],
BillingMode: 'PAY_PER_REQUEST'
}
// Only products with reviews appear in ReviewedProductsIndex GSI
// Automatic filtering without application logic
// Multi-attribute sort key enables rating and count queries
```
### SaaS e multilocação
Plataforma SaaS multilocatário com isolamento de clientes
#### Exemplo de código
```
// Table design
{
TableName: 'SaasData',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'resourceId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'resourceId', AttributeType: 'S' },
{ AttributeName: 'tenantId', AttributeType: 'S' },
{ AttributeName: 'customerId', AttributeType: 'S' },
{ AttributeName: 'resourceType', AttributeType: 'S' }
],
// GSI with multi-attribute keys for tenant-customer isolation
GlobalSecondaryIndexes: [{
IndexName: 'TenantCustomerIndex',
KeySchema: [
{ AttributeName: 'tenantId', KeyType: 'HASH' },
{ AttributeName: 'customerId', KeyType: 'HASH' },
{ AttributeName: 'resourceType', KeyType: 'RANGE' },
{ AttributeName: 'resourceId', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
}],
BillingMode: 'PAY_PER_REQUEST'
}
// Query GSI: All resources for tenant T001, customer C001
const resources = await docClient.send(new QueryCommand({
TableName: 'SaasData',
IndexName: 'TenantCustomerIndex',
KeyConditionExpression: 'tenantId = :tenant AND customerId = :customer',
ExpressionAttributeValues: {
':tenant': 'T001',
':customer': 'C001'
}
}));
// Query GSI: Specific resource type for tenant/customer
const documents = await docClient.send(new QueryCommand({
TableName: 'SaasData',
IndexName: 'TenantCustomerIndex',
KeyConditionExpression: 'tenantId = :tenant AND customerId = :customer AND resourceType = :type',
ExpressionAttributeValues: {
':tenant': 'T001',
':customer': 'C001',
':type': 'document'
}
}));
```
**Benefícios:** consultas eficientes no contexto locatário-cliente e na organização natural dos dados.
### Transações financeiras
Sistema bancário monitorando transações de contas usando GSIs
#### Exemplo de código
```
// Table design
{
TableName: 'BankTransactions',
// Base table: Simple partition key
KeySchema: [
{ AttributeName: 'transactionId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'transactionId', AttributeType: 'S' },
{ AttributeName: 'accountId', AttributeType: 'S' },
{ AttributeName: 'year', AttributeType: 'S' },
{ AttributeName: 'month', AttributeType: 'S' },
{ AttributeName: 'day', AttributeType: 'S' },
{ AttributeName: 'transactionType', AttributeType: 'S' }
],
GlobalSecondaryIndexes: [
{
IndexName: 'AccountTimeIndex',
KeySchema: [
{ AttributeName: 'accountId', KeyType: 'HASH' },
{ AttributeName: 'year', KeyType: 'RANGE' },
{ AttributeName: 'month', KeyType: 'RANGE' },
{ AttributeName: 'day', KeyType: 'RANGE' },
{ AttributeName: 'transactionId', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
},
{
IndexName: 'TransactionTypeIndex',
KeySchema: [
{ AttributeName: 'accountId', KeyType: 'HASH' },
{ AttributeName: 'transactionType', KeyType: 'RANGE' },
{ AttributeName: 'year', KeyType: 'RANGE' },
{ AttributeName: 'month', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
}
],
BillingMode: 'PAY_PER_REQUEST'
}
// Query AccountTimeIndex GSI: All transactions for account in 2023
const yearTransactions = await docClient.send(new QueryCommand({
TableName: 'BankTransactions',
IndexName: 'AccountTimeIndex',
KeyConditionExpression: 'accountId = :account AND #year = :year',
ExpressionAttributeNames: { '#year': 'year' },
ExpressionAttributeValues: {
':account': 'ACC-12345',
':year': '2023'
}
}));
// Query AccountTimeIndex GSI: Transactions in specific month
const monthTransactions = await docClient.send(new QueryCommand({
TableName: 'BankTransactions',
IndexName: 'AccountTimeIndex',
KeyConditionExpression: 'accountId = :account AND #year = :year AND #month = :month',
ExpressionAttributeNames: { '#year': 'year', '#month': 'month' },
ExpressionAttributeValues: {
':account': 'ACC-12345',
':year': '2023',
':month': '11'
}
}));
// Query TransactionTypeIndex GSI: Deposits in 2023
const deposits = await docClient.send(new QueryCommand({
TableName: 'BankTransactions',
IndexName: 'TransactionTypeIndex',
KeyConditionExpression: 'accountId = :account AND transactionType = :type AND #year = :year',
ExpressionAttributeNames: { '#year': 'year' },
ExpressionAttributeValues: {
':account': 'ACC-12345',
':type': 'deposit',
':year': '2023'
}
}));
```
## Exemplo completo
O exemplo a seguir demonstra chaves de vários atributos, da configuração à limpeza:
### Exemplo de código
```
import {
DynamoDBClient,
CreateTableCommand,
DeleteTableCommand,
waitUntilTableExists
} from "@aws-sdk/client-dynamodb";
import {
DynamoDBDocumentClient,
PutCommand,
QueryCommand
} from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({ region: 'us-west-2' });
const docClient = DynamoDBDocumentClient.from(client);
async function multiAttributeKeysDemo() {
console.log("Starting Multi-Attribute GSI Keys Demo\n");
// Step 1: Create table with GSIs using multi-attribute keys
console.log("1. Creating table with multi-attribute GSI keys...");
await client.send(new CreateTableCommand({
TableName: 'TournamentMatches',
KeySchema: [
{ AttributeName: 'matchId', KeyType: 'HASH' }
],
AttributeDefinitions: [
{ AttributeName: 'matchId', AttributeType: 'S' },
{ AttributeName: 'tournamentId', AttributeType: 'S' },
{ AttributeName: 'region', AttributeType: 'S' },
{ AttributeName: 'round', AttributeType: 'S' },
{ AttributeName: 'bracket', AttributeType: 'S' },
{ AttributeName: 'player1Id', AttributeType: 'S' },
{ AttributeName: 'matchDate', AttributeType: 'S' }
],
GlobalSecondaryIndexes: [
{
IndexName: 'TournamentRegionIndex',
KeySchema: [
{ AttributeName: 'tournamentId', KeyType: 'HASH' },
{ AttributeName: 'region', KeyType: 'HASH' },
{ AttributeName: 'round', KeyType: 'RANGE' },
{ AttributeName: 'bracket', KeyType: 'RANGE' },
{ AttributeName: 'matchId', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
},
{
IndexName: 'PlayerMatchHistoryIndex',
KeySchema: [
{ AttributeName: 'player1Id', KeyType: 'HASH' },
{ AttributeName: 'matchDate', KeyType: 'RANGE' },
{ AttributeName: 'round', KeyType: 'RANGE' }
],
Projection: { ProjectionType: 'ALL' }
}
],
BillingMode: 'PAY_PER_REQUEST'
}));
await waitUntilTableExists({ client, maxWaitTime: 120 }, { TableName: 'TournamentMatches' });
console.log("Table created\n");
// Step 2: Insert tournament matches
console.log("2. Inserting tournament matches...");
const matches = [
{ matchId: 'match-001', tournamentId: 'WINTER2024', region: 'NA-EAST', round: 'FINALS', bracket: 'CHAMPIONSHIP', player1Id: '101', player2Id: '103', matchDate: '2024-01-20', winner: '101', score: '3-1' },
{ matchId: 'match-002', tournamentId: 'WINTER2024', region: 'NA-EAST', round: 'SEMIFINALS', bracket: 'UPPER', player1Id: '101', player2Id: '105', matchDate: '2024-01-18', winner: '101', score: '3-2' },
{ matchId: 'match-003', tournamentId: 'WINTER2024', region: 'NA-WEST', round: 'FINALS', bracket: 'CHAMPIONSHIP', player1Id: '102', player2Id: '104', matchDate: '2024-01-20', winner: '102', score: '3-2' },
{ matchId: 'match-004', tournamentId: 'SPRING2024', region: 'NA-EAST', round: 'QUARTERFINALS', bracket: 'UPPER', player1Id: '101', player2Id: '108', matchDate: '2024-03-15', winner: '101', score: '3-0' }
];
for (const match of matches) {
await docClient.send(new PutCommand({ TableName: 'TournamentMatches', Item: match }));
}
console.log(`Inserted ${matches.length} tournament matches\n`);
// Step 3: Query GSI with multi-attribute partition key
console.log("3. Query TournamentRegionIndex GSI: WINTER2024/NA-EAST matches");
const gsiQuery1 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'TournamentRegionIndex',
KeyConditionExpression: 'tournamentId = :tournament AND #region = :region',
ExpressionAttributeNames: { '#region': 'region' },
ExpressionAttributeValues: { ':tournament': 'WINTER2024', ':region': 'NA-EAST' }
}));
console.log(` Found ${gsiQuery1.Items.length} matches:`);
gsiQuery1.Items.forEach(match => {
console.log(` ${match.round} - ${match.bracket} - ${match.winner} won`);
});
// Step 4: Query GSI with multi-attribute sort key
console.log("\n4. Query PlayerMatchHistoryIndex GSI: All matches for Player 101");
const gsiQuery2 = await docClient.send(new QueryCommand({
TableName: 'TournamentMatches',
IndexName: 'PlayerMatchHistoryIndex',
KeyConditionExpression: 'player1Id = :player',
ExpressionAttributeValues: { ':player': '101' }
}));
console.log(` Found ${gsiQuery2.Items.length} matches for Player 101:`);
gsiQuery2.Items.forEach(match => {
console.log(` ${match.tournamentId}/${match.region} - ${match.matchDate} - ${match.round}`);
});
console.log("\nDemo complete");
console.log("No synthetic keys needed - GSIs use native attributes automatically");
}
async function cleanup() {
console.log("Deleting table...");
await client.send(new DeleteTableCommand({ TableName: 'TournamentMatches' }));
console.log("Table deleted");
}
// Run demo
multiAttributeKeysDemo().catch(console.error);
// Uncomment to cleanup:
// cleanup().catch(console.error);
```
**Estrutura de código mínima**
### Exemplo de código
```
// 1. Create table with GSI using multi-attribute keys
await client.send(new CreateTableCommand({
TableName: 'MyTable',
KeySchema: [
{ AttributeName: 'id', KeyType: 'HASH' } // Simple base table PK
],
AttributeDefinitions: [
{ AttributeName: 'id', AttributeType: 'S' },
{ AttributeName: 'attr1', AttributeType: 'S' },
{ AttributeName: 'attr2', AttributeType: 'S' },
{ AttributeName: 'attr3', AttributeType: 'S' },
{ AttributeName: 'attr4', AttributeType: 'S' }
],
GlobalSecondaryIndexes: [{
IndexName: 'MyGSI',
KeySchema: [
{ AttributeName: 'attr1', KeyType: 'HASH' }, // GSI PK attribute 1
{ AttributeName: 'attr2', KeyType: 'HASH' }, // GSI PK attribute 2
{ AttributeName: 'attr3', KeyType: 'RANGE' }, // GSI SK attribute 1
{ AttributeName: 'attr4', KeyType: 'RANGE' } // GSI SK attribute 2
],
Projection: { ProjectionType: 'ALL' }
}],
BillingMode: 'PAY_PER_REQUEST'
}));
// 2. Insert items with native attributes (no concatenation needed for GSI)
await docClient.send(new PutCommand({
TableName: 'MyTable',
Item: {
id: 'item-001',
attr1: 'value1',
attr2: 'value2',
attr3: 'value3',
attr4: 'value4',
// ... other attributes
}
}));
// 3. Query GSI with all partition key attributes
await docClient.send(new QueryCommand({
TableName: 'MyTable',
IndexName: 'MyGSI',
KeyConditionExpression: 'attr1 = :v1 AND attr2 = :v2',
ExpressionAttributeValues: {
':v1': 'value1',
':v2': 'value2'
}
}));
// 4. Query GSI with sort key attributes (left-to-right)
await docClient.send(new QueryCommand({
TableName: 'MyTable',
IndexName: 'MyGSI',
KeyConditionExpression: 'attr1 = :v1 AND attr2 = :v2 AND attr3 = :v3',
ExpressionAttributeValues: {
':v1': 'value1',
':v2': 'value2',
':v3': 'value3'
}
}));
// Note: If any attribute name is a DynamoDB reserved keyword, use ExpressionAttributeNames:
// KeyConditionExpression: 'attr1 = :v1 AND #attr2 = :v2'
// ExpressionAttributeNames: { '#attr2': 'attr2' }
```
## Recursos adicionais
+ [Práticas recomendadas do DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/best-practices.html)
+ [Trabalho com tabelas e dados](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithTables.html)
+ [Índices secundários globais](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.html)
+ [Operações de consulta e verificação](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html)
# 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).
# Detectar e corrigir violações de chave de índice no DynamoDB
Durante a fase de preenchimento em segundo plano da criação de um índice secundário global, o Amazon DynamoDB examina cada item na tabela para determinar se ele está qualificado para inclusão no índice. Alguns itens podem não ser qualificados, pois causariam violações de chave de índice. Nesses casos, os itens permanecerão na tabela, mas o índice não terá uma entrada correspondente para eles.
Uma *infração na chave do índice* ocorre nas seguintes situações:
+ Há uma inconsistência de tipo de dados entre um valor de atributo e o tipo de dados do esquema de chaves de índice. Por exemplo, suponha que um dos itens na tabela `GameScores` tivesse um valor `TopScore` do tipo `String`. Se você adicionasse um `TopScore` com uma chave de partição de do tipo `Number`, o item da tabela violaria a chave de índice.
+ Um valor de atributo da tabela excede o comprimento máximo para um atributo de chave de índice. O comprimento máximo de uma chave de partição é 2048 bytes, enquanto o comprimento máximo de uma chave de classificação é 1024 bytes. Se qualquer um dos valores de atributo correspondente na tabela exceder esses limites, o item da tabela violará a chave de índice.
**nota**
Se um valor de atributo binário ou de string for definido para um atributo usado como uma chave de índice, o valor do atributo deverá ter um tamanho maior que zero. Caso contrário, o item da tabela violaria a chave de índice.
Esta ferramenta não sinaliza esta infração na chave do índice neste momento.
Se uma infração na chave do índice ocorrer, a fase de preenchimento em segundo plano continuará sem interrupção. No entanto, os itens infratores não são incluídos no índice. Concluída a fase de aterramento, todas as gravações em itens que violam o esquema de chaves do novo índice serão rejeitadas.
Para identificar e corrigir os valores de atributos em uma tabela que violam uma chave de índice, use a ferramenta Violation Detector. Para executar o Violation Detector, crie um arquivo de configuração que especifique o nome de uma tabela a ser verificada, os nomes e os tipos de dados da chave de partição do índice secundário global e a chave de classificação, bem como quais ações deverão ser realizadas se violações de chave de índice forem encontradas. O Violation Detector pode ser executado em um destes dois diferentes modos:
+ **Modo de detecção**: detecta violações de chave de índice. Use o modo de detecção para informar os itens na tabela que causariam violações de chaves em um índice secundário global. (Você tem a opção de solicitar que esses itens de tabela infratores sejam excluídos imediatamente quando forem encontrados.) A saída do modo de detecção é gravada em um arquivo, que você pode usar para análise posterior.
+ **Modo de correção**: corrige violações de chaves de índice. No modo de correção, o Violation Detector lê um arquivo de entrada com o mesmo formato que o arquivo de saída do modo de detecção. O modo de correção lê os registros do arquivo de entrada e, para cada registro, ele exclui ou atualiza os itens correspondentes na tabela. (Observe que, se você optar por atualizar os itens, deverá editar o arquivo de entrada e definir os valores apropriados para essas atualizações.)
## Baixar e executar o Violation Detector
O Violation Detector está disponível como um arquivo Java executável (arquivo `.jar`) e pode ser executado em computadores Windows, Mac ou Linux. O Violation Detector requer o Java 1.7 (ou posterior) e o Apache Maven.
+ [Baixar o Violation Detector do GitHub](https://github.com/awslabs/dynamodb-online-index-violation-detector)
Siga as instruções no arquivo `README.md` para fazer download e instalar o Violation Detector usando o Maven.
Para iniciar o Violation Detector, acesse o diretório no qual você compilou o arquivo `ViolationDetector.java` e insira o seguinte comando:
```
java -jar ViolationDetector.jar [options]
```
A linha de comando do Violation Detector aceita as seguintes opções:
+ `-h | --help`: imprime um resumo de uso e opções do Violation Detector.
+ `-p | --configFilePath` `value`: o nome totalmente qualificado de um arquivo de configuração do Violation Detector. Para obter mais informações, consulte [O arquivo de configuração do Violation Detector](#GSI.OnlineOps.ViolationDetection.ConfigFile).
+ `-t | --detect` `value`: detecta violações de chave de índice na tabela e as grava no arquivo de saída do Violation Detector. Se o valor desse parâmetro for definido como `keep`, os itens com violações de chave não serão modificados. Se o valor for definido como `delete`, os itens com violações de chave serão excluídos da tabela.
+ `-c | --correct` `value`: lê violações de chave de índice de um arquivo de entrada e toma ações corretivas nos itens da tabela. Se o valor desse parâmetro for definido como `update`, os itens com violações de chave serão atualizados com valores novos não infratores. Se o valor for definido como `delete`, os itens com violações de chave serão excluídos da tabela.
## O arquivo de configuração do Violation Detector
Em tempo de execução, a ferramenta Violation Detector requer um arquivo de configuração Os parâmetros nesse arquivo determinam quais recursos do DynamoDB o Violation Detector pode acessar e quanto throughput provisionado ele pode consumir. A tabela a seguir descreve esses parâmetros.
****
| Nome do parâmetro | Descrição | Obrigatório? |
| --- | --- | --- |
| `awsCredentialsFile` | O nome totalmente qualificado de um arquivo que contém suas credenciais da AWS. O arquivo de credenciais deve estar no seguinte formato: accessKey = access_key_id_goes_here
secretKey = secret_key_goes_here
| Sim |
| `dynamoDBRegion` | A região da AWS na qual a tabela reside. Por exemplo: `us-west-2`. | Sim |
| `tableName` | O nome da tabela do DynamoDB a ser verificada. | Sim |
| `gsiHashKeyName` | O nome da chave de partição do índice. | Sim |
| `gsiHashKeyType` | O tipo de dados da chave de partição do índice: `String`, `Number` ou `Binary` `S \| N \| B` | Sim |
| `gsiRangeKeyName` | O nome da chave de classificação do índice. Não especifique esse parâmetro se o índice tiver apenas uma chave primária simples (chave de partição). | Não |
| `gsiRangeKeyType` | O tipo de dados da chave de classificação do índice: `String`, `Number` ou `Binary` `S \| N \| B` Não especifique esse parâmetro se o índice tiver apenas uma chave primária simples (chave de partição). | Não |
| `recordDetails` | Se você deseja gravar os detalhes completos das violações de chaves de índice no arquivo de saída. Se a opção for definida como `true` (o padrão), todas as informações sobre os itens infratores serão relatadas. Se definido como `false`, apenas o número de violações será relatado. | Não |
| `recordGsiValueInViolationRecord` | Se você deseja gravar os valores das chaves de índice infratoras no arquivo de saída. Se a opção for definida como `true` (padrão), os valores das chaves serão relatados. Se definido como `false`, os valores das chave não serão relatados. | Não |
| `detectionOutputPath` | O caminho completo do arquivo de saída do Violation Detector. Esse parâmetro oferece suporte à gravação em um diretório local ou no Amazon Simple Storage Service (Amazon S3). Veja os exemplos a seguir: `detectionOutputPath = ``//local/path/filename.csv` `detectionOutputPath = ``s3://bucket/filename.csv` As informações no arquivo de saída são mostradas no formato CSV (valores separados por vírgula). Se você não definir `detectionOutputPath`, o arquivo de saída se chamará `violation_detection.csv` e será gravado no seu diretório de trabalho atual. | Não |
| `numOfSegments` | O número de segmentos de verificação paralela a serem usados quando o Violation Detector verificar a tabela. O valor padrão é 1, o que significa que a tabela é verificada de maneira sequencial. Se o valor for 2 ou superior, o Violation Detector dividirá a tabela no número correspondente de segmentos lógicos e em um número igual de threads de verificação. A configuração máxima para `numOfSegments` é 4096.Para tabelas maiores, uma verificação paralela é geralmente mais rápida do que uma verificação sequencial. Além disso, se a tabela for grande o suficiente para abranger várias partições, uma verificação paralela distribui sua atividade de leitura uniformemente entre essas várias partições.Para obter mais informações sobre verificações paralelas no DynamoDB, consulte [Verificar em paralelo](Scan.md#Scan.ParallelScan). | Não |
| `numOfViolations` | O limite superior de violações de chaves de índice a serem gravadas no arquivo de saída. Se definido como `-1` (o padrão), a tabela inteira é verificada. Se definido como um número inteiro positivo, o Violation Detector será interrompido quando encontrar esse número de violações. | Não |
| `numOfRecords` | O número de itens na tabela a ser verificada. Se definido como -1 (o padrão), a tabela inteira é verificada. Se definido como um número inteiro positivo, o Violation Detector será interrompido após verificar o mesmo número de itens na tabela. | Não |
| `readWriteIOPSPercent` | Regula a porcentagem de unidades de capacidade de leitura provisionada que são consumidas durante a verificação de tabela. Os valores válidos variam de `1` até `100`. O valor padrão (`25`) significa que o Violation Detector não consumirá mais de 25% do throughput provisionado da tabela. | Não |
| `correctionInputPath` | O caminho completo do arquivo de entrada de correção do Violation Detector. Se você executar o Violation Detector no modo de correção, o conteúdo desse arquivo será usado para modificar ou excluir os itens de dados na tabela que violam o índice secundário global. O formato do arquivo `correctionInputPath` é o mesmo que o do arquivo `detectionOutputPath`. Isso permite que você processe a saída do modo de detecção como uma entrada no modo de correção. | Não |
| `correctionOutputPath` | O caminho completo do arquivo de saída de correção do Violation Detector. Esse arquivo será criado somente se houver erros de atualização. Esse parâmetro oferece suporte à gravação em um diretório local ou no Amazon S3. Veja os exemplos a seguir: `correctionOutputPath = ``//local/path/filename.csv` `correctionOutputPath = ``s3://bucket/filename.csv` As informações no arquivo de saída são mostradas no formato CSV. Se você não definir `correctionOutputPath`, o arquivo de saída se chamará `violation_update_errors.csv` e será gravado no seu diretório de trabalho atual. | Não |
## Detecção
Para detectar violações de chave de índice, use o Violation Detector com a opção de linha de comando `--detect`. Para mostrar como essa opção funciona, considere a tabela `ProductCatalog`. Veja a seguir uma lista de itens na tabela. Apenas a chave primária (`Id`) e o atributo `Price` são mostrados.
****
| ID (chave primária) | Preço |
| --- | --- |
| 101 | 5 |
| 102 | 20 |
| 103 | 200 |
| 201 | 100 |
| 202 | 200 |
| 203 | 300 |
| 204 | 400 |
| 205 | 500 |
Todos os valores para `Price` são do tipo `Number`. No entanto, como o DynamoDB não tem esquema, é possível adicionar um item com um não numérico `Price`. Por exemplo, suponha que adicionemos outro item à tabela `ProductCatalog`:
****
| ID (chave primária) | Preço |
| --- | --- |
| 999 | "Hello" |
Agora, a tabela tem um total de nove itens.
Agora você adiciona um novo índice secundário global à tabela: `PriceIndex`. A chave primária desse índice é uma chave de partição, `Price`, do tipo `Number`. Depois que o índice tiver sido construído, ele conterá oito itens, mas a tabela `ProductCatalog` tem nove itens. O motivo dessa discrepância é que o valor `"Hello"` é do tipo `String`, mas `PriceIndex` tem uma chave primária do tipo `Number`. O valor de `String` viola a chave do índice secundário global e, por isso, não está presente no índice.
Para usar o Violation Detector nesse cenário, você primeiro deve criar um arquivo de configuração como este.
```
# Properties file for violation detection tool configuration.
# Parameters that are not specified will use default values.
awsCredentialsFile = /home/alice/credentials.txt
dynamoDBRegion = us-west-2
tableName = ProductCatalog
gsiHashKeyName = Price
gsiHashKeyType = N
recordDetails = true
recordGsiValueInViolationRecord = true
detectionOutputPath = ./gsi_violation_check.csv
correctionInputPath = ./gsi_violation_check.csv
numOfSegments = 1
readWriteIOPSPercent = 40
```
Em seguida, execute o Violation Detector como no exemplo a seguir.
```
$ java -jar ViolationDetector.jar --configFilePath config.txt --detect keep
Violation detection started: sequential scan, Table name: ProductCatalog, GSI name: PriceIndex
Progress: Items scanned in total: 9, Items scanned by this thread: 9, Violations found by this thread: 1, Violations deleted by this thread: 0
Violation detection finished: Records scanned: 9, Violations found: 1, Violations deleted: 0, see results at: ./gsi_violation_check.csv
```
Se o parâmetro de configuração `recordDetails` for definido como `true`, o Violation Detector gravará os detalhes de cada infração no arquivo de saída, como no exemplo a seguir.
```
Table Hash Key,GSI Hash Key Value,GSI Hash Key Violation Type,GSI Hash Key Violation Description,GSI Hash Key Update Value(FOR USER),Delete Blank Attributes When Updating?(Y/N)
999,"{""S"":""Hello""}",Type Violation,Expected: N Found: S,,
```
O arquivo de saída está no formato CSV. A primeira linha do arquivo é um cabeçalho, seguida de um registro por item que viola a chave de índice. Os campos desses registros infratores são os seguintes:
+ **Table Hash Key** (Chave de hash da tabela): o valor da chave de partição do item na tabela.
+ **Table Range Key** (Chave de classificação da tabela): o valor da chave de classificação do item na tabela.
+ **GSI Hash Key Value** (Valor da chave de hash do GSI): o valor da chave de partição do índice secundário global.
+ **GSI Hash Key Violation Type** (Tipo de violação da chave de hash do GSI): `Type Violation` ou `Size Violation`.
+ **GSI Hash Key Violation Description** (Descrição da violação da chave de hash do GSI): a causa da infração.
+ **GSI Hash Key Update Value(FORUSER)** (Valor da atualização da chave de hash do GSI [PARA USUÁRIO]): no modo de correção, um novo valor fornecido pelo usuário para o atributo.
+ **GSI Hash Key Value** (Valor da chave de hash do GSI): o valor da chave de classificação do índice secundário global.
+ **GSI Range Key Violation Type** (Tipo de violação da chave de intervalo do GSI: `Type Violation` ou `Size Violation`.
+ **GSI Range Key Violation Description** (Descrição da violação da chave de intervalo do GSI): a causa da infração.
+ **GSI Range Key Update Value(FOR USER)** (Valor da atualização da chave de intervalo do GSI [PARA USUÁRIO]: no modo de correção, um novo valor fornecido pelo usuário para o atributo.
+ **Delete Blank Attribute When Updating(Y/N)** (Excluir atributo em branco ao atualizar[S/N]): no modo de correção, determina se o item infrator deve ser excluído (Y) ou mantido (N) na tabela, mas apenas se algum dos seguintes campos estiver em branco:
+ `GSI Hash Key Update Value(FOR USER)`
+ `GSI Range Key Update Value(FOR USER)`
Se qualquer um desses campos não estiver em branco, `Delete Blank Attribute When Updating(Y/N)` não terá efeito.
**nota**
O formato de saída pode variar dependendo do arquivo de configuração e das opções da linha de comando. Por exemplo, se a tabela tiver uma chave primária simples (sem uma chave de classificação), nenhum campo de chave de classificação estará presente na saída.
Os registros de infração no arquivo podem não estar na ordem classificada.
## Correção
Para corrigir violações de chave de índice, use o Violation Detector com a opção de linha de comando `--correct`. No modo de correção, o Violation Detector lê o arquivo de entrada especificado pelo parâmetro `correctionInputPath`. Esse arquivo tem o mesmo formato que o arquivo `detectionOutputPath` e, portanto, você pode usar a saída da detecção como a entrada para a correção.
O Violation Detector fornece duas maneiras diferentes para corrigir violações de chave de índice:
+ **Excluir violações**: exclua os itens da tabela que possuem valores de atributo infratores.
+ **Atualizar violações**: atualize os itens da tabela substituindo os atributos infratores por valores não infratores.
Em ambos os casos, você pode usar o arquivo de saída do modo de detecção como uma entrada para o modo de correção.
Continuando com o exemplo de `ProductCatalog`, suponha que queiramos excluir o item infrator da tabela. Para fazer isso, use a seguinte linha de comando:
```
$ java -jar ViolationDetector.jar --configFilePath config.txt --correct delete
```
Neste ponto, você será solicitado a confirmar se deseja excluir os itens infratores.
```
Are you sure to delete all violations on the table?y/n
y
Confirmed, will delete violations on the table...
Violation correction from file started: Reading records from file: ./gsi_violation_check.csv, will delete these records from table.
Violation correction from file finished: Violations delete: 1, Violations Update: 0
```
Agora, tanto `ProductCatalog` quanto `PriceIndex` têm o mesmo número de itens.
# Como trabalhar com índices secundários globais: Java
Você pode usar a API de documentos do AWS SDK para Java para criar uma tabela do Amazon DynamoDB com um ou mais índices secundários globais na tabela e executar consultas usando os índices.
Veja a seguir as etapas comuns para as operações de tabela.
1. Crie uma instância da classe `DynamoDB`.
1. Forneça os parâmetros obrigatórios e opcionais para a operação, criando os objetos de solicitação correspondentes.
1. Chame o método apropriado fornecido pelo cliente que você criou na etapa anterior.
**Topics**
+ [Criar uma tabela com um índice secundário global](#GSIJavaDocumentAPI.CreateTableWithIndex)
+ [Descrever uma tabela com um índice secundário global](#GSIJavaDocumentAPI.DescribeTableWithIndex)
+ [Consultar um índice secundário global](#GSIJavaDocumentAPI.QueryAnIndex)
+ [Exemplo: índices secundários globais que usam a API de documento do AWS SDK para Java](GSIJavaDocumentAPI.Example.md)
## Criar uma tabela com um índice secundário global
Você pode criar índices secundários globais ao mesmo tempo em que cria uma tabela. Para fazer isso, use `CreateTable` e forneça suas especificações para um ou mais índices secundários globais. O exemplo de código Java a seguir cria uma tabela para armazenar informações sobre dados climáticos. A chave de partição é `Location` e a chave de classificação é `Date`. Um índice secundário global chamado `PrecipIndex` permite acesso rápido aos dados de precipitação de vários locais.
Veja a seguir as etapas necessárias para criar uma tabela com um índice secundário global usando a API de documentos do DynamoDB.
1. Crie uma instância da classe `DynamoDB`.
1. Crie uma instância da classe `CreateTableRequest` para fornecer as informações solicitadas.
Você deve fornecer o nome da tabela, sua chave primária e os valores de throughput provisionado. Para o índice secundário global, você deve fornecer o nome do índice, suas configurações de throughput provisionado, as definições de atributo da chave de classificação do índice, o esquema de chaves do índice e a projeção do atributo.
1. Chame o método `createTable`, fornecendo o objeto de solicitação como um parâmetro.
O exemplo de código Java a seguir demonstra as etapas anteriores. O código cria uma tabela (`WeatherData`) com um índice secundário global (`PrecipIndex`). A chave de partição do índice é `Date` e a chave de classificação é `Precipitation`. Todos os atributos da tabela estão projetados no índice. Os usuários podem consultar esse índice para obter dados climáticos de uma data específica, opcionalmente, classificar os dados por quantidade de precipitação.
Como `Precipitation` não é um atributo de chave para a tabela, ele não é necessário. No entanto, os itens de `WeatherData` sem `Precipitation` não aparecem no `PrecipIndex`.
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);
// Attribute definitions
ArrayList attributeDefinitions = new ArrayList();
attributeDefinitions.add(new AttributeDefinition()
.withAttributeName("Location")
.withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition()
.withAttributeName("Date")
.withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition()
.withAttributeName("Precipitation")
.withAttributeType("N"));
// Table key schema
ArrayList tableKeySchema = new ArrayList();
tableKeySchema.add(new KeySchemaElement()
.withAttributeName("Location")
.withKeyType(KeyType.HASH)); //Partition key
tableKeySchema.add(new KeySchemaElement()
.withAttributeName("Date")
.withKeyType(KeyType.RANGE)); //Sort key
// PrecipIndex
GlobalSecondaryIndex precipIndex = new GlobalSecondaryIndex()
.withIndexName("PrecipIndex")
.withProvisionedThroughput(new ProvisionedThroughput()
.withReadCapacityUnits((long) 10)
.withWriteCapacityUnits((long) 1))
.withProjection(new Projection().withProjectionType(ProjectionType.ALL));
ArrayList indexKeySchema = new ArrayList();
indexKeySchema.add(new KeySchemaElement()
.withAttributeName("Date")
.withKeyType(KeyType.HASH)); //Partition key
indexKeySchema.add(new KeySchemaElement()
.withAttributeName("Precipitation")
.withKeyType(KeyType.RANGE)); //Sort key
precipIndex.setKeySchema(indexKeySchema);
CreateTableRequest createTableRequest = new CreateTableRequest()
.withTableName("WeatherData")
.withProvisionedThroughput(new ProvisionedThroughput()
.withReadCapacityUnits((long) 5)
.withWriteCapacityUnits((long) 1))
.withAttributeDefinitions(attributeDefinitions)
.withKeySchema(tableKeySchema)
.withGlobalSecondaryIndexes(precipIndex);
Table table = dynamoDB.createTable(createTableRequest);
System.out.println(table.getDescription());
```
Você deve aguardar até que o DynamoDB crie a tabela e defina o status dessa tabela como `ACTIVE`. Depois disso, você poderá começar a inserir itens de dados na tabela.
## Descrever uma tabela com um índice secundário global
Para obter mais informações sobre índices secundários globais em uma tabela, use `DescribeTable`. Para cada índice, você pode acessar seu nome, esquema de chaves e atributos projetados.
Veja a seguir as etapas necessárias para acessar informações de índice secundário global em uma tabela.
1. Crie uma instância da classe `DynamoDB`.
1. Crie uma instância da classe `Table` para representar o índice com o qual você deseja trabalhar.
1. Chame o método `describe` no objeto `Table`.
O exemplo de código Java a seguir demonstra as etapas anteriores.
**Example**
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);
Table table = dynamoDB.getTable("WeatherData");
TableDescription tableDesc = table.describe();
Iterator gsiIter = tableDesc.getGlobalSecondaryIndexes().iterator();
while (gsiIter.hasNext()) {
GlobalSecondaryIndexDescription gsiDesc = gsiIter.next();
System.out.println("Info for index "
+ gsiDesc.getIndexName() + ":");
Iterator kseIter = gsiDesc.getKeySchema().iterator();
while (kseIter.hasNext()) {
KeySchemaElement kse = kseIter.next();
System.out.printf("\t%s: %s\n", kse.getAttributeName(), kse.getKeyType());
}
Projection projection = gsiDesc.getProjection();
System.out.println("\tThe projection type is: "
+ projection.getProjectionType());
if (projection.getProjectionType().toString().equals("INCLUDE")) {
System.out.println("\t\tThe non-key projected attributes are: "
+ projection.getNonKeyAttributes());
}
}
```
## Consultar um índice secundário global
Você pode usar `Query` em um índice secundário global de forma semelhante ao uso de `Query` em uma tabela. Você precisa especificar o nome do índice, os critérios de consulta da chave de partição e da chave de classificação (se houver) do índice, e os atributos que você deseja retornar. Neste exemplo, o índice é `PrecipIndex`, que tem uma chave de partição `Date` e uma chave de classificação `Precipitation`. A consulta de índice retorna todos os dados climáticos de uma data específica, na qual a precipitação é maior que zero.
Veja a seguir as etapas necessárias para consultar um índice secundário global usando a API de documentos do AWS SDK para Java.
1. Crie uma instância da classe `DynamoDB`.
1. Crie uma instância da classe `Table` para representar o índice com o qual você deseja trabalhar.
1. Crie uma instância da classe `Index` para o índice que deseja consultar.
1. Chame o método `query` no objeto `Index`.
O nome do atributo `Date` é uma palavra reservada do DynamoDB. Portanto, use um nome de atributo de expressão como um espaço reservado na `KeyConditionExpression`.
O exemplo de código Java a seguir demonstra as etapas anteriores.
**Example**
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);
Table table = dynamoDB.getTable("WeatherData");
Index index = table.getIndex("PrecipIndex");
QuerySpec spec = new QuerySpec()
.withKeyConditionExpression("#d = :v_date and Precipitation = :v_precip")
.withNameMap(new NameMap()
.with("#d", "Date"))
.withValueMap(new ValueMap()
.withString(":v_date","2013-08-10")
.withNumber(":v_precip",0));
ItemCollection items = index.query(spec);
Iterator- iter = items.iterator();
while (iter.hasNext()) {
System.out.println(iter.next().toJSONPretty());
}
```
# Exemplo: índices secundários globais que usam a API de documento do AWS SDK para Java
O código Java de exemplo a seguir mostra como trabalhar com índices secundários globais. O exemplo cria uma tabela chamada `Issues`, que pode ser usada em um sistema de controle de bugs simples para desenvolvimento de software. A chave de partição é `IssueId` e a chave de classificação é `Title`. Há três índices secundários globais nessa tabela:
+ `CreateDateIndex`: a chave de partição é `CreateDate` e a chave de classificação é `IssueId`. Além das chaves da tabela, os atributos `Description` e `Status` são projetados no índice.
+ `TitleIndex`: a chave de partição é `Title` e a chave de classificação é `IssueId`. Nenhum outro atributo além das chaves da tabela são projetos no índice.
+ `DueDateIndex`: a chave de partição é `DueDate` e não há chave de classificação. Todos os atributos da tabela estão projetados no índice.
Depois que a tabela `Issues` é criada, o programa carrega a tabela com os dados que representam relatórios de bugs do software. Ele consulta os dados usando os índices secundários globais. Por fim, o programa exclui a tabela `Issues`.
Para obter instruções passo a passo sobre como testar o exemplo a seguir, consulte [Exemplos de código Java](CodeSamples.Java.md).
**Example**
```
package com.amazonaws.codesamples.document;
import java.util.ArrayList;
import java.util.Iterator;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDB;
import com.amazonaws.services.dynamodbv2.AmazonDynamoDBClientBuilder;
import com.amazonaws.services.dynamodbv2.document.DynamoDB;
import com.amazonaws.services.dynamodbv2.document.Index;
import com.amazonaws.services.dynamodbv2.document.Item;
import com.amazonaws.services.dynamodbv2.document.ItemCollection;
import com.amazonaws.services.dynamodbv2.document.QueryOutcome;
import com.amazonaws.services.dynamodbv2.document.Table;
import com.amazonaws.services.dynamodbv2.document.spec.QuerySpec;
import com.amazonaws.services.dynamodbv2.document.utils.ValueMap;
import com.amazonaws.services.dynamodbv2.model.AttributeDefinition;
import com.amazonaws.services.dynamodbv2.model.CreateTableRequest;
import com.amazonaws.services.dynamodbv2.model.GlobalSecondaryIndex;
import com.amazonaws.services.dynamodbv2.model.KeySchemaElement;
import com.amazonaws.services.dynamodbv2.model.KeyType;
import com.amazonaws.services.dynamodbv2.model.Projection;
import com.amazonaws.services.dynamodbv2.model.ProvisionedThroughput;
public class DocumentAPIGlobalSecondaryIndexExample {
static AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
static DynamoDB dynamoDB = new DynamoDB(client);
public static String tableName = "Issues";
public static void main(String[] args) throws Exception {
createTable();
loadData();
queryIndex("CreateDateIndex");
queryIndex("TitleIndex");
queryIndex("DueDateIndex");
deleteTable(tableName);
}
public static void createTable() {
// Attribute definitions
ArrayList attributeDefinitions = new ArrayList();
attributeDefinitions.add(new AttributeDefinition().withAttributeName("IssueId").withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition().withAttributeName("Title").withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition().withAttributeName("CreateDate").withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition().withAttributeName("DueDate").withAttributeType("S"));
// Key schema for table
ArrayList tableKeySchema = new ArrayList();
tableKeySchema.add(new KeySchemaElement().withAttributeName("IssueId").withKeyType(KeyType.HASH)); // Partition
// key
tableKeySchema.add(new KeySchemaElement().withAttributeName("Title").withKeyType(KeyType.RANGE)); // Sort
// key
// Initial provisioned throughput settings for the indexes
ProvisionedThroughput ptIndex = new ProvisionedThroughput().withReadCapacityUnits(1L)
.withWriteCapacityUnits(1L);
// CreateDateIndex
GlobalSecondaryIndex createDateIndex = new GlobalSecondaryIndex().withIndexName("CreateDateIndex")
.withProvisionedThroughput(ptIndex)
.withKeySchema(new KeySchemaElement().withAttributeName("CreateDate").withKeyType(KeyType.HASH), // Partition
// key
new KeySchemaElement().withAttributeName("IssueId").withKeyType(KeyType.RANGE)) // Sort
// key
.withProjection(
new Projection().withProjectionType("INCLUDE").withNonKeyAttributes("Description", "Status"));
// TitleIndex
GlobalSecondaryIndex titleIndex = new GlobalSecondaryIndex().withIndexName("TitleIndex")
.withProvisionedThroughput(ptIndex)
.withKeySchema(new KeySchemaElement().withAttributeName("Title").withKeyType(KeyType.HASH), // Partition
// key
new KeySchemaElement().withAttributeName("IssueId").withKeyType(KeyType.RANGE)) // Sort
// key
.withProjection(new Projection().withProjectionType("KEYS_ONLY"));
// DueDateIndex
GlobalSecondaryIndex dueDateIndex = new GlobalSecondaryIndex().withIndexName("DueDateIndex")
.withProvisionedThroughput(ptIndex)
.withKeySchema(new KeySchemaElement().withAttributeName("DueDate").withKeyType(KeyType.HASH)) // Partition
// key
.withProjection(new Projection().withProjectionType("ALL"));
CreateTableRequest createTableRequest = new CreateTableRequest().withTableName(tableName)
.withProvisionedThroughput(
new ProvisionedThroughput().withReadCapacityUnits((long) 1).withWriteCapacityUnits((long) 1))
.withAttributeDefinitions(attributeDefinitions).withKeySchema(tableKeySchema)
.withGlobalSecondaryIndexes(createDateIndex, titleIndex, dueDateIndex);
System.out.println("Creating table " + tableName + "...");
dynamoDB.createTable(createTableRequest);
// Wait for table to become active
System.out.println("Waiting for " + tableName + " to become ACTIVE...");
try {
Table table = dynamoDB.getTable(tableName);
table.waitForActive();
} catch (InterruptedException e) {
e.printStackTrace();
}
}
public static void queryIndex(String indexName) {
Table table = dynamoDB.getTable(tableName);
System.out.println("\n***********************************************************\n");
System.out.print("Querying index " + indexName + "...");
Index index = table.getIndex(indexName);
ItemCollection items = null;
QuerySpec querySpec = new QuerySpec();
if (indexName == "CreateDateIndex") {
System.out.println("Issues filed on 2013-11-01");
querySpec.withKeyConditionExpression("CreateDate = :v_date and begins_with(IssueId, :v_issue)")
.withValueMap(new ValueMap().withString(":v_date", "2013-11-01").withString(":v_issue", "A-"));
items = index.query(querySpec);
} else if (indexName == "TitleIndex") {
System.out.println("Compilation errors");
querySpec.withKeyConditionExpression("Title = :v_title and begins_with(IssueId, :v_issue)")
.withValueMap(
new ValueMap().withString(":v_title", "Compilation error").withString(":v_issue", "A-"));
items = index.query(querySpec);
} else if (indexName == "DueDateIndex") {
System.out.println("Items that are due on 2013-11-30");
querySpec.withKeyConditionExpression("DueDate = :v_date")
.withValueMap(new ValueMap().withString(":v_date", "2013-11-30"));
items = index.query(querySpec);
} else {
System.out.println("\nNo valid index name provided");
return;
}
Iterator
- iterator = items.iterator();
System.out.println("Query: printing results...");
while (iterator.hasNext()) {
System.out.println(iterator.next().toJSONPretty());
}
}
public static void deleteTable(String tableName) {
System.out.println("Deleting table " + tableName + "...");
Table table = dynamoDB.getTable(tableName);
table.delete();
// Wait for table to be deleted
System.out.println("Waiting for " + tableName + " to be deleted...");
try {
table.waitForDelete();
} catch (InterruptedException e) {
e.printStackTrace();
}
}
public static void loadData() {
System.out.println("Loading data into table " + tableName + "...");
// IssueId, Title,
// Description,
// CreateDate, LastUpdateDate, DueDate,
// Priority, Status
putItem("A-101", "Compilation error", "Can't compile Project X - bad version number. What does this mean?",
"2013-11-01", "2013-11-02", "2013-11-10", 1, "Assigned");
putItem("A-102", "Can't read data file", "The main data file is missing, or the permissions are incorrect",
"2013-11-01", "2013-11-04", "2013-11-30", 2, "In progress");
putItem("A-103", "Test failure", "Functional test of Project X produces errors", "2013-11-01", "2013-11-02",
"2013-11-10", 1, "In progress");
putItem("A-104", "Compilation error", "Variable 'messageCount' was not initialized.", "2013-11-15",
"2013-11-16", "2013-11-30", 3, "Assigned");
putItem("A-105", "Network issue", "Can't ping IP address 127.0.0.1. Please fix this.", "2013-11-15",
"2013-11-16", "2013-11-19", 5, "Assigned");
}
public static void putItem(
String issueId, String title, String description, String createDate, String lastUpdateDate, String dueDate,
Integer priority, String status) {
Table table = dynamoDB.getTable(tableName);
Item item = new Item().withPrimaryKey("IssueId", issueId).withString("Title", title)
.withString("Description", description).withString("CreateDate", createDate)
.withString("LastUpdateDate", lastUpdateDate).withString("DueDate", dueDate)
.withNumber("Priority", priority).withString("Status", status);
table.putItem(item);
}
}
```
# Como trabalhar com índices secundários globais: .NET
Você pode usar a API de baixo nível do AWS SDK para .NET para criar uma tabela do Amazon DynamoDB com um ou mais índices secundários globais na tabela e executar consultas usando os índices. Essas operações são mapeadas nas operações do DynamoDB correspondentes. Para obter mais informações, consulte a [Referência de API do Amazon DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/).
Veja a seguir as etapas comuns para operações de tabela usando a API de baixo nível do .NET.
1. Crie uma instância da classe `AmazonDynamoDBClient`.
1. Forneça os parâmetros obrigatórios e opcionais para a operação, criando os objetos de solicitação correspondentes.
Por exemplo, crie um objeto `CreateTableRequest` para criar uma tabela e um objeto `QueryRequest` para consultar uma tabela ou um índice.
1. Execute o método apropriado fornecido pelo cliente que você criou na etapa anterior.
**Topics**
+ [Criar uma tabela com um índice secundário global](#GSILowLevelDotNet.CreateTableWithIndex)
+ [Descrever uma tabela com um índice secundário global](#GSILowLevelDotNet.DescribeTableWithIndex)
+ [Consultar um índice secundário global](#GSILowLevelDotNet.QueryAnIndex)
+ [Exemplo: índices secundários globais que usam a API de baixo nível do AWS SDK para .NET](GSILowLevelDotNet.Example.md)
## Criar uma tabela com um índice secundário global
Você pode criar índices secundários globais ao mesmo tempo em que cria uma tabela. Para fazer isso, use `CreateTable` e forneça suas especificações para um ou mais índices secundários globais. O exemplo de código C\$1a seguir cria uma tabela para armazenar informações sobre dados climáticos. A chave de partição é `Location` e a chave de classificação é `Date`. Um índice secundário global chamado `PrecipIndex` permite acesso rápido aos dados de precipitação de vários locais.
Veja a seguir as etapas necessárias para criar uma tabela com um índice secundário global usando a API de baixo nível do .NET.
1. Crie uma instância da classe `AmazonDynamoDBClient`.
1. Crie uma instância da classe `CreateTableRequest` para fornecer as informações solicitadas.
Você deve fornecer o nome da tabela, sua chave primária e os valores de throughput provisionado. Para o índice secundário global, você deve fornecer o nome do índice, suas configurações de throughput provisionado, as definições de atributo da chave de classificação do índice, o esquema de chaves do índice e a projeção do atributo.
1. Execute o método `CreateTable` fornecendo o objeto de solicitação como um parâmetro.
O exemplo de código C\$1 a seguir demonstra as etapas anteriores. O código cria uma tabela (`WeatherData`) com um índice secundário global (`PrecipIndex`). A chave de partição do índice é `Date` e a chave de classificação é `Precipitation`. Todos os atributos da tabela estão projetados no índice. Os usuários podem consultar esse índice para obter dados climáticos de uma data específica, opcionalmente, classificar os dados por quantidade de precipitação.
Como `Precipitation` não é um atributo de chave para a tabela, ele não é necessário. No entanto, os itens de `WeatherData` sem `Precipitation` não aparecem no `PrecipIndex`.
```
client = new AmazonDynamoDBClient();
string tableName = "WeatherData";
// Attribute definitions
var attributeDefinitions = new List()
{
{new AttributeDefinition{
AttributeName = "Location",
AttributeType = "S"}},
{new AttributeDefinition{
AttributeName = "Date",
AttributeType = "S"}},
{new AttributeDefinition(){
AttributeName = "Precipitation",
AttributeType = "N"}
}
};
// Table key schema
var tableKeySchema = new List()
{
{new KeySchemaElement {
AttributeName = "Location",
KeyType = "HASH"}}, //Partition key
{new KeySchemaElement {
AttributeName = "Date",
KeyType = "RANGE"} //Sort key
}
};
// PrecipIndex
var precipIndex = new GlobalSecondaryIndex
{
IndexName = "PrecipIndex",
ProvisionedThroughput = new ProvisionedThroughput
{
ReadCapacityUnits = (long)10,
WriteCapacityUnits = (long)1
},
Projection = new Projection { ProjectionType = "ALL" }
};
var indexKeySchema = new List {
{new KeySchemaElement { AttributeName = "Date", KeyType = "HASH"}}, //Partition key
{new KeySchemaElement{AttributeName = "Precipitation",KeyType = "RANGE"}} //Sort key
};
precipIndex.KeySchema = indexKeySchema;
CreateTableRequest createTableRequest = new CreateTableRequest
{
TableName = tableName,
ProvisionedThroughput = new ProvisionedThroughput
{
ReadCapacityUnits = (long)5,
WriteCapacityUnits = (long)1
},
AttributeDefinitions = attributeDefinitions,
KeySchema = tableKeySchema,
GlobalSecondaryIndexes = { precipIndex }
};
CreateTableResponse response = client.CreateTable(createTableRequest);
Console.WriteLine(response.CreateTableResult.TableDescription.TableName);
Console.WriteLine(response.CreateTableResult.TableDescription.TableStatus);
```
Você deve aguardar até que o DynamoDB crie a tabela e defina o status dessa tabela como `ACTIVE`. Depois disso, você poderá começar a inserir itens de dados na tabela.
## Descrever uma tabela com um índice secundário global
Para obter mais informações sobre índices secundários globais em uma tabela, use `DescribeTable`. Para cada índice, você pode acessar seu nome, esquema de chaves e atributos projetados.
Veja a seguir as etapas para acessar informações do índice secundário global para uma tabela usando a API de baixo nível do .NET.
1. Crie uma instância da classe `AmazonDynamoDBClient`.
1. Execute o método `describeTable` fornecendo o objeto de solicitação como um parâmetro.
Crie uma instância da classe `DescribeTableRequest` para fornecer as informações solicitadas. Você deve fornecer o nome da tabela.
O exemplo de código C\$1 a seguir demonstra as etapas anteriores.
**Example**
```
client = new AmazonDynamoDBClient();
string tableName = "WeatherData";
DescribeTableResponse response = client.DescribeTable(new DescribeTableRequest { TableName = tableName});
List globalSecondaryIndexes =
response.DescribeTableResult.Table.GlobalSecondaryIndexes;
// This code snippet will work for multiple indexes, even though
// there is only one index in this example.
foreach (GlobalSecondaryIndexDescription gsiDescription in globalSecondaryIndexes) {
Console.WriteLine("Info for index " + gsiDescription.IndexName + ":");
foreach (KeySchemaElement kse in gsiDescription.KeySchema) {
Console.WriteLine("\t" + kse.AttributeName + ": key type is " + kse.KeyType);
}
Projection projection = gsiDescription.Projection;
Console.WriteLine("\tThe projection type is: " + projection.ProjectionType);
if (projection.ProjectionType.ToString().Equals("INCLUDE")) {
Console.WriteLine("\t\tThe non-key projected attributes are: "
+ projection.NonKeyAttributes);
}
}
```
## Consultar um índice secundário global
Você pode usar `Query` em um índice secundário global de forma semelhante ao uso de `Query` em uma tabela. Você precisa especificar o nome do índice, os critérios de consulta da chave de partição e da chave de classificação (se houver) do índice, e os atributos que você deseja retornar. Neste exemplo, o índice é `PrecipIndex`, que tem uma chave de partição `Date` e uma chave de classificação `Precipitation`. A consulta de índice retorna todos os dados climáticos de uma data específica, na qual a precipitação é maior que zero.
Veja a seguir as etapas para consultar um índice secundário global usando a API de baixo nível do .NET.
1. Crie uma instância da classe `AmazonDynamoDBClient`.
1. Crie uma instância da classe `QueryRequest` para fornecer as informações solicitadas.
1. Execute o método `query` fornecendo o objeto de solicitação como um parâmetro.
O nome do atributo `Date` é uma palavra reservada do DynamoDB. Portanto, use um nome de atributo de expressão como um espaço reservado na `KeyConditionExpression`.
O exemplo de código C\$1 a seguir demonstra as etapas anteriores.
**Example**
```
client = new AmazonDynamoDBClient();
QueryRequest queryRequest = new QueryRequest
{
TableName = "WeatherData",
IndexName = "PrecipIndex",
KeyConditionExpression = "#dt = :v_date and Precipitation > :v_precip",
ExpressionAttributeNames = new Dictionary {
{"#dt", "Date"}
},
ExpressionAttributeValues = new Dictionary {
{":v_date", new AttributeValue { S = "2013-08-01" }},
{":v_precip", new AttributeValue { N = "0" }}
},
ScanIndexForward = true
};
var result = client.Query(queryRequest);
var items = result.Items;
foreach (var currentItem in items)
{
foreach (string attr in currentItem.Keys)
{
Console.Write(attr + "---> ");
if (attr == "Precipitation")
{
Console.WriteLine(currentItem[attr].N);
}
else
{
Console.WriteLine(currentItem[attr].S);
}
}
Console.WriteLine();
}
```
# Exemplo: índices secundários globais que usam a API de baixo nível do AWS SDK para .NET
O código de exemplo Java a seguir mostra como trabalhar com índices secundários globais. O exemplo cria uma tabela chamada `Issues`, que pode ser usada em um sistema de controle de bugs simples para desenvolvimento de software. A chave de partição é `IssueId` e a chave de classificação é `Title`. Há três índices secundários globais nessa tabela:
+ `CreateDateIndex`: a chave de partição é `CreateDate` e a chave de classificação é `IssueId`. Além das chaves da tabela, os atributos `Description` e `Status` são projetados no índice.
+ `TitleIndex`: a chave de partição é `Title` e a chave de classificação é `IssueId`. Nenhum outro atributo além das chaves da tabela são projetos no índice.
+ `DueDateIndex`: a chave de partição é `DueDate` e não há chave de classificação. Todos os atributos da tabela estão projetados no índice.
Depois que a tabela `Issues` é criada, o programa carrega a tabela com os dados que representam relatórios de bugs do software. Ele consulta os dados usando os índices secundários globais. Por fim, o programa exclui a tabela `Issues`.
Para obter instruções detalhadas sobre como testar o exemplo a seguir, consulte [Exemplos de código .NET](CodeSamples.DotNet.md).
**Example**
```
using System;
using System.Collections.Generic;
using System.Linq;
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.DataModel;
using Amazon.DynamoDBv2.DocumentModel;
using Amazon.DynamoDBv2.Model;
using Amazon.Runtime;
using Amazon.SecurityToken;
namespace com.amazonaws.codesamples
{
class LowLevelGlobalSecondaryIndexExample
{
private static AmazonDynamoDBClient client = new AmazonDynamoDBClient();
public static String tableName = "Issues";
public static void Main(string[] args)
{
CreateTable();
LoadData();
QueryIndex("CreateDateIndex");
QueryIndex("TitleIndex");
QueryIndex("DueDateIndex");
DeleteTable(tableName);
Console.WriteLine("To continue, press enter");
Console.Read();
}
private static void CreateTable()
{
// Attribute definitions
var attributeDefinitions = new List()
{
{new AttributeDefinition {
AttributeName = "IssueId", AttributeType = "S"
}},
{new AttributeDefinition {
AttributeName = "Title", AttributeType = "S"
}},
{new AttributeDefinition {
AttributeName = "CreateDate", AttributeType = "S"
}},
{new AttributeDefinition {
AttributeName = "DueDate", AttributeType = "S"
}}
};
// Key schema for table
var tableKeySchema = new List() {
{
new KeySchemaElement {
AttributeName= "IssueId",
KeyType = "HASH" //Partition key
}
},
{
new KeySchemaElement {
AttributeName = "Title",
KeyType = "RANGE" //Sort key
}
}
};
// Initial provisioned throughput settings for the indexes
var ptIndex = new ProvisionedThroughput
{
ReadCapacityUnits = 1L,
WriteCapacityUnits = 1L
};
// CreateDateIndex
var createDateIndex = new GlobalSecondaryIndex()
{
IndexName = "CreateDateIndex",
ProvisionedThroughput = ptIndex,
KeySchema = {
new KeySchemaElement {
AttributeName = "CreateDate", KeyType = "HASH" //Partition key
},
new KeySchemaElement {
AttributeName = "IssueId", KeyType = "RANGE" //Sort key
}
},
Projection = new Projection
{
ProjectionType = "INCLUDE",
NonKeyAttributes = {
"Description", "Status"
}
}
};
// TitleIndex
var titleIndex = new GlobalSecondaryIndex()
{
IndexName = "TitleIndex",
ProvisionedThroughput = ptIndex,
KeySchema = {
new KeySchemaElement {
AttributeName = "Title", KeyType = "HASH" //Partition key
},
new KeySchemaElement {
AttributeName = "IssueId", KeyType = "RANGE" //Sort key
}
},
Projection = new Projection
{
ProjectionType = "KEYS_ONLY"
}
};
// DueDateIndex
var dueDateIndex = new GlobalSecondaryIndex()
{
IndexName = "DueDateIndex",
ProvisionedThroughput = ptIndex,
KeySchema = {
new KeySchemaElement {
AttributeName = "DueDate",
KeyType = "HASH" //Partition key
}
},
Projection = new Projection
{
ProjectionType = "ALL"
}
};
var createTableRequest = new CreateTableRequest
{
TableName = tableName,
ProvisionedThroughput = new ProvisionedThroughput
{
ReadCapacityUnits = (long)1,
WriteCapacityUnits = (long)1
},
AttributeDefinitions = attributeDefinitions,
KeySchema = tableKeySchema,
GlobalSecondaryIndexes = {
createDateIndex, titleIndex, dueDateIndex
}
};
Console.WriteLine("Creating table " + tableName + "...");
client.CreateTable(createTableRequest);
WaitUntilTableReady(tableName);
}
private static void LoadData()
{
Console.WriteLine("Loading data into table " + tableName + "...");
// IssueId, Title,
// Description,
// CreateDate, LastUpdateDate, DueDate,
// Priority, Status
putItem("A-101", "Compilation error",
"Can't compile Project X - bad version number. What does this mean?",
"2013-11-01", "2013-11-02", "2013-11-10",
1, "Assigned");
putItem("A-102", "Can't read data file",
"The main data file is missing, or the permissions are incorrect",
"2013-11-01", "2013-11-04", "2013-11-30",
2, "In progress");
putItem("A-103", "Test failure",
"Functional test of Project X produces errors",
"2013-11-01", "2013-11-02", "2013-11-10",
1, "In progress");
putItem("A-104", "Compilation error",
"Variable 'messageCount' was not initialized.",
"2013-11-15", "2013-11-16", "2013-11-30",
3, "Assigned");
putItem("A-105", "Network issue",
"Can't ping IP address 127.0.0.1. Please fix this.",
"2013-11-15", "2013-11-16", "2013-11-19",
5, "Assigned");
}
private static void putItem(
String issueId, String title,
String description,
String createDate, String lastUpdateDate, String dueDate,
Int32 priority, String status)
{
Dictionary item = new Dictionary();
item.Add("IssueId", new AttributeValue
{
S = issueId
});
item.Add("Title", new AttributeValue
{
S = title
});
item.Add("Description", new AttributeValue
{
S = description
});
item.Add("CreateDate", new AttributeValue
{
S = createDate
});
item.Add("LastUpdateDate", new AttributeValue
{
S = lastUpdateDate
});
item.Add("DueDate", new AttributeValue
{
S = dueDate
});
item.Add("Priority", new AttributeValue
{
N = priority.ToString()
});
item.Add("Status", new AttributeValue
{
S = status
});
try
{
client.PutItem(new PutItemRequest
{
TableName = tableName,
Item = item
});
}
catch (Exception e)
{
Console.WriteLine(e.ToString());
}
}
private static void QueryIndex(string indexName)
{
Console.WriteLine
("\n***********************************************************\n");
Console.WriteLine("Querying index " + indexName + "...");
QueryRequest queryRequest = new QueryRequest
{
TableName = tableName,
IndexName = indexName,
ScanIndexForward = true
};
String keyConditionExpression;
Dictionary expressionAttributeValues = new Dictionary();
if (indexName == "CreateDateIndex")
{
Console.WriteLine("Issues filed on 2013-11-01\n");
keyConditionExpression = "CreateDate = :v_date and begins_with(IssueId, :v_issue)";
expressionAttributeValues.Add(":v_date", new AttributeValue
{
S = "2013-11-01"
});
expressionAttributeValues.Add(":v_issue", new AttributeValue
{
S = "A-"
});
}
else if (indexName == "TitleIndex")
{
Console.WriteLine("Compilation errors\n");
keyConditionExpression = "Title = :v_title and begins_with(IssueId, :v_issue)";
expressionAttributeValues.Add(":v_title", new AttributeValue
{
S = "Compilation error"
});
expressionAttributeValues.Add(":v_issue", new AttributeValue
{
S = "A-"
});
// Select
queryRequest.Select = "ALL_PROJECTED_ATTRIBUTES";
}
else if (indexName == "DueDateIndex")
{
Console.WriteLine("Items that are due on 2013-11-30\n");
keyConditionExpression = "DueDate = :v_date";
expressionAttributeValues.Add(":v_date", new AttributeValue
{
S = "2013-11-30"
});
// Select
queryRequest.Select = "ALL_PROJECTED_ATTRIBUTES";
}
else
{
Console.WriteLine("\nNo valid index name provided");
return;
}
queryRequest.KeyConditionExpression = keyConditionExpression;
queryRequest.ExpressionAttributeValues = expressionAttributeValues;
var result = client.Query(queryRequest);
var items = result.Items;
foreach (var currentItem in items)
{
foreach (string attr in currentItem.Keys)
{
if (attr == "Priority")
{
Console.WriteLine(attr + "---> " + currentItem[attr].N);
}
else
{
Console.WriteLine(attr + "---> " + currentItem[attr].S);
}
}
Console.WriteLine();
}
}
private static void DeleteTable(string tableName)
{
Console.WriteLine("Deleting table " + tableName + "...");
client.DeleteTable(new DeleteTableRequest
{
TableName = tableName
});
WaitForTableToBeDeleted(tableName);
}
private static void WaitUntilTableReady(string tableName)
{
string status = null;
// Let us wait until table is created. Call DescribeTable.
do
{
System.Threading.Thread.Sleep(5000); // Wait 5 seconds.
try
{
var res = client.DescribeTable(new DescribeTableRequest
{
TableName = tableName
});
Console.WriteLine("Table name: {0}, status: {1}",
res.Table.TableName,
res.Table.TableStatus);
status = res.Table.TableStatus;
}
catch (ResourceNotFoundException)
{
// DescribeTable is eventually consistent. So you might
// get resource not found. So we handle the potential exception.
}
} while (status != "ACTIVE");
}
private static void WaitForTableToBeDeleted(string tableName)
{
bool tablePresent = true;
while (tablePresent)
{
System.Threading.Thread.Sleep(5000); // Wait 5 seconds.
try
{
var res = client.DescribeTable(new DescribeTableRequest
{
TableName = tableName
});
Console.WriteLine("Table name: {0}, status: {1}",
res.Table.TableName,
res.Table.TableStatus);
}
catch (ResourceNotFoundException)
{
tablePresent = false;
}
}
}
}
}
```
# Trabalhar com índices secundários globais no DynamoDB usando a AWS CLI
Você pode usar a AWS CLI para criar uma tabela do Amazon DynamoDB com um ou mais índices secundários globais na tabela e executar consultas usando os índices.
**Topics**
+ [Criar uma tabela com um índice secundário global](#GCICli.CreateTableWithIndex)
+ [Adicionar um índice secundário global a uma tabela existente](#GCICli.CreateIndexAfterTable)
+ [Descrever uma tabela com um índice secundário global](#GCICli.DescribeTableWithIndex)
+ [Consultar um índice secundário global](#GCICli.QueryAnIndex)
## Criar uma tabela com um índice secundário global
Você pode criar índices secundários globais ao mesmo tempo que cria uma tabela. Para fazer isso, use o parâmetro `create-table` e forneça suas especificações para um ou mais índices secundários globais. O exemplo a seguir cria uma tabela chamada `GameScores` com um índice secundário global chamado `GameTitleIndex`. A tabela-base tem uma chave de partição `UserId` e uma chave de classificação `GameTitle`, permitindo que você encontre a melhor pontuação de um usuário individual para um jogo específico de forma eficiente, enquanto o GSI tem uma chave de partição `GameTitle` e uma chave de classificação `TopScore`, permitindo que você encontre rapidamente a pontuação mais alta geral para um jogo específico.
```
aws dynamodb create-table \
--table-name GameScores \
--attribute-definitions AttributeName=UserId,AttributeType=S \
AttributeName=GameTitle,AttributeType=S \
AttributeName=TopScore,AttributeType=N \
--key-schema AttributeName=UserId,KeyType=HASH \
AttributeName=GameTitle,KeyType=RANGE \
--provisioned-throughput ReadCapacityUnits=10,WriteCapacityUnits=5 \
--global-secondary-indexes \
"[
{
\"IndexName\": \"GameTitleIndex\",
\"KeySchema\": [{\"AttributeName\":\"GameTitle\",\"KeyType\":\"HASH\"},
{\"AttributeName\":\"TopScore\",\"KeyType\":\"RANGE\"}],
\"Projection\":{
\"ProjectionType\":\"INCLUDE\",
\"NonKeyAttributes\":[\"UserId\"]
},
\"ProvisionedThroughput\": {
\"ReadCapacityUnits\": 10,
\"WriteCapacityUnits\": 5
}
}
]"
```
Você deve aguardar até que o DynamoDB crie a tabela e defina o status dessa tabela como `ACTIVE`. Depois disso, você poderá começar a inserir itens de dados na tabela. Você pode usar [describe-table](https://docs.aws.amazon.com/cli/latest/reference/dynamodb/describe-table.html) para determinar o status da criação da tabela.
## Adicionar um índice secundário global a uma tabela existente
Os índices secundários globais também podem ser adicionados ou modificados após a criação da tabela. Para fazer isso, use o parâmetro `update-table` e forneça suas especificações para um ou mais índices secundários globais. O exemplo a seguir usa o mesmo esquema do exemplo anterior, mas pressupõe que a tabela já foi criada e que adicionaremos o GSI mais tarde.
```
aws dynamodb update-table \
--table-name GameScores \
--attribute-definitions AttributeName=TopScore,AttributeType=N \
--global-secondary-index-updates \
"[
{
\"Create\": {
\"IndexName\": \"GameTitleIndex\",
\"KeySchema\": [{\"AttributeName\":\"GameTitle\",\"KeyType\":\"HASH\"},
{\"AttributeName\":\"TopScore\",\"KeyType\":\"RANGE\"}],
\"Projection\":{
\"ProjectionType\":\"INCLUDE\",
\"NonKeyAttributes\":[\"UserId\"]
}
}
}
]"
```
## Descrever uma tabela com um índice secundário global
Para obter mais informações sobre índices secundários globais em uma tabela, use o parâmetro `describe-table`. Para cada índice, você pode acessar seu nome, esquema de chaves e atributos projetados.
```
aws dynamodb describe-table --table-name GameScores
```
## Consultar um índice secundário global
Você pode usar a operação `query` em um índice secundário global de forma semelhante ao uso de `query` em uma tabela. Você deve especificar o nome do índice, os critérios de consulta da chave de classificação do índice e os atributos que deseja retornar. Neste exemplo, o índice é `GameTitleIndex` e a chave de classificação do índice é `GameTitle`.
Os únicos atributos retornados são aqueles que foram projetados no índice. É possível modificar essa consulta para selecionar atributos não chave também, mas isso exigiria atividades de busca de tabela que são relativamente caras. Para obter mais informações sobre buscas de tabela, consulte [Projeções de atributo](GSI.md#GSI.Projections).
```
aws dynamodb query --table-name GameScores\
--index-name GameTitleIndex \
--key-condition-expression "GameTitle = :v_game" \
--expression-attribute-values '{":v_game":{"S":"Alien Adventure"} }'
```
# Índices secundários locais
Alguns aplicativos só precisam consultar dados usando a chave primária da tabela base. No entanto, podem haver situações em que uma chave de classificação alternativa seria útil. Para oferecer à sua aplicação opções de chaves de classificação, você pode criar um ou mais índices secundários locais em uma tabela do Amazon DynamoDB e emitir solicitações de `Query` ou `Scan` nesses índices.
**Topics**
+ [Cenário: Uso de um índice secundário local](#LSI.Scenario)
+ [Projeções de atributo](#LSI.Projections)
+ [Criação de um índice secundário local](#LSI.Creating)
+ [Ler dados de um índice secundário local](#LSI.Reading)
+ [Gravações de itens e índices secundários locais](#LSI.Writes)
+ [Considerações sobre throughput provisionado para índices secundários locais](#LSI.ThroughputConsiderations)
+ [Considerações sobre armazenamento para índices secundários locais](#LSI.StorageConsiderations)
+ [Conjuntos de itens em índices secundários locais](#LSI.ItemCollections)
+ [Como trabalhar com índices secundários locais: Java](LSIJavaDocumentAPI.md)
+ [Como trabalhar com índices secundários locais: .NET](LSILowLevelDotNet.md)
+ [Trabalhar com índices secundários locais no DynamoDB usando a AWS CLI](LCICli.md)
## Cenário: Uso de um índice secundário local
Como exemplo, considere a tabela `Thread`. Esta tabela é útil para aplicações como os [Fóruns de discussão da AWS](https://forums.aws.amazon.com/). O diagrama a seguir mostra como os itens da tabela seriam organizados. (Nem todos os atributos são mostrados.)
![\[A tabela Thread que contém uma lista de nomes, assuntos, hora da última publicação e o número de repostas do fórum.\]](http://docs.aws.amazon.com/pt_br/amazondynamodb/latest/developerguide/images/LSI_01.png)
O DynamoDB armazena continuamente todos os itens com o mesmo valor de chave de partição. Neste exemplo, dado um determinado `ForumName`, uma operação `Query` poderia localizar imediatamente todos os threads desse fórum. Em um grupo de itens com o mesmo valor de chave de partição, os itens são classificados pelo valor de chave de classificação. Se a chave de classificação (`Subject`) também for fornecida na consulta, o DynamoDB poderá reduzir os resultados que são retornados. Por exemplo, retornar todos os threads do fórum "S3" em que `Subject` começa com a letra "a".
Algumas solicitações podem exigir padrões mais complexos de acesso aos dados. Por exemplo:
+ Quais threads do fórum recebem visualizações e respostas?
+ Qual thread em um determinado fórum tem o maior número de mensagens?
+ Quantos threads foram publicados em um fórum específico em um determinado período?
A ação `Query` não seria suficiente para responder a essas perguntas. Em vez disso, você teria de `Scan` toda a tabela. Para uma tabela com milhões de itens, isso poderia consumir uma grande quantidade de throughput provisionado de leitura e levar muito tempo para ser concluído.
No entanto, é possível especificar um ou mais índices secundários em atributos que não são chaves, como `Replies` ou `LastPostDateTime`.
Um *índice secundário local* mantém uma chave de classificação alternativa para um determinado valor de chave de partição. Um índice secundário local também contém uma cópia de alguns ou de todos os atributos de sua tabela-base. Você especifica quais atributos são projetados no índice secundário local ao criar a tabela. Os dados em um índice secundário local são organizados com a mesma chave de partição que a tabela-base, mas com outra chave de classificação. Isso permite que você acesse os itens de dados de forma eficiente nessa dimensão diferente. Para uma maior flexibilidade de consulta ou verificação, você pode criar até cinco índices secundários locais por tabela.
Suponha que um aplicativo precise encontrar todos os threads que foram publicados nos últimos três meses em um fórum específico. Sem um índice secundário local, a aplicação precisaria realizar `Scan` de toda a tabela `Thread` e descartar todas as publicações que não estivessem dentro do período especificado. Com um índice secundário local, uma operação de `Query` poderia usar `LastPostDateTime` como uma chave de classificação e encontrar os dados rapidamente.
O diagrama a seguir mostra um índice secundário local chamado `LastPostIndex`. Observe que a chave de partição é a mesma que a da tabela `Thread`, mas a chave de classificação é `LastPostDateTime`.
![\[A tabela LastPostIndex que contém uma lista de nomes, assuntos e a hora da última publicação do fórum.\]](http://docs.aws.amazon.com/pt_br/amazondynamodb/latest/developerguide/images/LSI_02.png)
Cada índice secundário local deve atender às seguintes condições:
+ A chave de partição é a mesma que a de sua tabela-base.
+ A chave de classificação consiste em exatamente um atributo escalar.
+ A chave de classificação da tabela-base é projetada no índice, onde ela atua como um atributo que não é chave.
Neste exemplo, a chave de partição é `ForumName` e a chave de classificação do índice secundário local é `LastPostDateTime`. Além disso, o valor da chave de classificação da tabela base (neste exemplo, `Subject`) é projetado no índice, mas não faz parte da chave do índice. Se um aplicativo precisar de uma lista baseada em `ForumName` e `LastPostDateTime`, ele poderá emitir uma solicitação de `Query` com relação a `LastPostIndex`. Os resultados da consulta são classificados por `LastPostDateTime` e podem ser retornados em ordem crescente ou decrescente. A consulta também pode aplicar condições de chave, como retornar apenas os itens que têm uma `LastPostDateTime` dentro de um período específico.
Cada índice secundário local contém automaticamente as chave de partição e de classificação de sua tabela-base, mas você pode opcionalmente projetar atributos não chave no índice. Quando você consultar o índice, o DynamoDB poderá recuperar esses atributos projetados com eficiência. Quando você consulta um índice secundário local, a consulta também pode recuperar atributos que *não* são projetados no índice. O DynamoDB buscará automaticamente esses atributos na tabela-base, mas com uma latência maior e com custos de throughput provisionado mais altos.
Para qualquer índice secundário local, você pode armazenar até 10 GB de dados por valor de chave de partição distinta. Esta imagem inclui todos os itens na tabela-base, além de todos os itens nos índices, que têm o mesmo valor de chave de partição. Para obter mais informações, consulte [Conjuntos de itens em índices secundários locais](#LSI.ItemCollections).
## Projeções de atributo
Com `LastPostIndex`, um aplicativo poderia usar `ForumName` e `LastPostDateTime` como critérios de consulta. No entanto, para recuperar qualquer atributo adicional, o DynamoDB deve executar operações de leitura adicionais na tabela `Thread`. Essas leituras extras são conhecidas como *buscas* e podem aumentar a quantidade total de throughput provisionado necessário para uma consulta.
Suponha que você quisesse preencher uma página da Web com uma lista de todos os threads de "S3" e o número de respostas para cada thread, classificados pela última data/hora de resposta, começando pela resposta mais recente. Para preencher essa lista, você precisaria dos seguintes atributos:
+ `Subject`
+ `Replies`
+ `LastPostDateTime`
A maneira mais eficiente de consultar esses dados e evitar operações de busca seria projetar o atributo `Replies` da tabela no índice secundário local conforme mostrado neste diagrama.
![\[A tabela LastPostIndex que contém uma lista de nomes, datas das últimas publicações, assuntos e respostas do fórum.\]](http://docs.aws.amazon.com/pt_br/amazondynamodb/latest/developerguide/images/LSI_03.png)
Uma *projeção* é o conjunto de atributos que é copiado de uma tabela para um índice secundário. A chave de partição e a chave de classificação da tabela são sempre projetadas no índice; você pode projetar outros atributos para suportar os requisitos de consulta da sua aplicação. Quando você consulta um índice, o Amazon DynamoDB pode acessar quaisquer atributos na projeção como se estivessem em uma tabela própria.
Quando você cria um índice secundário, é necessário especificar os atributos que serão projetados no índice. O DynamoDB proporciona três opções diferentes para fazer isso:
+ *KEYS\$1ONLY*: 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. A opção `KEYS_ONLY` resulta no menor índice secundário possível.
+ *INCLUDE*: além dos atributos descritos em `KEYS_ONLY`, o índice secundário incluirá outros atributos não chave que você especificar.
+ *ALL*: o índice secundário inclui todos os atributos da tabela de origem. Como todos os dados da tabela são duplicados no índice, uma projeção `ALL` resulta no maior índice secundário possível.
No diagrama anterior, o atributo `Replies` que não é chave é projetado em `LastPostIndex`. Um aplicativo pode consultar `LastPostIndex` em vez da tabela `Thread` completa para preencher uma página da Web com `Subject`, `Replies` e `LastPostDateTime`. Se quaisquer outros atributos que não são chaves forem solicitados, o DynamoDB precisará buscar esses atributos na tabela `Thread`.
Do ponto de vista de um aplicativo, buscar atributos adicionais da tabela-base é automático e transparente, portanto, não há necessidade de reescrever qualquer lógica de aplicativo. No entanto, essa busca pode reduzir significativamente a vantagem de performance proporcionada pelo uso de um índice secundário local.
Ao escolher os atributos para projetar em um índice secundário local, você deve considerar a desvantagem entre os custos de throughput provisionado e os custos de armazenamento:
+ Se você precisar acessar apenas alguns atributos com a latência mais baixa possível, considere projetar apenas os atributos em um índice secundário local. Quanto menor o índice, menores serão os custos de armazenamento e de gravação. Se houver atributos que você precisa buscar ocasionalmente, o custo de throughput provisionado pode ultrapassar o custo por um prazo mais longo do armazenamento desses atributos.
+ Se sua aplicação acessar frequentemente alguns atributos não chave, considere projetar esses atributos em um índice secundário local. Os custos adicionais de armazenamento do índice secundário local compensarão o custo de executar verificações de tabelas frequentes.
+ Se precisar acessar a maioria dos atributos não chave com frequência, você poderá projetar esses atributos, inclusive a tabela-base inteira, em um índice secundário local. Isso fornece flexibilidade máxima e menor consumo de throughput provisionado, porque nenhuma busca será necessária. No entanto, o custo do armazenamento deve aumentar ou até dobrar se você estiver projetando todos os atributos.
+ Se o seu aplicativo precisa consultar uma tabela com pouca frequência, mas deve realizar muitas gravações ou atualizações nos dados na tabela, pense em projetar *KEYS\$1ONLY*. O índice secundário local seria de tamanho mínimo, mas ainda estaria disponível quando necessário para a atividade de consulta.
## Criação de um índice secundário local
Para criar um ou mais índices secundários locais, use o parâmetro `LocalSecondaryIndexes` da operação `CreateTable`. Os índices secundários locais em uma tabela são criados quando a tabela é criada. Quando você exclui uma tabela, todos os índices secundários locais da tabela também são excluídos.
Você deve especificar um atributo não chave para atuar como a chave de classificação do índice secundário local. O atributo escolhido deve ser de um tipo escalar como `String`, `Number` ou `Binary` Outros tipos escalares, tipos de documento e tipos de conjunto não são permitidos. Para obter uma lista completa de tipos de dados, consulte [Tipos de dados](HowItWorks.NamingRulesDataTypes.md#HowItWorks.DataTypes).
**Importante**
Para tabelas com índices secundários locais, há um limite de tamanho de 10 GB para cada valor de chave de partição. Uma tabela com índices secundários locais pode armazenar qualquer número de itens, desde que o tamanho total de qualquer valor de chave de partição não exceda 10 GB. Para obter mais informações, consulte [Limite de tamanho de conjunto de itens](#LSI.ItemCollections.SizeLimit).
Você pode projetar atributos de qualquer tipo de dados em um índice secundário local. Isso inclui escalares, documentos e conjuntos. Para obter uma lista completa de tipos de dados, consulte [Tipos de dados](HowItWorks.NamingRulesDataTypes.md#HowItWorks.DataTypes).
## Ler dados de um índice secundário local
Você pode recuperar itens de um índice secundário local usando as operações `Query` e `Scan`. As operações `GetItem` e `BatchGetItem` não podem ser usadas em um índice secundário local.
### Como consultar um índice secundário local
Em uma tabela do DynamoDB, o valor da chave de partição combinada e o valor da chave de classificação de cada item devem ser exclusivos. No entanto, em um índice secundário local, o valor da chave de classificação não precisa ser exclusivo para um determinado valor de chave de partição. Se houver vários itens no índice secundário local com o mesmo valor de chave de classificação, uma operação `Query` retornará todos os itens que têm o mesmo valor de chave de partição. Na resposta, os itens correspondentes não são retornados em uma ordem específica.
Você pode consultar um índice secundário local usando leituras fortemente consistentes ou finais consistentes. Para especificar qual tipo de consistência você deseja, use o parâmetro `ConsistentRead` da operação `Query`. Uma leitura fortemente consistente de um índice secundário local sempre retorna os valores atualizados mais recentes. Se a consulta precisar buscar atributos adicionais na tabela base, esses atributos serão consistentes com relação ao índice.
**Example**
Considere os seguintes dados retornados de uma `Query` que solicita dados dos threads de discussão em um determinado fórum.
```
{
"TableName": "Thread",
"IndexName": "LastPostIndex",
"ConsistentRead": false,
"ProjectionExpression": "Subject, LastPostDateTime, Replies, Tags",
"KeyConditionExpression":
"ForumName = :v_forum and LastPostDateTime between :v_start and :v_end",
"ExpressionAttributeValues": {
":v_start": {"S": "2015-08-31T00:00:00.000Z"},
":v_end": {"S": "2015-11-31T00:00:00.000Z"},
":v_forum": {"S": "EC2"}
}
}
```
Nesta consulta:
+ O DynamoDB acessa `LastPostIndex` usando a chave de partição `ForumName` para localizar os itens do índice para o "EC2". Todos os itens do índice com essa chave são armazenados lado a lado para rápida recuperação.
+ Neste fórum, o DynamoDB usa o índice para pesquisar as chaves que correspondem à condição `LastPostDateTime` especificada.
+ Como o atributo `Replies` é projetado no índice, o DynamoDB pode recuperar esse atributo sem consumir nenhum throughput provisionado adicional.
+ O atributo `Tags` não é projetado no índice, portanto, o DynamoDB deve acessar a tabela `Thread` e buscar esse atributo.
+ Os resultados são retornados, classificados por `LastPostDateTime`. As entradas de índice são classificadas por valor de chave de partição e, em seguida, pelo valor de chave de classificação, e `Query` retorna-as na ordem em que são armazenadas. (Você pode usar o parâmetro `ScanIndexForward` para retornar os resultados em ordem decrescente.)
Como o atributo `Tags` não é projetado no índice secundário local, o DynamoDB deve consumir unidades de capacidade de leitura adicionais para buscar esse atributo na tabela-base. Se for necessário executar essa consulta com frequência, projete `Tags` no `LastPostIndex` para evitar a busca na tabela base. No entanto, se for necessário acessar `Tags` apenas ocasionalmente, o custo do armazenamento adicional para a projeção de `Tags` no índice pode não valer a pena.
### Verificação de um índice secundário local
Você pode usar `Scan` para recuperar todos os dados de um índice secundário local. Você deve fornecer o nome da tabela-base e o nome de índice na solicitação. Com uma operação `Scan`, o DynamoDB lê todos os dados do índice e os retorna para a aplicação. Você também pode solicitar que apenas alguns dos dados sejam retornados, e que os dados restantes sejam descartados. Para fazer isso, use o parâmetro `FilterExpression` da API `Scan`. Para obter mais informações, consulte [Expressões de filtro para verificação](Scan.md#Scan.FilterExpression).
## Gravações de itens e índices secundários locais
O DynamoDB mantém automaticamente todos os índices secundários locais sincronizados com suas respectivas tabelas base. Os aplicativos nunca gravam diretamente em um índice. No entanto, é importante compreender as implicações de como o DynamoDB mantém esses índices.
Ao criar um índice secundário local, você especifica um atributo para servir como a chave de classificação do índice. Você também especifica um tipo de dados desse atributo. Isso significa que sempre que você grava um item na tabela-base, se o item define um atributo de chave do índice, seu tipo deve corresponder ao tipo de dados do esquema de chaves do índice. No caso de `LastPostIndex`, a chave de classificação de `LastPostDateTime` no índice é definida como um tipo de dados `String`. Se você tentar adicionar um item à tabela `Thread` e especificar um tipo de dados diferente para `LastPostDateTime` (como `Number`), o DynamoDB retornará uma `ValidationException` devido à inconsistência do tipo de dados.
Não há necessidade de um relacionamento de um para um entre os itens em uma tabela-base e os itens em um índice secundário local. Na verdade, esse comportamento pode ser vantajoso para muitas aplicações.
Os custos das atividades de gravação em uma tabela com muitos índices secundários serão mais altos do que em uma tabela com um número menor de índices. Para obter mais informações, consulte [Considerações sobre throughput provisionado para índices secundários locais](#LSI.ThroughputConsiderations).
**Importante**
Para tabelas com índices secundários locais, há um limite de tamanho de 10 GB para cada valor de chave de partição. Uma tabela com índices secundários locais pode armazenar qualquer número de itens, desde que o tamanho total de qualquer valor de chave de partição não exceda 10 GB. Para obter mais informações, consulte [Limite de tamanho de conjunto de itens](#LSI.ItemCollections.SizeLimit).
## Considerações sobre throughput provisionado para índices secundários locais
Ao criar uma tabela no DynamoDB, você provisiona unidades de capacidade de leitura e gravação para a workload esperada na tabela. Essa workload inclui a atividade de leitura e gravação nos índices secundários locais da tabela.
Para visualizar as taxas atuais da capacidade de throughput provisionado, acesse [Preços do Amazon DynamoDB](https://aws.amazon.com/dynamodb/pricing).
### Unidades de capacidade de leitura
Quando você consulta um índice secundário local, o número de unidades de capacidade de leitura consumidas depende de como os dados são acessados.
Assim como ocorre com as consultas de tabela, uma consulta de índice pode usar leituras fortemente consistentes ou eventualmente consistentes, dependendo do valor de `ConsistentRead`. Uma leitura fortemente consistente consome uma unidade de capacidade de leitura, uma leitura eventualmente consistente consome apenas metade disso. Assim, escolhendo leituras eventualmente consistentes, você pode reduzir seus encargos de unidade de capacidade de leitura.
Para consultas do índice que solicitam apenas chaves de índice e atributos projetados, o DynamoDB calcula a atividade de leitura provisionada da mesma forma que para consultas em tabelas. A única diferença é que o cálculo é baseado no tamanho das entradas de índice, em vez do tamanho do item na tabela-base. O número de unidades de capacidade de leitura é a soma de todos os tamanhos de atributos projetados em todos os itens retornados; o resultado é, então, arredondado para o próximo limite de 4 KB. Para obter mais informações sobre como o DynamoDB calcula a utilização de throughput provisionado, consulte [Modo de capacidade provisionada do DynamoDB](provisioned-capacity-mode.md).
Para consultas de índice que leem atributos que não estão projetados no índice secundário local, o DynamoDB precisa buscar esses atributos na tabela-base, além de ler os atributos projetados no índice. Essas buscas ocorrem quando você inclui quaisquer atributos não projetados nos parâmetros `Select` ou `ProjectionExpression` da operação `Query`. A busca causa latência adicional nas respostas da consulta, e também incorre em um custo mais alto de throughput provisionado: além das leituras do índice secundário local descritas acima, você é cobrado pelas unidades de capacidade de leitura de cada item buscado na tabela-base. Essa cobrança é para ler cada item inteiro da tabela, não apenas os atributos solicitados.
O tamanho máximo dos resultados retornados por uma operação `Query` é 1 MB. Isso inclui os tamanhos de todos os nomes e valores de atributos de todos os itens retornados. No entanto, se uma consulta em um índice secundário local fizer o DynamoDB buscar atributos de item na tabela-base, o tamanho máximo dos dados no resultado poderá ser menor. Neste caso, o tamanho do resultado é a soma de:
+ O tamanho dos itens correspondentes no índice, arredondado para os próximos 4 KB.
+ O tamanho de cada item correspondente na tabela-base, com cada item individualmente arredondado para os próximos 4 KB.
Usando esta fórmula, o tamanho máximo dos resultados retornados por uma operação Query ainda é 1 MB.
Por exemplo, considere uma tabela na qual o tamanho de cada item é 300 bytes. Há um índice secundário local nessa tabela, mas apenas 200 bytes de cada item são projetados no índice. Agora, suponha que você use a operação `Query` nesse índice, que a consulta requer buscas de tabela para cada item e que a consulta retorne 4 itens. O DynamoDB soma o seguinte:
+ O tamanho dos itens correspondentes no índice: 200 bytes × 4 itens = 800 bytes; isso é, então, arredondado para 4 KB.
+ O tamanho de cada item correspondente na tabela-base: (300 bytes, arredondados para 4 KB) × 4 itens = 16 KB.
O tamanho total dos dados no resultado é, portanto, 20 KB.
### Unidades de capacidade de gravação
Quando um item é adicionado, atualizado ou excluído de uma tabela, a atualização dos índices secundários locais consome unidades de capacidade de gravação provisionadas para a tabela. O custo total do throughput provisionado para uma gravação é a soma das unidades de capacidade de gravação consumidas pela gravação na tabela e aquelas consumidas pela atualização dos índices secundários locais.
O custo de gravar um item em um índice secundário local depende de vários fatores:
+ Se você gravar um novo item na tabela que define um atributo indexado, ou atualizar um item existente para definir um atributo indexado indefinido anteriormente, uma operação de gravação é necessária para inserir o item no índice.
+ Se uma atualização na tabela alterar o valor de um atributo de chave indexado (de A para B), duas gravações serão necessárias, uma para excluir o item anterior do índice e outra gravação para inserir o novo item no índice.
+ Se um item estava presente no índice, mas uma gravação na tabela fez com que o atributo indexado fosse excluído, uma gravação é necessária para excluir a projeção do item antigo do índice.
+ Se um item não estiver presente no índice antes ou depois que o item é atualizado, não haverá custo de gravação adicionais para o índice.
Todos esses fatores supõem que o tamanho de cada item no índice seja menor ou igual ao tamanho de item de 1 KB para calcular unidades de capacidade de gravação. Entradas de índice maiores exigirão unidades adicionais de capacidade de gravação. Você pode minimizar os custos de gravação considerando de quais atributos suas consultas precisam para retornar e projetar apenas esses atributos no índice.
## Considerações sobre armazenamento para índices secundários locais
Quando uma aplicação grava um item em uma tabela, o DynamoDB copia automaticamente o subconjunto correto de atributos em todos os índices secundários locais nos quais esses atributos devem aparecer. Sua conta da AWS é cobrada pelo armazenamento do item na tabela-base e também pelo armazenamento dos atributos em todos os índices secundários locais nessa tabela.
A quantidade de espaço usada por um item do índice é a soma do seguinte:
+ O tamanho em bytes da chave primária da tabela-base (chave de partição e chave de classificação)
+ O tamanho em bytes do atributo de chave do índice
+ O tamanho em bytes dos atributos projetados (se houver)
+ 100 bytes de sobrecarga por item de índice
Para estimar os requisitos de armazenamento de um índice secundário local, você pode estimar o tamanho médio de um item no índice e multiplicar pelo número de itens no índice.
Se uma tabela contiver um item em que um determinado atributo não está definido, mas esse atributo estiver definido como uma chave de classificação do índice, o DynamoDB não gravará nenhum dado desse item no índice.
## Conjuntos de itens em índices secundários locais
**nota**
A seção refere-se apenas a tabelas que têm índices secundários locais.
No DynamoDB, uma *coleção de itens* é qualquer grupo de itens que têm o mesmo valor de chave de partição em uma tabela e todos os seus índices secundários locais. Nos exemplos usados nesta seção, a chave de partição da tabela `Thread` é `ForumName`, e a chave de partição de `LastPostIndex` também é `ForumName`. Todos os itens da tabela e do índice com o mesmo `ForumName` fazem parte da mesma coleção de itens. Por exemplo, na tabela `Thread` e no índice secundário local `LastPostIndex`, existe uma coleção de itens para o fórum do `EC2` e uma coleção de itens diferente para o fórum do `RDS`.
O seguinte diagrama mostra a coleção de itens do fórum do `S3`.
![\[Uma coleção de itens do DynamoDB com itens de tabela e de índice secundário local que têm o mesmo valor de chave de partição de S3.\]](http://docs.aws.amazon.com/pt_br/amazondynamodb/latest/developerguide/images/LSI_04.png)
Neste diagrama, a coleção de itens consiste em todos os itens em `Thread` e `LastPostIndex` em que o valor da chave da partição `ForumName` é "S3". Se houver outros índices secundários locais na tabela, todos os itens nesses índices com `ForumName` igual a "S3" também farão parte da coleção de itens.
Você pode usar qualquer uma das operações a seguir no DynamoDB para retornar informações sobre coleções de itens:
+ `BatchWriteItem`
+ `DeleteItem`
+ `PutItem`
+ `UpdateItem`
+ `TransactWriteItems`
Cada uma dessas operações é compatível com o parâmetro `ReturnItemCollectionMetrics`. Ao definir esse parâmetro como `SIZE`, você pode exibir informações sobre o tamanho de cada coleção de itens no índice.
**Example**
Este é um exemplo da saída de uma operação `UpdateItem` na tabela `Thread`, com `ReturnItemCollectionMetrics` definido como `SIZE`. O item que foi atualizado tinha um valor `ForumName` de "EC2", portanto, a saída inclui informações sobre essa coleção de itens.
```
{
ItemCollectionMetrics: {
ItemCollectionKey: {
ForumName: "EC2"
},
SizeEstimateRangeGB: [0.0, 1.0]
}
}
```
O objeto `SizeEstimateRangeGB` mostra que o tamanho dessa coleção de itens está entre 0 e 1 GB. O DynamoDB atualiza periodicamente essa estimativa de tamanho, portanto, os números podem ser diferentes na próxima vez em que o item é modificado.
### Limite de tamanho de conjunto de itens
O tamanho máximo de qualquer coleção de itens para uma tabela com um ou mais índices secundários locais é 10 GB. Isso não se aplica a coleções de itens em tabelas sem índices secundários locais e também não se aplica a coleções de itens em índices secundários globais. Apenas as tabelas que têm um ou mais índices secundários locais são afetadas.
Se uma coleção de itens exceder o limite de 10 GB, o DynamoDB pode retornar um `ItemCollectionSizeLimitExceededException`, e você não poderá adicionar mais itens à coleção de itens ou aumentar os tamanhos dos itens que estão na coleção de itens. (As operações de leitura e gravação que diminuem o tamanho da coleção de itens ainda são permitidas.) Você ainda pode adicionar itens a outras coleções de itens.
Para reduzir o tamanho de uma coleção de itens, você pode executar uma das seguintes ações:
+ Excluir todos os itens desnecessários com o valor da chave de partição em questão. Quando você exclui esses itens da tabela-base, o DynamoDB também remove todas as entradas do índice que têm o mesmo valor de chave de partição.
+ Atualize os itens, removendo atributos ou reduzindo o tamanho dos atributos. Se esses atributos forem projetados em qualquer índice secundário local, o DynamoDB também reduzirá o tamanho das entradas do índice correspondentes.
+ Crie uma nova tabela com a mesma chave de partição e chave de classificação e, em seguida, mova os itens da tabela antiga para a nova tabela. Essa pode ser uma boa abordagem, se uma tabela tiver dados históricos que são acessados com pouca frequência. Você também pode considerar arquivar esses dados históricos no Amazon Simple Storage Service (Amazon S3).
Quando o tamanho total da coleção de itens tornar-se inferior a 10 GB, você poderá adicionar itens novamente com o mesmo valor de chave de partição.
Recomendamos como uma melhor prática que você instrumente seu aplicativo para monitorar os tamanhos de suas coleções de itens. Uma maneira de fazer isso é definir o parâmetro `ReturnItemCollectionMetrics` como `SIZE` sempre que você usar `BatchWriteItem`, `DeleteItem`, `PutItem` ou `UpdateItem`. Seu aplicativo deve examinar o objeto `ReturnItemCollectionMetrics` na saída e gerar uma mensagem de erro sempre que uma coleção de itens exceder um limite definido pelo usuário (por exemplo, 8 GB). Configurar um limite menor que 10 GB oferece um sistema de aviso antecipado para que você saiba que uma coleção de itens está se aproximando do limite a tempo de resolver o problema.
### Conjuntos de itens e partições
Em uma tabela com um ou mais índices secundários locais, uma coleção de itens é armazenada em uma partição. O tamanho total dessa coleção de itens é limitado à capacidade dessa partição: 10 GB. Para uma aplicação em que o modelo de dados inclui coleções de itens de tamanho ilimitado ou na qual a expectativa é de que algumas coleções de itens aumentem além de 10 GB no futuro, pense em usar um índice secundário global.
Você deve criar seus aplicativos para que os dados da tabela sejam distribuídos uniformemente entre diferentes valores de chave de partição. Para tabelas com índices secundários locais, seus aplicativos não devem criar pontos de atividade de leitura e gravação em uma única coleção de itens em uma única partição.
# Como trabalhar com índices secundários locais: Java
Você pode usar a API de documentos do AWS SDK para Java para criar uma tabela do Amazon DynamoDB com um ou mais índices secundários locais na tabela e executar consultas usando os índices.
Veja a seguir as etapas comuns para operações de tabela usando a API de documento do AWS SDK para Java.
1. Crie uma instância da classe `DynamoDB`.
1. Forneça os parâmetros obrigatórios e opcionais para a operação, criando os objetos de solicitação correspondentes.
1. Chame o método apropriado fornecido pelo cliente que você criou na etapa anterior.
**Topics**
+ [Criar uma tabela com um índice secundário local](#LSIJavaDocumentAPI.CreateTableWithIndex)
+ [Descrever uma tabela com um índice secundário local](#LSIJavaDocumentAPI.DescribeTableWithIndex)
+ [Consultar um índice secundário local](#LSIJavaDocumentAPI.QueryAnIndex)
+ [Exemplo: índices secundários locais que usam a API de documentos do Java](LSIJavaDocumentAPI.Example.md)
## Criar uma tabela com um índice secundário local
Os índices secundários locais devem ser criados ao mesmo tempo que uma tabela é criada. Para fazer isso, use o método `createTable` e forneça suas especificações para um ou mais índices secundários locais. O exemplo de código Java a seguir cria uma tabela para armazenar informações sobre músicas em uma coleção de músicas. A chave de partição é `Artist` e a chave de classificação é `SongTitle`. Um índice secundário, `AlbumTitleIndex`, facilita consultas por título de álbum.
Veja a seguir as etapas necessárias para criar uma tabela com um índice secundário local usando a API de documentos do DynamoDB.
1. Crie uma instância da classe `DynamoDB`.
1. Crie uma instância da classe `CreateTableRequest` para fornecer as informações solicitadas.
Você deve fornecer o nome da tabela, sua chave primária e os valores de throughput provisionado. Para o índice secundário local, você deve fornecer o nome do índice, o nome e o tipo de dados da chave de classificação do índice, o esquema de chave para o índice e a projeção de atributos.
1. Chame o método `createTable`, fornecendo o objeto de solicitação como um parâmetro.
O exemplo de código Java a seguir demonstra as etapas anteriores. O código cria uma tabela (`Music`) com um índice secundário no atributo `AlbumTitle`. A chave de partição de tabela e a chave de classificação, bem como a chave de classificação de índice, são os únicos atributos projetados para o índice.
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);
String tableName = "Music";
CreateTableRequest createTableRequest = new CreateTableRequest().withTableName(tableName);
//ProvisionedThroughput
createTableRequest.setProvisionedThroughput(new ProvisionedThroughput().withReadCapacityUnits((long)5).withWriteCapacityUnits((long)5));
//AttributeDefinitions
ArrayList attributeDefinitions= new ArrayList();
attributeDefinitions.add(new AttributeDefinition().withAttributeName("Artist").withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition().withAttributeName("SongTitle").withAttributeType("S"));
attributeDefinitions.add(new AttributeDefinition().withAttributeName("AlbumTitle").withAttributeType("S"));
createTableRequest.setAttributeDefinitions(attributeDefinitions);
//KeySchema
ArrayList tableKeySchema = new ArrayList();
tableKeySchema.add(new KeySchemaElement().withAttributeName("Artist").withKeyType(KeyType.HASH)); //Partition key
tableKeySchema.add(new KeySchemaElement().withAttributeName("SongTitle").withKeyType(KeyType.RANGE)); //Sort key
createTableRequest.setKeySchema(tableKeySchema);
ArrayList indexKeySchema = new ArrayList();
indexKeySchema.add(new KeySchemaElement().withAttributeName("Artist").withKeyType(KeyType.HASH)); //Partition key
indexKeySchema.add(new KeySchemaElement().withAttributeName("AlbumTitle").withKeyType(KeyType.RANGE)); //Sort key
Projection projection = new Projection().withProjectionType(ProjectionType.INCLUDE);
ArrayList nonKeyAttributes = new ArrayList();
nonKeyAttributes.add("Genre");
nonKeyAttributes.add("Year");
projection.setNonKeyAttributes(nonKeyAttributes);
LocalSecondaryIndex localSecondaryIndex = new LocalSecondaryIndex()
.withIndexName("AlbumTitleIndex").withKeySchema(indexKeySchema).withProjection(projection);
ArrayList localSecondaryIndexes = new ArrayList();
localSecondaryIndexes.add(localSecondaryIndex);
createTableRequest.setLocalSecondaryIndexes(localSecondaryIndexes);
Table table = dynamoDB.createTable(createTableRequest);
System.out.println(table.getDescription());
```
Você deve aguardar até que o DynamoDB crie a tabela e defina o status dessa tabela como `ACTIVE`. Depois disso, você poderá começar a inserir itens de dados na tabela.
## Descrever uma tabela com um índice secundário local
Para obter mais informações sobre índices secundários locais em uma tabela, use o método `describeTable`. Para cada índice, você pode acessar seu nome, esquema de chaves e atributos projetados.
Veja a seguir as etapas para acessar informações do índice secundário local de uma tabela usando a API de documento do AWS SDK para Java.
1. Crie uma instância da classe `DynamoDB`.
1. Crie uma instância da classe `Table`. Você deve fornecer o nome da tabela.
1. Chame o método `describeTable` no objeto `Table`.
O exemplo de código Java a seguir demonstra as etapas anteriores.
**Example**
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);
String tableName = "Music";
Table table = dynamoDB.getTable(tableName);
TableDescription tableDescription = table.describe();
List localSecondaryIndexes
= tableDescription.getLocalSecondaryIndexes();
// This code snippet will work for multiple indexes, even though
// there is only one index in this example.
Iterator lsiIter = localSecondaryIndexes.iterator();
while (lsiIter.hasNext()) {
LocalSecondaryIndexDescription lsiDescription = lsiIter.next();
System.out.println("Info for index " + lsiDescription.getIndexName() + ":");
Iterator kseIter = lsiDescription.getKeySchema().iterator();
while (kseIter.hasNext()) {
KeySchemaElement kse = kseIter.next();
System.out.printf("\t%s: %s\n", kse.getAttributeName(), kse.getKeyType());
}
Projection projection = lsiDescription.getProjection();
System.out.println("\tThe projection type is: " + projection.getProjectionType());
if (projection.getProjectionType().toString().equals("INCLUDE")) {
System.out.println("\t\tThe non-key projected attributes are: " + projection.getNonKeyAttributes());
}
}
```
## Consultar um índice secundário local
Você pode usar a operação `Query` em um índice secundário local de forma semelhante ao uso de `Query` em uma tabela. Você deve especificar o nome do índice, os critérios de consulta da chave de classificação do índice e os atributos que deseja retornar. Neste exemplo, o índice é `AlbumTitleIndex` e a chave de classificação do índice é `AlbumTitle`.
Os únicos atributos retornados são aqueles que foram projetados no índice. É possível modificar essa consulta para selecionar atributos não chave também, mas isso exigiria atividades de busca de tabela que são relativamente caras. Para obter mais informações sobre buscas de tabela, consulte [Projeções de atributo](LSI.md#LSI.Projections).
Veja a seguir as etapas para consultar um índice secundário local usando a API de documento do AWS SDK para Java.
1. Crie uma instância da classe `DynamoDB`.
1. Crie uma instância da classe `Table`. Você deve fornecer o nome da tabela.
1. Crie uma instância da classe `Index`. Você deve fornecer o nome do índice.
1. Chame o método `query` da classe `Index`.
O exemplo de código Java a seguir demonstra as etapas anteriores.
**Example**
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);
String tableName = "Music";
Table table = dynamoDB.getTable(tableName);
Index index = table.getIndex("AlbumTitleIndex");
QuerySpec spec = new QuerySpec()
.withKeyConditionExpression("Artist = :v_artist and AlbumTitle = :v_title")
.withValueMap(new ValueMap()
.withString(":v_artist", "Acme Band")
.withString(":v_title", "Songs About Life"));
ItemCollection items = index.query(spec);
Iterator
- itemsIter = items.iterator();
while (itemsIter.hasNext()) {
Item item = itemsIter.next();
System.out.println(item.toJSONPretty());
}
```
### Leituras consistentes em um índice secundário local
Ao contrário dos índices secundários globais, que permitem leituras finais consistentes, o índice secundário local permite leituras altamente consistentes. Uma leitura fortemente consistente de um índice secundário local sempre retorna os valores atualizados mais recentes. Se a consulta precisar buscar atributos adicionais na tabela base, esses atributos também serão consistentes com relação ao índice.
Por padrão, `Query` usa leituras finais consistentes. Para solicitar uma leitura altamente consistente, defina `ConsistentRead` como `true` em `QuerySpec`. O exemplo a seguir consulta `AlbumTitleIndex` usando uma leitura altamente consistente:
**Example**
```
QuerySpec spec = new QuerySpec()
.withKeyConditionExpression("Artist = :v_artist and AlbumTitle = :v_title")
.withValueMap(new ValueMap()
.withString(":v_artist", "Acme Band")
.withString(":v_title", "Songs About Life"))
.withConsistentRead(true);
```
**nota**
Uma leitura altamente consistente consome 1 unidade de capacidade de leitura por 4 KB de dados exibidos (arredondados para cima), enquanto uma leitura final consistente consome metade disso. Por exemplo, uma leitura altamente consistente que exibe 9 KB de dados consome 3 unidades de capacidade de leitura (9 KB/4 KB = 2,25, arredondado para 3), enquanto a mesma consulta usando uma leitura final consistente consome 1,5 unidade de capacidade de leitura. Se sua aplicação admitir a leitura de dados que possam estar um pouco obsoletos, use leituras finais consistentes para reduzir o uso da capacidade de leitura. Para obter mais informações, consulte [Unidades de capacidade de leitura](LSI.md#LSI.ThroughputConsiderations.Reads).
# Exemplo: índices secundários locais que usam a API de documentos do Java
O exemplo de código Java a seguir mostra como trabalhar com índices secundários locais no Amazon DynamoDB. O exemplo cria uma tabela chamada `CustomerOrders` com uma chave de partição `CustomerId` e uma chave de classificação `OrderId`. Há dois índices secundários locais nessa tabela:
+ `OrderCreationDateIndex`: a chave de classificação é `OrderCreationDate`, e os seguintes atributos são projetados no índice:
+ `ProductCategory`
+ `ProductName`
+ `OrderStatus`
+ `ShipmentTrackingId`
+ `IsOpenIndex`: a chave de classificação é `IsOpen`, e todos os atributos da tabela estão projetados no índice.
Depois que a tabela `CustomerOrders` é criada, o programa carrega a tabela com os dados que representam pedidos de clientes. Ele então consulta os dados usando os índices secundários globais. Por fim, o programa exclui a tabela `CustomerOrders`.
Para obter instruções detalhadas sobre como testar o exemplo a seguir, consulte [Exemplos de código Java](CodeSamples.Java.md).
**Example**
```
package com.example.dynamodb;
import software.amazon.awssdk.core.waiters.WaiterResponse;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.*;
import software.amazon.awssdk.services.dynamodb.waiters.DynamoDbWaiter;
import java.util.HashMap;
import java.util.Map;
public class DocumentAPILocalSecondaryIndexExample {
static DynamoDbClient client = DynamoDbClient.create();
public static String tableName = "CustomerOrders";
public static void main(String[] args) {
createTable();
loadData();
query(null);
query("IsOpenIndex");
query("OrderCreationDateIndex");
deleteTable(tableName);
}
public static void createTable() {
CreateTableRequest request = CreateTableRequest.builder()
.tableName(tableName)
.provisionedThroughput(ProvisionedThroughput.builder()
.readCapacityUnits(1L)
.writeCapacityUnits(1L)
.build())
.attributeDefinitions(
AttributeDefinition.builder().attributeName("CustomerId").attributeType(ScalarAttributeType.S).build(),
AttributeDefinition.builder().attributeName("OrderId").attributeType(ScalarAttributeType.N).build(),
AttributeDefinition.builder().attributeName("OrderCreationDate").attributeType(ScalarAttributeType.N).build(),
AttributeDefinition.builder().attributeName("IsOpen").attributeType(ScalarAttributeType.N).build())
.keySchema(
KeySchemaElement.builder().attributeName("CustomerId").keyType(KeyType.HASH).build(),
KeySchemaElement.builder().attributeName("OrderId").keyType(KeyType.RANGE).build())
.localSecondaryIndexes(
LocalSecondaryIndex.builder()
.indexName("OrderCreationDateIndex")
.keySchema(
KeySchemaElement.builder().attributeName("CustomerId").keyType(KeyType.HASH).build(),
KeySchemaElement.builder().attributeName("OrderCreationDate").keyType(KeyType.RANGE).build())
.projection(Projection.builder()
.projectionType(ProjectionType.INCLUDE)
.nonKeyAttributes("ProductCategory", "ProductName")
.build())
.build(),
LocalSecondaryIndex.builder()
.indexName("IsOpenIndex")
.keySchema(
KeySchemaElement.builder().attributeName("CustomerId").keyType(KeyType.HASH).build(),
KeySchemaElement.builder().attributeName("IsOpen").keyType(KeyType.RANGE).build())
.projection(Projection.builder()
.projectionType(ProjectionType.ALL)
.build())
.build())
.build();
System.out.println("Creating table " + tableName + "...");
client.createTable(request);
try (DynamoDbWaiter waiter = client.waiter()) {
WaiterResponse response = waiter.waitUntilTableExists(r -> r.tableName(tableName));
response.matched().response().ifPresent(System.out::println);
}
}
public static void query(String indexName) {
System.out.println("\n***********************************************************\n");
System.out.println("Querying table " + tableName + "...");
if ("IsOpenIndex".equals(indexName)) {
System.out.println("\nUsing index: '" + indexName + "': Bob's orders that are open.");
System.out.println("Only a user-specified list of attributes are returned\n");
Map values = new HashMap<>();
values.put(":v_custid", AttributeValue.builder().s("bob@example.com").build());
values.put(":v_isopen", AttributeValue.builder().n("1").build());
QueryRequest request = QueryRequest.builder()
.tableName(tableName)
.indexName(indexName)
.keyConditionExpression("CustomerId = :v_custid and IsOpen = :v_isopen")
.expressionAttributeValues(values)
.projectionExpression("OrderCreationDate, ProductCategory, ProductName, OrderStatus")
.build();
System.out.println("Query: printing results...");
client.query(request).items().forEach(System.out::println);
} else if ("OrderCreationDateIndex".equals(indexName)) {
System.out.println("\nUsing index: '" + indexName + "': Bob's orders that were placed after 01/31/2015.");
System.out.println("Only the projected attributes are returned\n");
Map values = new HashMap<>();
values.put(":v_custid", AttributeValue.builder().s("bob@example.com").build());
values.put(":v_orddate", AttributeValue.builder().n("20150131").build());
QueryRequest request = QueryRequest.builder()
.tableName(tableName)
.indexName(indexName)
.keyConditionExpression("CustomerId = :v_custid and OrderCreationDate >= :v_orddate")
.expressionAttributeValues(values)
.select(Select.ALL_PROJECTED_ATTRIBUTES)
.build();
System.out.println("Query: printing results...");
client.query(request).items().forEach(System.out::println);
} else {
System.out.println("\nNo index: All of Bob's orders, by OrderId:\n");
Map values = new HashMap<>();
values.put(":v_custid", AttributeValue.builder().s("bob@example.com").build());
QueryRequest request = QueryRequest.builder()
.tableName(tableName)
.keyConditionExpression("CustomerId = :v_custid")
.expressionAttributeValues(values)
.build();
System.out.println("Query: printing results...");
client.query(request).items().forEach(System.out::println);
}
}
public static void deleteTable(String tableName) {
System.out.println("Deleting table " + tableName + "...");
client.deleteTable(DeleteTableRequest.builder().tableName(tableName).build());
try (DynamoDbWaiter waiter = client.waiter()) {
waiter.waitUntilTableNotExists(r -> r.tableName(tableName));
}
}
public static void loadData() {
System.out.println("Loading data into table " + tableName + "...");
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("alice@example.com").build(),
"OrderId", AttributeValue.builder().n("1").build(),
"IsOpen", AttributeValue.builder().n("1").build(),
"OrderCreationDate", AttributeValue.builder().n("20150101").build(),
"ProductCategory", AttributeValue.builder().s("Book").build(),
"ProductName", AttributeValue.builder().s("The Great Outdoors").build(),
"OrderStatus", AttributeValue.builder().s("PACKING ITEMS").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("alice@example.com").build(),
"OrderId", AttributeValue.builder().n("2").build(),
"IsOpen", AttributeValue.builder().n("1").build(),
"OrderCreationDate", AttributeValue.builder().n("20150221").build(),
"ProductCategory", AttributeValue.builder().s("Bike").build(),
"ProductName", AttributeValue.builder().s("Super Mountain").build(),
"OrderStatus", AttributeValue.builder().s("ORDER RECEIVED").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("alice@example.com").build(),
"OrderId", AttributeValue.builder().n("3").build(),
"OrderCreationDate", AttributeValue.builder().n("20150304").build(),
"ProductCategory", AttributeValue.builder().s("Music").build(),
"ProductName", AttributeValue.builder().s("A Quiet Interlude").build(),
"OrderStatus", AttributeValue.builder().s("IN TRANSIT").build(),
"ShipmentTrackingId", AttributeValue.builder().s("176493").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("1").build(),
"OrderCreationDate", AttributeValue.builder().n("20150111").build(),
"ProductCategory", AttributeValue.builder().s("Movie").build(),
"ProductName", AttributeValue.builder().s("Calm Before The Storm").build(),
"OrderStatus", AttributeValue.builder().s("SHIPPING DELAY").build(),
"ShipmentTrackingId", AttributeValue.builder().s("859323").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("2").build(),
"OrderCreationDate", AttributeValue.builder().n("20150124").build(),
"ProductCategory", AttributeValue.builder().s("Music").build(),
"ProductName", AttributeValue.builder().s("E-Z Listening").build(),
"OrderStatus", AttributeValue.builder().s("DELIVERED").build(),
"ShipmentTrackingId", AttributeValue.builder().s("756943").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("3").build(),
"OrderCreationDate", AttributeValue.builder().n("20150221").build(),
"ProductCategory", AttributeValue.builder().s("Music").build(),
"ProductName", AttributeValue.builder().s("Symphony 9").build(),
"OrderStatus", AttributeValue.builder().s("DELIVERED").build(),
"ShipmentTrackingId", AttributeValue.builder().s("645193").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("4").build(),
"IsOpen", AttributeValue.builder().n("1").build(),
"OrderCreationDate", AttributeValue.builder().n("20150222").build(),
"ProductCategory", AttributeValue.builder().s("Hardware").build(),
"ProductName", AttributeValue.builder().s("Extra Heavy Hammer").build(),
"OrderStatus", AttributeValue.builder().s("PACKING ITEMS").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("5").build(),
"OrderCreationDate", AttributeValue.builder().n("20150309").build(),
"ProductCategory", AttributeValue.builder().s("Book").build(),
"ProductName", AttributeValue.builder().s("How To Cook").build(),
"OrderStatus", AttributeValue.builder().s("IN TRANSIT").build(),
"ShipmentTrackingId", AttributeValue.builder().s("440185").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("6").build(),
"OrderCreationDate", AttributeValue.builder().n("20150318").build(),
"ProductCategory", AttributeValue.builder().s("Luggage").build(),
"ProductName", AttributeValue.builder().s("Really Big Suitcase").build(),
"OrderStatus", AttributeValue.builder().s("DELIVERED").build(),
"ShipmentTrackingId", AttributeValue.builder().s("893927").build()));
putItem(Map.of(
"CustomerId", AttributeValue.builder().s("bob@example.com").build(),
"OrderId", AttributeValue.builder().n("7").build(),
"OrderCreationDate", AttributeValue.builder().n("20150324").build(),
"ProductCategory", AttributeValue.builder().s("Golf").build(),
"ProductName", AttributeValue.builder().s("PGA Pro II").build(),
"OrderStatus", AttributeValue.builder().s("OUT FOR DELIVERY").build(),
"ShipmentTrackingId", AttributeValue.builder().s("383283").build()));
}
private static void putItem(Map item) {
client.putItem(PutItemRequest.builder().tableName(tableName).item(item).build());
}
}
```
# Como trabalhar com índices secundários locais: .NET
**Topics**
+ [Criar uma tabela com um índice secundário local](#LSILowLevelDotNet.CreateTableWithIndex)
+ [Descrever uma tabela com um índice secundário local](#LSILowLevelDotNet.DescribeTableWithIndex)
+ [Consultar um índice secundário local](#LSILowLevelDotNet.QueryAnIndex)
+ [Exemplo: índices secundários locais que usam a API de baixo nível do AWS SDK para .NET](LSILowLevelDotNet.Example.md)
Você pode usar a API de baixo nível do AWS SDK para .NET para criar uma tabela do Amazon DynamoDB com um ou mais índices secundários locais na tabela e executar consultas usando os índices. Essas operações são mapeadas nas ações correspondentes da API de baixo nível do DynamoDB. Para obter mais informações, consulte [Exemplos de código .NET](CodeSamples.DotNet.md).
Veja a seguir as etapas comuns para operações de tabela usando a API de baixo nível do .NET.
1. Crie uma instância da classe `AmazonDynamoDBClient`.
1. Forneça os parâmetros obrigatórios e opcionais para a operação, criando os objetos de solicitação correspondentes.
Por exemplo, crie um objeto `CreateTableRequest` para criar uma tabela e crie um objeto `QueryRequest` para consultar uma tabela ou um índice.
1. Execute o método apropriado fornecido pelo cliente que você criou na etapa anterior.
## Criar uma tabela com um índice secundário local
Os índices secundários locais devem ser criados ao mesmo tempo que uma tabela é criada. Para fazer isso, use `CreateTable` e forneça suas especificações para um ou mais índices secundários locais. O exemplo de código C\$1 a seguir cria uma tabela para armazenar informações sobre músicas em uma coleção de músicas. A chave de partição é `Artist` e a chave de classificação é `SongTitle`. Um índice secundário, `AlbumTitleIndex`, facilita consultas por título de álbum.
Veja a seguir as etapas necessárias para criar uma tabela com um índice secundário local usando a API de baixo nível do .NET.
1. Crie uma instância da classe `AmazonDynamoDBClient`.
1. Crie uma instância da classe `CreateTableRequest` para fornecer as informações solicitadas.
Você deve fornecer o nome da tabela, sua chave primária e os valores de throughput provisionado. Para o índice secundário local, você deve fornecer o nome do índice, o nome e o tipo de dados da chave de classificação do índice, o esquema de chave para o índice e a projeção de atributos.
1. Execute o método `CreateTable` fornecendo o objeto de solicitação como um parâmetro.
O exemplo de código C\$1 a seguir demonstra as etapas anteriores. O código cria uma tabela (`Music`) com um índice secundário no atributo `AlbumTitle`. A chave de partição de tabela e a chave de classificação, bem como a chave de classificação de índice, são os únicos atributos projetados para o índice.
```
AmazonDynamoDBClient client = new AmazonDynamoDBClient();
string tableName = "Music";
CreateTableRequest createTableRequest = new CreateTableRequest()
{
TableName = tableName
};
//ProvisionedThroughput
createTableRequest.ProvisionedThroughput = new ProvisionedThroughput()
{
ReadCapacityUnits = (long)5,
WriteCapacityUnits = (long)5
};
//AttributeDefinitions
List attributeDefinitions = new List();
attributeDefinitions.Add(new AttributeDefinition()
{
AttributeName = "Artist",
AttributeType = "S"
});
attributeDefinitions.Add(new AttributeDefinition()
{
AttributeName = "SongTitle",
AttributeType = "S"
});
attributeDefinitions.Add(new AttributeDefinition()
{
AttributeName = "AlbumTitle",
AttributeType = "S"
});
createTableRequest.AttributeDefinitions = attributeDefinitions;
//KeySchema
List tableKeySchema = new List();
tableKeySchema.Add(new KeySchemaElement() { AttributeName = "Artist", KeyType = "HASH" }); //Partition key
tableKeySchema.Add(new KeySchemaElement() { AttributeName = "SongTitle", KeyType = "RANGE" }); //Sort key
createTableRequest.KeySchema = tableKeySchema;
List indexKeySchema = new List();
indexKeySchema.Add(new KeySchemaElement() { AttributeName = "Artist", KeyType = "HASH" }); //Partition key
indexKeySchema.Add(new KeySchemaElement() { AttributeName = "AlbumTitle", KeyType = "RANGE" }); //Sort key
Projection projection = new Projection() { ProjectionType = "INCLUDE" };
List nonKeyAttributes = new List();
nonKeyAttributes.Add("Genre");
nonKeyAttributes.Add("Year");
projection.NonKeyAttributes = nonKeyAttributes;
LocalSecondaryIndex localSecondaryIndex = new LocalSecondaryIndex()
{
IndexName = "AlbumTitleIndex",
KeySchema = indexKeySchema,
Projection = projection
};
List localSecondaryIndexes = new List();
localSecondaryIndexes.Add(localSecondaryIndex);
createTableRequest.LocalSecondaryIndexes = localSecondaryIndexes;
CreateTableResponse result = client.CreateTable(createTableRequest);
Console.WriteLine(result.CreateTableResult.TableDescription.TableName);
Console.WriteLine(result.CreateTableResult.TableDescription.TableStatus);
```
Você deve aguardar até que o DynamoDB crie a tabela e defina o status dessa tabela como `ACTIVE`. Depois disso, você poderá começar a inserir itens de dados na tabela.
## Descrever uma tabela com um índice secundário local
Para obter mais informações sobre índices secundários locais em uma tabela, use a API `DescribeTable`. Para cada índice, você pode acessar seu nome, esquema de chaves e atributos projetados.
Veja a seguir as etapas para acessar informações do índice secundário local para uma tabela usando a API de baixo nível do .NET.
1. Crie uma instância da classe `AmazonDynamoDBClient`.
1. Crie uma instância da classe `DescribeTableRequest` para fornecer as informações solicitadas. Você deve fornecer o nome da tabela.
1. Execute o método `describeTable` fornecendo o objeto de solicitação como um parâmetro.
O exemplo de código C\$1 a seguir demonstra as etapas anteriores.
**Example**
```
AmazonDynamoDBClient client = new AmazonDynamoDBClient();
string tableName = "Music";
DescribeTableResponse response = client.DescribeTable(new DescribeTableRequest() { TableName = tableName });
List localSecondaryIndexes =
response.DescribeTableResult.Table.LocalSecondaryIndexes;
// This code snippet will work for multiple indexes, even though
// there is only one index in this example.
foreach (LocalSecondaryIndexDescription lsiDescription in localSecondaryIndexes)
{
Console.WriteLine("Info for index " + lsiDescription.IndexName + ":");
foreach (KeySchemaElement kse in lsiDescription.KeySchema)
{
Console.WriteLine("\t" + kse.AttributeName + ": key type is " + kse.KeyType);
}
Projection projection = lsiDescription.Projection;
Console.WriteLine("\tThe projection type is: " + projection.ProjectionType);
if (projection.ProjectionType.ToString().Equals("INCLUDE"))
{
Console.WriteLine("\t\tThe non-key projected attributes are:");
foreach (String s in projection.NonKeyAttributes)
{
Console.WriteLine("\t\t" + s);
}
}
}
```
## Consultar um índice secundário local
Você pode usar `Query` em um índice secundário local de forma semelhante ao uso de `Query` em uma tabela. Você deve especificar o nome do índice, os critérios de consulta da chave de classificação do índice e os atributos que deseja retornar. Neste exemplo, o índice é `AlbumTitleIndex` e a chave de classificação do índice é `AlbumTitle`.
Os únicos atributos retornados são aqueles que foram projetados no índice. É possível modificar essa consulta para selecionar atributos não chave também, mas isso exigiria atividades de busca de tabela que são relativamente caras. Para obter mais informações sobre buscas de tabela, consulte [Projeções de atributo](LSI.md#LSI.Projections)
Veja a seguir as etapas para consultar um índice secundário local usando a API de baixo nível do .NET.
1. Crie uma instância da classe `AmazonDynamoDBClient`.
1. Crie uma instância da classe `QueryRequest` para fornecer as informações solicitadas.
1. Execute o método `query` fornecendo o objeto de solicitação como um parâmetro.
O exemplo de código C\$1 a seguir demonstra as etapas anteriores.
**Example**
```
QueryRequest queryRequest = new QueryRequest
{
TableName = "Music",
IndexName = "AlbumTitleIndex",
Select = "ALL_ATTRIBUTES",
ScanIndexForward = true,
KeyConditionExpression = "Artist = :v_artist and AlbumTitle = :v_title",
ExpressionAttributeValues = new Dictionary()
{
{":v_artist",new AttributeValue {S = "Acme Band"}},
{":v_title",new AttributeValue {S = "Songs About Life"}}
},
};
QueryResponse response = client.Query(queryRequest);
foreach (var attribs in response.Items)
{
foreach (var attrib in attribs)
{
Console.WriteLine(attrib.Key + " ---> " + attrib.Value.S);
}
Console.WriteLine();
}
```
# Exemplo: índices secundários locais que usam a API de baixo nível do AWS SDK para .NET
O exemplo de código C\$1 a seguir mostra como trabalhar com índices secundários locais no Amazon DynamoDB. O exemplo cria uma tabela chamada `CustomerOrders` com uma chave de partição `CustomerId` e uma chave de classificação `OrderId`. Há dois índices secundários locais nessa tabela:
+ `OrderCreationDateIndex`: a chave de classificação é `OrderCreationDate`, e os seguintes atributos são projetados no índice:
+ `ProductCategory`
+ `ProductName`
+ `OrderStatus`
+ `ShipmentTrackingId`
+ `IsOpenIndex`: a chave de classificação é `IsOpen`, e todos os atributos da tabela estão projetados no índice.
Depois que a tabela `CustomerOrders` é criada, o programa carrega a tabela com os dados que representam pedidos de clientes. Ele então consulta os dados usando os índices secundários globais. Por fim, o programa exclui a tabela `CustomerOrders`.
Para obter instruções passo a passo sobre como testar o exemplo a seguir, consulte [Exemplos de código .NET](CodeSamples.DotNet.md).
**Example**
```
using System;
using System.Collections.Generic;
using System.Linq;
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.DataModel;
using Amazon.DynamoDBv2.DocumentModel;
using Amazon.DynamoDBv2.Model;
using Amazon.Runtime;
using Amazon.SecurityToken;
namespace com.amazonaws.codesamples
{
class LowLevelLocalSecondaryIndexExample
{
private static AmazonDynamoDBClient client = new AmazonDynamoDBClient();
private static string tableName = "CustomerOrders";
static void Main(string[] args)
{
try
{
CreateTable();
LoadData();
Query(null);
Query("IsOpenIndex");
Query("OrderCreationDateIndex");
DeleteTable(tableName);
Console.WriteLine("To continue, press Enter");
Console.ReadLine();
}
catch (AmazonDynamoDBException e) { Console.WriteLine(e.Message); }
catch (AmazonServiceException e) { Console.WriteLine(e.Message); }
catch (Exception e) { Console.WriteLine(e.Message); }
}
private static void CreateTable()
{
var createTableRequest =
new CreateTableRequest()
{
TableName = tableName,
ProvisionedThroughput =
new ProvisionedThroughput()
{
ReadCapacityUnits = (long)1,
WriteCapacityUnits = (long)1
}
};
var attributeDefinitions = new List()
{
// Attribute definitions for table primary key
{ new AttributeDefinition() {
AttributeName = "CustomerId", AttributeType = "S"
} },
{ new AttributeDefinition() {
AttributeName = "OrderId", AttributeType = "N"
} },
// Attribute definitions for index primary key
{ new AttributeDefinition() {
AttributeName = "OrderCreationDate", AttributeType = "N"
} },
{ new AttributeDefinition() {
AttributeName = "IsOpen", AttributeType = "N"
}}
};
createTableRequest.AttributeDefinitions = attributeDefinitions;
// Key schema for table
var tableKeySchema = new List()
{
{ new KeySchemaElement() {
AttributeName = "CustomerId", KeyType = "HASH"
} }, //Partition key
{ new KeySchemaElement() {
AttributeName = "OrderId", KeyType = "RANGE"
} } //Sort key
};
createTableRequest.KeySchema = tableKeySchema;
var localSecondaryIndexes = new List();
// OrderCreationDateIndex
LocalSecondaryIndex orderCreationDateIndex = new LocalSecondaryIndex()
{
IndexName = "OrderCreationDateIndex"
};
// Key schema for OrderCreationDateIndex
var indexKeySchema = new List()
{
{ new KeySchemaElement() {
AttributeName = "CustomerId", KeyType = "HASH"
} }, //Partition key
{ new KeySchemaElement() {
AttributeName = "OrderCreationDate", KeyType = "RANGE"
} } //Sort key
};
orderCreationDateIndex.KeySchema = indexKeySchema;
// Projection (with list of projected attributes) for
// OrderCreationDateIndex
var projection = new Projection()
{
ProjectionType = "INCLUDE"
};
var nonKeyAttributes = new List()
{
"ProductCategory",
"ProductName"
};
projection.NonKeyAttributes = nonKeyAttributes;
orderCreationDateIndex.Projection = projection;
localSecondaryIndexes.Add(orderCreationDateIndex);
// IsOpenIndex
LocalSecondaryIndex isOpenIndex
= new LocalSecondaryIndex()
{
IndexName = "IsOpenIndex"
};
// Key schema for IsOpenIndex
indexKeySchema = new List()
{
{ new KeySchemaElement() {
AttributeName = "CustomerId", KeyType = "HASH"
}}, //Partition key
{ new KeySchemaElement() {
AttributeName = "IsOpen", KeyType = "RANGE"
}} //Sort key
};
// Projection (all attributes) for IsOpenIndex
projection = new Projection()
{
ProjectionType = "ALL"
};
isOpenIndex.KeySchema = indexKeySchema;
isOpenIndex.Projection = projection;
localSecondaryIndexes.Add(isOpenIndex);
// Add index definitions to CreateTable request
createTableRequest.LocalSecondaryIndexes = localSecondaryIndexes;
Console.WriteLine("Creating table " + tableName + "...");
client.CreateTable(createTableRequest);
WaitUntilTableReady(tableName);
}
public static void Query(string indexName)
{
Console.WriteLine("\n***********************************************************\n");
Console.WriteLine("Querying table " + tableName + "...");
QueryRequest queryRequest = new QueryRequest()
{
TableName = tableName,
ConsistentRead = true,
ScanIndexForward = true,
ReturnConsumedCapacity = "TOTAL"
};
String keyConditionExpression = "CustomerId = :v_customerId";
Dictionary expressionAttributeValues = new Dictionary {
{":v_customerId", new AttributeValue {
S = "bob@example.com"
}}
};
if (indexName == "IsOpenIndex")
{
Console.WriteLine("\nUsing index: '" + indexName
+ "': Bob's orders that are open.");
Console.WriteLine("Only a user-specified list of attributes are returned\n");
queryRequest.IndexName = indexName;
keyConditionExpression += " and IsOpen = :v_isOpen";
expressionAttributeValues.Add(":v_isOpen", new AttributeValue
{
N = "1"
});
// ProjectionExpression
queryRequest.ProjectionExpression = "OrderCreationDate, ProductCategory, ProductName, OrderStatus";
}
else if (indexName == "OrderCreationDateIndex")
{
Console.WriteLine("\nUsing index: '" + indexName
+ "': Bob's orders that were placed after 01/31/2013.");
Console.WriteLine("Only the projected attributes are returned\n");
queryRequest.IndexName = indexName;
keyConditionExpression += " and OrderCreationDate > :v_Date";
expressionAttributeValues.Add(":v_Date", new AttributeValue
{
N = "20130131"
});
// Select
queryRequest.Select = "ALL_PROJECTED_ATTRIBUTES";
}
else
{
Console.WriteLine("\nNo index: All of Bob's orders, by OrderId:\n");
}
queryRequest.KeyConditionExpression = keyConditionExpression;
queryRequest.ExpressionAttributeValues = expressionAttributeValues;
var result = client.Query(queryRequest);
var items = result.Items;
foreach (var currentItem in items)
{
foreach (string attr in currentItem.Keys)
{
if (attr == "OrderId" || attr == "IsOpen"
|| attr == "OrderCreationDate")
{
Console.WriteLine(attr + "---> " + currentItem[attr].N);
}
else
{
Console.WriteLine(attr + "---> " + currentItem[attr].S);
}
}
Console.WriteLine();
}
Console.WriteLine("\nConsumed capacity: " + result.ConsumedCapacity.CapacityUnits + "\n");
}
private static void DeleteTable(string tableName)
{
Console.WriteLine("Deleting table " + tableName + "...");
client.DeleteTable(new DeleteTableRequest()
{
TableName = tableName
});
WaitForTableToBeDeleted(tableName);
}
public static void LoadData()
{
Console.WriteLine("Loading data into table " + tableName + "...");
Dictionary item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "alice@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "1"
};
item["IsOpen"] = new AttributeValue
{
N = "1"
};
item["OrderCreationDate"] = new AttributeValue
{
N = "20130101"
};
item["ProductCategory"] = new AttributeValue
{
S = "Book"
};
item["ProductName"] = new AttributeValue
{
S = "The Great Outdoors"
};
item["OrderStatus"] = new AttributeValue
{
S = "PACKING ITEMS"
};
/* no ShipmentTrackingId attribute */
PutItemRequest putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "alice@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "2"
};
item["IsOpen"] = new AttributeValue
{
N = "1"
};
item["OrderCreationDate"] = new AttributeValue
{
N = "20130221"
};
item["ProductCategory"] = new AttributeValue
{
S = "Bike"
};
item["ProductName"] = new AttributeValue
{
S = "Super Mountain"
};
item["OrderStatus"] = new AttributeValue
{
S = "ORDER RECEIVED"
};
/* no ShipmentTrackingId attribute */
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "alice@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "3"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130304"
};
item["ProductCategory"] = new AttributeValue
{
S = "Music"
};
item["ProductName"] = new AttributeValue
{
S = "A Quiet Interlude"
};
item["OrderStatus"] = new AttributeValue
{
S = "IN TRANSIT"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "176493"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "1"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130111"
};
item["ProductCategory"] = new AttributeValue
{
S = "Movie"
};
item["ProductName"] = new AttributeValue
{
S = "Calm Before The Storm"
};
item["OrderStatus"] = new AttributeValue
{
S = "SHIPPING DELAY"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "859323"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "2"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130124"
};
item["ProductCategory"] = new AttributeValue
{
S = "Music"
};
item["ProductName"] = new AttributeValue
{
S = "E-Z Listening"
};
item["OrderStatus"] = new AttributeValue
{
S = "DELIVERED"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "756943"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "3"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130221"
};
item["ProductCategory"] = new AttributeValue
{
S = "Music"
};
item["ProductName"] = new AttributeValue
{
S = "Symphony 9"
};
item["OrderStatus"] = new AttributeValue
{
S = "DELIVERED"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "645193"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "4"
};
item["IsOpen"] = new AttributeValue
{
N = "1"
};
item["OrderCreationDate"] = new AttributeValue
{
N = "20130222"
};
item["ProductCategory"] = new AttributeValue
{
S = "Hardware"
};
item["ProductName"] = new AttributeValue
{
S = "Extra Heavy Hammer"
};
item["OrderStatus"] = new AttributeValue
{
S = "PACKING ITEMS"
};
/* no ShipmentTrackingId attribute */
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "5"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130309"
};
item["ProductCategory"] = new AttributeValue
{
S = "Book"
};
item["ProductName"] = new AttributeValue
{
S = "How To Cook"
};
item["OrderStatus"] = new AttributeValue
{
S = "IN TRANSIT"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "440185"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "6"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130318"
};
item["ProductCategory"] = new AttributeValue
{
S = "Luggage"
};
item["ProductName"] = new AttributeValue
{
S = "Really Big Suitcase"
};
item["OrderStatus"] = new AttributeValue
{
S = "DELIVERED"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "893927"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
item = new Dictionary();
item["CustomerId"] = new AttributeValue
{
S = "bob@example.com"
};
item["OrderId"] = new AttributeValue
{
N = "7"
};
/* no IsOpen attribute */
item["OrderCreationDate"] = new AttributeValue
{
N = "20130324"
};
item["ProductCategory"] = new AttributeValue
{
S = "Golf"
};
item["ProductName"] = new AttributeValue
{
S = "PGA Pro II"
};
item["OrderStatus"] = new AttributeValue
{
S = "OUT FOR DELIVERY"
};
item["ShipmentTrackingId"] = new AttributeValue
{
S = "383283"
};
putItemRequest = new PutItemRequest
{
TableName = tableName,
Item = item,
ReturnItemCollectionMetrics = "SIZE"
};
client.PutItem(putItemRequest);
}
private static void WaitUntilTableReady(string tableName)
{
string status = null;
// Let us wait until table is created. Call DescribeTable.
do
{
System.Threading.Thread.Sleep(5000); // Wait 5 seconds.
try
{
var res = client.DescribeTable(new DescribeTableRequest
{
TableName = tableName
});
Console.WriteLine("Table name: {0}, status: {1}",
res.Table.TableName,
res.Table.TableStatus);
status = res.Table.TableStatus;
}
catch (ResourceNotFoundException)
{
// DescribeTable is eventually consistent. So you might
// get resource not found. So we handle the potential exception.
}
} while (status != "ACTIVE");
}
private static void WaitForTableToBeDeleted(string tableName)
{
bool tablePresent = true;
while (tablePresent)
{
System.Threading.Thread.Sleep(5000); // Wait 5 seconds.
try
{
var res = client.DescribeTable(new DescribeTableRequest
{
TableName = tableName
});
Console.WriteLine("Table name: {0}, status: {1}",
res.Table.TableName,
res.Table.TableStatus);
}
catch (ResourceNotFoundException)
{
tablePresent = false;
}
}
}
}
}
```
# Trabalhar com índices secundários locais no DynamoDB usando a AWS CLI
Você pode usar a AWS CLI para criar uma tabela do Amazon DynamoDB com um ou mais índices secundários locais, descrever os índices na tabela e realizar consultas usando os índices.
**Topics**
+ [Criar uma tabela com um índice secundário local](#LCICli.CreateTableWithIndex)
+ [Descrever uma tabela com um índice secundário local](#LCICli.DescribeTableWithIndex)
+ [Consultar um índice secundário local](#LCICli.QueryAnIndex)
## Criar uma tabela com um índice secundário local
Os índices secundários locais devem ser criados ao mesmo tempo que uma tabela é criada. Para fazer isso, use o parâmetro `create-table` e forneça as especificações para um ou mais índices secundários locais. O exemplo a seguir cria uma tabela (`Music`) para armazenar informações sobre músicas em uma coleção de músicas. A chave de partição é `Artist` e a chave de classificação é `SongTitle`. Um índice secundário, `AlbumTitleIndex`, no atributo `AlbumTitle` facilita consultas por título de álbum.
```
aws dynamodb create-table \
--table-name Music \
--attribute-definitions AttributeName=Artist,AttributeType=S AttributeName=SongTitle,AttributeType=S \
AttributeName=AlbumTitle,AttributeType=S \
--key-schema AttributeName=Artist,KeyType=HASH AttributeName=SongTitle,KeyType=RANGE \
--provisioned-throughput \
ReadCapacityUnits=10,WriteCapacityUnits=5 \
--local-secondary-indexes \
"[{\"IndexName\": \"AlbumTitleIndex\",
\"KeySchema\":[{\"AttributeName\":\"Artist\",\"KeyType\":\"HASH\"},
{\"AttributeName\":\"AlbumTitle\",\"KeyType\":\"RANGE\"}],
\"Projection\":{\"ProjectionType\":\"INCLUDE\", \"NonKeyAttributes\":[\"Genre\", \"Year\"]}}]"
```
Você deve aguardar até que o DynamoDB crie a tabela e defina o status dessa tabela como `ACTIVE`. Depois disso, você poderá começar a inserir itens de dados na tabela. Você pode usar [describe-table](https://docs.aws.amazon.com/cli/latest/reference/dynamodb/describe-table.html) para determinar o status da criação da tabela.
## Descrever uma tabela com um índice secundário local
Para obter mais informações sobre índices secundários locais em uma tabela, use o parâmetro `describe-table`. Para cada índice, você pode acessar seu nome, esquema de chaves e atributos projetados.
```
aws dynamodb describe-table --table-name Music
```
## Consultar um índice secundário local
Você pode usar a operação `query` em um índice secundário local de modo semelhante a como você `query` em uma tabela. Você deve especificar o nome do índice, os critérios de consulta da chave de classificação do índice e os atributos que deseja retornar. Neste exemplo, o índice é `AlbumTitleIndex` e a chave de classificação do índice é `AlbumTitle`.
Os únicos atributos retornados são aqueles que foram projetados no índice. É possível modificar essa consulta para selecionar atributos não chave também, mas isso exigiria atividades de busca de tabela que são relativamente caras. Para obter mais informações sobre buscas de tabela, consulte [Projeções de atributo](LSI.md#LSI.Projections).
```
aws dynamodb query \
--table-name Music \
--index-name AlbumTitleIndex \
--key-condition-expression "Artist = :v_artist and AlbumTitle = :v_title" \
--expression-attribute-values '{":v_artist":{"S":"Acme Band"},":v_title":{"S":"Songs About Life"} }'
```
# Gerenciar fluxos de trabalho complexos com transações do DynamoDB
As Amazon DynamoDB Transactions simplificam a experiência do desenvolvedor ao fazer alterações de tudo ou nada em vários itens dentro e entre tabelas. As transações fornecem atomicidade, consistência, isolamento e durabilidade (ACID) no DynamoDB, ajudando você a manter a correção dos dados em suas aplicações.
Você pode usar as APIs de leitura e gravação transacionais do DynamoDB para gerenciar fluxos de trabalho empresariais complexos que precisão de adição, atualização ou exclusão de vários itens como uma única operação tudo ou nada. Por exemplo, um desenvolvedor de videogames pode garantir que os perfis dos jogadores sejam atualizados corretamente quando eles trocam itens em um jogo ou fazem compras dentro do jogo.
Com a API de gravação de transações, você pode agrupar várias ações `Put`, `Update`, `Delete` e `ConditionCheck`. Você pode enviar as ações como uma única operação `TransactWriteItems` que é bem-sucedida ou falha como uma unidade. O mesmo é verdade para várias ações `Get`, que você pode agrupar e enviar como uma única operação `TransactGetItems`.
Não há custo adicional para habilitar transações para suas tabelas do DynamoDB. Você paga apenas pelas leituras ou gravações que fazem parte de sua transação. O DynamoDB realiza duas leituras subjacentes ou gravações de cada item na transação: uma para preparar a transação e outra para enviar a transação. Essas duas operações de leitura/gravação subjacentes são visíveis nas métricas do Amazon CloudWatch.
Para começar a usar as transações do DynamoDB, baixe o AWS SDK mais recente ou da AWS Command Line Interface (AWS CLI). Em seguida, siga o [Exemplo de transações do DynamoDB](transaction-example.md).
As seções a seguir fornecem uma visão geral detalhada das APIs de transação e como você pode usá-las no DynamoDB.
**Topics**
+ [Como funciona](transaction-apis.md)
+ [Usar o IAM com transações](transaction-apis-iam.md)
+ [Código de exemplo](transaction-example.md)
# Amazon DynamoDB Transactions: como funciona
Com as Amazon DynamoDB Transactions, você pode agrupar várias ações juntas e enviá-las como uma única operação tudo ou nada `TransactWriteItems` ou `TransactGetItems`. As seções a seguir descrevem operações de API, gerenciamento de capacidade, práticas recomendadas e outros detalhes sobre o uso de operações transacionais no DynamoDB.
**Topics**
+ [API TransactWriteItems](#transaction-apis-txwriteitems)
+ [API TransactGetItems](#transaction-apis-txgetitems)
+ [Níveis de isolamento para transações do DynamoDB](#transaction-isolation)
+ [Tratamento de conflitos em transações com o DynamoDB](#transaction-conflict-handling)
+ [Usar APIs transacionais no DynamoDB Accelerator (DAX)](#transaction-apis-dax)
+ [Gerenciar capacidade para transações](#transaction-capacity-handling)
+ [Práticas recomendadas para transações](#transaction-best-practices)
+ [Usar APIs Transacionais com tabelas globais](#transaction-integration)
+ [Transações do DynamoDB comparadas com biblioteca de clientes de transações do AWSLabs](#transaction-vs-library)
## API TransactWriteItems
`TransactWriteItems` é uma operação de gravação síncrona e idempotente que agrupa até 100 ações de gravação em uma única operação tudo ou nada. Essas ações podem ter como destino até 100 itens distintos em uma ou mais tabelas do DynamoDB na mesma conta e região da AWS. O tamanho agregado dos itens na transação não podem exceder 4 MB. As ações são concluídas de forma atômica para que todas sejam bem-sucedidas ou nenhuma tenha êxito.
**nota**
Uma operação `TransactWriteItems` difere de uma operação `BatchWriteItem` em que todas as ações contidas devem ser concluídas com êxito, ou nenhuma alteração foi feita. Com uma operação `BatchWriteItem`, é possível que apenas as ações no lote sejam bem-sucedidas enquanto as outras não.
As transações não podem ser realizadas usando índices.
Você não pode visar o mesmo item com várias operações dentro da mesma transação. Por exemplo, você não pode executar uma ação `ConditionCheck` e também uma `Update` no mesmo item na mesma transação.
Você pode adicionar os tipos a seguir de ações a uma transação:
+ `Put`: inicia uma operação `PutItem` para criar um novo item ou substituir um item antigo com um item novo, de forma condicional ou sem especificar qualquer condição.
+ `Update`: inicia uma operação `UpdateItem` para editar um atributo de item existente ou adicionar um novo item à tabela se ele já não existir. Use essa ação para adicionar, excluir ou atualizar atributos ou um item existente de forma condicional ou sem uma condição.
+ `Delete`: inicia uma operação `DeleteItem` para excluir um único item em uma tabela identificada por essa chave principal.
+ `ConditionCheck`: verifica se um item existe ou verifica a condição de atributos específicos do item.
Quando uma transação é concluída no DynamoDB, suas alterações começam a se propagar para índices secundários globais (GSIs), fluxos e backups. Essa propagação ocorre gradualmente: registros de fluxo da mesma transação podem aparecer em momentos diferentes e podem ser intercalados com registros de outras transações. Os consumidores do fluxo não devem presumir a atomicidade da transação ou as garantias de ordenação.
Para garantir um snapshot atômico dos itens modificados em uma transação, use a operação TransactGetItems para ler todos os itens relevantes juntos. Essa operação fornece uma visão consistente dos dados, garantindo que você veja todas as alterações de uma transação concluída ou nenhuma.
Como a propagação não é imediata, se uma tabela for restaurada do backup ([RestoreTableFromBackup](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_RestoreTableFromBackup.html)) ou exportada para um ponto anterior no tempo ([ExportTableToPointInTime](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_ExportTableToPointInTime.html)) no meio da transação, ela poderá conter apenas algumas das alterações feitas durante uma transação recente.
### Potência igual
Você pode, opcionalmente, incluir um token de cliente quando fizer uma chamada `TransactWriteItems` para garantir que a solicitação é *idempotente*. Realizar transações idempotentes ajuda a prevenir erros de aplicação se a mesma operação for enviada diversas vezes por conta de uma desconexão ou outro problema de conexão.
Se a chamada `TransactWriteItems` original for bem-sucedida, as chamadas `TransactWriteItems` subsequentes com o mesmo token de cliente retornarão com êxito sem nenhuma alteração. Se o parâmetro `ReturnConsumedCapacity` estiver definido, a chamada `TransactWriteItems` inicial retornará o número de unidades de capacidade de gravação consumidas para realizar as alterações. Chamadas `TransactWriteItems` subsequentes com o mesmo token de cliente devolvem o número de unidades de capacidade de leitura consumidas na leitura do item.
**Pontos importantes sobre idempotência**
+ Um token de cliente é válido por 10 minutos após a solicitação utilizada acabar. Depois de 10 minutos, quaisquer solicitações que usarem o mesmo token de cliente são tratadas como uma nova solicitação. Você não deve reutilizar o mesmo token de cliente para a mesma solicitação após 10 minutos.
+ Se você repetir uma solicitação com o mesmo token de cliente dentro de 10 minutos na janela de idempotência, mas alterar algum parâmetro de solicitação, o DynamoDB retornará uma exceção `IdempotentParameterMismatch`.
### Tratamento de erros para gravação
Transações de gravação não são bem-sucedidas nas circunstâncias a seguir:
+ Quando uma condição em uma das expressões de condição não é alcançada.
+ Quando uma validação de transação ocorrer por conta de mais de uma ação na mesma operação `TransactWriteItems` ter como destino o mesmo item.
+ Quando uma solicitação `TransactWriteItems` entra em conflito com uma operação `TransactWriteItems` em andamento em um ou mais itens na operação `TransactWriteItems`. Nesse caso, a solicitação falha com um `TransactionCanceledException`.
+ Quando há capacidade provisionada insuficiente para a transação ser concluída.
+ Quando o tamanho de um item é muito maior (maior que 400 KB), ou um índice secundário local (LSI) se torna muito grande, ou um erro de validação semelhante ocorre por conta das alterações feitas pela transação.
+ Quando houver um erro de usuário, como formato de dados inválidos.
Para obter mais informações sobre como os conflitos com operações `TransactWriteItems` são gerenciados, consulte [Tratamento de conflitos em transações com o DynamoDB](#transaction-conflict-handling).
## API TransactGetItems
`TransactGetItems` é uma operação de leitura síncrona que agrupa até 100 ações `Get`. Essas ações podem ter como destino até 100 itens distintos em uma ou mais tabelas do DynamoDB na mesma conta e região da AWS. O tamanho agregado dos itens na transação não pode exceder 4 MB.
As ações `Get` são realizadas de forma atômica para que todas sejam bem-sucedidas ou nenhuma tenha êxito:
+ `Get`: inicia uma operação `GetItem` para recuperar um conjunto de atributos do item com a chave primária fornecida. Se não houver item correspondente, `Get` não retornará quaisquer dados.
### Tratamento de erros para leitura
Transações de leitura não são bem-sucedidas nas circunstâncias a seguir:
+ Quando uma solicitação `TransactGetItems` entra em conflito com uma operação `TransactWriteItems` em andamento em um ou mais itens na operação `TransactGetItems`. Nesse caso, a solicitação falha com um `TransactionCanceledException`.
+ Quando há capacidade provisionada insuficiente para a transação ser concluída.
+ Quando houver um erro de usuário, como formato de dados inválidos.
Para obter mais informações sobre como os conflitos com operações `TransactGetItems` são gerenciados, consulte [Tratamento de conflitos em transações com o DynamoDB](#transaction-conflict-handling).
## Níveis de isolamento para transações do DynamoDB
Os níveis de isolamento de operações transacionais (`TransactWriteItems` ou `TransactGetItems`) e outras operações são os seguintes.
### SERIALIZÁVEL
Isolamento *Serializável* garante que os resultados de várias operações concomitantes sejam os mesmos como se nenhuma operação começar com o anterior finalizado.
Há um isolamento serializável entre os tipos a seguir de operação:
+ Entre qualquer operação transacional e qualquer padrão de operação de gravação (`PutItem`, `UpdateItem` ou `DeleteItem`).
+ Entre qualquer operação transacional e qualquer padrão de operação de leitura (`GetItem`).
+ Entre uma operação `TransactWriteItems` e `TransactGetItems`.
Apesar de haver isolamento serializável entre operações transacionais, e cada padrão individual de gravação em uma operação `BatchWriteItem`, não há isolamento serializável entre a transação e a operação `BatchWriteItem` como uma unidade.
De modo semelhante, o nível de isolamento entre uma operação transacional e `GetItems` individual em uma operação `BatchGetItem` é serializável. Porém, o nível de isolamento entre a transação e a operação `BatchGetItem` como uma unidade é *confirmado para leitura*.
Uma única solicitação `GetItem` é serializável em relação a uma solicitação `TransactWriteItems` de duas formas, antes ou depois da solicitação `TransactWriteItems`. Várias solicitações `GetItem`, contra chaves em solicitações `TransactWriteItems`, podem ser executadas em qualquer ordem e, portanto, os resultados são *confirmado para leitura*.
Por exemplo, se solicitações `GetItem` para o item A e o item B forem executadas simultaneamente com uma solicitação `TransactWriteItems` que modifica o item A e o item B, existem quatro possibilidades:
+ Ambas as solicitações `GetItem` são executadas antes da solicitação `TransactWriteItems`.
+ Ambas as solicitações `GetItem` são executadas após a solicitação `TransactWriteItems`.
+ A solicitação `GetItem` para o item A é executada antes da solicitação `TransactWriteItems`. Para o item B, `GetItem` é executada após `TransactWriteItems`.
+ A solicitação `GetItem` para o item B é executada antes da solicitação `TransactWriteItems`. Para o item A, `GetItem` é executada após `TransactWriteItems`.
Você deverá usar `TransactGetItems` se preferir o nível de isolamento serializável para várias solicitações `GetItem`.
Se uma leitura não transacional for feita em vários itens que faziam parte da mesma solicitação de gravação de transação em andamento, é possível que você consiga ler o novo estado de alguns dos itens e o estado antigo dos outros itens. Você poderá ler o novo estado de todos os itens que faziam parte da solicitação de gravação da transação somente quando uma resposta bem-sucedida for recebida para a gravação transacional, indicando que a transação foi concluída.
Depois que a transação for concluída com êxito e uma resposta for recebida, as operações de leitura *finalmente consistente* subsequentes ainda poderão exibir o estado antigo por um curto período devido ao modelo de consistência final do DynamoDB. Para garantir a leitura dos dados mais atualizados imediatamente após uma transação, você deve usar leituras [*altamente consistentes*](HowItWorks.ReadConsistency.md#HowItWorks.ReadConsistency.Strongly) definindo `ConsistentRead` como verdadeiro.
### CONFIRMADO PARA LEITURA
O isolamento *confirmado para leitura* garante que as operações de leitura sempre retornem valores confirmados para um item; a leitura nunca apresentará uma visualização do item representando um estado de uma gravação transacional que não teve êxito final. Isolamento confirmado para leitura não previne modificações do item imediatamente após operação de leitura.
O nível de isolamento é confirmado para leitura entre qualquer operação transacional e qualquer operação de leitura que envolva vários padrões de leitura (`BatchGetItem`, `Query` ou `Scan`). Se uma gravação transacional atualizar um item no meio de uma operação de `BatchGetItem`, `Query` ou `Scan`, a parte subsequente da operação de leitura retornará o novo valor confirmado [com `ConsistentRead)` ou possivelmente um valor confirmado anteriormente (leitura final consistente)].
### Resumo da operação
Para resumir, a tabela a seguir mostra os níveis de isolamento entre uma operação transacional (`TransactWriteItems` ou `TransactGetItems`) e outras operações.
| Operation | Nível de isolamento |
| --- | --- |
| `DeleteItem` | *Serializável* |
| `PutItem` | *Serializável* |
| `UpdateItem` | *Serializável* |
| `GetItem` | *Serializável* |
| `BatchGetItem` | *Confirmado para leitura*\$1 |
| `BatchWriteItem` | *NÃO serializável*\$1 |
| `Query` | *Confirmado para leitura* |
| `Scan` | *Confirmado para leitura* |
| Outra operação transacional | *Serializável* |
Níveis marcados com asterisco (\$1) aplicam-se à operação como uma unidade. No entanto, ações individuais dentro dessas operações tem um nível de isolamento *serializável*.
## Tratamento de conflitos em transações com o DynamoDB
Um conflito de transação pode correr em solicitações simultâneas no nível do item, em um item dentro de uma transação. Os conflitos de transação podem ocorrer nos seguintes casos:
+ Uma solicitação `PutItem`, `UpdateItem` ou `DeleteItem` de um item conflita com uma solicitação `TransactWriteItems` em andamento que inclui o mesmo item.
+ Um item dentro de uma solicitação `TransactWriteItems` é parte de outra solicitação `TransactWriteItems` em andamento.
+ Um item dentro de uma solicitação `TransactGetItems` é parte de outra solicitação `TransactWriteItems`, `BatchWriteItem`, `PutItem`, `UpdateItem` ou `DeleteItem` em andamento.
**nota**
Quando uma solicitação `PutItem`, `UpdateItem` ou `DeleteItem` é rejeitada, a solicitação falha com um `TransactionConflictException`,
Se qualquer solicitação no nível do item dentro de `TransactWriteItems` ou `TransactGetItems` é rejeitada, a solicitação falha com um `TransactionCanceledException`. Se essa solicitação falhar, os AWS SDKs não tentarão repetir a solicitação.
Se você estiver usando AWS SDK para Java, a exceção conterá a lista de [CancellationReasons](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_CancellationReason.html), em ordem de acordo com a lista de itens no parâmetro de solicitação `TransactItems`. Para outros idiomas, uma representação em string da lista é incluída na mensagem de erro de exceção.
Se uma operação `TransactWriteItems` ou `TransactGetItems` em andamento entrar em conflito com uma solicitação `GetItem` simultânea, as duas podem ter êxito.
A métrica [TransactionConflict do CloudWatch](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/metrics-dimensions.html) é incrementada em cada solicitação que falhou no nível do item
## Usar APIs transacionais no DynamoDB Accelerator (DAX)
O DynamoDB Accelerator (DAX) oferece suporte a `TransactWriteItems` e `TransactGetItems` com os mesmos níveis de isolamento que no DynamoDB.
`TransactWriteItems` grava via DAX. O DAX passa uma chamada `TransactWriteItems` para o DynamoDB e retorna a resposta. Para preencher o cache após a gravação, o DAX chama `TransactGetItems` em segundo plano para cada item na operação `TransactWriteItems`, o que consome unidades de capacidade de leitura adicionais. (Para ter mais informações, consulte [Gerenciar capacidade para transações](#transaction-capacity-handling).) Essa funcionalidade permite manter simples a lógica da aplicação e usar o DAX para operações transacionais e não transacionais.
`TransactGetItems`Chamadas de são transmitidas pelo DAX sem que os itens sejam armazenados em cache localmente. É o mesmo comportamento para APIs de leitura fortemente consistente no DAX.
## Gerenciar capacidade para transações
Não há custo adicional para habilitar transações para suas tabelas do DynamoDB. Você paga apenas pelas leituras ou gravações que fazem parte de sua transação. O DynamoDB realiza duas leituras subjacentes ou gravações de cada item na transação: uma para preparar a transação e outra para enviar a transação. Essas duas operações de leitura/gravação subjacente são visíveis nas métricas do Amazon CloudWatch.
Planeje para leituras e gravações adicionais que são necessárias por APIs transacionais ao provisionar a capacidade de suas tabelas. Por exemplo, suponha que sua aplicação execute uma transação por segundo e cada transação grave itens de 500 bytes em sua tabela. Cada item requer duas capacidades de gravação (WCUs): uma para preparar a transação e uma para enviar a transação. Portanto, você precisa provisionar seis WCUs na tabela.
Se você usar o DynamoDB Accelerator (DAX) no exemplo anterior, use também as unidades de capacidade de leitura (RCUs) em cada item na chamada `TransactWriteItems`. Então, você precisa provisionar seis RCUs adicionais na tabela.
De forma semelhante, se sua aplicação executa uma transação de leitura por segundo, e cada transação lê itens de 500 bytes na sua tabela, é preciso prover seis unidades de capacidade de leitura (RCUs) na tabela. A leitura de cada item requer duas RCUs: uma para preparar a transação e uma para enviar a transação.
Além disso, comportamento de SDK padrão é tentar transações novamente em caso de uma exceção `TransactionInProgressException`. Planeje para as unidades de capacidade de leitura adicional (RCUs) que essas tentativas repetitivas consumem. O mesmo é verdade se você estiver tentando novamente transações em seu código usando um `ClientRequestToken`.
## Práticas recomendadas para transações
Considere as seguintes práticas recomendadas ao usar transações do DynamoDB.
+ Habilitar Auto Scaling nas suas tabelas, ou garantir que você tem capacidade de throughput suficiente para realizar as duas operações de leitura ou gravação em cada item na transação.
+ Se não estiver usando um SDK fornecido pela AWS, inclua um atributo `ClientRequestToken` quando realizar uma chamada `TransactWriteItems` para garantir que a solicitação é idempotente.
+ Não agrupe operações em uma transação se não for necessário. Por exemplo, se uma transação única com 10 operações puder ser separada em várias transações sem comprometimento da exatidão do aplicativo, recomendamos separar a transação. Transações mais simples melhorar a taxa de transferência e têm maior chance de êxito.
+ Transações múltiplas atualizando os mesmos itens simultaneamente podem causar conflitos que cancelam as transações. Recomendamos as práticas recomendadas do DynamoDB a seguir para modelagem de dados a fim de minimizar esses conflitos.
+ Se um conjunto de atributos for frequentemente atualizado entre vários itens como parte de uma única transação, considere agrupar os atributos em um único item para reduzir o escopo da transação.
+ Evite usar transações para adicionar dados no grupo. Para gravações em grupo, é melhor usar `BatchWriteItem`.
## Usar APIs Transacionais com tabelas globais
As operações transacionais oferecem garantia de atomicidade, consistência, isolamento e durabilidade (ACID) somente na região da AWS em que a API de gravação foi invocada. As transações não são compatíveis entre regiões em tabelas globais. Por exemplo, suponha que você tenha uma tabela global com réplicas nas regiões Leste dos EUA (Ohio) e Oeste dos EUA (Oregon) e execute uma operação `TransactWriteItems` na região Leste dos EUA (Norte da Virgínia). Você pode observar transações parcialmente concluídas na região Oeste dos EUA (Oregon) conforme as alterações são replicadas. As alterações só serão replicadas para outras regiões quando forem confirmadas na região de origem.
## Transações do DynamoDB comparadas com biblioteca de clientes de transações do AWSLabs
As transações do DynamoDB fornecem uma substituição mais eficiente em termos de custos, efetiva e com maior performance para as transações da biblioteca de clientes do [AWSLabs](https://github.com/awslabs). Sugerimos atualizar os aplicativos para usar com as APIs de transação do lado do servidor nativas.
# Usar o IAM com transações do DynamoDB
Você pode usar o AWS Identity and Access Management (IAM) para restringir as ações que as operações transacionais podem executar no Amazon DynamoDB. Para obter mais informações sobre como usar as políticas do IAM no DynamoDB, consulte [Políticas baseadas em identidade para o DynamoDB](security_iam_service-with-iam.md#security_iam_service-with-iam-id-based-policies).
Permissões para `Put`, `Update`, `Delete`, e ações `Get` são governadas pelas permissões usadas para operações `PutItem`, `UpdateItem`, `DeleteItem` e `GetItem` subjacentes. Para a ação `ConditionCheck`, é possível usar a permissão `dynamodb:ConditionCheckItem` nas políticas do IAM.
Veja a seguir exemplos de políticas do IAM que você pode usar para configurar transações do DynamoDB.
## Exemplo 1: permitir operações transacionais
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:ConditionCheckItem",
"dynamodb:PutItem",
"dynamodb:UpdateItem",
"dynamodb:DeleteItem",
"dynamodb:GetItem"
],
"Resource": [
"arn:aws:dynamodb:*:*:table/table04"
]
}
]
}
```
------
## Exemplo 2: permitir apenas operações transacionais
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:ConditionCheckItem",
"dynamodb:PutItem",
"dynamodb:UpdateItem",
"dynamodb:DeleteItem",
"dynamodb:GetItem"
],
"Resource": [
"arn:aws:dynamodb:*:*:table/table04"
],
"Condition": {
"ForAnyValue:StringEquals": {
"dynamodb:EnclosingOperation": [
"TransactWriteItems",
"TransactGetItems"
]
}
}
}
]
}
```
------
## Exemplo 3: permitir leituras e gravações não transacionais e bloquear leituras e gravações transacionais
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": [
"dynamodb:ConditionCheckItem",
"dynamodb:PutItem",
"dynamodb:UpdateItem",
"dynamodb:DeleteItem",
"dynamodb:GetItem"
],
"Resource": [
"arn:aws:dynamodb:*:*:table/table04"
],
"Condition": {
"ForAnyValue:StringEquals": {
"dynamodb:EnclosingOperation": [
"TransactWriteItems",
"TransactGetItems"
]
}
}
},
{
"Effect": "Allow",
"Action": [
"dynamodb:PutItem",
"dynamodb:DeleteItem",
"dynamodb:GetItem",
"dynamodb:UpdateItem"
],
"Resource": [
"arn:aws:dynamodb:*:*:table/table04"
]
}
]
}
```
------
## Exemplo 4: evitar que informações sejam devolvidas com a falha ConditionCheck
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:ConditionCheckItem",
"dynamodb:PutItem",
"dynamodb:UpdateItem",
"dynamodb:DeleteItem",
"dynamodb:GetItem"
],
"Resource": "arn:aws:dynamodb:*:*:table/table01",
"Condition": {
"StringEqualsIfExists": {
"dynamodb:ReturnValues": "NONE"
}
}
}
]
}
```
------
# Exemplo de transações do DynamoDB
Como exemplo de uma situação em que as Amazon DynamoDB Transactions podem ser úteis, considere este exemplo de aplicação Java para um marketplace online.
A aplicação tem três tabelas do DynamoDB no backend:
+ `Customers`: esta tabela armazena detalhes sobre os clientes do marketplace. Sua chave primária é um identificador exclusivo `CustomerId`.
+ `ProductCatalog`: esta tabela armazena detalhes como preço e disponibilidade sobre os produtos para venda no mercado. Sua chave primária é um identificador exclusivo `ProductId`.
+ `Orders`: esta tabela armazena detalhes sobre os pedidos do marketplace. Sua chave primária é um identificador exclusivo `OrderId`.
## Fazer um pedido
Os trechos de código a seguir ilustram como usar transações do DynamoDB para coordenar as várias etapas necessárias para criar e processar um pedido. O uso de uma única operação de tudo ou nada garante que, se qualquer parte da transação falhar, nenhuma ação na transação será executada e nenhuma alteração será feita.
Neste exemplo, você configura um pedido de um cliente cujo `customerId` é `09e8e9c8-ec48`. Em seguida, execute-o como uma única transação usando o seguinte fluxo de trabalho simples de processamento de pedidos:
1. Determine se o ID do cliente é válido.
1. Verifique se o produto é `IN_STOCK` e atualize o status do produto para `SOLD`.
1. Certifique-se de que o pedido ainda não exista e crie-o.
### Validar o cliente
Primeiro, defina uma ação para verificar se um cliente com `customerId` igual a `09e8e9c8-ec48` existe na tabela de clientes.
```
final String CUSTOMER_TABLE_NAME = "Customers";
final String CUSTOMER_PARTITION_KEY = "CustomerId";
final String customerId = "09e8e9c8-ec48";
final HashMap customerItemKey = new HashMap<>();
customerItemKey.put(CUSTOMER_PARTITION_KEY, new AttributeValue(customerId));
ConditionCheck checkCustomerValid = new ConditionCheck()
.withTableName(CUSTOMER_TABLE_NAME)
.withKey(customerItemKey)
.withConditionExpression("attribute_exists(" + CUSTOMER_PARTITION_KEY + ")");
```
### Atualizar o status do produto
Em seguida, defina uma ação para atualizar o status do produto para `SOLD` se a condição do status atual do produto `IN_STOCK` for `true`. Configurar a opção `ReturnValuesOnConditionCheckFailure` retornará o item se o atributo de status do produto do item não for igual a `IN_STOCK`.
```
final String PRODUCT_TABLE_NAME = "ProductCatalog";
final String PRODUCT_PARTITION_KEY = "ProductId";
HashMap productItemKey = new HashMap<>();
productItemKey.put(PRODUCT_PARTITION_KEY, new AttributeValue(productKey));
Map expressionAttributeValues = new HashMap<>();
expressionAttributeValues.put(":new_status", new AttributeValue("SOLD"));
expressionAttributeValues.put(":expected_status", new AttributeValue("IN_STOCK"));
Update markItemSold = new Update()
.withTableName(PRODUCT_TABLE_NAME)
.withKey(productItemKey)
.withUpdateExpression("SET ProductStatus = :new_status")
.withExpressionAttributeValues(expressionAttributeValues)
.withConditionExpression("ProductStatus = :expected_status")
.withReturnValuesOnConditionCheckFailure(ReturnValuesOnConditionCheckFailure.ALL_OLD);
```
### Criar o pedido
Por último, crie o pedido, desde que um pedido com esse `OrderId` ainda não exista.
```
final String ORDER_PARTITION_KEY = "OrderId";
final String ORDER_TABLE_NAME = "Orders";
HashMap orderItem = new HashMap<>();
orderItem.put(ORDER_PARTITION_KEY, new AttributeValue(orderId));
orderItem.put(PRODUCT_PARTITION_KEY, new AttributeValue(productKey));
orderItem.put(CUSTOMER_PARTITION_KEY, new AttributeValue(customerId));
orderItem.put("OrderStatus", new AttributeValue("CONFIRMED"));
orderItem.put("OrderTotal", new AttributeValue("100"));
Put createOrder = new Put()
.withTableName(ORDER_TABLE_NAME)
.withItem(orderItem)
.withReturnValuesOnConditionCheckFailure(ReturnValuesOnConditionCheckFailure.ALL_OLD)
.withConditionExpression("attribute_not_exists(" + ORDER_PARTITION_KEY + ")");
```
### Executar a transação
O exemplo a seguir ilustra como executar as ações definidas anteriormente como uma única operação tudo ou nada.
```
Collection actions = Arrays.asList(
new TransactWriteItem().withConditionCheck(checkCustomerValid),
new TransactWriteItem().withUpdate(markItemSold),
new TransactWriteItem().withPut(createOrder));
TransactWriteItemsRequest placeOrderTransaction = new TransactWriteItemsRequest()
.withTransactItems(actions)
.withReturnConsumedCapacity(ReturnConsumedCapacity.TOTAL);
// Run the transaction and process the result.
try {
client.transactWriteItems(placeOrderTransaction);
System.out.println("Transaction Successful");
} catch (ResourceNotFoundException rnf) {
System.err.println("One of the table involved in the transaction is not found" + rnf.getMessage());
} catch (InternalServerErrorException ise) {
System.err.println("Internal Server Error" + ise.getMessage());
} catch (TransactionCanceledException tce) {
System.out.println("Transaction Canceled " + tce.getMessage());
}
```
## Ler os detalhes do pedido
O exemplo a seguir mostra como ler a ordem concluída transacionalmente entre as tabelas `Orders` e `ProductCatalog`.
```
HashMap productItemKey = new HashMap<>();
productItemKey.put(PRODUCT_PARTITION_KEY, new AttributeValue(productKey));
HashMap orderKey = new HashMap<>();
orderKey.put(ORDER_PARTITION_KEY, new AttributeValue(orderId));
Get readProductSold = new Get()
.withTableName(PRODUCT_TABLE_NAME)
.withKey(productItemKey);
Get readCreatedOrder = new Get()
.withTableName(ORDER_TABLE_NAME)
.withKey(orderKey);
Collection getActions = Arrays.asList(
new TransactGetItem().withGet(readProductSold),
new TransactGetItem().withGet(readCreatedOrder));
TransactGetItemsRequest readCompletedOrder = new TransactGetItemsRequest()
.withTransactItems(getActions)
.withReturnConsumedCapacity(ReturnConsumedCapacity.TOTAL);
// Run the transaction and process the result.
try {
TransactGetItemsResult result = client.transactGetItems(readCompletedOrder);
System.out.println(result.getResponses());
} catch (ResourceNotFoundException rnf) {
System.err.println("One of the table involved in the transaction is not found" + rnf.getMessage());
} catch (InternalServerErrorException ise) {
System.err.println("Internal Server Error" + ise.getMessage());
} catch (TransactionCanceledException tce) {
System.err.println("Transaction Canceled" + tce.getMessage());
}
```
# Captura de dados de alterações com o Amazon DynamoDB
Muitas aplicações podem se beneficiar da capacidade de capturar alterações nos itens armazenados em uma tabela do DynamoDB no momento em que elas ocorrem. Veja a seguir alguns exemplos de casos de uso:
+ Uma aplicação móvel popular modifica os dados em uma tabela do DynamoDB a uma taxa de milhares de atualizações por segundo. Outra aplicação captura e armazena dados sobre essas atualizações, fornecendo métricas de uso quase em tempo real para a aplicação móvel.
+ Uma aplicação financeira modifica os dados do mercado de ações em uma tabela do DynamoDB. Diferentes aplicações executadas em paralelo acompanham essas mudanças em tempo real, calculam o valor em risco e reequilibram automaticamente as carteiras com base nos movimentos dos preços das ações.
+ Sensores em veículos de transporte e equipamentos industriais enviam dados para uma tabela do DynamoDB. Diferentes aplicações monitoram a performance e enviam alertas de mensagens quando um problema é detectado, preveem possíveis defeitos aplicando algoritmos de machine learning e compactam e arquivam dados no Amazon Simple Storage Service (Amazon S3).
+ Uma aplicação envia notificações automaticamente aos dispositivos móveis de todos os jogadores de um grupo assim que um deles carrega uma nova imagem.
+ Um novo cliente adiciona dados a uma tabela do DynamoDB. Esse evento invoca outra aplicação que envia um e-mail de boas-vindas ao novo cliente.
O DynamoDB oferece suporte a streaming de registros de captura de dados de alteração em nível de item em tempo quase real. Você pode criar aplicações que consomem esses fluxos e executam ações com base no conteúdo.
**nota**
Não há suporte para a adição de tags ao DynamoDB Streams e o uso de [controle de acesso por atributo (ABAC)](access-control-resource-based.md) com o DynamoDB Streams.
O vídeo a seguir apresenta uma introdução sobre o conceito de captura de dados de alteração.
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/VVv_-mZ5Ge8)
**Topics**
+ [Opções de streaming para captura de dados de alteração](#streamsmain.choose)
+ [Use o Kinesis Data Streams para capturar alterações do DynamoDB](kds.md)
+ [Capturar dados de alterações para o DynamoDB Streams](Streams.md)
## Opções de streaming para captura de dados de alteração
O DynamoDB oferece dois modelos de streaming para captura de dados de alteração: Kinesis Data Streams para DynamoDB e DynamoDB Streams.
Para ajudar você a escolher a solução certa para sua aplicação, a tabela a seguir resume os recursos de cada modelo de streaming.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/amazondynamodb/latest/developerguide/streamsmain.html)
É possível habilitar ambos os modelos de streaming na mesma tabela do DynamoDB.
O vídeo a seguir aprofunda-se nas diferenças entre as duas opções.
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/UgG17Wh2y0g)
# Use o Kinesis Data Streams para capturar alterações do DynamoDB
É possível usar o Amazon Kinesis Data Streams para capturar alterações no Amazon DynamoDB.
O Kinesis Data Streams capta alterações no nível de item em qualquer DynamoDB e as replica em um [fluxo de dados do Kinesis](https://docs.aws.amazon.com/streams/latest/dev/introduction.html). Suas aplicações podem acessar esse fluxo e visualizar as alterações em nível de item praticamente em tempo real. Você pode capturar e armazenar continuamente terabytes de dados por hora. Aproveite o tempo de retenção de dados mais longo e com o recurso de distribuição avançada para atingir simultaneamente duas ou mais aplicações downstream. Outros benefícios incluem auditoria adicional e transparência de segurança.
O Kinesis Data Streams também oferece acesso ao [Amazon Kinesis Data Firehose](https://docs.aws.amazon.com/firehose/latest/dev/what-is-this-service.html) e ao [Amazon Managed Service for Apache Flink](https://docs.aws.amazon.com/kinesisanalytics/latest/dev/what-is.html). Isso permite construir aplicações para alimentar painéis em tempo real, gerar alertas, implementar definições de preço e de publicidade dinâmicas e implementar análises de dados e algoritmos de machine learning sofisticados.
**nota**
O uso de Kinesis Data Streams para DynamoDB está sujeito aos [preços do Kinesis Data Streams](https://aws.amazon.com/kinesis/data-streams/pricing/) para o fluxo de dados e aos [preços do DynamoDB](https://aws.amazon.com/dynamodb/pricing/) para a tabela de origem.
Para habilitar o streaming do Kinesis em uma tabela do DynamoDB usando o console ou o AWS CLI SDK para Java, consulte [Conceitos básicos do Kinesis Data Streams para o Amazon DynamoDB](kds_gettingstarted.md).
**Topics**
+ [Como o Kinesis Data Streams funciona com o DynamoDB](#kds_howitworks)
+ [Conceitos básicos do Kinesis Data Streams para o Amazon DynamoDB](kds_gettingstarted.md)
+ [Usar fragmentos e métricas com o DynamoDB Streams e o Kinesis Data Streams](kds_using-shards-and-metrics.md)
+ [Usar políticas do IAM para o Amazon Kinesis Data Streams e Amazon DynamoDB](kds_iam.md)
## Como o Kinesis Data Streams funciona com o DynamoDB
Quando um fluxo de dados do Kinesis é habilitado para uma tabela do DynamoDB, a tabela envia um registro de dados que captura alterações nos dados dessa tabela. Esse registro de dados inclui:
+ O horário específico em que um item foi criado, atualizado ou excluído recentemente
+ A chave primária desse item
+ Um snapshot do registro antes da modificação
+ Um snapshot do registro após a modificação
Esses registros de dados são capturados e publicados praticamente em tempo real. Depois de gravados no fluxo de dados do Kinesis, poderão ser lidos como qualquer outro registro. É possível usar a Biblioteca de clientes Kinesis, usar o AWS Lambda, chamar a API do Kinesis Data Streams e usar outros serviços conectados. Para obter mais informações, consulte [Ler dados do Amazon Kinesis Data Streams](https://docs.aws.amazon.com/streams/latest/dev/building-consumers.html) no Guia do desenvolvedor do Amazon Kinesis Data Streams.
Essas alterações nos dados também são capturadas de forma assíncrona. O Kinesis não afetará a performance da tabela da qual estiver fazendo streaming. Os registros de fluxo armazenados no fluxo de dados do Kinesis também são criptografados em repouso. Para obter mais informações, consulte [Proteção de dados no Amazon Kinesis Data Streams](https://docs.aws.amazon.com/streams/latest/dev/server-side-encryption.html).
Os registros de fluxo de dados do Kinesis poderão aparecer em uma sequência diferente da sequência na qual ocorreram as modificações dos itens. As mesmas notificações de item também poderão aparecer mais de uma vez no fluxo. Confira o atributo `ApproximateCreationDateTime` para identificar a sequência em que as modificações dos itens ocorreram e para identificar registros duplicados.
Ao habilitar um fluxo de dados do Kinesis como destino de streaming de uma tabela do DynamoDB, você pode configurar a precisão dos valores de `ApproximateCreationDateTime` em milissegundos ou microssegundos. Por padrão, `ApproximateCreationDateTime` indica a hora da alteração em milissegundos. Além disso, é possível alterar esse valor em um destino de streaming ativo. Depois dessa atualização, os registros de fluxo gravados no Kinesis terão valores de `ApproximateCreationDateTime` com a precisão desejada.
Valores binários gravados no DynamoDB devem ser codificados em [formato codificado em base64](HowItWorks.NamingRulesDataTypes.md). No entanto, quando os registros de dados são gravados em um fluxo de dados do Kinesis, esses valores binários são codificados em base64 pela segunda vez. Ao ler esses registros de um fluxo de dados do Kinesis, para recuperar os valores binários brutos, as aplicações devem decodificar esses valores duas vezes.
O DynamoDB cobra pelo uso para Kinesis Data Streams em unidades de captura de dados de alterações. 1 KB de alteração por item único conta como uma unidade de captura de dados de alteração. Os KB de alteração em cada item são calculados pela maior das imagens de “antes” e “depois” do item gravado no fluxo, usando a mesma lógica que o [consumo de unidades de capacidade para operações de gravação](read-write-operations.md#write-operation-consumption). Não é necessário provisionar a capacidade de throughput para unidades de captura de dados de alteração, semelhante a como o modo [sob demanda](capacity-mode.md#capacity-mode-on-demand) do DynamoDB funciona.
### Ativar um fluxo de dados do Kinesis para a tabela do DynamoDB
Você pode habilitar ou desabilitar o streaming para o Kinesis em uma tabela existente do DynamoDB usando o Console de gerenciamento da AWS, o AWS SDK ou a AWS Command Line Interface (AWS CLI).
+ Só é possível fazer o streaming de dados do DynamoDB para o Kinesis Data Streams na mesma conta da AWS e região da AWS que sua tabela.
+ Só é possível fazer o streaming de dados de uma tabela do DynamoDB para um fluxo de dados do Kinesis.
### Alterar um destino do Kinesis Data Streams em uma tabela do DynamoDB
Por padrão, todos os registros de fluxo de dados do Kinesis incluem um atributo `ApproximateCreationDateTime`. Esse atributo representa um carimbo de data e hora, em milissegundos, da hora aproximada em que cada registro foi criado. Você pode alterar a precisão desses valores usando o [https://console.aws.amazon.com/kinesis](https://console.aws.amazon.com/kinesis), o SDK ou a AWS CLI.
# Conceitos básicos do Kinesis Data Streams para o Amazon DynamoDB
Esta seção descreve como usar o Kinesis Data Streams para tabelas do Amazon DynamoDB com o console do Amazon DynamoDB, a AWS Command Line Interface (AWS CLI) e a API.
## Criar um fluxo de dados ativo do Amazon Kinesis
Todos esses exemplos usam a tabela `Music` do DynamoDB que foi criada como parte do tutorial [Conceitos básicos do DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GettingStartedDynamoDB.html).
Para saber mais sobre como criar consumidores e conectar seu fluxo de dados do Kinesis a outros produtos da AWS, consulte [Ler dados do Amazon Kinesis Data Streams](https://docs.aws.amazon.com/streams/latest/dev/building-consumers.html) no *Guia do desenvolvedor do Amazon Kinesis Data Streams*.
**nota**
Quando você estiver usando fragmentos do KDS pela primeira vez, recomendamos configurá-los para que aumentem e reduzam a escala verticalmente de acordo com os padrões de uso. Depois de acumular mais dados sobre os padrões de uso, você poderá ajustar os fragmentos em seu fluxo para fazer a correspondência.
------
#### [ Console ]
1. Faça login no Console de gerenciamento da AWS e abra o console do Kinesis em [ https://console.aws.amazon.com/kinesis/](https://console.aws.amazon.com/kinesis/).
1. Escolha **Create data stream** (Criar fluxo de dados) e siga as instruções para criar um fluxo chamado `samplestream`.
1. Abra o console do DynamoDB em [https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/).
1. No painel de navegação, no lado esquerdo do console, selecione **Tables** (Tabelas).
1. Escolha a tabela **Music**.
1. Escolha a guia **Exports and streams** (Exportações e fluxos).
1. (Opcional) Em **Detalhes do stream de dados do Amazon Kinesis**, você pode alterar a precisão do carimbo de data e hora do registro de microssegundos (padrão) para milissegundos.
1. Escolha **samplestream** na lista suspensa.
1. Escolha o botão **Ativar**.
------
#### [ AWS CLI ]
1. Criar um fluxo de dados do Kinesis denominado `samplestream` usando o [comando create-stream](https://docs.aws.amazon.com/cli/latest/reference/kinesis/create-stream.html).
```
aws kinesis create-stream --stream-name samplestream --shard-count 3
```
Consulte [Considerações sobre gerenciamento de fragmentos para o Kinesis Data Streams](kds_using-shards-and-metrics.md#kds_using-shards-and-metrics.shardmanagment) antes de definir o número de fragmentos para o fluxo de dados do Kinesis.
1. Verifique se o stream do Kinesis está ativo e pronto para uso usando o [comando describe-stream](https://docs.aws.amazon.com/cli/latest/reference/kinesis/describe-stream.html).
```
aws kinesis describe-stream --stream-name samplestream
```
1. Habilite o streaming do Kinesis na tabela do DynamoDB usando o comando `enable-kinesis-streaming-destination` do DynamoDB. Substitua o valor de `stream-arn` pelo que foi retornado por `describe-stream` na etapa anterior. Opcionalmente, habilite o streaming com uma precisão mais granular (microssegundos) dos valores de carimbo de data e hora retornados em cada registro.
Habilite o streaming com precisão de carimbo de data e hora em microssegundos:
```
aws dynamodb enable-kinesis-streaming-destination \
--table-name Music \
--stream-arn arn:aws:kinesis:us-west-2:12345678901:stream/samplestream
--enable-kinesis-streaming-configuration ApproximateCreationDateTimePrecision=MICROSECOND
```
Ou habilite o streaming com a precisão padrão do carimbo de data e hora (milissegundos):
```
aws dynamodb enable-kinesis-streaming-destination \
--table-name Music \
--stream-arn arn:aws:kinesis:us-west-2:12345678901:stream/samplestream
```
1. Verifique se o streaming do Kinesis está ativa na tabela usando o comando `describe-kinesis-streaming-destination` do DynamoDB.
```
aws dynamodb describe-kinesis-streaming-destination --table-name Music
```
1. Grave os dados na tabela do DynamoDB usando o comando `put-item`, conforme descrito no [Guia do desenvolvedor do DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/getting-started-step-2.html).
```
aws dynamodb put-item \
--table-name Music \
--item \
'{"Artist": {"S": "No One You Know"}, "SongTitle": {"S": "Call Me Today"}, "AlbumTitle": {"S": "Somewhat Famous"}, "Awards": {"N": "1"}}'
aws dynamodb put-item \
--table-name Music \
--item \
'{"Artist": {"S": "Acme Band"}, "SongTitle": {"S": "Happy Day"}, "AlbumTitle": {"S": "Songs About Life"}, "Awards": {"N": "10"} }'
```
1. Use o comando [get-records](https://docs.aws.amazon.com/cli/latest/reference/kinesis/get-records.html) da CLI do Kinesis para recuperar o conteúdo de fluxo do Kinesis. Em seguida, use o trecho de código a seguir para desserializar o conteúdo do fluxo.
```
/**
* Takes as input a Record fetched from Kinesis and does arbitrary processing as an example.
*/
public void processRecord(Record kinesisRecord) throws IOException {
ByteBuffer kdsRecordByteBuffer = kinesisRecord.getData();
JsonNode rootNode = OBJECT_MAPPER.readTree(kdsRecordByteBuffer.array());
JsonNode dynamoDBRecord = rootNode.get("dynamodb");
JsonNode oldItemImage = dynamoDBRecord.get("OldImage");
JsonNode newItemImage = dynamoDBRecord.get("NewImage");
Instant recordTimestamp = fetchTimestamp(dynamoDBRecord);
/**
* Say for example our record contains a String attribute named "stringName" and we want to fetch the value
* of this attribute from the new item image. The following code fetches this value.
*/
JsonNode attributeNode = newItemImage.get("stringName");
JsonNode attributeValueNode = attributeNode.get("S"); // Using DynamoDB "S" type attribute
String attributeValue = attributeValueNode.textValue();
System.out.println(attributeValue);
}
private Instant fetchTimestamp(JsonNode dynamoDBRecord) {
JsonNode timestampJson = dynamoDBRecord.get("ApproximateCreationDateTime");
JsonNode timestampPrecisionJson = dynamoDBRecord.get("ApproximateCreationDateTimePrecision");
if (timestampPrecisionJson != null && timestampPrecisionJson.equals("MICROSECOND")) {
return Instant.EPOCH.plus(timestampJson.longValue(), ChronoUnit.MICROS);
}
return Instant.ofEpochMilli(timestampJson.longValue());
}
```
------
#### [ Java ]
1. Siga as instruções no Guia do desenvolvedor do Kinesis Data Streams para [criar](https://docs.aws.amazon.com/streams/latest/dev/kinesis-using-sdk-java-create-stream.html) um fluxo de dados do Kinesis chamada `samplestream` usando Java.
Consulte [Considerações sobre gerenciamento de fragmentos para o Kinesis Data Streams](kds_using-shards-and-metrics.md#kds_using-shards-and-metrics.shardmanagment) antes de definir o número de fragmentos para o fluxo de dados do Kinesis.
1. Use o trecho de código a seguir para habilitar a transmissão do Kinesis na tabela do DynamoDB. Opcionalmente, habilite o streaming com uma precisão mais granular (microssegundos) dos valores de carimbo de data e hora retornados em cada registro.
Habilite o streaming com precisão de carimbo de data e hora em microssegundos:
```
EnableKinesisStreamingConfiguration enableKdsConfig = EnableKinesisStreamingConfiguration.builder()
.approximateCreationDateTimePrecision(ApproximateCreationDateTimePrecision.MICROSECOND)
.build();
EnableKinesisStreamingDestinationRequest enableKdsRequest = EnableKinesisStreamingDestinationRequest.builder()
.tableName(tableName)
.streamArn(kdsArn)
.enableKinesisStreamingConfiguration(enableKdsConfig)
.build();
EnableKinesisStreamingDestinationResponse enableKdsResponse = ddbClient.enableKinesisStreamingDestination(enableKdsRequest);
```
Ou habilite o streaming com a precisão padrão do carimbo de data e hora (milissegundos):
```
EnableKinesisStreamingDestinationRequest enableKdsRequest = EnableKinesisStreamingDestinationRequest.builder()
.tableName(tableName)
.streamArn(kdsArn)
.build();
EnableKinesisStreamingDestinationResponse enableKdsResponse = ddbClient.enableKinesisStreamingDestination(enableKdsRequest);
```
1. Siga as instruções do [Kinesis Data Streams developer guide](https://docs.aws.amazon.com/streams/latest/dev/building-consumers.html) (Guia do desenvolvedor do Kinesis Data Streams) para *ler* o fluxo de dados criado.
1. Use o trecho de código a seguir para desserializar o conteúdo do fluxo
```
/**
* Takes as input a Record fetched from Kinesis and does arbitrary processing as an example.
*/
public void processRecord(Record kinesisRecord) throws IOException {
ByteBuffer kdsRecordByteBuffer = kinesisRecord.getData();
JsonNode rootNode = OBJECT_MAPPER.readTree(kdsRecordByteBuffer.array());
JsonNode dynamoDBRecord = rootNode.get("dynamodb");
JsonNode oldItemImage = dynamoDBRecord.get("OldImage");
JsonNode newItemImage = dynamoDBRecord.get("NewImage");
Instant recordTimestamp = fetchTimestamp(dynamoDBRecord);
/**
* Say for example our record contains a String attribute named "stringName" and we wanted to fetch the value
* of this attribute from the new item image, the below code would fetch this.
*/
JsonNode attributeNode = newItemImage.get("stringName");
JsonNode attributeValueNode = attributeNode.get("S"); // Using DynamoDB "S" type attribute
String attributeValue = attributeValueNode.textValue();
System.out.println(attributeValue);
}
private Instant fetchTimestamp(JsonNode dynamoDBRecord) {
JsonNode timestampJson = dynamoDBRecord.get("ApproximateCreationDateTime");
JsonNode timestampPrecisionJson = dynamoDBRecord.get("ApproximateCreationDateTimePrecision");
if (timestampPrecisionJson != null && timestampPrecisionJson.equals("MICROSECOND")) {
return Instant.EPOCH.plus(timestampJson.longValue(), ChronoUnit.MICROS);
}
return Instant.ofEpochMilli(timestampJson.longValue());
}
```
------
## Alterar um fluxo de dados ativo do Amazon Kinesis
Esta seção descreve como alterar uma configuração ativa do Kinesis Data Streams para o DynamoDB usando o console, a AWS CLI e a API.
**Console de gerenciamento da AWS**
1. Abra o console do DynamoDB em [https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/).
1. Acesse a tabela.
1. Escolha **Exportações e streams**.
**AWS CLI**
1. Chame `describe-kinesis-streaming-destination` para confirmar se o fluxo está `ACTIVE`.
1. Chame `UpdateKinesisStreamingDestination`, como neste exemplo:
```
aws dynamodb update-kinesis-streaming-destination --table-name enable_test_table --stream-arn arn:aws:kinesis:us-east-1:12345678901:stream/enable_test_stream --update-kinesis-streaming-configuration ApproximateCreationDateTimePrecision=MICROSECOND
```
1. Chame `describe-kinesis-streaming-destination` para confirmar se o fluxo está `UPDATING`.
1. Chame `describe-kinesis-streaming-destination` periodicamente até que o status de streaming volte a ser `ACTIVE`. Normalmente, demora até 5 minutos para que as atualizações de precisão do carimbo de data e hora entrem em vigor. A atualização desse status indicará que a operação terá sido concluída e que o novo valor de precisão será aplicado em registros futuros.
1. Grave na tabela usando `putItem`.
1. Use o comando `get-records` do Kinesis para obter o conteúdo do fluxo.
1. Confirme se `ApproximateCreationDateTime` das gravações tem a precisão desejada.
**API Java**
1. Forneça um trecho de código que construa uma solicitação `UpdateKinesisStreamingDestination` e uma resposta `UpdateKinesisStreamingDestination`.
1. Forneça um trecho de código que construa uma solicitação `DescribeKinesisStreamingDestination` e uma `DescribeKinesisStreamingDestination response`.
1. Chame `describe-kinesis-streaming-destination` periodicamente até que o status de streaming volte a ser `ACTIVE`, indicando que a atualização foi concluída e que o novo valor de precisão será aplicado em registros futuros.
1. Faça gravações na tabela.
1. Faça uma leitura do fluxo e desserialize o conteúdo do fluxo.
1. Confirme se `ApproximateCreationDateTime` das gravações tem a precisão desejada.
# Usar fragmentos e métricas com o DynamoDB Streams e o Kinesis Data Streams
## Considerações sobre gerenciamento de fragmentos para o Kinesis Data Streams
Um fluxo de dados do Kinesis contabiliza o throughput em [fragmentos](https://docs.aws.amazon.com/streams/latest/dev/key-concepts.html). No Amazon Kinesis Data Streams, você pode escolher entre os modos **sob demanda** e **provisionado** para os fluxos de dados.
Recomendamos usar o modo sob demanda para seu fluxo de dados do Kinesis se sua workload de gravação do DynamoDB for altamente variável e imprevisível. No modo sob demanda, nenhum planejamento de capacidade é necessário, já que o Kinesis Data Streams gerencia automaticamente os fragmentos para fornecer o throughput necessário.
Para workloads previsíveis, você pode usar o modo provisionado para seu fluxo de dados do Kinesis. No modo provisionado, você precisa especificar o número de fragmentos para o fluxo de dados a fim de acomodar os registros de captura de dados de alterações do DynamoDB. Para determinar o número de fragmentos de que o fluxo de dados do Kinesis precisará para oferecer suporte à sua tabela do DynamoDB, são necessários os seguintes valores de entrada:
+ O tamanho médio do registro da tabela do DynamoDB em bytes (`average_record_size_in_bytes`).
+ O número máximo de operações de gravação que a tabela do DynamoDB executará por segundo. Isso inclui operações de criação, exclusão e atualização executadas pelas aplicações, bem como operações geradas automaticamente, como operações de exclusão geradas por vida útil (`write_throughput`).
+ O percentual de operações de atualização e substituição que você executou na tabela em comparação com operações de criação ou exclusão (`percentage_of_updates`). As operações de atualização e substituição replicam as imagens antigas e novas do item modificado para o fluxo. Isso gera o dobro do tamanho do item do DynamoDB.
Você pode calcular o número de fragmentos (`number_of_shards`) necessários para o fluxo de dados do Kinesis usando os valores de entrada na seguinte fórmula:
```
number_of_shards = ceiling( max( ((write_throughput * (4+percentage_of_updates) * average_record_size_in_bytes) / 1024 / 1024), (write_throughput/1000)), 1)
```
Por exemplo, você tem um throughput máximo de 1.040 operações de gravação por segundo (`write_throughput`) com um tamanho médio de registro de 800 bytes (`average_record_size_in_bytes)`. Se 25% dessas operações de gravação forem operações de atualização (`percentage_of_updates`), serão necessários dois fragmentos (`number_of_shards`) para acomodar o throughput de streaming do DynamoDB:
```
ceiling( max( ((1040 * (4+25/100) * 800)/ 1024 / 1024), (1040/1000)), 1).
```
Considere o seguinte antes de usar a fórmula para calcular o número de fragmentos necessários com o modo provisionado para fluxos de dados do Kinesis:
+ Essa fórmula ajuda a estimar o número de fragmentos que serão necessários para acomodar seus registros de dados de alterações do DynamoDB. Ela não representa o número total de fragmentos necessários no fluxo de dados do Kinesis, como o número de fragmentos necessários para oferecer suporte aos consumidores adicionais de fluxos de dados do Kinesis.
+ Ainda será possível ocorrer exceções de throughput de leitura e gravação no modo provisionado se o fluxo de dados não for configurado para lidar com o throughput máximo. Nesse caso, será preciso escalar manualmente o fluxo para acomodar o tráfego de dados.
+ Essa fórmula leva em consideração o inchaço adicional gerado pelo DynamoDB antes de fazer streaming dos registros de dados dos logs de alterações para o fluxo de dados do Kinesis.
Para saber mais sobre os modos de capacidade no Kinesis Data Streams, consulte [Choosing the Data Stream Capacity Mode](https://docs.aws.amazon.com/streams/latest/dev/how-do-i-size-a-stream.html). Para saber mais sobre a diferença de preços entre os diferentes modos de capacidade, consulte [Preços do Amazon Kinesis Data Streams](https://aws.amazon.com/kinesis/data-streams/pricing/).
## Monitorar a captura de dados de alterações com o Kinesis Data Streams
O DynamoDB fornece várias métricas do Amazon CloudWatch que ajudam a monitorar a replicação da captura de dados de alterações para o Kinesis. Para obter uma lista completa de métricas do CloudWatch, consulte [Métricas e dimensões do DynamoDB](metrics-dimensions.md).
Para determinar se o fluxo tem capacidade suficiente, recomendamos monitorar os seguintes itens durante a ativação do fluxo e na produção:
+ `ThrottledPutRecordCount`: o número de registros aos quais o fluxo de dados do Kinesis aplicou controle de utilização devido à capacidade insuficiente do fluxo de dados do Kinesis. O `ThrottledPutRecordCount` deve permanecer o mais baixo possível, embora você possa sentir algum controle de utilização durante picos excepcionais de uso. O DynamoDB tenta novamente enviar os registros limitados ao fluxo de dados do Kinesis, mas isso pode resultar em maior latência de replicação.
Se você perceber controle de utilização excessivo e regular, talvez seja necessário aumentar o número de fragmentos de fluxos do Kinesis proporcionalmente ao throughput de gravação observada da tabela. Para saber mais sobre a determinação do tamanho de um fluxo de dados do Kinesis, consulte [Como determinar o tamanho inicial de um fluxo de dados do Kinesis](https://docs.aws.amazon.com/streams/latest/dev/amazon-kinesis-streams.html#how-do-i-size-a-stream).
+ `AgeOfOldestUnreplicatedRecord`: o tempo decorrido desde a que alteração de nível de item mais antiga ainda a ser replicada para o fluxo de dados do Kinesis surgiu na tabela do DynamoDB. Em condições normais de operação, `AgeOfOldestUnreplicatedRecord` deve estar na ordem dos milissegundos. Esse número aumenta de acordo com as tentativas de replicação malsucedidas quando elas são causadas por opções de configuração controladas pelo cliente.
Se a métrica `AgeOfOldestUnreplicatedRecord` exceder 168 horas, a replicação das alterações no nível do item da tabela do DynamoDB para o fluxo de dados do Kinesis será automaticamente desabilitada.
São exemplos de configurações controladas pelo cliente que levam a tentativas de replicação malsucedidas: uma capacidade de fluxo de dados do Kinesis com provisionamento insuficiente, o que leva a controle de utilização excessivo, ou uma atualização manual das políticas de acesso do fluxo de dados do Kinesis que impede que o DynamoDB adicione dados ao fluxo de dados. Para manter essa métrica no mínimo possível, talvez seja necessário garantir o provisionamento correto da capacidade do fluxo de dados do Kinesis e que as permissões do DynamoDB permaneçam inalteradas.
+ `FailedToReplicateRecordCount`: número de registros que o DynamoDB não conseguiu replicar para o fluxo de dados do Kinesis. Determinados itens com mais de 34 KB podem se expandir em tamanho para alterar registros de dados maiores que o limite de 1 MB para itens do Kinesis Data Streams. Essa expansão de tamanho ocorre quando os itens com mais de 34 KB contêm um grande número de valores de atributos booleanos ou vazios. Valores de atributos booleanos e vazios são armazenados como 1 byte no DynamoDB, mas expandem até 5 bytes quando são serializados usando JSON padrão para replicação do Kinesis Data Streams. O DynamoDB não consegue replicar esses registros de alteração para o fluxo de dados do Kinesis. O DynamoDB ignora esses registros de dados de alteração e continua automaticamente a replicar registros subsequentes.
Você pode criar alarmes do Amazon CloudWatch que enviam uma mensagem do Amazon Simple Notification Service (Amazon SNS) para notificação quando qualquer uma das métricas anteriores exceder um limite específico.
# Usar políticas do IAM para o Amazon Kinesis Data Streams e Amazon DynamoDB
Na primeira vez que você habilitar o Amazon Kinesis Data Streams para Amazon DynamoDB, o DynamoDB criará automaticamente uma função vinculada ao serviço do AWS Identity and Access Management (IAM) para você. Esta função, `AWSServiceRoleForDynamoDBKinesisDataStreamsReplication`, permite que o DynamoDB gerencie a replicação de alterações em nível de item no Kinesis Data Streams em seu nome. Não exclua essa função vinculada ao serviço.
Para ter mais informações sobre perfis vinculados ao serviço, consulte [Criar um perfil vinculado ao serviço](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html) no *Guia do usuário do IAM*.
**nota**
O DynamoDB não oferece suporte a condições baseadas em etiqueta para políticas do IAM.
Para habilitar o Amazon Kinesis Data Streams para o Amazon DynamoDB, é necessário ter as seguintes permissões na tabela:
+ `dynamodb:EnableKinesisStreamingDestination`
+ `kinesis:ListStreams`
+ `kinesis:PutRecords`
+ `kinesis:DescribeStream`
A fim de descrever o Amazon Kinesis Data Streams para Amazon DynamoDB para determinada tabela do DynamoDB, é necessário ter as permissões a seguir na tabela.
+ `dynamodb:DescribeKinesisStreamingDestination`
+ `kinesis:DescribeStreamSummary`
+ `kinesis:DescribeStream`
A fim de desabilitar o Amazon Kinesis Data Streams para o Amazon DynamoDB, é necessário ter permissões a seguir na tabela.
+ `dynamodb:DisableKinesisStreamingDestination`
Para atualizar o Amazon Kinesis Data Streams para o Amazon DynamoDB, é necessário ter as permissões a seguir na tabela.
+ `dynamodb:UpdateKinesisStreamingDestination`
Os exemplos a seguir mostram como usar políticas do IAM para conceder permissões para o Amazon Kinesis Data Streams para Amazon DynamoDB.
## Exemplo: habilitar o Amazon Kinesis Data Streams para Amazon DynamoDB
A política do IAM a seguir concede permissões para habilitar o Amazon Kinesis Data Streams para o Amazon DynamoDB na tabela `Music`: Ela não concede permissões para desabilitar, atualizar ou descrever o Kinesis Data Streams para o DynamoDB na tabela `Music`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iam:CreateServiceLinkedRole",
"Resource": "arn:aws:iam::*:role/aws-service-role/kinesisreplication.dynamodb.amazonaws.com/AWSServiceRoleForDynamoDBKinesisDataStreamsReplication",
"Condition": {
"StringLike": {
"iam:AWSServiceName": "kinesisreplication.dynamodb.amazonaws.com"
}
}
},
{
"Effect": "Allow",
"Action": [
"dynamodb:EnableKinesisStreamingDestination"
],
"Resource": "arn:aws:dynamodb:us-west-2:111122223333:table/Music"
}
]
}
```
------
## Exemplo: Atualizar o Amazon Kinesis Data Streams para o Amazon DynamoDB
A política do IAM a seguir concede permissões para atualizar o Amazon Kinesis Data Streams para o Amazon DynamoDB na tabela `Music`: Ela não concede permissões para habilitar, desabilitar ou descrever o Amazon Kinesis Data Streams para o Amazon DynamoDB na tabela `Music`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:UpdateKinesisStreamingDestination"
],
"Resource": "arn:aws:dynamodb:us-west-2:111122223333:table/Music"
}
]
}
```
------
## Exemplo: desabilitar o Amazon Kinesis Data Streams para Amazon DynamoDB
A política do IAM a seguir concede permissões para desabilitar o Amazon Kinesis Data Streams para o Amazon DynamoDB na tabela `Music`: Ela não concede permissões para habilitar, atualizar ou descrever o Amazon Kinesis Data Streams para o Amazon DynamoDB na tabela `Music`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:DisableKinesisStreamingDestination"
],
"Resource": "arn:aws:dynamodb:us-west-2:111122223333:table/Music"
}
]
}
```
------
## Exemplo: aplicar seletivamente permissões para o Amazon Kinesis Data Streams para Amazon DynamoDB com base no recurso
A política do IAM a seguir concede permissões para habilitar e descrever o Amazon Kinesis Data Streams para o Amazon DynamoDB na tabela `Music` e nega permissões para desabilitar o Amazon Kinesis Data Streams para o Amazon DynamoDB na tabela `Orders`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:EnableKinesisStreamingDestination",
"dynamodb:DescribeKinesisStreamingDestination"
],
"Resource": "arn:aws:dynamodb:us-west-2:111122223333:table/Music"
},
{
"Effect": "Deny",
"Action": [
"dynamodb:DisableKinesisStreamingDestination"
],
"Resource": "arn:aws:dynamodb:us-west-2:111122223333:table/Orders"
}
]
}
```
------
## Usar funções vinculadas ao serviço para o Kinesis Data Streams para DynamoDB
O Amazon Kinesis Data Streams para Amazon DynamoDB usa [funções vinculadas ao serviço](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-service-linked-role) do AWS Identity and Access Management (IAM). A função vinculada ao serviço é um tipo exclusivo de perfil do IAM vinculada diretamente ao Kinesis Data Streams para DynamoDB. As funções vinculadas a serviços são predefinidas pelo Kinesis Data Streams para DynamoDB e incluem todas as permissões que o serviço requer para chamar outros serviços da AWS em seu nome.
Uma função vinculada ao serviço facilita a configuração do Kinesis Data Streams para DynamoDB porque você não precisa adicionar as permissões necessárias manualmente. O Kinesis Data Streams para DynamoDB define as permissões de suas funções vinculadas a serviços e, exceto se definido de outra forma, somente o Kinesis Data Streams para DynamoDB pode assumir suas funções. As permissões definidas incluem a política de confiança e a política de permissões, que não pode ser anexada a nenhuma outra entidade do IAM.
Para saber mais sobre outros serviços compatíveis com funções vinculadas a serviços, consulte [Serviços da AWS compatíveis com o IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html) e procure os serviços que contenham **Sim **na coluna **Função vinculada a serviço**. Escolha um **Sim** com um link para visualizar a documentação da função vinculada a esse serviço.
### Permissões de função vinculada ao serviço para o Kinesis Data Streams para DynamoDB
O Kinesis Data Streams para DynamoDB usa a função vinculada ao serviço chamada **AWSServiceRoleForDynamoDBKinesisDataStreamsReplication**. O objetivo dessa função vinculada ao serviço é permitir que o Amazon DynamoDB gerencie a replicação de alterações em nível de item no Kinesis Data Streams em seu nome.
O perfil vinculado ao serviço `AWSServiceRoleForDynamoDBKinesisDataStreamsReplication` confia nos seguintes serviços para aceitar o perfil:
+ `kinesisreplication.dynamodb.amazonaws.com`
A política de permissões da função permite que o Kinesis Data Streams for DynamoDB conclua as seguintes ações nos recursos especificados:
+ Ação: `Put records and describe` em `Kinesis stream`
+ Ação: `Generate data keys` no `AWS KMS` para colocar dados em fluxos do Kinesis que são criptografados usando chaves do AWS KMS geradas pelo usuário.
Para obter o conteúdo exato do documento de política, consulte [DynamoDBKinesisReplicationServiceRolePolicy](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/aws-service-role/DynamoDBKinesisReplicationServiceRolePolicy).
Você deve configurar permissões para que uma entidade do IAM (por exemplo, um usuário, grupo ou função) crie, edite ou exclua um perfil vinculado a serviço. Para saber mais, consulte [Permissões de Função Vinculadas ao Serviço](https://docs.aws.amazon.com/IAM/latest/UserGuide/contributorinsights-service-linked-roles.html#service-linked-role-permissions) no *Guia do Usuário do IAM*.
### Criar uma função vinculada ao serviço para o Kinesis Data Streams para DynamoDB
Não é necessário criar manualmente uma função vinculada ao serviço. Quando você habilita o Kinesis Data Streams para DynamoDB no Console de gerenciamento da AWS, na AWS CLI ou na API da AWS, o Kinesis Data Streams para DynamoDB cria a função vinculada ao serviço para você.
Se excluir essa função vinculada ao serviço e precisar criá-la novamente, você poderá usar esse mesmo processo para recriar a função em sua conta. Quando você habilita o Kinesis Data Streams para DynamoDB, o Kinesis Data Streams para DynamoDB cria a função vinculada ao serviço para você.
### Editar uma função vinculada ao serviço para o Kinesis Data Streams para DynamoDB
O Kinesis Data Streams para DynamoDB não permite editar a função vinculada ao serviço `AWSServiceRoleForDynamoDBKinesisDataStreamsReplication`. Depois que criar um perfil vinculado ao serviço, você não poderá alterar o nome do perfil, pois várias entidades podem fazer referência a ele. No entanto, será possível editar a descrição do perfil usando o IAM. Para saber mais, consulte [Editar uma função vinculada a serviço](https://docs.aws.amazon.com/IAM/latest/UserGuide/contributorinsights-service-linked-roles.html#edit-service-linked-role) no *Guia do usuário do IAM*.
### Excluir uma função vinculada ao serviço para o Kinesis Data Streams para DynamoDB
Também é possível usar o console do IAM, a AWS CLI ou a API da AWS para excluir manualmente a função vinculada ao serviço. Para isso, primeiro você deve limpar manualmente os recursos de sua função vinculada ao serviço e depois excluí-la manualmente.
**nota**
Se o serviço Kinesis Data Streams para DynamoDB estiver usando a função quando você tenta excluir os recursos, a exclusão poderá falhar. Se isso acontecer, espere alguns minutos e tente a operação novamente.
**Para excluir manualmente a função vinculada ao serviço usando o IAM**
Use o console do IAM, a AWS CLI ou a API da AWS para excluir a função vinculada ao serviço `AWSServiceRoleForDynamoDBKinesisDataStreamsReplication`. Para obter mais informações, consulte [Excluir uma função vinculada ao serviço](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html) no *Guia do usuário do IAM*.
# Capturar dados de alterações para o DynamoDB Streams
O DynamoDB Streams captura uma sequência em ordem temporal de modificações em nível de item em qualquer tabela do DynamoDB e armazena essas informações em um log por até 24 horas. As aplicações podem acessar esse log e visualizar os itens de dados à medida que eles aparecem antes e depois de serem modificados, quase em tempo real.
A criptografia em repouso criptografa os dados em fluxos do DynamoDB. Para obter mais informações, consulte [Criptografia em repouso do DynamoDB](EncryptionAtRest.md).
Um *fluxo do DynamoDB* é um fluxo ordenado de informações sobre alterações em itens de uma tabela do DynamoDB. Quando você habilita um fluxo em uma tabela, o DynamoDB captura informações sobre todas as modificações em itens de dados na tabela.
Sempre que uma aplicação cria, atualiza ou exclui itens nessa tabela, o DynamoDB Streams grava um registro de fluxo com os atributos de chave primária dos itens que foram modificados. Um *registro de fluxo* contém informações sobre uma modificação de dados em um único item de uma tabela do DynamoDB. É possível configurar o stream de modo que os registros de stream capturem informações adicionais, como as imagens "antes" e "depois" de itens modificados.
O DynamoDB Streams ajuda a garantir:
+ Cada registro do fluxo aparece exatamente uma vez no fluxo.
+ Para cada item modificado em uma tabela do DynamoDB, os registros de fluxo aparecem na mesma sequência que as modificações reais no item.
O DynamoDB Streams grava registros de fluxo em tempo quase real para que você possa criar aplicações que consomem esses fluxos e executam ações com base no conteúdo.
**Topics**
+ [Endpoints para DynamoDB Streams](#Streams.Endpoints)
+ [Habilitar um fluxo](#Streams.Enabling)
+ [Ler e processar um fluxo](#Streams.Processing)
+ [DynamoDB Streams e vida útil](time-to-live-ttl-streams.md)
+ [Usar o adaptador do DynamoDB Streams Kinesis Adapter para processar registros de fluxos](Streams.KCLAdapter.md)
+ [API de baixo nível do DynamoDB Streams: exemplo em Java](Streams.LowLevel.Walkthrough.md)
+ [DynamoDB Streams e acionadores do AWS Lambda](Streams.Lambda.md)
+ [DynamoDB Streams e Apache Flink](StreamsApacheFlink.xml.md)
## Endpoints para DynamoDB Streams
AWSO mantém endpoints separados para fluxos do DynamoDB e DynamoDB Streams. Para trabalhar com índices e tabelas de banco de dados, sua aplicação precisa acessar um endpoint do DynamoDB. Para ler e processar registros do DynamoDB Streams, sua aplicação precisa acessar um endpoint do DynamoDB Streams na mesma região.
O DynamoDB Streams oferece dois conjuntos de endpoints. Eles são:
+ **Endpoints somente IPv4**: endpoints com a convenção de nomenclatura `streams.dynamodb..amazonaws.com`.
+ **Endpoints de pilha dupla**: novos endpoints compatíveis com IPv4 e IPv6 e que seguem a convenção de nomenclatura `streams-dynamodb..api.aws`.
**nota**
Para obter uma lista completa de regiões e endpoints do DynamoDB e do DynamoDB Streams, consulte [Regiões e endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html) na *Referência geral da AWS*.
Os AWS SDKs fornecem clientes separados para o DynamoDB e o DynamoDB Streams. Dependendo das suas necessidades, sua aplicação pode acessar um endpoint do DynamoDB, um endpoint do DynamoDB Streams ou ambos ao mesmo tempo. Para conectar aos dois endpoints, a aplicação precisa instanciar dois clientes, um para o DynamoDB e outro para o DynamoDB Streams.
## Habilitar um fluxo
Você pode habilitar um stream em uma nova tabela ao criá-la usando a AWS CLI ou um dos AWS SDKs. Também pode habilitar ou desabilitar um stream em uma tabela existente ou alterar as configurações de um stream. O DynamoDB Streams opera de forma assíncrona e, portanto, não haverá impacto sobre a performance de uma tabela se você habilitar um stream.
A maneira mais fácil de gerenciar o DynamoDB Streams é usar o Console de gerenciamento da AWS.
1. Faça login no Console de gerenciamento da AWS e abra o console do DynamoDB em [https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/).
1. No painel do console do DynamoDB, escolha **Tables** (Tabelas) e selecione uma tabela existente.
1. Escolha a guia **Exports and streams** (Exportações e fluxos).
1. Na seção **Detalhes do stream do DynamoDB**, escolha **Ativar**.
1. Na página **Ativar fluxo do DynamoDB**, escolha as informações que serão gravadas no fluxo sempre que os dados da tabela forem modificados:
+ **Key attributes only (Somente atributos de chaves)**: somente os atributos de chaves do item modificado.
+ **New image** (Nova imagem): o item inteiro como é exibido depois de modificado.
+ **Old image** (Imagem antiga): o item inteiro como era exibido antes de modificado.
+ **New and old images** (Imagens nova e antiga): as imagens nova e antiga do item.
Quando estiver de acordo com as configurações, escolha **Ativar fluxo**.
1. (Opcional) Para desabilitar um fluxo existente, escolha **Desativar** em **Detalhes do stream do DynamoDB**.
Você também pode usar as operações da API `CreateTable` ou `UpdateTable` para habilitar ou modificar um fluxo. O parâmetro `StreamSpecification` determina como o fluxo é configurado:
+ `StreamEnabled`: especifica se um fluxo está habilitado (`true`) ou desabilitado (`false`) para a tabela.
+ `StreamViewType`: especifica as informações que serão gravadas no fluxo sempre que os dados na tabela forem modificados:
+ `KEYS_ONLY`: somente os atributos de chaves do item modificado.
+ `NEW_IMAGE`: o item inteiro como é exibido depois de ser modificado.
+ `OLD_IMAGE`: o item inteiro como era exibido antes de ser modificado.
+ `NEW_AND_OLD_IMAGES`: as imagens nova e antiga do item.
É possível habilitar ou desabilitar um fluxo a qualquer momento. No entanto, você receberá uma `ValidationException` se tentar habilitar um fluxo em uma tabela que já tenha um fluxo. Você também receberá uma `ValidationException` se tentar desabilitar um fluxo em uma tabela que não tenha um fluxo.
Quando você define `StreamEnabled` como `true`, o DynamoDB cria um novo fluxo com um descritor de streaming exclusivo atribuído a ele. Se você desabilitar e reabilitar um fluxo na tabela, será criado um fluxo com um descritor diferente.
Cada fluxo é identificado exclusivamente por um nome do recurso da Amazon (ARN). Veja a seguir um ARN de exemplo para um fluxo em uma tabela do DynamoDB chamada `TestTable`.
```
arn:aws:dynamodb:us-west-2:111122223333:table/TestTable/stream/2015-05-11T21:21:33.291
```
Para determinar o descritor de streaming mais recente de uma tabela, emita uma solicitação `DescribeTable` do DynamoDB e procure o elemento `LatestStreamArn` na resposta.
**nota**
Não é possível editar um `StreamViewType` após a configuração de um fluxo. Se você precisar fazer alterações em um fluxo depois que ele tiver sido configurado, será necessário desativar o fluxo atual e criar outro.
## Ler e processar um fluxo
Para ler e processar um fluxo, sua aplicação deve se conectar a um endpoint do DynamoDB Streams e emitir solicitações de API.
Um fluxo consiste em *registros de fluxo*. Cada registro de stream representa uma única modificação de dados na tabela do DynamoDB à qual o fluxo pertence. Cada registro de fluxo recebe um número de sequência, refletindo a ordem em que ele foi publicado no fluxo.
Os registros de fluxo estão organizados em grupos ou *fragmentos*. Cada fragmento atua como um contêiner para vários registros de fluxo e contém informações necessárias para acessar esses registros e fazer iterações neles. Os registros de fluxo em um fragmento são removidos automaticamente depois de 24 horas.
Fragmentos são efêmeros: eles são criados e excluídos automaticamente, conforme necessário. Qualquer fragmento também pode ser dividido em vários novos fragmentos, o que também ocorre automaticamente. (Também é possível que um fragmento pai tenha apenas um fragmento filho.) Um fragmento pode ser dividido em resposta a altos níveis de atividades de gravação em sua tabela principal e, portanto, as aplicações podem processar registros de vários fragmentos em paralelo.
Se você desabilitar um fluxo, todos os fragmentos que estiverem abertos serão fechados. Os dados no stream continuarão legíveis por 24 horas.
Como fragmentos têm uma linhagem (pai e filhos), uma aplicação sempre deverá processar um fragmento pai antes de um fragmento filho. Isso ajuda a garantir que os registros de fluxo também sejam processados na ordem correta. (Se você usa o DynamoDB Streams Kinesis Adapter, isso será feito para você. Sua aplicação processará os fragmentos e os registros de fluxo na ordem correta. Ela manipulará automaticamente fragmentos novos ou expirados, bem como fragmentos que são divididos enquanto a aplicação está em execução. Para obter mais informações, consulte [Usar o adaptador do DynamoDB Streams Kinesis Adapter para processar registros de fluxos](Streams.KCLAdapter.md).)
O diagrama a seguir mostra a relação entre um fluxo, os fragmentos nesse fluxo e os registros de fluxo nesses fragmentos.
![\[Estrutura do DynamoDB Streams. Os registros de fluxo que representam modificações de dados são organizados em fragmentos.\]](http://docs.aws.amazon.com/pt_br/amazondynamodb/latest/developerguide/images/streams-terminology.png)
**nota**
Se você executar uma operação `PutItem` ou `UpdateItem` que não altere nenhum dado em um item, o DynamoDB Streams *não* gravará um registro de fluxo para essa operação.
Para acessar um fluxo e processar os registros de fluxo dentro dele, você deve fazer o seguinte:
+ Determinar o ARN exclusivo do fluxo que deseja acessar.
+ Determinar quais fragmentos no fluxo contêm os registros de fluxo desejados.
+ Acessar os fragmentos e recuperar os registros de fluxo desejados.
**nota**
No máximo dois processos devem estar lendo simultaneamente do mesmo fragmento de fluxo. Ter mais de dois leitores por fragmento pode resultar em controle de utilização.
A API do DynamoDB Streams fornece as seguintes ações para uso por programas de aplicações:
+ `[ListStreams](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_streams_ListStreams.html)`: retorna uma lista de descritores de fluxos para a conta e o endpoint atuais. Opcionalmente, você pode solicitar apenas os descritores de fluxo de um nome de tabela específico.
+ `[DescribeStream](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_streams_DescribeStream.html)`: retorna informações sobre um streaming, incluindo o status atual do streaming, o Nome de recurso da Amazon (ARN), a composição de seus estilhaços e sua tabela correspondente do DynamoDB Você pode opcionalmente usar o campo `ShardFilter` para recuperar o fragmento filho existente associado ao fragmento pai.
+ `[GetShardIterator](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_streams_GetShardIterator.html)`: retorna um *iterador de fragmentos* que descreve um local dentro de um fragmento. Você pode solicitar que o iterador forneça acesso ao ponto mais antigo, o ponto mais novo ou um ponto específico no fluxo.
+ `[GetRecords](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_streams_GetRecords.html)`: retorna os registros do fluxo de um determinado fragmento. Você deve fornecer o iterador de fragmentos retornado de uma solicitação `GetShardIterator`.
Para obter descrições completas dessas operações da API, incluindo solicitações e respostas de exemplo, consulte a [Referência da API do Amazon DynamoDB Streams](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Operations_Amazon_DynamoDB_Streams.html).
### Descoberta de fragmentos
Descubra novos fragmentos em seu stream do DynamoDB com dois métodos poderosos. Como usuário do Amazon DynamoDB Streams, você tem duas maneiras eficazes de rastrear e identificar novos fragmentos:
**Pesquisando toda a topologia do stream**
Use a API `DescribeStream` para pesquisar regularmente o stream. Isso retorna todos os fragmentos no stream, incluindo novos fragmentos que tenham sido criados. Ao comparar os resultados ao longo do tempo, você pode detectar fragmentos recém-adicionados.
**Descobrindo fragmentos filhos**
Use a API `DescribeStream` com o parâmetro `ShardFilter` para encontrar um subconjunto de fragmentos. Ao especificar um fragmento pai na solicitação, o DynamoDB Streams retornará seus fragmentos filhos imediatos. Essa abordagem é útil quando você só precisa rastrear a linhagem do fragmento sem escanear todo o stream.
Os aplicativos que consomem dados do DynamoDB Streams podem fazer a transição eficiente da leitura de um fragmento fechado para seu fragmento filho usando esse parâmetro `ShardFilter`, evitando chamadas repetidas à API `DescribeStream` para recuperar e percorrer o mapa de fragmentos de todos os fragmentos fechados e abertos. Isso ajuda a descobrir rapidamente os fragmentos filhos após o fechamento de um fragmento pai, tornando seus aplicativos de processamento de stream mais responsivos e econômicos.
Ambos os métodos permitem que você fique por dentro da estrutura em evolução do seu DynamoDB Streams, garantindo que você nunca perca atualizações críticas de dados ou modificações de fragmentos.
### Limite de retenção de dados para o DynamoDB Streams
Todos os dados no DynamoDB Streams estão sujeitos a um tempo de vida de 24 horas. É possível recuperar e analisar as atividades das últimas 24 horas de qualquer tabela. No entanto, os dados mais antigos que 24 horas estão suscetíveis a remoção a qualquer momento.
Se você desabilitar um fluxo em uma tabela, os dados nesse fluxo continuarão legíveis por 24 horas. Depois desse tempo, os dados expirarão, e os registros de fluxo serão excluídos automaticamente. Não há nenhum mecanismo para excluir manualmente um fluxo existente. Aguarde até que o limite de retenção expire (24 horas), e todos os registros do fluxo sejam excluídos.
# DynamoDB Streams e vida útil
Você pode fazer backup ou processar os itens excluídos por [vida útil](TTL.md) (TTL) habilitando o Amazon DynamoDB Streams na tabela e processando os registros de fluxos dos itens expirados. Para obter mais informações, consulte [Ler e processar um fluxo](Streams.md#Streams.Processing).
O registro de fluxos contém um campo de identidade do usuário `Records[].userIdentity`.
Os itens excluídos pelo processo de vida útil após a expiração têm os seguintes campos:
+ `Records[].userIdentity.type`
`"Service"`
+ `Records[