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();
}
}
}
}
```
# 在 DynamoDB 中使用二级索引改进数据访问
Amazon DynamoDB 通过指定主键值来提供对表中项目的快速访问。但是，很多应用程序可能适合有一个或多个二级（或替代）键，以便通过主键以外的属性对数据进行高效访问。要解决此问题，您可以对表创建一个或多个二级索引，然后对这些索引发出 `Query` 或 `Scan` 请求。
*二级索引*是一种数据结构，它包含表中属性的子集以及一个支持 `Query` 操作的替代键。您可以使用 `Query` 从索引中检索数据，其方式与对表使用 `Query` 大致相同。一个表可以有多个二级索引，这样，应用程序可以访问许多不同的查询模式。
**注意**
也可以对索引使用 `Scan`，其方式与对表使用 `Scan` 大致相同。
[基于资源的策略](access-control-resource-based.md)目前不支持跨账户访问二级索引扫描操作。
每个二级索引关联且仅关联一个表，并从该表中获取其数据。这称为索引的*基表*。在创建索引时，您为索引定义一个替代键 (分区键和排序键)。您还可以定义要从基表*投影*或复制到索引的属性。DynamoDB 将这些属性以及基表中的主键属性一起复制到索引中。然后，您可以查询或扫描该索引，就像查询或扫描表一样。
每个二级索引都由 DynamoDB 自动维护。在基表中添加、修改或删除项目时，表上的所有索引也会更新，以反映这些更改。
DynamoDB 支持两种类型的二级索引：
+ **[全局二级索引](GSI.html) — **分区键和排序键可与基表中的这些键不同的索引。全局二级索引之所以称为“全局”，是因为索引上的查询可跨过所有分区，覆盖基表的所有数据。全局二级索引存储在其远离基表的分区空间中，并且独立于基表进行扩展。
+ **[本地二级索引](LSI.html) — **分区键与基表相同但排序键不同的索引。本地二级索引之所以称为“本地”，是因为索引的每个分区的范围都限定为具有相同分区键值的基表分区。
有关全局二级索引和本地二级索引的比较，请观看此视频。
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/BkEu7zBWge8)
**Topics**
+ [在 DynamoDB 中使用全局二级索引](GSI.md)
+ [本地二级索引](LSI.md)
在确定要使用的索引类型时，应考虑应用程序的要求。下表显示了全局二级索引和本地二级索引之间的主要区别。
****
| 特征 | 全局二级索引 | 本地二级索引 |
| --- | --- | --- |
| 键架构 | 全局二级索引的主键可以是简单主键（分区键）或复合主键（分区键和排序键）。 | 本地二级索引的主键必须是复合主键（分区键和排序键）。 |
| 键属性 | 索引分区键和排序键 (如果有) 可以是字符串、数字或二进制类型的任何基表属性。 | 索引的分区键是与基表的分区键相同的属性。排序键可以是字符串、数字或二进制类型的任何基表属性。 |
| 每个分区键值的大小限制 | 全局二级索引没有大小限制。 | 对于每个分区键值，所有索引项目的大小总和必须为 10 GB 或更小。 |
| 在线索引操作 | 全局二级索引可以在您创建表的同时创建。您还可以向现有表中添加新的全局二级索引，或删除现有的全局二级索引。有关更多信息，请参阅 [在 DynamoDB 中管理全局二级索引](GSI.OnlineOps.md)。 | 本地二级索引在您创建表的同时创建。您不能向现有表添加本地二级索引，也不能删除已存在的任何本地二级索引。 |
| 查询和分区 | 通过全局二级索引，可以跨所有分区查询整个表。 | 借助本地二级索引，您可以对查询中分区键值指定的单个分区进行查询。 |
| 读取一致性 | 全局二级索引查询仅支持最终一致性。 | 查询本地二级索引时，您可以选择最终一致性或强一致性。 |
| 预置吞吐量使用 | 每个全局二级索引都有自己的用于读取和写入活动的预置吞吐量设置。对全局二级索引执行的查询或扫描会占用索引（而非基表）的容量单位。全局二级索引更新也是如此，因为会进行表写入。与全局表关联的全局二级索引会占用写入容量单位。 | 对本地二级索引执行的查询或扫描会占用基表的读取容量单位。写入一个表时，其本地二级索引也将更新；这些更新会占用基表的写入容量单位。与全局表关联的本地二级索引会占用复制的写入容量单位。 |
| 投影属性 | 对于全局二级索引查询或扫描，您只能请求投影到索引的属性。DynamoDB 不会从表中获取任何属性。 | 如果查询或扫描本地二级索引，可以请求未投影到索引的属性。DynamoDB 会自动从表中获取这些属性。 |
如果要创建多个含有二级索引的表，必须按顺序执行此操作。例如，您可以创建第一个表，等待其状态变为 `ACTIVE`，创建下一个表，等待其状态变为 `ACTIVE`，依此类推。如果您尝试同时创建多个含有二级索引的表，DynamoDB 会返回 `LimitExceededException`。
每个二级索引都使用与其关联的基表相同的[表类](HowItWorks.TableClasses.html)和[容量模式](capacity-mode.md)。对于每个二级索引，必须指定以下内容：
+ 要创建的索引类型 — 全局二级索引或本地二级索引。
+ 索引的名称。索引的命名规则与表的命名规则相同，具体请参阅 [Amazon DynamoDB 中的配额](ServiceQuotas.md)。就相关联的基表而言，索引的名称必须唯一，不过，与不同的基表相关联的索引的名称可以相同。
+ 索引的键架构。索引键架构中的每个属性必须是类型为 `String`、`Number` 或 `Binary` 的顶级属性。其他数据类型，包括文档和集，均不受支持。键架构的其他要求取决于索引的类型：
+ 对于全局二级索引，分区键可以是基表的任何标量属性。排序键是可选的，也可以是基表的任何标量属性。
+ 对于本地二级索引，分区键必须与基表的分区键相同，排序键必须是非键基表属性。
+ 要从基表投影到索引中的其他属性 (如果有)。这些属性是除表键属性之外的属性，表键属性会自动投影到每个索引。您可以投影任何数据类型的属性，包括标量、文档和集。
+ 索引的预置吞吐量设置（如有必要）：
+ 对于全局二级索引，您必须指定读取和写入容量单位设置。这些预置吞吐量设置独立于基表的设置。
+ 对于本地二级索引，您无需指定读取和写入容量单位设置。对本地二级索引进行的读取和写入操作会占用其基表的预置吞吐量设置。
为获得最高的查询灵活性，您可以为每个表创建最多 20 个全局二级索引（默认配额）和最多 5 个本地二级索引。
要获取表的二级索引的详细列表，请使用 `DescribeTable` 操作。`DescribeTable` 将返回表上每个的名称、存储大小和项目计数。系统并不会实时更新这些值，但会大约每隔六个小时刷新一次。
您可以使用 `Query` 或 `Scan` 操作来访问二级索引中的数据。您必须指定您要使用的基表的名称和索引的名称、要在结果中返回的属性以及要应用的任何条件表达式或筛选条件。DynamoDB 可以按升序或降序返回结果。
删除表时，会同时删除与该表关联的全部索引。
有关最佳实践，请参阅[在 DynamoDB 中使用二级索引的最佳实践](bp-indexes.md)。
# 在 DynamoDB 中使用全局二级索引
一些应用程序可能需要使用很多不同的属性作为查询条件，来执行许多类型的查询。要支持这些要求，您可以创建一个或多个*全局二级索引*，在 Amazon DynamoDB 中针对这些索引发出 `Query` 请求。
**Topics**
+ [场景：使用全局二级索引](#GSI.scenario)
+ [属性投影](#GSI.Projections)
+ [多属性键架构](#GSI.MultiAttributeKeys)
+ [从全局二级索引读取数据](#GSI.Reading)
+ [表与全局二级索引之间的数据同步](#GSI.Writes)
+ [具有全局二级索引的表类别](#GSI.tableclasses)
+ [全局二级索引的预调配吞吐量注意事项](#GSI.ThroughputConsiderations)
+ [全局二级索引的存储注意事项](#GSI.StorageConsiderations)
+ [设计模式](GSI.DesignPatterns.md)
+ [在 DynamoDB 中管理全局二级索引](GSI.OnlineOps.md)
+ [在 DynamoDB 中检测和纠正索引键违规](GSI.OnlineOps.ViolationDetection.md)
+ [处理全局二级索引：Java](GSIJavaDocumentAPI.md)
+ [处理全局二级索引：.NET](GSILowLevelDotNet.md)
+ [借助 AWS CLI 在 DynamoDB 中使用全局二级索引](GCICli.md)
## 场景：使用全局二级索引
为进行说明，考虑使用一个名为 `GameScores` 的表跟踪一个移动游戏应用程序的用户和分数。`GameScores` 中的每一项使用一个分区键 (`UserId`) 和一个排序键 (`GameTitle`) 标识。下表显示了此表中项目的组织方式，（并未显示所有属性。）
![\[包含用户 ID、头衔、得分、日期和输赢次数的 GameScores 表。\]](http://docs.aws.amazon.com/zh_cn/amazondynamodb/latest/developerguide/images/GSI_01.png)
现在假设您要编写一个排行榜应用程序以显示每个游戏的最高分数。指定键属性 (`UserId` 和 `GameTitle`) 的查询将会非常高效。但是，如果应用程序仅需要基于 `GameScores` 从 `GameTitle` 检索数据，则需要使用 `Scan` 操作。随着更多项目添加到表中，所有数据的扫描会变得缓慢且低效。这会使得难于回答以下问题：
+ 对游戏 Meteor Blasters 记录的最高分数是多少？
+ 哪个用户拥有 Galaxy Invaders 的最高分数？
+ 最高赢输比是多少？
要加快对非键属性的查询，您可以创建一个全局二级索引。全局二级索引包含从基表中选择的一组属性，但是这些属性按与表主键不同的主键进行排列。索引键不必具有来自表的任何键属性。它甚至不必具有与表相同的键架构。
例如，您可以创建名为 `GameTitleIndex` 的全局二级索引，其分区键为 `GameTitle`，排序键为 `TopScore`。基表的主键属性始终投影到某个索引，因此 `UserId` 属性也存在。`GameTitleIndex` 索引如下图所示。
![\[包含头衔、得分和用户 ID 的 GameTitleIndex 表。\]](http://docs.aws.amazon.com/zh_cn/amazondynamodb/latest/developerguide/images/GSI_02.png)
现在，您可以查询 `GameTitleIndex` 并方便地获取 Meteor Blasters 的分数。结果按排序键值 `TopScore` 进行排序。如果您将 `ScanIndexForward` 参数设置为 false，则结果按降序返回，因此最高分数最先返回。
每个全局二级索引都必须有分区键，另外可以有可选的排序键。索引键架构可以不同于基表架构。您可以拥有带有简单主键（分区键）的表，然后使用复合主键（分区键和排序键）创建全局二级索引，反之亦然。索引键属性可以包含来自基表的任意顶级 `String`、`Number` 或 `Binary` 属性。不允许使用其他标量类型、文档类型和集合类型。
您可以在需要时将其他基表属性投影到索引。当您查询索引时，DynamoDB 便可高效地检索这些已投影的属性。但是，全局二级索引查询无法从基表提取属性。例如，如果您如上图所示查询 `GameTitleIndex`，则查询无法访问除 `TopScore`（虽然键属性 `GameTitle` 和 `UserId` 将自动投影）之外的任何非键属性。
在 DynamoDB 表中，每个键值都必须唯一。但是，全局二级索引中的键值无需唯一。为进行说明，假设一个名为 Comet Quest 的游戏难度特别高，许多新用户进行尝试，但是无法获得零以上的分数。以下是可以表示这种情况的一些数据。
****
| UserId | GameTitle | TopScore |
| --- | --- | --- |
| 123 | Comet Quest | 0 |
| 201 | Comet Quest | 0 |
| 301 | Comet Quest | 0 |
当此数据添加到 `GameScores` 表中时，DynamoDB 将其传播到 `GameTitleIndex`。如果我们随后以 Comet Quest 作为 `GameTitle` 并以 0 作为 `TopScore` 来查询索引，则将返回以下数据。
![\[包含头衔、最高得分和用户 ID 的表。\]](http://docs.aws.amazon.com/zh_cn/amazondynamodb/latest/developerguide/images/GSI_05.png)
响应中仅显示具有指定键值的项。在该组数据中，项没有特定顺序。
全局二级索引仅跟踪其键属性实际存在的数据项。例如，假设您向 `GameScores` 表添加了另一个新项目，但是仅提供了必需的主键属性。
****
| UserId | GameTitle |
| --- | --- |
| 400 | Comet Quest |
因为您未指定 `TopScore` 属性，DynamoDB 不会将此项目传播到 `GameTitleIndex`。因此，如果您针对所有 Comet Quest 项目查询 `GameScores`，则会获得以下四个项目。
![\[包含 4 个头衔列表、最高得分和用户 ID 的表。\]](http://docs.aws.amazon.com/zh_cn/amazondynamodb/latest/developerguide/images/GSI_04.png)
对 `GameTitleIndex` 执行的相似查询仍会返回三项，而不是四个。这是因为，不存在 `TopScore` 的项不会传播到索引。
![\[包含 3 个头衔列表、最高得分和用户 ID 的表。\]](http://docs.aws.amazon.com/zh_cn/amazondynamodb/latest/developerguide/images/GSI_05.png)
## 属性投影
*投影*是从表复制到二级索引的属性集。表的分区键和排序键始终投影到索引中；您可以投影其他属性以支持应用程序的查询要求。当您查询索引时，Amazon DynamoDB 可以访问投影中的任何属性，就像这些属性位于自己的表中一样。
创建二级索引时，需要指定将投影到索引中的属性。DynamoDB 为此提供了三种不同的选项：
+ *KEYS\$1ONLY* – 索引中的每个项目仅包含表的分区键、排序键值以及索引键值。`KEYS_ONLY` 选项会导致最小二级索引。
+ *INCLUDE* – 除 `KEYS_ONLY` 中描述的属性外，二级索引还包括您指定的其他非键属性。
+ *ALL* – 二级索引包括源表中的所有属性。由于所有表数据都在索引中复制，因此 `ALL` 投影会产生最大二级索引。
在上图中，`GameTitleIndex` 只有一个投影属性：`UserId`。因此，尽管应用程序通过在查询中使用 `UserId` 和 `GameTitle` 能够高效确定每个游戏中得分榜选手的 `TopScore`，但不能高效确定得分榜选手的最高输赢比。为此，应用程序必须对基表执行额外查询，以获取每个得分榜选手的输赢数据。要支持对此数据进行查询，更高效的方法是将这些属性从基表投影到全局二级索引，如下图所示。
![\[将非键属性投影到 GSI 中以支持高效查询的描述。\]](http://docs.aws.amazon.com/zh_cn/amazondynamodb/latest/developerguide/images/GSI_06.png)
因为非键属性 `Wins` 和 `Losses` 投影到索引，所以应用程序可以确定任何游戏或是任何游戏和用户 ID 组合的赢输比。
您在选择要投影到全局二级索引的属性时，必须在预置吞吐量成本和存储成本之间做出权衡：
+ 如果只需要访问少量属性，同时尽可能降低延迟，就应考虑仅将键属性投影到全局二级索引。索引越小，存储索引所需的成本越少，并且写入成本也会越少。
+ 如果您的应用程序频繁访问某些非键属性，就应考虑将这些属性投影到全局二级索引。全局二级索引的额外存储成本会抵消频繁执行表扫描的成本。
+ 如果需要频繁访问大多数非键属性，则可以将这些属性（甚至整个基表）投影到全局二级索引中。这为您带来了最大限度的灵活性。但是，您的存储成本将增长，甚至翻倍。
+ 如果您的应用程序并不会频繁查询表，但必须要对表中的数据执行大量写入或更新操作，就应考虑投影 `KEYS_ONLY`。这是最小的全局二级索引，但仍可用于查询活动。
## 多属性键架构
全局二级索引支持多属性键，让您可以从多个属性组成分区键和排序键。使用多属性键，您可以从最多四个属性创建分区键，从最多四个属性创建排序键，这样每个键架构最多总共可以有八个属性。
多属性键无需手动将属性连接成合成键，这样可以简化数据模型。您可以直接使用域模型中的自然属性，而不是创建像 `TOURNAMENT#WINTER2024#REGION#NA-EAST` 这样的复合字符串。DynamoDB 自动处理复合键逻辑，对多个分区键属性一起进行哈希处理用于数据分布，并维护多个排序键属性的分层排序顺序。
例如，假设有一个游戏锦标赛系统，您想按锦标赛和地区组织比赛。使用多属性键，您可以将分区键定义为两个单独的属性：`tournamentId` 和 `region`。同样，您可以使用 `round`、`bracket` 和 `matchId` 等多个属性来定义排序键，用于创建自然的层次结构。这种方法可以保持数据类型化和代码整洁，无需对字符串进行操作或解析。
使用多属性键查询全局二级索引时，必须使用相等条件指定所有分区键属性。对于排序键属性，您可以按照它们在键架构中定义的顺序从左到右进行查询。这意味着您可以单独查询第一个排序键属性，同时查询前两个属性，或者同时查询所有属性，但您不能跳过中间的属性。不相等条件（例如 `>`、`<`、`BETWEEN` 或 `begins_with()`）必须是查询中的最后一个条件。
在现有表上创建全局二级索引时，多属性键特别有效。您可以使用表中已经存在的属性，而无需在数据中回填合成键。这样就可以创建索引，使用不同的属性组合来识别数据，从而直接向应用程序添加新的查询模式。
多属性键中的每个属性都可以有自己的数据类型：`String`（S）、`Number`（N）或 `Binary`（B）。选择数据类型时，请考虑 `Number` 属性按数字排序而无需补零，而 `String` 属性则按字典顺序排序。例如，如果您为分数属性使用 `Number` 类型，则值 5、50、500 和 1000 将按自然数字顺序排序。为相同的值使用 `String` 类型时，则排序的结果为“1000”、“5”、“50”、“500”，除非您用前导零填充它们。
在设计多属性键时，请按从最一般到最具体的顺序对属性进行排序。对于分区键，请将始终会一起查询且能够提供良好数据分布的属性组合在一起。对于排序键，请将经常查询的属性放在层次结构的前面，以最大限度地提高查询灵活性。这种排序让您可以按照与访问模式匹配的任何粒度级别进行查询。
有关实施示例，请参阅[多属性键](GSI.DesignPattern.MultiAttributeKeys.md)。
## 从全局二级索引读取数据
您可以使用 `Query` 和 `Scan` 操作从全局二级索引检索项目。`GetItem` 和 `BatchGetItem` 操作不能用于全局二级索引。
### 查询全局二级索引
您可以使用 `Query` 操作来访问全局二级索引中的一个或多个项目。查询必须指定要使用的基表名称和索引名称、查询结果中要返回的属性以及要应用的任何查询条件。DynamoDB 可以按升序或降序返回结果。
考虑为排行榜应用程序请求游戏数据的 `Query` 返回的以下数据。
```
{
"TableName": "GameScores",
"IndexName": "GameTitleIndex",
"KeyConditionExpression": "GameTitle = :v_title",
"ExpressionAttributeValues": {
":v_title": {"S": "Meteor Blasters"}
},
"ProjectionExpression": "UserId, TopScore",
"ScanIndexForward": false
}
```
在此查询中：
+ DynamoDB 使用 *GameTitle* 分区键访问 *GameTitleIndex*，查找 Meteor Blasters 的索引项目。具有此键的所有索引项目都彼此相邻存储，以实现快速检索。
+ 在此游戏中，DynamoDB 使用索引访问此游戏的所有用户 ID 和最高分数。
+ 因为 `ScanIndexForward` 参数设置为 false，所以结果按降序返回。
### 扫描全局二级索引
您可以使用 `Scan` 操作从全局二级索引检索全部数据。您必须在请求中提供基表名称和索引名称。通过 `Scan`，DynamoDB 可读取索引中的全部数据并将其返回到应用程序。您还可以请求仅返回部分数据并放弃其余数据。为此，请使用 `FilterExpression` 操作的 `Scan` 参数。有关更多信息，请参阅 [扫描的筛选表达式](Scan.md#Scan.FilterExpression)。
## 表与全局二级索引之间的数据同步
DynamoDB 自动将每个全局二级索引与其基表同步。当应用程序对某个表写入或删除项目时，该表的所有全局二级索引都会使用最终一致性模型异步更新。应用程序绝不会直接向索引中写入内容。但是，您有必要了解 DynamoDB 如何维护这些索引。
全局二级索引继承基表的读/写入容量模式。有关更多信息，请参阅 [在 DynamoDB 中切换容量模式时的注意事项](bp-switching-capacity-modes.md)。
在创建全局二级索引之后，您可以指定一个或多个索引键属性及其数据类型。这就意味着，无论您何时向基表中写入项目，这些属性的数据类型必须与索引键架构的数据类型匹配。在 `GameTitleIndex` 的情况下，索引中的 `GameTitle` 分区键定义为 `String` 数据类型。索引中的 `TopScore` 排序键为 `Number` 类型。如果您尝试向 `GameScores` 表添加项目并为 `GameTitle` 或 `TopScore` 指定其他数据类型，DynamoDB 会因数据类型不匹配而返回 `ValidationException`。
在表中放置或删除项目时，表的全局二级索引会以最终一致性方式进行更新。在正常情况下，对表数据进行的更改会瞬间传播到全局二级索引。但是，在某些不常发生的故障情况下，可能出现较长时间的传播延迟。因此，应用程序需要预计和处理对全局二级索引进行的查询返回不是最新结果的情况。
如果向表中写入项目，无需指定全局二级索引任何排序键的属性。以 `GameTitleIndex` 为例，您无需指定 `TopScore` 属性的值就可以向 `GameScores` 表写入新项目。在本示例中，DynamoDB 不会向此特定项目的索引写入任何数据。
相较于索引数量较少的表，拥有较多全局二级索引的表会产生较高的写入活动成本。有关更多信息，请参阅 [全局二级索引的预调配吞吐量注意事项](#GSI.ThroughputConsiderations)。
## 具有全局二级索引的表类别
全局二级索引将始终使用与其基表相同的表类别。为表添加新的全局二级索引时，新索引将使用与其基表相同的表类别。更新表的表类别时，所有关联的全局二级索引也会更新。
## 全局二级索引的预调配吞吐量注意事项
在预置模式表创建全局二级索引时，必须根据该索引的预期工作负载指定读取和写入容量单位。全局二级索引的预置吞吐量设置独立于其基表的相应设置。对全局二级索引执行的 `Query` 操作占用索引（而非基表）的读取容量单位。在表中放置、更新或删除项目时，还会更新表的全局二级索引。这些索引更新占用索引（而非基表）的写入容量单位。
例如，如果您对全局二级索引执行 `Query` 操作并超过其预配置读取容量，则您的请求会受到阻止。如果您对表执行大量写入活动，但是该表的全局二级索引没有足够写入容量，则对该表进行的写入活动会受到限制。
**重要**
为了避免触发可能的限制，全局二级索引的预配置写入容量应等于或大于基表的写入容量，因为新更新将同时写入基表和全局二级索引。
要查看全局二级索引的预配置吞吐量设置，请使用 `DescribeTable` 操作。这将返回表的所有全局二级索引的详细信息。
### 读取容量单位
全局二级索引支持最终一致性读取，每个读取占用一半的读取容量单位。这意味着，单个全局二级索引查询对于每个读取容量单位，可以检索最多 2 × 4 KB = 8 KB。
对于全局二级索引查询，DynamoDB 计算预配置读取活动的方式与对表查询使用的方式相同。唯一不同的是，本次计算基于索引条目的大小，而不是基表中项目的大小。读取容量单位的数量就是返回的所有项目的所有投影属性大小之和。然后，该结果会向上取整到 4 KB 边界。有关 DynamoDB 如何计算预配置吞吐量使用情况的更多信息，请参阅 [DynamoDB 预置容量模式](provisioned-capacity-mode.md)。
`Query` 操作返回的结果大小上限为 1 MB。这包括所有属性名称的大小和所返回的所有项目的值。
例如，请考虑使用每项均包含 2000 字节数据的 全局二级索引。现在假设您对此索引执行 `Query` 操作，并且该查询的 `KeyConditionExpression` 匹配八个项目。匹配项目的总大小为 2000 字节 x 8 个项目 = 16000 字节。然后，该结果会向上取整到最近的 4 KB 边界。由于全局二级索引查询具有最终一致性，因此总成本是 0.5 × (16 KB / 4 KB))，即 2 个读取容量单位。
### 写入容量单位
在添加、更新或删除表中的项目，并且全局二级索引受此影响时，全局二级索引将占用为此操作预配置的写入容量单位。一次写入操作的预配置吞吐量总成本是对基表执行的写入操作以及更新全局二级索引所占用的写入容量单位之和。如果对表执行的写入操作不需要全局二级索引更新，则不会占用索引的写入容量。
要成功写入表，表及其所有全局二级索引的预配置吞吐量设置必须具有足够的写入容量来允许写入。否则，对表的写入将受到限制。
**重要**
创建全局二级索引（GSI）时，如果写入基表所产生的 GSI 活动超过了 GSI 的预置写入容量，则对基表的写入操作会受限。这种节流会影响所有写入操作，其影响小至干扰索引编制流程，大至可能中断您的生产工作负载。有关更多信息，请参阅 [Amazon DynamoDB 中节流故障排除](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/TroubleshootingThrottling.html)。
向全局二级索引写入项目的成本取决于多个因素：
+ 如果您向定义了索引属性的表中写入新项目，或更新现有的项目来定义之前未定义的索引属性，只需一个写入操作即可将项目放置到索引中。
+ 如果对表执行的更新操作更改了索引键属性的值（从 A 更改为 B），就需要执行两次写入操作，一次用于删除索引中之前的项目，另一次用于将新项目放置到索引中。
+ 如果索引中已有某一项目，而对表执行的写入操作删除了索引属性，就需要执行一次写入操作删除索引中旧的项目投影。
+ 如果更新项目前后索引中没有此项目，此索引就不会额外产生写入成本。
+ 如果对表的更新仅更改了索引键架构中投影属性的值，但不更改任何索引键属性的值，则需要执行一次写入以将投影属性的值更新到索引中。
所有这些因素都假定索引中每个项目的大小小于或等于 1 KB 这一项目大小（用于计算写入容量单位）。如果索引条目大于这一大小，就会占用额外的写入容量单位。您可以考虑查询需要返回的属性类型并仅将这些属性投影到索引中，从而最大程度地减少写入成本。
## 全局二级索引的存储注意事项
当应用程序向表中写入项目时，DynamoDB 会自动将适当的属性子集复制到应包含这些属性的所有全局二级索引。您的 AWS 账户需要支付在基表中存储项目以及在表的任何全局二级索引中存储属性的费用。
索引项目所占用的空间大小就是以下内容之和：
+ 基表的主键 (分区键和排序键) 的大小 (按字节计算)
+ 索引键属性的大小（按字节计算）
+ 投影的属性（如果有）的大小（按字节计算）
+ 每个索引项目 100 字节的开销
要估算全局二级索引的存储要求，您可以估算索引中项目的平均大小，然后乘以基表中具有全局二级索引键属性的项目数。
如果表包含的某个项目未定义特定属性，但是该属性定义为索引分区键或排序键，则 DynamoDB 不会将该项目的任何数据写入到索引中。
# 设计模式
设计模式为使用全局二级索引时的常见挑战提供了行之有效的解决方案。这些模式向您展示如何针对特定使用案例设计索引结构，从而帮助您构建高效、可扩展的应用程序。
每种模式都包含完整的实施指南，其中包含代码示例、最佳实践和实际使用案例，帮助您将模式应用于自己的应用程序。
**Topics**
+ [多属性键](GSI.DesignPattern.MultiAttributeKeys.md)
# 多属性键模式
## 概述
通过多属性键，您可以创建全局二级索引（GSI）分区键和排序键，每个分区键和排序键最多由四个属性组成。这可减少客户端的代码数量，并简化了对数据进行初始建模和以后添加新访问模式的工作。
考虑一个常见的场景：要创建按多个分层属性查询项目的 GSI，传统上需要通过连接值来创建合成键。例如，在游戏应用程序中，如果要按锦标赛、地区和回合查询锦标赛比赛，您可以创建一个合成 GSI 分区键（例如 TOURNAMENT\$1WINTER2024\$1REGION\$1NA-EAST）和一个合成排序键（例如 ROUND\$1SEMIFINALS\$1BRACKET\$1UPPER）。这种方法是可行的，但是在写入数据时需要连接字符串，在读取时需要进行解析，如果要将 GSI 添加到现有表中，还需要在所有现有项目上回填合成键。这使得代码更加混乱，更难维护各个关键组件的类型安全。
多属性键可以解决 GSI 的这个问题。您可以使用多个现有属性（例如 tournamentId 和 region）来定义 GSI 分区键。DynamoDB 会自动处理复合键逻辑，将它们一起进行哈希处理用于数据分布。您使用域模型中的自然属性编写项目，而 GSI 会自动为它们编制索引。无需连接，无需解析，也无需回填。代码保持干净，数据保持类型化，查询保持简单。当您拥有使用自然属性分组的分层数据时（例如锦标赛 → 区域 → 回合，或企业 → 部门 → 团队），这种方法特别有用。
## 应用程序示例
本指南介绍如何为电子竞技平台构建锦标赛比赛跟踪系统。该平台需要有效地按多个维度查询比赛：按锦标赛和地区进行分组管理，按玩家查询比赛历史记录，按日期进行排程。
## 数据模型
在本演练中，锦标赛比赛跟踪系统支持三种主要访问模式，每种模式都需要不同的键结构：
**访问模式 1：**通过唯一 ID 查找特定比赛
+ **解决方案：**使用 `matchId` 作为分区键的基表
**访问模式 2：**查询特定锦标赛和地区的所有比赛，可以选择按回合、分组或比赛进行筛选
+ **解决方案：**使用多属性分区键（`tournamentId` \$1 `region`）和多属性排序键（`round` \$1`bracket` \$1 `matchId`）的全局二级索引
+ **查询示例：**“北美东部地区的所有 WINTER2024 比赛”或“北美东部地区 WINTER2024 上半区分组的所有半决赛”
**访问模式 3：**查询某个玩家的比赛历史记录，可以选择按日期范围或锦标赛回合进行筛选
+ **解决方案：**使用单分区键（`player1Id`）和多属性排序键（`matchDate` \$1 `round`）的全局二级索引
+ **查询示例：**“玩家 101 的所有比赛”或“玩家 101 在 2024 年 1 月的比赛”
通过查看项目结构，您可以清楚地看到传统方法与多属性方法之间的主要区别：
**传统的全局二级索引方法（连接键）：**
```
// 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
};
```
**多属性全局二级索引方法（原生键）：**
```
// 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
};
```
使用多属性键，您将具有自然领域属性的项目写入一次。DynamoDB 会自动将它们编入多个 GSI 的索引，而无需合成连接键。
**基表架构：**
+ 分区键：`matchId`（1 个属性）
**全局二级索引架构（具有多属性键的 TournamentRegionIndex）：**
+ 分区键：`tournamentId`、`region`（2 个属性）
+ 排序键：`round`、`bracket`、`matchId`（3 个属性）
**全局二级索引架构（具有多属性键的 PlayerMatchHistoryIndex）：**
+ 分区键：`player1Id`（1 个属性）
+ 排序键：`matchDate`、`round`（2 个属性）
### 基表：TournamentMatches
| matchId（PK） | tournamentId | 区域 | round | bracket | player1Id | player2Id | matchDate | winner | 分数 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 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（多属性键）
| tournamentId（PK） | region（PK） | round（SK） | bracket（SK） | matchId（SK） | player1Id | player2Id | matchDate | winner | 分数 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 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（多属性键）
| player1Id（PK） | matchDate（SK） | round（SK） | tournamentId | 区域 | bracket | matchId | player2Id | winner | 分数 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 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 |
## 先决条件
在开始之前，请确保您满足以下条件：
### 账户和权限
+ 有效 AWS 账户（如有必要，[可在此处创建](https://aws.amazon.com/free/)）
+ DynamoDB 操作的 IAM 权限：
+ `dynamodb:CreateTable`
+ `dynamodb:DeleteTable`
+ `dynamodb:DescribeTable`
+ `dynamodb:PutItem`
+ `dynamodb:Query`
+ `dynamodb:BatchWriteItem`
**注意**
**安全说明：**对于生产用途，请创建仅包含所需权限的自定义 IAM 策略。在本教程中，您可以使用 AWS 托管式策略 `AmazonDynamoDBFullAccessV2`。
### 开发环境
+ 计算机上已安装 Node.js
+ 使用以下方法之一配置的 AWS 凭证：
**选项 1：AWS CLI**
```
aws configure
```
**选项 2：环境变量**
```
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
```
### 安装所需的程序包
```
npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
```
## 实现
### 步骤 1：使用多属性键创建带有 GSI 的表
创建具有简单基本键结构和使用多属性键的 GSI 的表。
#### 代码示例
```
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");
```
**关键设计决策：**
**基表：**基表使用简单的 `matchId` 分区键直接查询比赛，保持基表结构简单，而 GSI 则提供复杂的查询模式。
**TournamentRegionIndex 全局二级索引：**`TournamentRegionIndex` 全局二级索引使用 `tournamentId` \$1 `region` 作为多属性分区键，创建锦标赛-区域隔离，其中数据按两个属性的组合哈希分布，从而实现在特定的锦标赛-区域上下文中的高效查询。多属性排序键（`round` \$1 `bracket` \$1 `matchId`）提供分层排序，该排序支持层次结构中任何级别的查询，并采用从一般（回合）到特定（比赛 ID）的自然排序。
**PlayerMatchHistoryIndex 全局二级索引：**`PlayerMatchHistoryIndex` 全局二级索引使用 `player1Id` 作为分区键来按玩家重新组织数据，从而实现针对特定玩家的跨锦标赛查询。多属性排序键（`matchDate` \$1 `round`）按时间顺序排序，能够按日期范围或特定锦标赛回合进行筛选。
### 步骤 2：插入具有原生属性的数据
使用自然属性添加锦标赛比赛数据。GSI 将自动为这些属性编制索引，无需合成键。
#### 代码示例
```
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");
```
**数据结构解释：**
**自然属性用法：**每个属性都代表一个真实的锦标赛概念，无需字符串连接或解析，可直接映射到领域模型。
**全局二级索引自动编制索引：**GSI 自动使用现有属性（对于 TournamentRegionIndex 为 `tournamentId`、`region`、`round`、`bracket`、`matchId`，对于 PlayerMatchHistoryIndex 为 `player1Id`、`matchDate`、`round`）为项目编制索引，而无需合成连接键。
**无需回填：**向现有表添加带有多属性键的新全局二级索引时，DynamoDB 会使用其自然属性自动为所有现有项目编制索引，无需使用合成键更新项目。
### 第 3 步：使用所有分区键属性查询 TournamentRegionIndex 全局二级索引
此示例查询具有多属性分区键（`tournamentId` \$1 `region`）的 TournamentRegionIndex 全局二级索引。所有分区键属性都必须在查询中使用相等条件来指定，不能单独使用 `tournamentId` 进行查询，也不能对分区键属性使用不相等运算符。
#### 代码示例
```
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`);
});
```
**预期输出。**
```
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
```
**无效的查询：**
```
// Missing region attribute
KeyConditionExpression: 'tournamentId = :tournament'
// Using inequality on partition key attribute
KeyConditionExpression: 'tournamentId = :tournament AND #region > :region'
```
**性能：**多属性分区键一起进行哈希处理，提供与单属性键相同的 O(1) 查找性能。
### 步骤 4：从左到右查询全局二级索引排序键
排序键属性必须按照其在全局二级索引中定义的顺序，从左到右进行查询。此示例演示了在不同的层次结构级别上查询 TournamentRegionIndex：仅按 `round`、按 `round` \$1 `bracket` 或按所有三个排序键属性进行筛选。您不能跳过中间的属性，例如，您不能按照 `round` 和 `matchId` 而跳过 `bracket` 进行查询。
#### 代码示例
```
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`);
}
```
**预期输出。**
```
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
```
**从左到右的查询规则：**您必须按从左到右的顺序查询属性，不能跳过任何属性。
**有效模式：**
+ 仅第一个属性：`round = 'SEMIFINALS'`
+ 前两个属性：`round = 'SEMIFINALS' AND bracket = 'UPPER'`
+ 全部三个属性：`round = 'SEMIFINALS' AND bracket = 'UPPER' AND matchId = 'match-002'`
**无效的模式：**
+ 跳过第一个属性：`bracket = 'UPPER'`（跳过回合）
+ 乱序查询：`matchId = 'match-002' AND round = 'SEMIFINALS'`
+ 留空白：`round = 'SEMIFINALS' AND matchId = 'match-002'`（跳过分组）
**注意**
**设计提示：**按从最一般到最具体的顺序对排序键属性进行排序，以充分提高查询灵活性。
### 步骤 5：在全局二级索引排序键上使用不相等条件
不相等条件必须是查询中的最后一个条件。此示例演示在排序键属性上使用比较运算符（`>=`、`BETWEEN`）和前缀匹配（`begins_with()`）。如果您使用了不相等运算符，就无法在后面添加任何其他排序键条件，不相等必须是键条件表达式中的最后一个条件。
#### 代码示例
```
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`);
}
```
**不相等运算符规则：**您可以使用比较运算符（`>`、`>=`、`<`、`<=`），`BETWEEN` 用于范围查询，`begins_with()` 用于前缀匹配。不相等必须是查询中的最后一个条件。
**有效模式：**
+ 相等条件后跟不相等：`round = 'SEMIFINALS' AND bracket = 'UPPER' AND matchId > 'match-001'`
+ 第一个属性上的不相等：`round BETWEEN 'QUARTERFINALS' AND 'SEMIFINALS'`
+ 前缀匹配作为最后一个条件：`round = 'SEMIFINALS' AND begins_with(bracket, 'U')`
**无效的模式：**
+ 在不相等后添加条件：`round > 'QUARTERFINALS' AND bracket = 'UPPER'`
+ 使用多个不相等：`round > 'QUARTERFINALS' AND bracket > 'L'`
**重要**
`begins_with()` 被视为不相等条件，因此后面不能有其他排序键条件。
### 步骤 6：查询具有多属性排序键的 PlayerMatchHistoryIndex 全局二级索引架构
此示例查询 PlayerMatchHistoryIndex，其中有单个分区键（`player1Id`）和多属性排序键（`matchDate` \$1 `round`）。这样就实现了跨锦标赛的分析，可以查询某个特定玩家的所有比赛，而无需知道锦标赛 ID，而基表则需要对每个锦标赛-区域组合进行单独查询。
#### 代码示例
```
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`);
```
## 模式变化
### 具有多属性键的时间序列数据
针对具有分层时间属性的时间序列查询进行优化
#### 代码示例
```
{
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
```
**优点：**自然时间层次结构（年 → 月 → 日 → 时间戳），允许在任何时间粒度进行高效查询，无需解析或操作日期。全局二级索引使用其自然时间属性，自动为所有读数编制索引。
### 带有多属性键的电子商务订单
按多个维度追踪订单
#### 代码示例
```
{
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
```
### 分层组织数据
组织层次结构建模
#### 代码示例
```
{
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
```
### 稀疏多属性键
组合多属性键以生成稀疏 GSI
#### 代码示例
```
{
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 多租赁
具有客户隔离功能的多租户 SaaS 平台
#### 代码示例
```
// 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'
}
}));
```
**好处：**在租户-客户上下文和自然数据组织中高效地进行查询。
### 金融交易
银行系统使用 GSI 跟踪账户交易
#### 代码示例
```
// 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'
}
}));
```
## 完整示例
以下示例演示了多属性键从设置到清理的过程：
### 代码示例
```
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);
```
**最小代码脚手架**
### 代码示例
```
// 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' }
```
## 其他资源
+ [DynamoDB 最佳实践](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/best-practices.html)
+ [处理表和数据](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithTables.html)
+ [全局二级索引](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.html)：
+ [查询和扫描操作](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html)
# 在 DynamoDB 中管理全局二级索引
本节介绍如何在 Amazon DynamoDB 中创建、修改和删除全局二级索引。
**Topics**
+ [创建具有全局二级索引的表](#GSI.Creating)
+ [描述表的全局二级索引](#GSI.Describing)
+ [向现有表添加全局二级索引](#GSI.OnlineOps.Creating)
+ [删除全局二级索引](#GSI.OnlineOps.Deleting)
+ [在创建期间修改全局二级索引](#GSI.OnlineOps.Creating.Modify)
## 创建具有全局二级索引的表
要创建具有一个或多个全局二级索引的表，请使用 `CreateTable` 和 `GlobalSecondaryIndexes` 参数。为获得最高的查询灵活性，您可以为每个表创建最多 20 个全局二级索引（默认配额）。
您必须指定一个属性以充当索引分区键。您可以选择为索引排序键指定另一个属性。这些关键属性中的任何一个都不必与表中的关键属性相同。例如，在 *GameScores* 表（请参阅 [在 DynamoDB 中使用全局二级索引](GSI.md)），`TopScore` 和 `TopScoreDateTime` 都不是关键属性。您可以创建具有分区键 `TopScore` 以及排序键 `TopScoreDateTime` 的全局二级索引。您可以使用这样的索引来确定高分与玩游戏时间之间是否存在相关性。
每个索引键属性必须是标量类型 `String`、`Number` 或 `Binary`。（它不能是文档或集合。） 您可以将任何数据类型的属性投影到全局二级索引中。其中包括标量、文档和集。有关数据类型的完整列表，请参阅 [数据类型](HowItWorks.NamingRulesDataTypes.md#HowItWorks.DataTypes)。
如果使用预置模式，必须提供索引的 `ProvisionedThroughput` 设置，包括 `ReadCapacityUnits` 和 `WriteCapacityUnits`。这些预置吞吐量设置与表的设置分开，但行为方式相似。有关更多信息，请参阅 [全局二级索引的预调配吞吐量注意事项](GSI.md#GSI.ThroughputConsiderations)。
全局二级索引继承基表的读/写入容量模式。有关更多信息，请参阅 [在 DynamoDB 中切换容量模式时的注意事项](bp-switching-capacity-modes.md)。
**注意**
创建新的 GSI 时，请务必检查您选择的分区键在新索引的分区键值之间生成的数据或流量是否分布不均或缩小。如果发生这种情况，您可能会看到同时发生回填和写入操作并且会限制对基表的写入操作。该服务采取措施最大限度地减少这种情况的可能性，但不会深入了解与索引分区键、所选的预测或索引主键的稀疏程度相关的客户数据的形状。
如果您怀疑新的全局二级索引可能出现分区键值中的数据或流量过窄或偏斜，请先考虑以下方面，然后再向操作重要的表添加新索引。
最安全的方法是在应用程序驱动最少流量时添加索引。
请考虑在基表和索引上启用 CloudWatch Contributor Insights。这将为您提供有用的流量分布洞察。
在整个过程中观察 `WriteThrottleEvents`、`ThrottledRequests` 和 `OnlineIndexPercentageProgress` CloudWatch 指标。根据需要调整预置的写入容量，以便在合理的时间内完成回填，而不会对正在进行的操作产生任何重大的节流影响。在索引回填过程中，`OnlineIndexConsumedWriteCapacity` 和 `OnlineThrottleEvents` 预计显示 0。
如果由于写节流而对操作产生影响，请准备取消索引创建。
## 描述表的全局二级索引
要查看表上所有全局二级索引的状态，请使用 `DescribeTable` 操作。响应的 `GlobalSecondaryIndexes` 部分显示表上的所有索引，以及各自当前状态 (`IndexStatus`)。
全局二级索引的 `IndexStatus` 为：
+ `CREATING`— 索引当前正在创建，但是还不能使用。
+ `ACTIVE`— 索引已准备就绪，应用程序可以对索引执行 `Query` 操作。
+ `UPDATING`— 索引的预置吞吐量设置正在更改。
+ `DELETING`— 索引当前正在删除，不能再使用。
当 DynamoDB 完成构建全局二级索引时，索引状态会从 `CREATING` 变为 `ACTIVE`。
## 向现有表添加全局二级索引
要将全局二级索引添加到现有表，请使用 `UpdateTable` 操作和 `GlobalSecondaryIndexUpdates` 参数。您必须提供以下参数：
+ 索引名称。该名称在表的所有索引中必须唯一。
+ 索引的键架构。您必须为索引分区键指定一个属性；您可以选择为索引排序键指定另一个属性。这些关键属性中的任何一个都不必与表中的关键属性相同。每个架构属性的数据类型必须是标量：`String`、`Number` 或 `Binary`。
+ 从表投影到索引中的属性：
+ `KEYS_ONLY`— 索引中的每个项目仅包含表的分区键、排序键值以及索引键值。
+ `INCLUDE` – 除 `KEYS_ONLY` 中描述的属性外，二级索引还包括您指定的其他非键属性。
+ `ALL`— 索引包括源表中的所有属性。
+ 索引的预置吞吐量，由 `ReadCapacityUnits` 和 `WriteCapacityUnits` 组成。与表的预吞吐量设置是分开的。
您只能为每个 `UpdateTable` 操作创建一个全局二级索引。
### 索引创建的阶段
将新的全局二级索引添加到现有表时，该表在构建索引期间继续可用。但是，新索引不可用于查询操作，直到其状态从 `CREATING` 变为 `ACTIVE`。
**注意**
创建全局二级索引不会使用 Application Auto Scaling。增加 `MIN` Application Auto Scaling 容量不会缩短全局二级索引的创建时间。
DynamoDB 后台分两个阶段构建索引：
**资源分配**
DynamoDB 分配构建索引所需的计算和存储资源。
在资源分配阶段，`IndexStatus` 属性为 `CREATING`，`Backfilling` 属性为 false。使用 `DescribeTable` 操作检索表及其所有二级索引的状态。
当索引处于资源分配阶段时，无法删除索引或删除其父表。您也无法修改索引或表的预置吞吐量。您无法在表上添加或删除其他索引。但是，您可以修改这些其他索引的预置吞吐量。
**回填**
对于表中的每个项目，DynamoDB 根据其投影确定要写入索引的属性集合（`KEYS_ONLY`、`INCLUDE` 或 `ALL`）。然后，它将这些属性写入索引。在回填阶段，DynamoDB 会跟踪表中正在添加、删除或更新的项目。也会根据需要在索引中添加、删除或更新这些项目的属性。
在回填阶段，`IndexStatus` 属性设置为 `CREATING`，`Backfilling` 属性为 true。使用 `DescribeTable` 操作检索表及其所有二级索引的状态。
当索引处于回填状态时，您不能删除其父表。但是，您仍然可以删除索引或修改表及其任何全局二级索引的预置吞吐量。
在回填阶段，一些违规项目的写入可能会成功，而另一些则会被拒绝。回填后，对违反新索引的键架构的项目的所有写入操作都将被拒绝。我们建议您在回填阶段完成后运行 Violation Detector 工具，以检测和解决可能发生的任何关键违规。有关更多信息，请参阅 [在 DynamoDB 中检测和纠正索引键违规](GSI.OnlineOps.ViolationDetection.md)。
当资源分配和回填阶段正在进行中时，索引位于 `CREATING` 状态。在此期间，DynamoDB 会对表执行读取操作。对于从基表中填充全局二级索引的读取操作，您不需要付费。
当索引构建完成后，其状态将更改为 `ACTIVE`。您不能 `Query` 或 `Scan` 索引，直到变为 `ACTIVE`。
**注意**
某些情况下，DynamoDB 会因索引键冲突而无法将表中的数据写入索引。在以下情况下，可能会发生这种情况：
属性值的数据类型与索引键架构数据类型不匹配。
属性的大小超出索引键属性的最大长度。
索引键属性具有空字符串或空二进制属性值。
索引键冲突不会干扰全局二级索引的创建。但是，当索引变为 `ACTIVE` 后，则索引中不存在违规键。
DynamoDB 提供了一个独立的工具来查找和解决这些问题。有关更多信息，请参阅 [在 DynamoDB 中检测和纠正索引键违规](GSI.OnlineOps.ViolationDetection.md)。
### 向大型表添加全局二级索引
构建全局二级索引所需的时间取决于几个因素，例如：
+ 表的大小
+ 表中有资格包含在索引中的项目数
+ 投影到索引中的属性数量
+ 在索引构建期间在主表上写入活动
如果要将全局二级索引添加到非常大的表中，则创建过程可能需要很长时间才能完成。要监控进度并确定索引是否具有足够的写入容量，请参阅以下 Amazon CloudWatch 指标：
+ `OnlineIndexPercentageProgress`
有关 DynamoDB 相关 CloudWatch 指标的更多信息，请参阅 [DynamoDB 指标](metrics-dimensions.md#dynamodb-metrics)。
**重要**
在创建或更新全局二级索引之前，您可能需要将大量表加入允许列表。请联系 AWS Support 以将您的表加入允许列表。
回填索引时，DynamoDB 会使用内部系统容量从表中读取。这是为了最大限度地减少创建索引的影响，并确保您的表不会耗尽读取容量。
## 删除全局二级索引
如果您不再需要全局二级索引，可以使用 `UpdateTable` 操作删除。
您只能为每个 `UpdateTable` 操作删除一个全局二级索引。
删除全局二级索引时，对父表中的任何读取或写入活动都没有影响。删除过程中，您仍然可以修改其他索引上的预置吞吐量。
**注意**
使用 `DeleteTable` 操作删除表时，会同时删除该表的全局二级索引。
将不会针对全局二级索引的删除操作向您的账户收取费用。
## 在创建期间修改全局二级索引
在构建索引时，您可以使用 `DescribeTable` 操作确定它处于哪个阶段。索引的描述包括一个布尔属性 `Backfilling`，指示 DynamoDB 当前是否正在使用表中的项目加载索引。如果 `Backfilling` 为 true，则资源分配阶段已完成，索引现在正在回填。
在回填阶段，您可以删除正在创建的索引。在此阶段中，您无法在表上添加或删除其他索引。
**注意**
对于作为 `CreateTable` 操作的一部分创建的索引，`Backfilling` 属性未显示在 `DescribeTable` 输出。有关更多信息，请参阅 [索引创建的阶段](#GSI.OnlineOps.Creating.Phases)。
# 在 DynamoDB 中检测和纠正索引键违规
在全局二级索引创建的回填阶段，Amazon DynamoDB 会检查表中的每个项目，以确定它是否符合包含在索引中的条件。某些项目可能不符合条件，因为它们会导致索引键冲突。在这些情况下，项目仍保留在表中，但索引没有该项的相应条目。
以下情况下发生*索引键冲突*：
+ 属性值与索引键架构数据类型不匹配。例如，假设 `GameScores` 表的一个项目的类型 `String` 为 `TopScore` 值。如果您添加的全局二级索引的分区键 `TopScore` 类型 `Number`，则表中的项目将违反索引键。
+ 表的属性值超出索引键属性的最大长度。分区键的最大长度为 2048 字节，排序键的最大长度为 1024 字节。如果表中的任何相应属性值超过这些限制，则表中的项目将违反索引键。
**注意**
如果为用作索引键的属性设置了字符串或二进制属性值，则属性值的长度必须大于零；否则，表中的项将与索引键冲突。
此工具目前不会标记此索引键冲突。
如果发生索引键冲突，回填阶段将继续不会中断。但是，索引中不包含任何违规项目。回填阶段完成后，所有违反新索引键架构的项目写入操作都将被拒绝。
要标识和修复表中违反索引键的属性值，请使用 Violation Detector 工具。要运行 Violation Detector，您需要创建一个配置文件，该文件指定要扫描的表的名称、全局二级索引分区键和排序键的名称和数据类型，以及在发现任何索引键冲突时要执行的操作。Violation Detector 可以在以下两种不同模式之一运行：
+ **检测模式**— 检测索引键违规。使用检测模式报告表中会导致全局二级索引中键违规的项目。（您可以选择要求在找到这些违规表项时立即删除它们。） 检测模式的输出将写入文件，您可以使用该文件进行进一步分析。
+ **更正模式**— 更正索引键冲突。在更正模式下，Violation Detector 从检测模式中读取与输出文件格式相同的输入文件。更正模式从输入文件中读取记录，并且对于每条记录，它会删除或更新表中的相应项目。（请注意，如果选择更新项目，则必须编辑输入文件并为这些更新设置适当的值。）
## 下载并运行 Violation Detector
Violation Detector 可作为可执行 Java 归档文件（`.jar` 文件）提供，并在 Windows、macOS 或 Linux 计算机上运行。Violation Detector 需要 Java 1.7（或更高版本）和 Apache Maven。
+ [从 GitHub 下载 Violation Detector](https://github.com/awslabs/dynamodb-online-index-violation-detector)
按照 `README.md` 文件说明下载并使用 Maven 安装 Violation Detector。
要启动 Violation Detector，请转至生成 `ViolationDetector.java` 的目录并输入以下命令。
```
java -jar ViolationDetector.jar [options]
```
Violation Detector 命令行接受以下选项：
+ `-h | --help`— 输出 Violation Detector 的使用摘要和选项。
+ `-p | --configFilePath` `value`— Violation Detector 配置文件的完全限定名称。有关更多信息，请参阅 [Violation Detector 配置文件](#GSI.OnlineOps.ViolationDetection.ConfigFile)。
+ `-t | --detect` `value`— 检测表中的索引键违规，并将其写入 Violation Detector 输出文件。如果此参数的值设置为 `keep`，则不会修改带有键违规的项目。如果值设置为 `delete`，则会从表中删除带有键违规的项目。
+ `-c | --correct` `value`— 从输入文件中读取索引键冲突，并对表中的项目采取纠正措施。如果此参数的值设置为 `update`，则具有键违规的项目将使用新的不违规值进行更新。如果值设置为 `delete`，则会从表中删除带有键违规的项目。
## Violation Detector 配置文件
在运行时，Violation Detector 工具需要配置文件。此文件中的参数确定违规检测器可以访问哪些 DynamoDB 资源，以及它可以占用的预置吞吐量。下表介绍这些参数。
****
| 参数名称 | 说明 | 必填？ |
| --- | --- | --- |
| `awsCredentialsFile` | 包含 AWS 凭证的文件完全限定名称。凭证文件必须为以下格式： accessKey = access_key_id_goes_here
secretKey = secret_key_goes_here
| 是 |
| `dynamoDBRegion` | 表所在的 AWS 区域。例如：`us-west-2`。 | 是 |
| `tableName` | 要扫描的 DynamoDB 表的名称。 | 是 |
| `gsiHashKeyName` | 索引分区键的名称。 | 是 |
| `gsiHashKeyType` | 索引分区键的数据类型 —`String`、`Number` 或 `Binary`： `S \| N \| B` | 是 |
| `gsiRangeKeyName` | 索引排序键的名称。如果索引只有简单主键（分区键），请不要指定此参数。 | 否 |
| `gsiRangeKeyType` | 索引排序键的数据类型 —`String`、`Number` 或 `Binary`： `S \| N \| B` 如果索引只有简单主键（分区键），请不要指定此参数。 | 否 |
| `recordDetails` | 是否将索引键违规的完整详细信息写入输出文件。如果设置为 `true`（默认值），则会报告有关违规项目的完整信息。如果设置为 `false`，则仅报告违规次数。 | 否 |
| `recordGsiValueInViolationRecord` | 是否将违规索引键的值写入输出文件。如果设置为 `true`（默认值），则会报告键值。如果设置为 `false`，则不会报告键值。 | 否 |
| `detectionOutputPath` | Violation Detector 输出文件的完整路径。此参数支持写入本地目录或 Amazon Simple Storage Service (Amazon S3)。示例如下： `detectionOutputPath = ``//local/path/filename.csv` `detectionOutputPath = ``s3://bucket/filename.csv` 输出文件中的信息以逗号分隔值 (CSV) 格式显示。如果您没有设置 `detectionOutputPath`，则输出文件名为 `violation_detection.csv`，并写入到您当前的工作目录中。 | 否 |
| `numOfSegments` | Violation Detector 扫描表时要使用的并行扫描段数。默认值为 1，表示按顺序扫描表。如果值为 2 或更高，则 Violation Detector 将表划分为多个逻辑段和相同数量的扫描线程。`numOfSegments` 最大设置为 4096。对于较大的表，并行扫描通常比顺序扫描快。此外，如果表大到跨越多个分区，则并行扫描会将其读取活动均匀分布到多个分区。有关 DynamoDB 中并行扫描的更多信息，请参阅 [并行扫描](Scan.md#Scan.ParallelScan)。 | 否 |
| `numOfViolations` | 写入到输出文件的索引键违规上限。如果设置为 `-1`（默认值），则扫描整个表。如果设置为正整数，则 Violation Detector 会在遇到该数量的违规后停止。 | 否 |
| `numOfRecords` | 要扫描的表中的项目数。如果设置为 -1（默认值），则扫描整个表。如果设置为正整数，Violation Detector 会在扫描表中的该数量项目后停止。 | 否 |
| `readWriteIOPSPercent` | 调节表扫描期间使用的预置读取容量单位的百分比。有效值范围为 `1` 至 `100`。默认值 (`25`) 表示违规检测器消耗的表预置读取吞吐量不超过 25%。 | 否 |
| `correctionInputPath` | Violation Detector 更正输入文件的完整路径。如果在更正模式下运行 Violation Detector，则此文件的内容将用于修改或删除表中违反全局二级索引的数据项。 `correctionInputPath` 文件的格式与 `detectionOutputPath` 文件相同。这样，您就可以将检测模式的输出作为更正模式下的输入进行处理。 | 否 |
| `correctionOutputPath` | Violation Detector 更正输出文件的完整路径。仅当存在更新错误时创建此文件。 此参数支持写入本地目录或 Amazon S3。示例如下： `correctionOutputPath = ``//local/path/filename.csv` `correctionOutputPath = ``s3://bucket/filename.csv` 输出文件中的信息以 CSV 格式显示。如果您没有设置 `correctionOutputPath`，则输出文件名为 `violation_update_errors.csv`，并写入到您当前的工作目录中。 | 否 |
## 检测
若要检测索引键违规，请将 Violation Detector 与 `--detect` 命令行选项一起使用。要显示此选项的工作原理，请考虑 `ProductCatalog` 表。以下是表中项目的列表。仅显示主键 (`Id`) 和 `Price` 属性。
****
| ID（主键） | Price |
| --- | --- |
| 101 | 5 |
| 102 | 20 |
| 103 | 200 |
| 201 | 100 |
| 202 | 200 |
| 203 | 300 |
| 204 | 400 |
| 205 | 500 |
`Price` 的所有值类型为 `Number`。但是，由于 DynamoDB 无架构，可以添加具有非数字 `Price` 项目。例如，假设您将另一项添加到 `ProductCatalog` 表。
****
| ID（主键） | Price |
| --- | --- |
| 999 | "Hello" |
该表现在共有 9 个项目。
现在，您将新的全局二级索引添加到表中：`PriceIndex`。此索引的主键为分区键 `Price`，类型为 `Number`。构建索引后，它将包含 8 个项目-但 `ProductCatalog` 表中有 9 个项目。这种差异的原因是，`"Hello"` 值是类型 `String`，但 `PriceIndex` 具有 `Number` 类型的主键。`String` 值违反了全局二级索引键，因此不出现在索引中。
若要在这种情况下使用 Violation Detector，请首先创建一个配置文件，如下所示。
```
# 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
```
接下来，您运行 Violation Detector，如以下示例所示。
```
$ 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
```
如果 `recordDetails` 配置参数设置为 `true`，Violation Detector 将每个违规的详细信息写入输出文件，如以下示例所示。
```
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,,
```
输出文件采用 CSV 格式。文件中的第一行是标题，后面是违反索引键的每个项目的一条记录。这些违规记录的字段如下：
+ **Table hash key**（表哈希键）– 表中项目的分区键值。
+ **Table range key**（表范围键）– 表中项目的排序键值。
+ **GSI hash key value**（GSI 哈希键值）– 全局二级索引的分区键值。
+ **GSI hash key violation type**（GSI 哈希键违规类型）– `Type Violation` 或 `Size Violation`。
+ **GGSI hash key violation description**（GSI 哈希键违规描述）– 违规的原因。
+ **GSI hash key update Value(FOR USER)** [GSI 哈希键更新值（针对用户）] – 在更正模式下，用户为属性提供的新值。
+ **GSI range key value**（GSI 范围键值）– 全局二级索引的排序键值。
+ **GSI range key violation type**（GSI 范围键违规类型）– `Type Violation` 或 `Size Violation`。
+ **GSI range key violation description**（GSI 范围键违规描述）– 违规的原因。
+ **GSI range key update Value(FOR USER)** [GSI 范围键更新值（针对用户）] – 在更正模式下，用户为属性提供的新值。
+ **Delete blank attribute when Updating(Y/N)** [在更新时删除空白属性（是/否）] – 在更正模式下，确定是删除 (Y) 还是保留 (N) 表中违规项目，但仅当以下任一字段为空时：
+ `GSI Hash Key Update Value(FOR USER)`
+ `GSI Range Key Update Value(FOR USER)`
如果这些字段中的任何一个不为空，则 `Delete Blank Attribute When Updating(Y/N)` 无效。
**注意**
输出格式可能有所不同，具体取决于配置文件和命令行选项。例如，如果表具有简单主键（没有排序键），则输出中不会出现排序键字段。
文件中的违规记录可能不按排序顺序排列。
## 纠正
要更正索引键冲突，请将 Violation Detector 与 `--correct` 命令行选项一起使用。在更正模式下，Violation Detector 读取 `correctionInputPath` 参数指定的输入文件。此文件具有的格式与 `detectionOutputPath` 文件相同，以便您可以使用检测输出作为更正的输入。
Violation Detector 提供了两种不同的方法来纠正索引键违规：
+ **删除违反**— 删除具有违反属性值的表项。
+ **更新违反**— 更新表项目，将违规属性替换为不违规的值。
无论哪种情况，都可以使用检测模式的输出文件作为更正模式的输入。
继续 `ProductCatalog` 示例，假设您要从表中删除违规项目。为此，请使用以下命令行。
```
$ java -jar ViolationDetector.jar --configFilePath config.txt --correct delete
```
此时，系统将要求您确认是否要删除违规项目。
```
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
```
现在 `ProductCatalog` 和 `PriceIndex` 具有相同数量的项目。
# 处理全局二级索引：Java
您可以使用 适用于 Java 的 AWS SDK 文档 API 创建具有一个或多个全局二级索引的 Amazon DynamoDB 表，描述表中的索引，以及使用索引执行查询。
下面是表操作的常见步骤。
1. 创建 `DynamoDB` 类的实例。
1. 通过创建对应的请求对象，为操作提供必需参数和可选参数。
1. 调用您在前面步骤中创建的客户端提供的适当方法。
**Topics**
+ [创建一个具有全局二级索引的表。](#GSIJavaDocumentAPI.CreateTableWithIndex)
+ [描述一个具有全局二级索引的表](#GSIJavaDocumentAPI.DescribeTableWithIndex)
+ [查询全局二级索引](#GSIJavaDocumentAPI.QueryAnIndex)
+ [示例：使用 适用于 Java 的 AWS SDK 文档 API 创建全局二级索引](GSIJavaDocumentAPI.Example.md)
## 创建一个具有全局二级索引的表。
创建表时可以同时创建全局二级索引。为此，请使用 `CreateTable` 并为一个或多个全局二级索引提供您的规范。以下 Java 代码示例创建一个保存天气数据信息的表。分区键为 `Location`，排序键为 `Date`。全局二级索引 `PrecipIndex` 允许快速访问各个位置的降水数据。
下面是使用 DynamoDB 文档 API 创建具有全局二级索引的表的步骤。
1. 创建 `DynamoDB` 类的实例。
1. 创建 `CreateTableRequest` 类实例，以提供请求信息。
您必须提供表名称、主键以及预配置吞吐量值。对于全局二级索引，您必须提供索引名称、其预置吞吐量设置、索引排序键的属性定义、索引的键架构以及属性投影。
1. 以参数形式提供请求对象，以调用 `createTable` 方法。
以下 Java 代码示例演示了上述步骤。创建具有全局二级索引 (`PrecipIndex`) 的表 (`WeatherData`)。索引分区键为 `Date`，排序键为 `Precipitation`。所有表属性都投影到索引中。用户可以查询此索引以获取特定日期的天气数据，也可以选择按降水量对数据进行排序。
由于 `Precipitation` 不是表的键属性，它不是必需的。然而,`WeatherData` 项目不包含 `Precipitation`，不会显示在 `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());
```
您必须等待 DynamoDB 创建该表并将表的状态设置为 `ACTIVE`。然后，您就可以开始在表中添加数据项目。
## 描述一个具有全局二级索引的表
要获取表上全局二级索引的信息，请使用 `DescribeTable`。对于每个索引，您都可以查看其名称、键架构和投影的属性。
以下是访问表的全局二级索引信息的步骤。
1. 创建 `DynamoDB` 类的实例。
1. 创建 `Table` 类的实例表示要处理的表。
1. 调用 `describe` 对象上的 `Table` 方法。
以下 Java 代码示例演示了上述步骤。
**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());
}
}
```
## 查询全局二级索引
您可以对全局二级索引使用 `Query`，基本上与对表执行 `Query` 操作相同。您需要指定索引名称、索引分区键和排序键（如果有）的查询条件以及要返回的属性。在本示例中，索引是 `PrecipIndex`，其分区键为 `Date`，排序键 `Precipitation`。索引查询返回特定日期降水量大于零的所有天气数据。
以下是使用 适用于 Java 的 AWS SDK 文档 API 查询全局二级索引的步骤。
1. 创建 `DynamoDB` 类的实例。
1. 创建 `Table` 类的实例来代表要处理的索引。
1. 为要查询的索引创建 `Index` 类实例。
1. 调用 `query` 对象上的 `Index` 方法。
属性名称 `Date` 是 DynamoDB 保留字。因此，您必须将表达式属性名称用作 `KeyConditionExpression` 的占位符。
以下 Java 代码示例演示了上述步骤。
**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());
}
```
# 示例：使用 适用于 Java 的 AWS SDK 文档 API 创建全局二级索引
以下 Java 代码示例显示如何处理全局二级索引。本示例创建了一个 `Issues` 表，可以用于软件开发的简单错误跟踪系统。分区键为 `IssueId`，排序键为 `Title`。此表上有 3 个全局二级索引：
+ `CreateDateIndex` — 分区键为 `CreateDate`，排序键为 `IssueId`。除了表键之外，属性 `Description` 和 `Status` 投影到索引中。
+ `TitleIndex` — 分区键为 `Title`，排序键为 `IssueId`。表键以外的其他属性都不投影到索引中。
+ `DueDateIndex` — 分区键为 `DueDate`；没有排序键。所有表属性都投影到索引中。
创建 `Issues` 表后，程序为该表加载表示软件问题报告的数据。然后使用全局二级索引查询这些数据。最后，程序会删除 `Issues` 表。
有关测试以下示例的分步说明，请参阅 [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);
}
}
```
# 处理全局二级索引：.NET
您可以使用 适用于 .NET 的 AWS SDK 低级 API 创建具有一个或多个全局二级索引的 Amazon DynamoDB 表、描述表中的索引，以及使用索引执行查询。这些操作映射到对应的 DynamoDB 操作。有关更多信息，请参阅 [Amazon DynamoDB API 参考](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/)。
以下是使用 .NET 低级 API 执行表操作的常见步骤。
1. 创建 `AmazonDynamoDBClient` 类的实例。
1. 通过创建对应的请求对象，为操作提供必需参数和可选参数。
例如，创建一个 `CreateTableRequest` 对象以创建表；创建一个 `QueryRequest` 数据元以查询表或索引。
1. 执行您在前面步骤中创建的客户端提供的适当方法。
**Topics**
+ [创建一个具有全局二级索引的表。](#GSILowLevelDotNet.CreateTableWithIndex)
+ [描述一个具有全局二级索引的表](#GSILowLevelDotNet.DescribeTableWithIndex)
+ [查询全局二级索引](#GSILowLevelDotNet.QueryAnIndex)
+ [示例：使用 适用于 .NET 的 AWS SDK 低级 API 的全局二级索引](GSILowLevelDotNet.Example.md)
## 创建一个具有全局二级索引的表。
创建表时可以同时创建全局二级索引。为此，请使用 `CreateTable` 并为一个或多个全局二级索引提供您的规范。以下 C\$1 代码示例创建一个保存天气数据信息的表。分区键为 `Location`，排序键为 `Date`。全局二级索引 `PrecipIndex` 允许快速访问各个位置的降水数据。
以下是使用 .NET 低级别 API 创建具有全局二级索引的表的步骤。
1. 创建 `AmazonDynamoDBClient` 类的实例。
1. 创建 `CreateTableRequest` 类实例，以提供请求信息。
您必须提供表名称、主键以及预配置吞吐量值。对于全局二级索引，您必须提供索引名称、其预置的吞吐量设置、索引排序键的属性定义、索引的键架构以及属性投影。
1. 以参数形式提供请求对象，运行 `CreateTable` 方法。
以下 C\$1 代码示例演示了上述步骤。创建具有全局二级索引 (`PrecipIndex`) 的表 (`WeatherData`)。索引分区键为 `Date`，排序键为 `Precipitation`。所有表属性都投影到索引中。用户可以查询此索引以获取特定日期的天气数据，也可以选择按降水量对数据进行排序。
由于 `Precipitation` 不是表的键属性，它不是必需的。然而,`WeatherData` 项目不包含 `Precipitation`，不会显示在 `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);
```
您必须等待 DynamoDB 创建该表并将表的状态设置为 `ACTIVE`。然后，您就可以开始在表中添加数据项目。
## 描述一个具有全局二级索引的表
要获取表上全局二级索引的信息，请使用 `DescribeTable`。对于每个索引，您都可以查看其名称、键架构和投影的属性。
以下介绍使用 .NET 低级 API 访问表中全局二级索引信息的步骤。
1. 创建 `AmazonDynamoDBClient` 类的实例。
1. 以参数形式提供请求对象，运行 `describeTable` 方法。
创建 `DescribeTableRequest` 类实例，以提供请求信息。您必须提供表名称。
以下 C\$1 代码示例演示了上述步骤。
**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);
}
}
```
## 查询全局二级索引
您可以对全局二级索引使用 `Query`，基本上与对表执行 `Query` 操作相同。您需要指定索引名称、索引分区键和排序键（如果有）的查询条件以及要返回的属性。在本示例中，索引是 `PrecipIndex`，其分区键为 `Date`，排序键 `Precipitation`。索引查询返回特定日期降水量大于零的所有天气数据。
以下是使用 .NET 低级别 API 查询全局二级索引的步骤。
1. 创建 `AmazonDynamoDBClient` 类的实例。
1. 创建 `QueryRequest` 类实例，以提供请求信息。
1. 以参数形式提供请求对象，运行 `query` 方法。
属性名称 `Date` 是 DynamoDB 保留关键字。因此，您必须将表达式属性名称用作 `KeyConditionExpression` 的占位符。
以下 C\$1 代码示例演示了上述步骤。
**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();
}
```
# 示例：使用 适用于 .NET 的 AWS SDK 低级 API 的全局二级索引
以下 C\$1 代码示例显示如何处理全局二级索引。本示例创建了一个 `Issues` 表，可以用于软件开发的简单错误跟踪系统。分区键为 `IssueId`，排序键为 `Title`。此表上有 3 个全局二级索引：
+ `CreateDateIndex` — 分区键为 `CreateDate`，排序键为 `IssueId`。除了表键之外，属性 `Description` 和 `Status` 投影到索引中。
+ `TitleIndex` — 分区键为 `Title`，排序键为 `IssueId`。表键以外的其他属性都不投影到索引中。
+ `DueDateIndex` — 分区键为 `DueDate`；没有排序键。所有表属性都投影到索引中。
创建 `Issues` 表后，程序为该表加载表示软件问题报告的数据。然后使用全局二级索引查询这些数据。最后，程序会删除 `Issues` 表。
有关测试以下示例的分步说明，请参阅 [.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;
}
}
}
}
}
```
# 借助 AWS CLI 在 DynamoDB 中使用全局二级索引
您可以使用 AWS CLI 创建具有一个或多个全局二级索引的 Amazon DynamoDB 表、描述表中的索引，以及使用索引执行查询。
**Topics**
+ [创建一个具有全局二级索引的表。](#GCICli.CreateTableWithIndex)
+ [向现有表添加全局二级索引](#GCICli.CreateIndexAfterTable)
+ [描述一个具有全局二级索引的表](#GCICli.DescribeTableWithIndex)
+ [查询全局二级索引](#GCICli.QueryAnIndex)
## 创建一个具有全局二级索引的表。
全局二级索引可以在您创建表的同时创建。为此，请使用 `create-table` 参数并为一个或多个全局二级索引提供您的规范。下面的示例创建了一个 `GameScores` 表，全局二级索引 `GameTitleIndex`。基表的分区键为 `UserId`，排序键 `GameTitle`，可以有效地找到特定游戏的单个用户的最佳分数，而 GSI 则具有分区键 `GameTitle` 和排序键 `TopScore`，允许您快速找到特定游戏的总体最高分。
```
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
}
}
]"
```
您必须等待 DynamoDB 创建该表并将表的状态设置为 `ACTIVE`。然后，您就可以开始在表中添加数据项目。您可以使用 [describe-table](https://docs.aws.amazon.com/cli/latest/reference/dynamodb/describe-table.html) 确定表创建的状态。
## 向现有表添加全局二级索引
创建表后也可以添加或修改全局二级索引。为此，请使用 `update-table` 参数并为一个或多个全局二级索引提供您的规范。以下示例使用与前面示例相同的架构，但假定表已经创建，我们稍后将添加 GSI。
```
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\"]
}
}
}
]"
```
## 描述一个具有全局二级索引的表
要获取有关表的全局二级索引的信息，请使用 `describe-table` 参数。对于每个索引，您都可以查看其名称、键架构和投影的属性。
```
aws dynamodb describe-table --table-name GameScores
```
## 查询全局二级索引
您可以对全局二级索引使用 `query` 操作，基本上与对表执行 `query` 操作相同。您需要指定索引名称、索引排序键的查询条件以及要返回的属性。在本示例中，索引为 `GameTitleIndex`，索引排序键为 `GameTitle`。
要返回的只包含投影到索引的属性。您也可以修改此查询，让返回结果中也包含非键属性，但是这样会导致表抓取活动的成本相对较高的。有关表获取的更多信息，请参阅 [属性投影](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"} }'
```
# 本地二级索引
某些应用程序只需要使用基表的主键查询数据。但是，在某些情况下，替代排序键可能会有所帮助。要为您的应用程序选择排序键，您可以在 Amazon DynamoDB 表上创建一个或多个本地二级索引，然后对这些索引发出 `Query` 或 `Scan` 请求。
**Topics**
+ [场景：使用本地二级索引](#LSI.Scenario)
+ [属性投影](#LSI.Projections)
+ [创建本地二级索引](#LSI.Creating)
+ [从本地二级索引读取数据](#LSI.Reading)
+ [项目写入和本地二级索引](#LSI.Writes)
+ [全局二级索引的预调配吞吐量注意事项](#LSI.ThroughputConsiderations)
+ [本地二级索引的存储注意事项](#LSI.StorageConsiderations)
+ [本地二级索引中的项目集合](#LSI.ItemCollections)
+ [处理本地二级索引：Java](LSIJavaDocumentAPI.md)
+ [处理本地二级索引：.NET](LSILowLevelDotNet.md)
+ [在 DynamoDB AWS CLI 中使用本地二级索引](LCICli.md)
## 场景：使用本地二级索引
例如，请考虑 `Thread` 表。此表对于 [AWS 论坛](https://forums.aws.amazon.com/)等应用程序有用。下表显示了此表中项目的组织方式，（并未显示所有属性。）
![\[包含论坛名称、主题、上次发布时间和回复次数列表的 Thread 表。\]](http://docs.aws.amazon.com/zh_cn/amazondynamodb/latest/developerguide/images/LSI_01.png)
DynamoDB 连续存储具有相同分区键值的所有项目。在本例中，给定特定 `ForumName`，`Query` 操作可以立即找到该论坛的所有话题。在具有相同分区键值的项目组中，按排序键值对项目进行排序。如果排序键 (`Subject`)，DynamoDB 可以缩小返回的结果范围-例如，返回“S3”论坛中 `Subject` 以字母“a”开始的所有话题。
某些请求可能需要更复杂的数据访问模式。例如：
+ 哪些论坛主题获得的查看和回复最多？
+ 特定论坛中的哪个主题具有最多的消息？
+ 在特定时间段内，特定论坛上发布了多少主题？
要回答这些问题，`Query` 操作是不够的。相反，您将不得不`Scan`整个表。对于包含数百万个项目的表，这将占用大量预置读取吞吐量，并需要很长时间才能完成。
但是，您可以在非键属性上指定一个或多个本地二级索引，例如 `Replies` 或 `LastPostDateTime`。
*本地二级索引*为给定分区键值维护替代排序键。本地二级索引还包含其基表中部分或全部属性的副本。您可以指定在创建表时将哪些属性投影到本地二级索引中。本地二级索引数据按照基表相同分区键组织，但排序键不同。这样，您就可以跨不同维度高效地访问数据项。为获得更高的查询或扫描灵活性，您可以为每个表创建最多 5 个本地二级索引。
假设应用程序需要查找过去三个月内在某个论坛中发布的所有话题。如果没有本地二级索引，应用程序将不得不 `Scan` 整个 `Thread` 表并放弃任何未在指定时间范围内的帖子。使用本地二级索引，`Query` 操作可以使用 `LastPostDateTime` 作为排序键，快速查找数据。
下图显示了名为 `LastPostIndex` 的本地二级索引。请注意，分区键与 `Thread` 表相同，但排序键是 `LastPostDateTime`。
![\[LastPostIndex 表包含论坛名称、主题和上次发布时间的列表。\]](http://docs.aws.amazon.com/zh_cn/amazondynamodb/latest/developerguide/images/LSI_02.png)
每个本地二级索引必须符合以下条件：
+ 分区键与其基表的分区键相同。
+ 排序键仅由一个标量属性组成。
+ 基表的排序键将投影到索引中，其中它充当非键属性。
在本示例中，分区键是 `ForumName`，本地二级索引的排序键为 `LastPostDateTime`。此外，基表中的排序键值（在本示例中，`Subject`）投影到索引中，但它不是索引键的一部分。如果应用程序需要基于 `ForumName` 和 `LastPostDateTime` 的列表，它可以对 `LastPostIndex` 发出 `Query` 请求。查询结果按照 `LastPostDateTime` 排序，并且可以按升序或降序排序返回。查询还可以应用关键条件，例如，仅返回在特定的时间范围内具有 `LastPostDateTime` 的项目。
每个本地二级索引自动包含其基表中的分区和排序键；您可以选择将非键属性投影到索引中。当您查询索引时，DynamoDB 便可高效地检索这些已投影的属性。查询本地二级索引时，查询还可以检索*未*投影到索引的属性。DynamoDB 会自动从基表中提取这些属性，但延迟更大，预置吞吐量成本也更高。
对于任何本地二级索引，每个不同分区键值最多可以存储 10 GB 的数据。此数字包括基表中的所有项目，以及索引中具有相同分区键值的所有项目。有关更多信息，请参阅 [本地二级索引中的项目集合](#LSI.ItemCollections)。
## 属性投影
对于 `LastPostIndex`，应用程序可以使用 `ForumName` 和 `LastPostDateTime` 作为查询条件。但是，要检索任何其他属性，DynamoDB 必须对 `Thread` 表执行额外读取操作。这些额外读取称为*获取*，可以增加查询所需的预置吞吐量总量。
假设您希望使用“S3”中所有话题的列表以及每个话题的回复数量填充一个网页，并按最近回复开始的最后一个回复日期/时间排序。要填充此列表，您需要以下属性：
+ `Subject`
+ `Replies`
+ `LastPostDateTime`
查询这些数据并避免获取操作的最有效方法是将 `Replies` 属性从表投影到本地二级索引，如此图所示。
![\[LastPostIndex 表，其中包含论坛名称、上次发布时间、主题和回复的列表。\]](http://docs.aws.amazon.com/zh_cn/amazondynamodb/latest/developerguide/images/LSI_03.png)
*投影*是从表复制到二级索引的属性集。表的分区键和排序键始终投影到索引中；您可以投影其他属性以支持应用程序的查询要求。当您查询索引时，Amazon DynamoDB 可以访问投影中的任何属性，就像这些属性位于自己的表中一样。
创建二级索引时，需要指定将投影到索引中的属性。DynamoDB 为此提供了三种不同的选项：
+ *KEYS\$1ONLY* – 索引中的每个项目仅包含表的分区键、排序键值以及索引键值。`KEYS_ONLY` 选项会导致最小二级索引。
+ *INCLUDE* – 除 `KEYS_ONLY` 中描述的属性外，二级索引还包括您指定的其他非键属性。
+ *ALL* – 二级索引包括源表中的所有属性。由于所有表数据都在索引中复制，因此 `ALL` 投影会产生最大二级索引。
在上图中，非键属性 `Replies` 投影到 `LastPostIndex`。应用程序可以查询 `LastPostIndex` 而不是整个 `Thread` 表，用 `Subject`、`Replies` 和 `LastPostDateTime` 填充网页。如果请求任何其他非键属性，DynamoDB 将需要从 `Thread` 表获取这些属性。
从应用程序的角度来看，从基表中获取其他属性是自动且透明的，因此无需重写任何应用程序逻辑。但是，这种读取可以大大降低使用本地二级索引的性能优势。
选择要投影到本地二级索引中的属性时，必须在预置吞吐量成本和存储成本之间做出权衡：
+ 如果只需要访问少量属性，同时尽可能降低延迟，就应考虑仅将键属性投影到本地二级索引。索引越小，存储索引所需的成本越少，并且写入成本也会越少。如果您偶尔需要获取属性，则预置吞吐量的成本可能会超过存储这些属性的较长期成本。
+ 如果您的应用程序频繁访问某些非键属性，就应考虑将这些属性投影到本地二级索引。本地二级索引的额外存储成本会抵消频繁执行表扫描的成本。
+ 如果需要频繁访问大多数非键属性，则可以将这些属性（甚至整个基表）投影到本地二级索引中。这为您提供了最大的灵活性和最低的预置吞吐量消耗，因为不需要提取。但是，如果投影所有属性，您的存储成本将增加，甚至翻倍。
+ 如果您的应用程序并不会频繁查询表，但必须要对表中的数据执行大量写入或更新操作，就应考虑投影 *KEYS\$1ONLY*。这是最小的本地二级索引，但仍可用于查询活动。
## 创建本地二级索引
要在表上创建一个或多个本地二级索引，请使用 `CreateTable` 操作的 `LocalSecondaryIndexes` 参数。表上的本地二级索引是在创建表时创建的。删除表时，会同时删除该表的任何本地二级索引。
必须指定一个非键属性以充当本地二级索引的排序键。您选择的属性必须是标量 `String`、`Number` 或 `Binary`。不允许使用其他标量类型、文档类型和集合类型。有关数据类型的完整列表，请参阅 [数据类型](HowItWorks.NamingRulesDataTypes.md#HowItWorks.DataTypes)。
**重要**
对于具有本地二级索引的表，每个分区键值有 10 GB 的大小限制。具有本地二级索引的表可以存储任意数量的项目，只要任何一个分区键值的总大小不超过 10 GB。有关更多信息，请参阅 [项目集合大小限制](#LSI.ItemCollections.SizeLimit)。
您可以将任何数据类型的属性投影到本地二级索引中。这包括标量、文档和集。有关数据类型的完整列表，请参阅 [数据类型](HowItWorks.NamingRulesDataTypes.md#HowItWorks.DataTypes)。
## 从本地二级索引读取数据
您可以使用 `Query` 和 `Scan` 操作从本地二级索引检索项目。`GetItem` 和 `BatchGetItem` 操作不能在本地二级索引上使用。
### 查询本地二级索引
在 DynamoDB 表中，每个项目的组合分区键值和排序键值必须唯一。但是，在本地二级索引中，排序键值不需要对于给定分区键值唯一。如果本地二级索引中有多个具有相同排序键值的项目，则 `Query` 操作返回具有相同分区键值的所有项目。在响应中，匹配的项目不会以任何特定顺序返回。
您可以使用最终一致性读取或强一致性读取来查询本地二级索引。要指定所需的一致性类型，请使用 `Query` 操作的 `ConsistentRead` 参数。从本地二级索引进行的强一致性读取始终返回上次更新的值。如果查询需要从基表中获取其他属性，则这些属性将与索引保持一致。
**Example**
考虑以下数据从 `Query` 返回，请求来自特定论坛中的讨论主题的数据。
```
{
"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"}
}
}
```
在此查询中：
+ DynamoDB 访问 `LastPostIndex`，使用 `ForumName` 分区键查找“EC2”的索引项目。具有此键的所有索引项目都彼此相邻存储，以实现快速检索。
+ 在此论坛中，DynamoDB 使用索引来查找匹配指定 `LastPostDateTime` 条件的键。
+ 由于 `Replies` 属性投影到索引中，DynamoDB 可以检索此属性，而不会占用任何额外的预置吞吐量。
+ `Tags` 属性不会投影到索引中，因此 DynamoDB 必须访问 `Thread` 表并获取此属性。
+ 返回结果，按 `LastPostDateTime` 排序。索引条目按分区键值排序，然后按排序键值排序，`Query` 按照存储顺序返回它们。（可以使用 `ScanIndexForward` 参数按降序返回结果。）
由于 `Tags` 属性不会投影到本地二级索引中，DynamoDB 必须占用额外的读取容量单位才能从基表中获取此属性。如果需要经常运行此查询，应将 `Tags` 投影到 `LastPostIndex` 以避免从基表提取。但是，如果仅偶尔需要访问 `Tags`，将 `Tags` 投影到索引的额外存储成本可能不值得。
### 扫描本地二级索引
您可以使用 `Scan` 从本地二级索引检索全部数据。您必须在请求中提供基表名称和索引名称。通过 `Scan`，DynamoDB 可读取索引中的全部数据并将其返回到应用程序。您还可以请求仅返回部分数据并放弃其余数据。为此，请使用 `Scan` API 的 `FilterExpression` 参数。有关更多信息，请参阅 [扫描的筛选表达式](Scan.md#Scan.FilterExpression)。
## 项目写入和本地二级索引
DynamoDB 会自动保持所有本地二级索引与各自的基表同步。应用程序绝不会直接向索引中写入内容。但是，您有必要了解 DynamoDB 如何维护这些索引。
创建本地二级索引时，指定一个属性以作为索引的排序键。您还可以为该属性指定数据类型。这就意味着，无论您何时向基表中写入项目，如果项目定义索引键值，其类型必须匹配索引键架构的数据类型。在 `LastPostIndex` 的情况下，索引中的 `LastPostDateTime` 排序键定义为 `String` 数据类型。如果您尝试向 `Thread` 表添加项目并为 `LastPostDateTime`（如 `Number`）指定其他数据类型，DynamoDB 会因数据类型不匹配而返回 `ValidationException`。
基表中的项目与本地二级索引中的项目之间不需要一对一的关系。事实上，这种行为对于许多应用程序都是有利的。
相较于索引数量较少的表，拥有较多本地二级索引的表会产生较高的写入活动成本。有关更多信息，请参阅 [全局二级索引的预调配吞吐量注意事项](#LSI.ThroughputConsiderations)。
**重要**
对于具有本地二级索引的表，每个分区键值有 10 GB 的大小限制。具有本地二级索引的表可以存储任意数量的项目，只要任何一个分区键值的总大小不超过 10 GB。有关更多信息，请参阅 [项目集合大小限制](#LSI.ItemCollections.SizeLimit)。
## 全局二级索引的预调配吞吐量注意事项
在 DynamoDB 中创建表时，为表的预期工作负载预置读取和写入容量单位。该工作负载包括对表的本地二级索引的读取和写入活动。
要查看预置吞吐量容量的当前值，请参阅 [Amazon DynamoDB 定价](https://aws.amazon.com/dynamodb/pricing)。
### 读取容量单位
查询本地二级索引时，占用的读取容量单位数取决于访问数据的方式。
与表查询一样，索引查询可以使用最终一致性读取或强一致性读取，具体取决于 `ConsistentRead` 值。一个强一致性读取占用一个读取容量单位；最终一致性读取只占用一半的读取容量。因此，选择最终一致性读取，可以减少读取容量单位费用。
对于仅请求索引键和投影属性的索引查询，DynamoDB 计算预配置读取活动的方式与对表查询使用的方式相同。唯一不同的是，本次计算基于索引条目的大小，而不是基表中项目的大小。读取容量单位的数量就是返回的所有项目的所有投影属性大小之和；然后结果向上取整至 4 KB 边界。有关 DynamoDB 如何计算预置吞吐量使用情况的更多信息，请参阅 [DynamoDB 预置容量模式](provisioned-capacity-mode.md)。
对于读取未投影到本地二级索引的属性的索引查询，DynamoDB 除了从索引读取投影属性之外，还需要从基表中获取这些属性。如果在 `Query` 操作的 `Select` 或 `ProjectionExpression` 参数中加入任何非投影属性，将发生获取。读取会导致查询响应中的额外延迟，并且还会产生更高的预配置吞吐量成本：除了上述从本地二级索引进行读取之外，您还需要为获取的每个基表项目支付读取容量单位费用。此费用用于从表读取每个完整项目，而不仅仅是请求的属性。
`Query` 操作返回的结果大小上限为 1 MB。这包括所有属性名称的大小和所返回的所有项目的值。但是，如果针对本地二级索引的查询导致 DynamoDB 从基表中获取项目属性，则结果中数据的最大大小可能会较低。在此情况下，结果大小为以下总和：
+ 索引中匹配项目的大小，四舍五入到下一个 4 KB。
+ 基表中每个匹配项目的大小，每个项目分别向上舍入到下一个 4 KB。
使用此公式，查询操作返回的结果大小上限仍为 1 MB。
例如，请考虑使用每个项目为 300 字节的表。该表有一个本地二级索引，但只有 200 个字节的每个项目投影到索引中。现在假设 `Query` 此索引，查询需要为每个项目提取表，并且查询返回 4 个项目。DynamoDB 总结了以下几点：
+ 索引中匹配项目的大小：200 字节 × 4 个项目 = 800 字节；然后四舍五入为 4 KB。
+ 基表中每个匹配项目的大小：（300 字节，四舍五入为 4 KB）×4 个项目 = 16 KB。
因此，结果中数据的总大小为 20 KB。
### 写入容量单位
添加、更新或删除表中的项目时，更新本地二级索引将占用表的预置写入容量单位。一次写入操作的预置吞吐量总成本是对表执行的写入操作以及更新本地二级索引所占用的写入容量单位之和。
向本地二级索引写入项目的成本取决于多个因素：
+ 如果您向定义了索引属性的表中写入新项目，或更新现有的项目来定义之前未定义的索引属性，只需一个写入操作即可将项目放置到索引中。
+ 如果对表执行的更新操作更改了索引键属性的值（从 A 更改为 B），就需要执行两次写入操作，一次用于删除索引中之前的项目，另一次用于将新项目放置到索引中。
+ 如果索引中已有某一项目，而对表执行的写入操作删除了索引属性，就需要执行一次写入操作删除索引中旧的项目投影。
+ 如果更新项目前后索引中没有此项目，此索引就不会额外产生写入成本。
所有这些因素都假定索引中每个项目的大小小于或等于 1 KB 这一项目大小（用于计算写入容量单位）。如果索引条目大于这一大小，就会占用额外的写入容量单位。您可以考虑查询需要返回的属性类型并仅将这些属性投影到索引中，从而最大程度地减少写入成本。
## 本地二级索引的存储注意事项
当应用程序向表中写入项目时，DynamoDB 会自动将适当的属性子集复制到应包含这些属性的所有本地二级索引。您的 AWS 账户需要支付在基表中存储项目以及在表的任何本地二级索引中存储属性的费用。
索引项目所占用的空间大小就是以下内容之和：
+ 基表的主键 (分区键和排序键) 的大小 (按字节计算)
+ 索引键属性的大小（按字节计算）
+ 投影的属性（如果有）的大小（按字节计算）
+ 每个索引项目 100 字节的开销
要估算本地二级索引的存储要求，您可以估算索引中项目的平均大小，然后乘以索引中的项目数。
如果表包含的某个项目未定义特定属性，但是该属性定义为索引排序键，则 DynamoDB 不会将该项目的任何数据写入到索引中。
## 本地二级索引中的项目集合
**注意**
本节仅涉及具有本地二级索引的表。
在 DynamoDB 中，*项目集合*是指表中具有相同分区键值的项目及其所有本地二级索引的任何组。在本节中使用的示例中，`Thread` 表的分区键为 `ForumName`，`LastPostIndex` 的分区键也是 `ForumName`。所有具有相同 `ForumName` 的表和索引项目是同一个项目集合的一部分。例如，在 `Thread` 表和 `LastPostIndex` 本地二级索引，有一个论坛的项目集合 `EC2` 和论坛的不同项目集合 `RDS`。
下图显示了论坛 `S3` 的项目集合。
![\[DynamoDB 项目集合，其中包含具有相同 S3 分区键值的表项目和本地二级索引项目。\]](http://docs.aws.amazon.com/zh_cn/amazondynamodb/latest/developerguide/images/LSI_04.png)
在此图中，项目集合包含 `Thread` 和 `LastPostIndex` 中，`ForumName` 分区键值为“S3”的所有项目。如果表上有其他本地二级索引，那么这些索引中 `ForumName` 等于“S3”的任何项目也将成为项目集合的一部分。
您可以在 DynamoDB 中使用以下任何操作来返回有关项目集合的信息：
+ `BatchWriteItem`
+ `DeleteItem`
+ `PutItem`
+ `UpdateItem`
+ `TransactWriteItems`
这些操作中的每个操作都支持 `ReturnItemCollectionMetrics` 参数。将此参数设置为 `SIZE`，可以查看有关索引中每个项目集合大小的信息。
**Example**
下面是 `Thread` 表的 `UpdateItem` 操作输出示例，`ReturnItemCollectionMetrics` 设置为 `SIZE`。更新的项目的 `ForumName` 值为“EC2”，因此输出包含有关该项目集合的信息。
```
{
ItemCollectionMetrics: {
ItemCollectionKey: {
ForumName: "EC2"
},
SizeEstimateRangeGB: [0.0, 1.0]
}
}
```
`SizeEstimateRangeGB` 对象显示此项目集合的大小介于 0 到 1 GB 之间。DynamoDB 会定期更新此大小估计值，因此下次修改项目时，数字可能会有所不同。
### 项目集合大小限制
对于具有一个或多个本地二级索引的表，任何项目集合的最大大小均为 10GB。这不适用于没有本地二级索引的表中的项目集合，也不适用于全局二级索引中的项目集合。只有具有一个或多个本地二级索引的表受影响。
如果项目集合超过 10 GB 限制，则 DynamoDB 可能返回 `ItemCollectionSizeLimitExceededException`，并且您可能无法向项目集合添加更多项目或增加项目集合中项目的大小。（仍然允许对项目集合的大小进行读取和写入操作。） 您仍然可以将项目添加到其他项目集合。
要减小项目集合的大小，您可以执行以下操作之一：
+ 删除具有相关分区键值的所有不必要项目。从基表中删除这些项目时，DynamoDB 还会删除具有相同分区键值的所有索引条目。
+ 通过删除属性或减小属性的大小来更新项目。如果将这些属性投影到任何本地二级索引中，DynamoDB 还会减小相应索引条目的大小。
+ 使用相同的分区键和排序键创建新表，然后将项目从旧表移动到新表。如果表具有不经常访问的历史数据，这可能是一种很好的方法。您还可能考虑将此历史数据存档到 Amazon Simple Storage Service (Amazon S3)。
当项目集合的总大小低于 10 GB 时，您可以再次添加具有相同分区键值的项目。
作为最佳实践，我们建议设置应用程序监控项目集合的大小。一种方法使用 `BatchWriteItem`、`DeleteItem`、`PutItem` 或 `UpdateItem` 时将 `SIZE` 参数设置为 `ReturnItemCollectionMetrics`。您的应用程序应检查输出的 `ReturnItemCollectionMetrics` 对象，在项目集合超过用户定义的限制（例如 8 GB）时记录错误消息。设置一个小于 10 GB 的限制将提供一个预警系统，以便您知道项目集合即将接近限制，以便对其执行某些操作。
### 项目集合和分区
在带一个或多个本地二级索引的表中，每个项目集合存储在一个分区中。此类项目集合的总大小限制为该分区的容量：10GB。对于应用程序而言，如果其数据模型包含大小不受限制的项目集合，或者您可能合理地预期某些项目集合将来会增长到 10GB 以上，那么您应该考虑改用全局二级索引。
应设计应用程序，在不同分区键值之间均匀分布表数据。对于具有本地二级索引的表，应用程序不应在单个分区上的单个项目集合中创建读取和写入活动的“热点”。
# 处理本地二级索引：Java
您可以使用 适用于 Java 的 AWS SDK 文档 API 创建具有一个或多个本地二级索引的 Amazon DynamoDB 表、描述表中的索引，以及使用索引执行查询。
下面是使用 适用于 Java 的 AWS SDK 文档 API 执行表操作的常见步骤。
1. 创建 `DynamoDB` 类的实例。
1. 通过创建对应的请求对象，为操作提供必需参数和可选参数。
1. 调用您在前面步骤中创建的客户端提供的适当方法。
**Topics**
+ [创建具有本地二级索引的表](#LSIJavaDocumentAPI.CreateTableWithIndex)
+ [描述具有本地二级索引的表](#LSIJavaDocumentAPI.DescribeTableWithIndex)
+ [查询本地二级索引](#LSIJavaDocumentAPI.QueryAnIndex)
+ [示例：使用 Java 文档 API 的本地二级索引](LSIJavaDocumentAPI.Example.md)
## 创建具有本地二级索引的表
本地二级索引必须在您创建表的同时创建。为此，请使用 `createTable` 方法并为一个或多个本地二级索引提供您的规范。以下 Java 代码示例创建一个包含音乐精选中歌曲信息的表。分区键为 `Artist`，排序键为 `SongTitle`。`AlbumTitleIndex` 这一二级索引可以按专辑名称进行查询。
下面是使用 DynamoDB 文档 API 创建具有本地二级索引的表的步骤。
1. 创建 `DynamoDB` 类的实例。
1. 创建 `CreateTableRequest` 类实例，以提供请求信息。
您必须提供表名称、主键以及预配置吞吐量值。对于本地二级索引，您必须提供索引名称、索引排序键的名称和数据类型、索引的键架构以及属性投影。
1. 以参数形式提供请求对象，以调用 `createTable` 方法。
以下 Java 代码示例演示了上述步骤。该代码创建表 (`Music`)，在 `AlbumTitle` 属性上具有二级索引。投影到索引的属性只有表的分区键、排序键以及索引排序键。
```
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());
```
您必须等待 DynamoDB 创建该表并将表的状态设置为 `ACTIVE`。然后，您就可以开始在表中添加数据项目。
## 描述具有本地二级索引的表
要获取表上有关本地二级索引的信息，请使用 `describeTable` 方法。对于每个索引，您都可以查看其名称、键架构和投影的属性。
以下是使用 适用于 Java 的 AWS SDK 文档 API 访问表的本地二级索引信息的步骤。
1. 创建 `DynamoDB` 类的实例。
1. 创建 `Table` 类的实例。您必须提供表名称。
1. 调用 `describeTable` 对象上的 `Table` 方法。
以下 Java 代码示例演示了上述步骤。
**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());
}
}
```
## 查询本地二级索引
您可以对本地二级索引使用 `Query` 操作，基本与对表执行 `Query` 操作一样。您需要指定索引名称、索引排序键的查询条件以及要返回的属性。在本示例中，索引为 `AlbumTitleIndex`，索引排序键为 `AlbumTitle`。
要返回的只包含投影到索引的属性。您也可以修改此查询，让返回结果中也包含非键属性，但是这样会导致表抓取活动的成本相对较高的。有关表获取的更多信息，请参阅 [属性投影](LSI.md#LSI.Projections)。
以下是使用 适用于 Java 的 AWS SDK 文档 API 查询本地二级索引的步骤。
1. 创建 `DynamoDB` 类的实例。
1. 创建 `Table` 类的实例。您必须提供表名称。
1. 创建 `Index` 类的实例。您必须提供索引名称。
1. 调用 `query` 类的 `Index` 方法。
以下 Java 代码示例演示了上述步骤。
**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());
}
```
### 对本地二级索引的一致性读取
与仅支持最终一致性读取的全局二级索引不同，本地二级索引支持最终一致性读取和强一致性读取。从本地二级索引进行的强一致性读取始终返回上次更新的值。如果查询需要从基表中提取其他属性，则这些提取的属性同样与索引保持一致。
默认情况下，`Query` 使用最终一致性读取。要请求强一致性读取，请在 `QuerySpec` 中将 `ConsistentRead` 设置为 `true`。以下示例使用强一致性读取查询 `AlbumTitleIndex`：
**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);
```
**注意**
对于返回的每 4 KB 数据（向上取整），一个强一致性读取消耗一个读取容量单位，而最终一致性读取仅消耗一半的读取容量单位。例如，返回 9 KB 数据的强一致性读取消耗 3 个读取容量单位（9 KB/4 KB = 2.25，向上取整为 3），而使用最终一致性读取的相同查询消耗 1.5 个读取容量单位。如果您的应用程序能够容忍读取可能稍微陈旧的数据，请使用最终一致性读取来减少读取容量使用量。有关更多信息，请参阅 [读取容量单位](LSI.md#LSI.ThroughputConsiderations.Reads)。
# 示例：使用 Java 文档 API 的本地二级索引
以下 Java 代码示例显示如何在Amazon DynamoDB 中处理本地二级索引。示例创建名为 `CustomerOrders` 的表，其分区键为 `CustomerId`，排序键为 `OrderId`。此表上有两个本地二级索引：
+ `OrderCreationDateIndex` — 排序键是 `OrderCreationDate`，并将以下属性投影到索引：
+ `ProductCategory`
+ `ProductName`
+ `OrderStatus`
+ `ShipmentTrackingId`
+ `IsOpenIndex` — 排序键是 `IsOpen`，并将表的所有属性投影到索引。
创建 `CustomerOrders` 表后，程序为该表加载表示客户订单的数据。然后使用本地二级索引查询这些数据。最后，程序会删除 `CustomerOrders` 表。
有关测试以下示例的分步说明，请参阅 [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());
}
}
```
# 处理本地二级索引：.NET
**Topics**
+ [创建具有本地二级索引的表](#LSILowLevelDotNet.CreateTableWithIndex)
+ [描述具有本地二级索引的表](#LSILowLevelDotNet.DescribeTableWithIndex)
+ [查询本地二级索引](#LSILowLevelDotNet.QueryAnIndex)
+ [示例：使用 适用于 .NET 的 AWS SDK 低级 API 的本地二级索引](LSILowLevelDotNet.Example.md)
您可以使用 适用于 .NET 的 AWS SDK 低级 API 创建具有一个或多个本地二级索引的 Amazon DynamoDB 表、描述表中的索引，以及使用索引执行查询。这些操作会映射到对应的低级 DynamoDB API 操作。有关更多信息，请参阅 [.NET 代码示例](CodeSamples.DotNet.md)。
以下是使用 .NET 低级 API 执行表操作的常见步骤。
1. 创建 `AmazonDynamoDBClient` 类的实例。
1. 通过创建对应的请求对象，为操作提供必需参数和可选参数。
例如，创建一个 `CreateTableRequest` 数据元以创建表；创建一个 `QueryRequest` 数据元以查询表或索引。
1. 运行您在前面步骤中创建的客户端提供的适当方法。
## 创建具有本地二级索引的表
本地二级索引必须在您创建表的同时创建。为此，请使用 `CreateTable` 并为一个或多个本地二级索引提供您的规范。以下 C\$1 代码示例创建一个包含音乐精选中歌曲信息的表。分区键为 `Artist`，排序键为 `SongTitle`。`AlbumTitleIndex` 这一二级索引可以按专辑名称进行查询。
以下是使用 .NET 低级别 API 创建具有本地二级索引的表的步骤。
1. 创建 `AmazonDynamoDBClient` 类的实例。
1. 创建 `CreateTableRequest` 类实例，以提供请求信息。
您必须提供表名称、主键以及预配置吞吐量值。对于本地二级索引，您必须提供索引名称、索引排序键的名称和数据类型、索引的键架构以及属性投影。
1. 以参数形式提供请求对象，运行 `CreateTable` 方法。
以下 C\$1 代码示例演示了上述步骤。该代码创建表 (`Music`)，在 `AlbumTitle` 属性上具有二级索引。投影到索引的属性只有表的分区键、排序键以及索引排序键。
```
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);
```
您必须等待 DynamoDB 创建该表并将表的状态设置为 `ACTIVE`。然后，您就可以开始在表中添加数据项目。
## 描述具有本地二级索引的表
要获取表上有关本地二级索引的信息，请使用 `DescribeTable` API。对于每个索引，您都可以查看其名称、键架构和投影的属性。
以下介绍使用 .NET 低级 API 访问表中的本地二级索引信息的步骤。
1. 创建 `AmazonDynamoDBClient` 类的实例。
1. 创建 `DescribeTableRequest` 类实例，以提供请求信息。您必须提供表名称。
1. 以参数形式提供请求对象，运行 `describeTable` 方法。
以下 C\$1 代码示例演示了上述步骤。
**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);
}
}
}
```
## 查询本地二级索引
您可以对本地二级索引使用 `Query`，基本上与对表执行 `Query` 操作相同。您需要指定索引名称、索引排序键的查询条件以及要返回的属性。在本示例中，索引为 `AlbumTitleIndex`，索引排序键为 `AlbumTitle`。
要返回的只包含投影到索引的属性。您也可以修改此查询，让返回结果中也包含非键属性，但是这样会导致表抓取活动的成本相对较高的。有关表抓取的更多信息，请参阅 [属性投影](LSI.md#LSI.Projections)。
以下是使用 .NET 低级别 API 查询本地二级索引的步骤。
1. 创建 `AmazonDynamoDBClient` 类的实例。
1. 创建 `QueryRequest` 类实例，以提供请求信息。
1. 以参数形式提供请求对象，运行 `query` 方法。
以下 C\$1 代码示例演示了上述步骤。
**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();
}
```
# 示例：使用 适用于 .NET 的 AWS SDK 低级 API 的本地二级索引
以下 C\$1 代码示例显示如何在 Amazon DynamoDB 中处理本地二级索引。示例创建名为 `CustomerOrders` 的表，其分区键为 `CustomerId`，排序键为 `OrderId`。此表上有两个本地二级索引：
+ `OrderCreationDateIndex` — 排序键是 `OrderCreationDate`，并将以下属性投影到索引：
+ `ProductCategory`
+ `ProductName`
+ `OrderStatus`
+ `ShipmentTrackingId`
+ `IsOpenIndex` — 排序键是 `IsOpen`，并将表的所有属性投影到索引。
创建 `CustomerOrders` 表后，程序为该表加载表示客户订单的数据。然后使用本地二级索引查询这些数据。最后，程序会删除 `CustomerOrders` 表。
有关测试以下示例的分步说明，请参阅 [.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;
}
}
}
}
}
```
# 在 DynamoDB AWS CLI 中使用本地二级索引
您可以使用 AWS CLI 创建具有一个或多个本地二级索引的 Amazon DynamoDB 表、描述表中的索引，以及使用索引执行查询。
**Topics**
+ [创建具有本地二级索引的表](#LCICli.CreateTableWithIndex)
+ [描述具有本地二级索引的表](#LCICli.DescribeTableWithIndex)
+ [查询本地二级索引](#LCICli.QueryAnIndex)
## 创建具有本地二级索引的表
本地二级索引必须在您创建表的同时创建。为此，请使用 `create-table` 参数并为一个或多个本地二级索引提供您的规范。以下示例创建一个包含音乐精选中歌曲信息的表 (`Music`)。分区键为 `Artist`，排序键为 `SongTitle`。`AlbumTitle` 属性的二级索引 `AlbumTitleIndex` 可以按专辑名称进行查询。
```
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\"]}}]"
```
您必须等待 DynamoDB 创建该表并将表的状态设置为 `ACTIVE`。然后，您就可以开始在表中添加数据项目。您可以使用 [describe-table](https://docs.aws.amazon.com/cli/latest/reference/dynamodb/describe-table.html) 确定表创建的状态。
## 描述具有本地二级索引的表
要获取表上有关本地二级索引的信息，请使用 `describe-table` 参数。对于每个索引，您都可以查看其名称、键架构和投影的属性。
```
aws dynamodb describe-table --table-name Music
```
## 查询本地二级索引
您可以对本地二级索引使用 `query` 操作，基本上与对表执行 `query` 操作相同。您需要指定索引名称、索引排序键的查询条件以及要返回的属性。在本示例中，索引为 `AlbumTitleIndex`，索引排序键为 `AlbumTitle`。
要返回的只包含投影到索引的属性。您也可以修改此查询，让返回结果中也包含非键属性，但是这样会导致表抓取活动的成本相对较高的。有关表获取的更多信息，请参阅 [属性投影](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"} }'
```
# 使用 DynamoDB 事务管理复杂工作流
Amazon DynamoDB Transactions 简化了开发人员对表内和表间的多个项目进行“要么全有要么全无”的协调式更改的体验。在 DynamoDB 中，事务提供原子性、一致性、隔离性和持久性 (ACID)，帮助您维护应用程序中的数据正确性。
您可以使用 DynamoDB 事务读取和写入 API 管理复杂的业务工作流，这些业务流需要作为单个“要么全有要么全无”操作添加、更新或删除多个项目。例如，当玩家在游戏中交换物品或在游戏中购买物品时，视频游戏开发人员可以确保他们的个人资料得到正确更新。
使用事务写入 API，您可以分组多个 `Put`、`Update`、`Delete` 和 `ConditionCheck` 操作。您可将多个操作作为单个 `TransactWriteItems` 操作提交，然后整体成功或失败。这同样适用于多个 `Get` 操作，您可以对它们进行分组并作为单个 `TransactGetItems` 操作提交。
无需其他成本即可为 DynamoDB 表启用事务。您只需为作为事务一部分的读取或写入付费。DynamoDB 在事务中对于每个项目执行两次基础读写：一次是准备事务，一次是提交事务。这两个基础读/写操作显示在 Amazon CloudWatch 指标中。
要开始使用 DynamoDB 事务，请下载最新的 AWS SDK 或 AWS Command Line Interface (AWS CLI)。然后，按照 [DynamoDB 事务示例](transaction-example.md) 中的说明操作。
下面各个部分详细概述事务 API 以及如何在 DynamoDB 中使用它们。
**Topics**
+ [工作原理](transaction-apis.md)
+ [将 IAM 与事务结合使用](transaction-apis-iam.md)
+ [代码示例](transaction-example.md)
# Amazon DynamoDB Transactions：工作原理
借助 Amazon DynamoDB Transactions，您可以将多个操作分组在一起，并将它们作为单个“要么全有要么全无”的 `TransactWriteItems` 或 `TransactGetItems` 操作提交。以下各部分介绍有关在 DynamoDB 中使用事务操作的 API 操作、容量管理、最佳实践和其他详细信息。
**Topics**
+ [TransactWriteItems API](#transaction-apis-txwriteitems)
+ [TransactGetItems API](#transaction-apis-txgetitems)
+ [DynamoDB 事务的隔离级别](#transaction-isolation)
+ [DynamoDB 中的事务冲突处理](#transaction-conflict-handling)
+ [在 DynamoDB Accelerator（DAX）中使用事务 API](#transaction-apis-dax)
+ [事务的容量管理](#transaction-capacity-handling)
+ [事务的最佳实践](#transaction-best-practices)
+ [将事务 API 与全局表结合使用](#transaction-integration)
+ [DynamoDB 事务与 AWSLabs 事务客户端库](#transaction-vs-library)
## TransactWriteItems API
`TransactWriteItems` 是一个同步和幂等的写入操作，它可将多达 100 个写入操作分组在单个“要么全有要么全无”操作中。这些操作的目标是同一个 AWS 账户和同一个区域内的一个或多个 DynamoDB 表中有多达 100 个不同的项目。事务中项目的合计大小不能超过 4 MB。这些操作以原子方式完成，以便所有操作都成功或都失败。
**注意**
`TransactWriteItems` 不同于 `BatchWriteItem` 操作，因为前者包含的所有操作必须成功完成，否则根本不会进行任何更改。借助 `BatchWriteItem` 操作，批处理中的某些操作可能获得成功，而其他操作失败。
不能使用索引执行事务。
您不能将同一个事务中的多个操作指向同一个项目。例如，您不能在同一个事务中对相同项目既执行 `ConditionCheck` 又执行 `Update` 操作。
您可向事务添加下列类型的操作：
+ `Put` — 启动 `PutItem` 操作以创建一个新项目，或者将旧项目替换为新项目（有条件或未指定任何条件）。
+ `Update` — 启动 `UpdateItem` 操作以编辑现有项目的属性，或者将新项目添加到表中（如果它不存在）。使用此操作有条件或无条件添加、删除或更新现有项目的属性。
+ `Delete` — 启动 `DeleteItem` 操作，以删除表中由其主键标识的单个项目。
+ `ConditionCheck` — 检查项目是否存在，或者检查项目特定属性的条件。
某个事务在 DynamoDB 中完成之后，其更改开始传播到全局二级索引（GSI）、流和备份。这种传播是逐步进行的：来自同一事务的流记录可能显示为不同的时间，并且可以与其他事务的记录交错存放。流使用者不应假定事务的原子性或顺序保证。
要确保事务中修改的项目的原子快照，请使用 TransactGetItems 操作一起读取所有相关项目。此操作提供了一致的数据视图，可确保您看到已完成事务中的所有更改，否则不查看任何更改。
由于传播并不具有即时性，如果在传播过程中某个表从备份还原（[RestoreTableFromBackup](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_RestoreTableFromBackup.html)）或将其导出到某个时间点（[ExportTableToPointInTime](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_ExportTableToPointInTime.html)），则可能会包含在近期事务期间所做的部分而非全部更改。
### 幂等性
当您执行 `TransactWriteItems` 调用时，可以选择包含客户端令牌，以确保请求是*幂等的*。通过使事务成为幂等的，如果相同操作由于连接超时或其他连接问题而多次提交，则可帮助防止出现应用程序错误。
如果原始 `TransactWriteItems` 调用成功，则使用相同客户端令牌的后续 `TransactWriteItems` 调用将成功返回，而不做任何更改。如果设置了 `ReturnConsumedCapacity` 参数，则初始 `TransactWriteItems` 调用将返回在进行更改时占用的写入容量单位数。使用相同客户端令牌的后续 `TransactWriteItems` 调用将返回在读取项目时占用的读取容量单位数。
**有关幂等性的要点**
+ 客户端令牌在使用它的请求完成后的 10 分钟内有效。10 分钟后，任何使用相同客户端令牌的请求都将被视为一个新请求。10 分钟后，您不应为同一请求使用重新相同的客户端令牌。
+ 如果您在 10 分钟的幂等性时段内使用相同的客户端令牌重复请求，但更改了某个其他请求参数，则 DynamoDB 将返回 `IdempotentParameterMismatch` 异常。
### 写入错误处理
写入事务在以下情况下不会成功：
+ 其中一个条件表达式中的条件未得到满足时。
+ 因为同一个 `TransactWriteItems` 操作中的多个操作指向同一个项目而导致发生事务验证错误时。
+ `TransactWriteItems` 请求与 `TransactWriteItems` 请求中针对一个或多个项目的正在执行的 `TransactWriteItems` 操作冲突时。在这种情况下，请求将失败并显示 `TransactionCanceledException`。
+ 当完成事务所需的预置容量不足时。
+ 当项目大小变得过大（大于 400 KB），或者本地二级索引 (LSI) 变得过大，或者由于事务所做更改导致发生类似的验证错误时。
+ 出现用户错误（如数据格式无效）时。
有关如何处理与 `TransactWriteItems` 操作的冲突的更多信息，请参阅 [DynamoDB 中的事务冲突处理](#transaction-conflict-handling)。
## TransactGetItems API
`TransactGetItems` 是一个同步读取操作，它可将多达 100 个 `Get` 操作分组在一起。这些操作的目标是同一个 AWS 账户和区域内的一个或多个 DynamoDB 表中有多达 100 个不同的项目。事务中项目的合计大小不能超过 4 MB。
`Get` 以原子方式执行，以便所有操作都成功或都失败：
+ `Get` — 启动 `GetItem` 操作，以检索具有给定主键的项目的一组属性。如果找不到匹配项目，`Get` 将不返回任何数据。
### 读取错误处理
读取事务在以下情况下不会成功：
+ `TransactGetItems` 请求与 `TransactWriteItems` 请求中针对一个或多个项目的正在执行的 `TransactGetItems` 操作冲突时。在这种情况下，请求将失败并显示 `TransactionCanceledException`。
+ 当完成事务所需的预置容量不足时。
+ 出现用户错误（如数据格式无效）时。
有关如何处理与 `TransactGetItems` 操作的冲突的更多信息，请参阅 [DynamoDB 中的事务冲突处理](#transaction-conflict-handling)。
## DynamoDB 事务的隔离级别
事务操作的隔离级别（`TransactWriteItems` 或 `TransactGetItems`）和其他操作如下所示。
### 可序列化
*可序列化*隔离可确保多个并发操作的结果相同，就像当前操作在前一个操作完成之前不会开始。
以下操作类型之间具有可序列化隔离：
+ 在任何事务操作与任何标准写入操作（`PutItem`、`UpdateItem` 或 `DeleteItem`）之间。
+ 在任何事务操作与任何标准读取操作 (`GetItem`) 之间。
+ 在 `TransactWriteItems` 操作与 `TransactGetItems` 操作之间。
尽管在事务操作与 `BatchWriteItem` 操作中的每个单独标准写入之间具有可序列化隔离，但作为一个整体，在事务与 `BatchWriteItem` 操作之间没有可序列化隔离。
类似地，事务操作与 `GetItems` 操作中的单个 `BatchGetItem` 之间的隔离级别是可序列化的。但是事务和作为一个单元的 `BatchGetItem` 操作之间的隔离级别是*读取已提交*。
单个 `GetItem` 请求可以采用相对于 `TransactWriteItems` 请求的两种方式序列化，在 `TransactWriteItems` 请求 之前或之后。多个`GetItem`请求，针对并发`TransactWriteItems`请求可以按任何顺序运行，因此结果为*读取已提交*。
例如，如果对项目 A 和项目 B 的 `GetItem` 请求与修改项目 A 和项目 B 的 `TransactWriteItems` 请求同时运行，则有四种可能性：
+ 两个 `GetItem` 请求在 `TransactWriteItems` 请求之前运行。
+ 两个 `GetItem` 请求在 `TransactWriteItems` 请求之后运行。
+ 对项目 A 的 `GetItem` 请求在 `TransactWriteItems` 请求之前运行。对于项目 B，`GetItem` 在 `TransactWriteItems` 之后运行。
+ 对项目 B 的 `GetItem` 请求在 `TransactWriteItems` 请求之前运行。对于项目 A，`GetItem` 在 `TransactWriteItems` 之后运行。
如果对于多个 `GetItem` 请求偏好可序列化隔离级别，则应使用 `TransactGetItems`。
如果对属于传输中的同一事务写入请求的多个项目进行非事务性读取，则有可能能够读取其中一些项目的新状态以及其它项目的旧状态。仅当收到事务性写入的成功响应，指示事务已完成时，您才能读取属于事务写入请求的所有项目的新状态。
在事务成功完成并收到响应后，由于 DynamoDB 的最终一致性模型，后续的*最终一致性* 读取操作仍可能在短时间内返回旧状态。为了保证在事务处理后立即读取最新数据，应通过将 `ConsistentRead` 设置为 true 来使用[*强一致性*](HowItWorks.ReadConsistency.md#HowItWorks.ReadConsistency.Strongly) 读取。
### 读取已提交
*读取已提交*隔离可确保读取操作始终返回项目的已提交值，对于表现出事务写入未最终成功状态的项目，读取操作永远不会对该项目呈现视图。读取已提交隔离无法防止在读取操作后立即修改项目。
隔离级别在任何事务操作与涉及多个标准读取（`BatchGetItem`、`Query` 或 `Scan`）的任何读取操作之间为读取已提交。如果事务写入在 `BatchGetItem`、`Query` 或 `Scan` 操作中间更新了某个项目，则该读取操作接下来的部分将返回新的已提交值（对于 `ConsistentRead)`）或可能是之前的已提交值（最终一致性读取）。
### 操作摘要
简而言之，下表显示事务操作（`TransactWriteItems` 或 `TransactGetItems`）与其他操作之间的隔离级别。
| 操作 | 隔离级别 |
| --- | --- |
| `DeleteItem` | *可序列化* |
| `PutItem` | *可序列化* |
| `UpdateItem` | *可序列化* |
| `GetItem` | *可序列化* |
| `BatchGetItem` | *读取已提交*\$1 |
| `BatchWriteItem` | *不可序列化*\$1 |
| `Query` | *读取已提交* |
| `Scan` | *读取已提交* |
| 其他事务操作 | *可序列化* |
标记星号 (\$1) 的级别作为一个整体适用于操作。但是，这些操作内的各个操作具有*可序列化*隔离级别。
## DynamoDB 中的事务冲突处理
事务内的项目上的并发项级请求期间可能会发生事务冲突。在以下情况下可能发生事务冲突：
+ 项目的 `PutItem`、`UpdateItem` 或 `DeleteItem` 请求与包含相同项目的正在进行的 `TransactWriteItems` 请求冲突。
+ `TransactWriteItems` 请求中的某个项目是另一个正在进行的 `TransactWriteItems` 请求的一部分。
+ `TransactGetItems` 请求中的某个项目是正在进行的 `TransactWriteItems`、`BatchWriteItem`、`PutItem`、`UpdateItem` 或 `DeleteItem` 请求的一部分。
**注意**
当 `PutItem`、`UpdateItem` 或 `DeleteItem` 请求被拒绝时，请求会失败，并显示 `TransactionConflictException`。
如果 `TransactWriteItems` 或 `TransactGetItems` 任何项目级别请求被拒绝，则请求将失败并显示 `TransactionCanceledException`。如果该请求失败，AWS SDK 不重试请求。
如果您使用的是 适用于 Java 的 AWS SDK，则该异常包含 [CancellationReasons](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_CancellationReason.html) 列表，该列表根据 `TransactItems` 请求参数中的项目列表排序。对于其他语言，列表的字符串表示形式包含在异常的错误消息中。
但是，如果正在执行的 `TransactWriteItems` 或 `TransactGetItems` 操作与并发 `GetItem` 请求冲突，则这两个操作都会成功。
对于每个失败的项目级别请求，[TransactionConflict CloudWatch metric](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/metrics-dimensions.html) 指标会递增。
## 在 DynamoDB Accelerator（DAX）中使用事务 API
`TransactWriteItems` 和 `TransactGetItems` 在 DynamoDB Accelerator (DAX) 中都受支持，并且其隔离级别与 DynamoDB 中的相同。
`TransactWriteItems` 通过 DAX 写入。DAX 将一个 `TransactWriteItems` 调用传递到 DynamoDB，并返回响应。为了在写入后填充缓存，DAX 在后台对 `TransactWriteItems` 操作中的每个项目调用 `TransactGetItems`，这将使用额外的读取容量单位。（有关更多信息，请参阅 [事务的容量管理](#transaction-capacity-handling)。） 利用此功能，您可以保持应用程序逻辑的简单性，并将 DAX 同时用于事务操作和非事务操作。
`TransactGetItems` 调用将通过 DAX 进行传递，而不会在本地缓存项目。这与 DAX 中的强一致性读取 API 的行为相同。
## 事务的容量管理
无需其他成本即可为 DynamoDB 表启用事务。您只需为作为事务一部分的读取或写入付费。DynamoDB 在事务中对于每个项目执行两次基础读写：一次是准备事务，一次是提交事务。这两个基础读/写操作显示在 Amazon CloudWatch 指标中。
当您为表预配置容量时，规划事务 API 需要的其他读取和写入。例如，假设您的应用程序每秒执行一个事务，并且每个事务在表中写入三个 500 字节的项目。每个项目需要两个写入容量单位 (WCU)：一个用于准备事务，一个用于提交事务。因此，您需要为表预置六个 WCU。
如果您在前面的示例中使用 DynamoDB Accelerator (DAX)，则还将为 `TransactWriteItems` 调用中的每个项目使用两个读取容量单位 (RCU)。因此，您需要为表预配置另外六个 RCU。
同样，如果您的应用程序每秒执行一个读取事务，并且每个事务读取表中三个 500 字节的项目，则您需要为表预置六个读取容量单位 (RCU)。读取每个项目需要两个 RCU：一个用于准备事务，一个用于提交事务。
此外，默认的 SDK 行为是在引发 `TransactionInProgressException` 异常时重试事务。规划这些重试所占用的其他读取容量单位 (RCU)。这同样适用于您使用 `ClientRequestToken` 在您自己的代码中重试事务。
## 事务的最佳实践
使用 DynamoDB 事务时，请考虑以下建议的实践。
+ 对表启用自动扩展功能，或者确保您已预置了足够的吞吐容量，以便为事务中的每个项目执行两个读取或写入操作。
+ 如果您未使用 AWS 提供的 SDK，则在进行 `TransactWriteItems` 调用时加入 `ClientRequestToken` 属性，以确保请求具有幂等性。
+ 如果不必要，请勿将操作分组在一个事务中。例如，如果具有 10 个操作的单个事务可以分解为多个事务而不会妨碍应用程序正确性，则建议您拆分此事务。更简单的事务可提高吞吐量，且更可能成功。
+ 同时更新相同项目的多个事务可能导致冲突而取消事务。我们建议您遵循 DynamoDB 数据建模的最佳实践，以最大限度地减少此类冲突。
+ 如果一组属性经常跨多个项目作为单个事务的一部分进行更新，则考虑将这些属性分组到一个项目，以减小事务的范围。
+ 避免使用事务来成批注入数据。对于成批写入，使用 `BatchWriteItem` 则更好。
## 将事务 API 与全局表结合使用
事务操作仅在调用写入 API 的 AWS 区域内提供原子性、一致性、隔离性和持久性（ACID）保证。全局表中不支持跨区域的事务。例如，假设您在美国东部（俄亥俄州）和美国西部（俄勒冈州）区域有一个带副本的全局表，并且您在美国东部（弗吉尼亚州北部）区域执行 `TransactWriteItems` 操作。您可能会在复制更改时观察到美国西部（俄勒冈州）区域内已部分完成的事务。更改仅在源区域中提交后才复制到其它区域。
## DynamoDB 事务与 AWSLabs 事务客户端库
DynamoDB 事务为 [AWSLabs](https://github.com/awslabs) 事务客户端库提供了更经济实惠、强大且高性能的替代方式。我们建议您更新应用程序，以使用原生服务器端事务 API。
# 将 IAM 与 DynamoDB 事务结合使用
您可以使用 AWS Identity and Access Management (IAM) 限制事务操作可以在 Amazon DynamoDB 中执行的操作。有关在 DynamoDB 中使用 IAM 策略的更多信息，请参阅。[适用于 DynamoDB 的基于身份的策略](security_iam_service-with-iam.md#security_iam_service-with-iam-id-based-policies)
`Put`、`Update`、`Delete` 和 `Get` 操作的权限由用于基础 `PutItem`、`UpdateItem`、`DeleteItem` 和 `GetItem` 操作的权限管控。对于 `ConditionCheck` 操作，您可以在 IAM 策略中使用 `dynamodb:ConditionCheckItem` 权限。
以下是可用于配置 DynamoDB 事务的 IAM 策略的示例。
## 示例 1：允许事务操作
------
#### [ 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"
]
}
]
}
```
------
## 示例 2：仅允许事务操作
------
#### [ 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"
]
}
}
}
]
}
```
------
## 示例 3：允许非事务读取和写入，并阻止事务读取和写入
------
#### [ 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"
]
}
]
}
```
------
## 示例 4：阻止在 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"
}
}
}
]
}
```
------
# DynamoDB 事务示例
作为 Amazon DynamoDB Transactions 可能有用的情况示例，请考虑此适用于在线商城的 Java 应用程序示例。
该应用程序在后端有三个 DynamoDB 表：
+ `Customers`— 此表存储有关商城买家的详细信息。它的主键是 `CustomerId` 唯一标识符。
+ `ProductCatalog`— 此表存储有关商品在商城中销售的价格和供货情况等详细信息。它的主键是 `ProductId` 唯一标识符。
+ `Orders`— 此表存储有关来自市场的订单的详细信息。它的主键是 `OrderId` 唯一标识符。
## 下订单
以下代码片段说明了如何使用 DynamoDB 事务来协调创建和处理订单所需的多个步骤。使用单个全有或全无操作可确保如果事务的任何部分失败，事务中不会运行任何操作，也不会进行任何更改。
在此示例中，您设置来自 `customerId` 为 `09e8e9c8-ec48` 的客户订单。然后，您可以使用以下简单的订单处理工作流将其作为单个事务处理运行：
1. 确定客户 ID 是否有效。
1. 确保产品是 `IN_STOCK`，并将产品状态更新为 `SOLD`。
1. 确保订单不存在，然后创建订单。
### 验证客户
首先，定义一个操作以验证 `customerId` 等于 `09e8e9c8-ec48` 的客户存在于客户表中。
```
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 + ")");
```
### 更新产品状态
接下来，定义一个操作，如果产品状态当前设置为 `IN_STOCK` 的条件为 `true`，则将产品状态更新为 `SOLD`。设置 `ReturnValuesOnConditionCheckFailure` 参数，如果项目的产品状态属性不等于 `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);
```
### 创建订单
最后，只要不存在具有 `OrderId` 的订单，则创建订单。
```
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 + ")");
```
### 运行事务
以下示例说明如何运行以前定义为单个全有或全无操作的操作。
```
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());
}
```
## 阅读订单详细信息
以下示例演示了如何以事务方式读取 `Orders` 和 `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());
}
```
# 将更改数据捕获与 Amazon DynamoDB 结合使用
当存储在 DynamoDB 表中的项目发生更改时，许多应用程序都会因能够捕获此类更改而受益。下面是一些使用场景示例：
+ 一个热门移动应用程序以每秒数千次更新的速率修改 DynamoDB 表中的数据。第二个应用程序捕获和存储有关这些更新的数据，并提供针对该移动应用程序的近乎实时用量指标。
+ 财务应用程序修改 DynamoDB 表中的股票市场数据。并行运行的不同应用程序实时跟踪这些变化，计算风险价值，并根据股票价格变动自动重新平衡投资组合。
+ 运输车辆和工业设备中的传感器将数据发送到 DynamoDB 表中。不同的应用程序监控性能并在检测到问题时发送消息警报，通过应用机器学习算法预测任何潜在缺陷，并将数据压缩和存档到 Amazon Simple Storage Service (Amazon S3)。
+ 一旦某个好友上传新图片，一个应用程序就会自动向群组中的所有好友的移动设备发送通知。
+ 一个新客户将数据添加到 DynamoDB 表。此事件调用另一个应用程序，以便向该新客户发送欢迎电子邮件。
DynamoDB 支持近实时流式处理项目级别更改数据捕获记录。可以构建使用这些流并根据内容采取操作的应用程序。
**注意**
不支持向 DynamoDB Streams 添加标签以及将[基于属性的访问权限控制（ABAC）](access-control-resource-based.md)和 DynamoDB Streams 结合使用。
以下视频将向您介绍更改数据捕获概念。
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/VVv_-mZ5Ge8)
**Topics**
+ [更改数据捕获的流式传输选项](#streamsmain.choose)
+ [使用 Kinesis Data Streams 捕获 DynamoDB 的更改](kds.md)
+ [将更改数据捕获用于 DynamoDB Streams](Streams.md)
## 更改数据捕获的流式传输选项
DynamoDB 提供了两个用于更改数据捕获的流模型：Kinesis Data Streams for DynamoDB 和 DynamoDB Streams。
为了帮助选择适合应用程序的解决方案，下表总结了每个流式处理模型的功能。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/amazondynamodb/latest/developerguide/streamsmain.html)
您可以在同一 DynamoDB 表上启用两个流式处理模型。
下面的视频详细介绍了这两个选项之间的差异。
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/UgG17Wh2y0g)
# 使用 Kinesis Data Streams 捕获 DynamoDB 的更改
您可以使用 Amazon Kinesis Data Streams 捕获 Amazon DynamoDB 的更改。
Kinesis Data Streams 捕获任何 DynamoDB 表中的项目级别修改，并将它们复制到 [Kinesis Data Streams](https://docs.aws.amazon.com/streams/latest/dev/introduction.html)。您的应用程序可以访问此数据流，近实时查看项目级别的更改。您可以每小时持续捕获和存储 TB 级的数据。您可以利用更长的数据保留时间，还可以借助增强的扇出功能同时访问两个或更多下游应用程序。其他优势包括额外的审计和安全透明度。
Kinesis Data Streams 还可让您访问 [Amazon Data Firehose](https://docs.aws.amazon.com/firehose/latest/dev/what-is-this-service.html) 和[适用于 Apache Flink 的亚马逊托管服务](https://docs.aws.amazon.com/kinesisanalytics/latest/dev/what-is.html)。这些服务可帮助您构建应用程序来支持实时控制面板、生成警报、实施动态定价和广告以及实现复杂的数据分析和机器学习算法。
**注意**
为 DynamoDB 使用 Kinesis 数据流受数据流的 [Kinesis Data Streams 定价](https://aws.amazon.com/kinesis/data-streams/pricing/)和源表的 [DynamoDB 定价](https://aws.amazon.com/dynamodb/pricing/)影响。
要使用控制台、AWS CLI 或 Java SDK 在 DynamoDB 表上启用 Kinesis 流式传输，请参阅[适用于 Amazon DynamoDB 的 Kinesis Data Streams 入门](kds_gettingstarted.md)。
**Topics**
+ [Kinesis Data Streams 如何与 DynamoDB 结合使用](#kds_howitworks)
+ [适用于 Amazon DynamoDB 的 Kinesis Data Streams 入门](kds_gettingstarted.md)
+ [将 DynamoDB Streams 中的分片和指标与 Kinesis Data Streams 配合使用](kds_using-shards-and-metrics.md)
+ [使用适用于 Amazon Kinesis Data Streams 和 Amazon DynamoDB 的 IAM 策略](kds_iam.md)
## Kinesis Data Streams 如何与 DynamoDB 结合使用
为 DynamoDB 表启用 Kinesis 数据流时，该表将发送一条数据记录，其中捕获该表数据的任何更改。此数据记录包括：
+ 最近创建、更新或删除任何项目的具体时间
+ 该项目的主键
+ 修改前记录的快照
+ 修改后记录的快照
将近乎实时地捕获并发布这些数据记录。将它们写入 Kinesis 数据流后，就可以像任何其他记录一样读取它们。您可以使用 Kinesis 客户端库，使用 AWS Lambda，调用 Kinesis Data Streams API，以及使用其他连接的服务。有关更多信息，请参阅 Amazon Kinesis Data Streams 开发人员指南的[从 Amazon Kinesis Data Streams 读取数据](https://docs.aws.amazon.com/streams/latest/dev/building-consumers.html)。
数据的这些更改也是异步捕获的。Kinesis 对其正在进行流式传输的表没有性能影响。存储在 Kinesis 数据流中的流记录也会静态加密。有关更多信息，请参阅 [Amazon Kinesis Data Streams 数据保护](https://docs.aws.amazon.com/streams/latest/dev/server-side-encryption.html)。
Kinesis 数据流记录的显示顺序可能与项目更改发生时的顺序不同。同一项目通知也可能会在数据流中多次出现。您可以检查 `ApproximateCreationDateTime` 属性，以确定项目修改的发生顺序，并识别重复的记录。
当您启用 Kinesis 数据流作为 DynamoDB 表的流式传输目标时，您可以用毫秒或微秒为单位配置 `ApproximateCreationDateTime` 值的精度。默认情况下，`ApproximateCreationDateTime` 指示更改时间（以毫秒为单位）。此外，您可以在活动的流式传输目标上更改该值。更新后，写入 Kinesis 的流记录将具有所需精度的 `ApproximateCreationDateTime` 值。
写入 DynamoDB 的二进制值必须采用 [base64 编码格式](HowItWorks.NamingRulesDataTypes.md)进行编码。但是，当数据记录写入 Kinesis 数据流时，这些编码的二进制值将再次使用 base64 编码进行编码。从 Kinesis 数据流读取这些记录时，为了检索原始二进制值，应用程序必须对这些值进行两次解码。
DynamoDB 会对在更改数据捕获单元中使用 Kinesis Data Streams 收取费用。每个项目的 1KB 更改计为一个更改数据捕获单元。每个项目的更改 KB 数是由写入数据流的项目的“之前”和“之后”镜像中较大者计算得出，期间使用与[写入操作的容量单位消耗](read-write-operations.md#write-operation-consumption)相同的逻辑。您无需为更改数据捕获单元预置容量吞吐量，类似于 DynamoDB [按需](capacity-mode.md#capacity-mode-on-demand)模式的工作原理。
### 为 DynamoDB 表启用 Kinesis 数据流
可以使用 AWS 管理控制台、AWS SDK 或 AWS Command Line Interface (AWS CLI)，启用或禁用从现有 DynamoDB 表流式传输到 Kinesis。
+ 您只能从 DynamoDB 流式传输到从同一 AWS 账户和 AWS 区域中的 Kinesis Data Streams 作为您的表。
+ 您只能将数据从 DynamoDB 表流式传输到一个 Kinesis 数据流。
### 更改 DynamoDB 表上的 Kinesis Data Streams 目标
默认情况下，所有 Kinesis 数据流记录都包含一个 `ApproximateCreationDateTime` 属性。此属性表示创建每条记录的大致时间的时间戳（以毫秒为单位）。您可以使用 [https://console.aws.amazon.com/kinesis](https://console.aws.amazon.com/kinesis)、SDK 或 AWS CLI 更改这些值的精度
# 适用于 Amazon DynamoDB 的 Kinesis Data Streams 入门
本节介绍了如何通过 Amazon DynamoDB 控制台、AWS Command Line Interface（AWS CLI）和 API 将 Kinesis Data Streams 用于 Amazon DynamoDB 表。
## 创建有效的 Amazon Kinesis 数据流
所有这些示例都使用 [DynamoDB 入门](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GettingStartedDynamoDB.html)教程中创建的 `Music` DynamoDB 表。
要了解如何构建使用器并将 Kinesis Data Stream 连接到其他 AWS 服务，请参阅《Amazon Kinesis Data Streams 开发人员指南》**中的[从 Kinesis Data Streams 读取数据](https://docs.aws.amazon.com/streams/latest/dev/building-consumers.html)。
**注意**
当您首次使用 KDS 分片时，建议您将分片设置为根据使用模式横向和纵向扩展。在积累了更多有关使用模式的数据后，您可以调整数据流中的分片以与模式匹配。
------
#### [ Console ]
1. 登录到 AWS 管理控制台，然后打开 Kinesis 控制台：[https://console.aws.amazon.com/kinesis/](https://console.aws.amazon.com/kinesis/)。
1. 选择**创建数据流**并按照说明创建一个名为 `samplestream` 的流。
1. 打开 DynamoDB 控制台：[https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/)。
1. 在控制台左侧的导航窗格中，选择**表**。
1. 选择 **Music** 表。
1. 选择**导出和流式传输**选项卡。
1. （可选）在 **Amazon Kinesis Data Streams 详细信息**下，您可以将记录时间戳精度从微秒（默认）更改为毫秒。
1. 从下拉列表选择 **samplestream**。
1. 选择**开启**按钮。
------
#### [ AWS CLI ]
1. 使用 [create-stream 命令](https://docs.aws.amazon.com/cli/latest/reference/kinesis/create-stream.html)创建名为 `samplestream` 的 Kinesis 流。
```
aws kinesis create-stream --stream-name samplestream --shard-count 3
```
请参阅[Kinesis Data Streams 的分片管理注意事项](kds_using-shards-and-metrics.md#kds_using-shards-and-metrics.shardmanagment)，然后设置 Kinesis 数据流的分片数。
1. 使用 [describe-stream 命令](https://docs.aws.amazon.com/cli/latest/reference/kinesis/describe-stream.html)，检查 Kinesis 流是否处于活动状态并准备好使用。
```
aws kinesis describe-stream --stream-name samplestream
```
1. 使用 DynamoDB `enable-kinesis-streaming-destination` 命令，在 DynamoDB 表上启用 Kinesis 数据流。将 `stream-arn` 值替换为上一步返回的 `describe-stream`。（可选）启用在每条记录上返回更精细（微秒）精度时间戳值的流式传输。
启用微秒时间戳精度的流式传输：
```
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
```
或者启用默认时间戳精度（毫秒）的流式传输：
```
aws dynamodb enable-kinesis-streaming-destination \
--table-name Music \
--stream-arn arn:aws:kinesis:us-west-2:12345678901:stream/samplestream
```
1. 使用 DynamoDB `describe-kinesis-streaming-destination` 命令检查是否在表上激活 Kinesis 流。
```
aws dynamodb describe-kinesis-streaming-destination --table-name Music
```
1. 使用 [DynamoDB 开发人员指南](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/getting-started-step-2.html)介绍的 `put-item` 命令，将数据写入 DynamoDB 表。
```
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. 使用 Kinesis [get-records](https://docs.aws.amazon.com/cli/latest/reference/kinesis/get-records.html) CLI 命令检索 Kinesis 流内容。然后使用以下代码片段来反序列化流内容。
```
/**
* 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. 按照 Kinesis Data Streams 开发人员指南中的说明，使用 Java 创建一个名为 `samplestream` 的[https://docs.aws.amazon.com/streams/latest/dev/kinesis-using-sdk-java-create-stream.html](https://docs.aws.amazon.com/streams/latest/dev/kinesis-using-sdk-java-create-stream.html) Kinesis 数据流。
请参阅[Kinesis Data Streams 的分片管理注意事项](kds_using-shards-and-metrics.md#kds_using-shards-and-metrics.shardmanagment)，然后设置 Kinesis 数据流的分片数。
1. 使用以下代码段在DynamoDB 表上启用 Kinesis 数据流。（可选）启用在每条记录上返回更精细（微秒）精度时间戳值的流式传输。
启用微秒时间戳精度的流式传输：
```
EnableKinesisStreamingConfiguration enableKdsConfig = EnableKinesisStreamingConfiguration.builder()
.approximateCreationDateTimePrecision(ApproximateCreationDateTimePrecision.MICROSECOND)
.build();
EnableKinesisStreamingDestinationRequest enableKdsRequest = EnableKinesisStreamingDestinationRequest.builder()
.tableName(tableName)
.streamArn(kdsArn)
.enableKinesisStreamingConfiguration(enableKdsConfig)
.build();
EnableKinesisStreamingDestinationResponse enableKdsResponse = ddbClient.enableKinesisStreamingDestination(enableKdsRequest);
```
或者启用默认时间戳精度（毫秒）的流式传输：
```
EnableKinesisStreamingDestinationRequest enableKdsRequest = EnableKinesisStreamingDestinationRequest.builder()
.tableName(tableName)
.streamArn(kdsArn)
.build();
EnableKinesisStreamingDestinationResponse enableKdsResponse = ddbClient.enableKinesisStreamingDestination(enableKdsRequest);
```
1. 按照 *Kinesis Data Streams 开发人员指南*中的说明进行操作，从创建的数据流[读取](https://docs.aws.amazon.com/streams/latest/dev/building-consumers.html)。
1. 然后使用以下代码段来反序列化流内容。
```
/**
* 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());
}
```
------
## 更改活动的 Amazon Kinesis Data Streams
本节介绍了如何使用控制台、AWS CLI 和 API 更改活动的 Kinesis Data Streams for DynamoDB 设置。
**AWS 管理控制台**
1. 打开 DynamoDB 控制台：[https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/)。
1. 转至您的表。
1. 选择**导出和流**。
**AWS CLI**
1. 调用 `describe-kinesis-streaming-destination` 以确认流的状态是 `ACTIVE`。
1. 调用 `UpdateKinesisStreamingDestination`，如以下示例所示：
```
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. 调用 `describe-kinesis-streaming-destination` 以确认流的状态是 `UPDATING`。
1. 定期调用 `describe-kinesis-streaming-destination`，直到流式传输状态恢复 `ACTIVE`。时间戳精度更新通常最多需要 5 分钟的时间才能生效。此状态更新后，即表示更新已完成，新的精度值将应用于未来的记录。
1. 使用 `putItem` 写入表。
1. 使用 Kinesis `get-records` 命令检索流内容。
1. 确认写入的 `ApproximateCreationDateTime` 具有所需的精度。
**Java API**
1. 提供构造 `UpdateKinesisStreamingDestination` 请求和 `UpdateKinesisStreamingDestination` 响应的代码段。
1. 提供构造 `DescribeKinesisStreamingDestination` 请求和 `DescribeKinesisStreamingDestination response` 的代码段。
1. 定期调用 `describe-kinesis-streaming-destination`，直到流状态恢复 `ACTIVE`，这表明更新已完成，新的精度值将应用于未来的记录。
1. 向表执行写入操作。
1. 从流中读取并反序列化流内容。
1. 确认写入的 `ApproximateCreationDateTime` 具有所需的精度。
# 将 DynamoDB Streams 中的分片和指标与 Kinesis Data Streams 配合使用
## Kinesis Data Streams 的分片管理注意事项
Kinesis 数据流以[分片](https://docs.aws.amazon.com/streams/latest/dev/key-concepts.html)形式计算其吞吐量。在 Amazon Kinesis Data Streams 中，您可以为数据流选择**按需**模式和**预置**模式。
如果您的 DynamoDB 写入工作负载变化很大且不可预测，我们建议您对 Kinesis Data Streams 使用按需模式。若采用按需模式，则无需容量规划，因为 Kinesis Data Streams 会自动管理分片来提供必要的吞吐量。
对于可预测的工作负载，您可以为 Kinesis Data Streams 使用预置模式。若采用预置模式，您必须为数据流指定分片数，以容纳 DynamoDB 的更改数据捕获记录。要确定 Kinesis 数据流支持 DynamoDB 表所需的分片数量，您需要以下输入值：
+ DynamoDB 表记录的平均大小，以字节为单位 (`average_record_size_in_bytes`)。
+ 每秒对 DynamoDB 表执行的最大写入操作数。这包括由您的应用程序执行的创建、删除和更新操作以及自动生成的操作，例如“生存时间”生成的删除操作（`write_throughput`）。
+ 您对表执行的更新和覆盖操作与创建或删除操作相比的百分比 (`percentage_of_updates`)。请注意，更新和覆盖操作会将已修改项目的旧镜像和新镜像复制到流中。这会生成两倍 DynamoDB 项目大小。
可使用以下公式中的输入值来计算 Kinesis 数据流所需的分片数量（`number_of_shards`）。
```
number_of_shards = ceiling( max( ((write_throughput * (4+percentage_of_updates) * average_record_size_in_bytes) / 1024 / 1024), (write_throughput/1000)), 1)
```
例如，您的最大吞吐量为 1040 个写入操作/秒（`write_throughput`），平均记录大小为 800 字节（`average_record_size_in_bytes)`）。如果这些写入操作中有 25% 是更新操作（`percentage_of_updates`），则将需要两个分片（`number_of_shards`）来容纳您的 DynamoDB 流式传输吞吐量：
```
ceiling( max( ((1040 * (4+25/100) * 800)/ 1024 / 1024), (1040/1000)), 1).
```
在使用公式计算 Kinesis 数据流在预置模式下所需的分片数之前，请考虑以下几点：
+ 此公式有助于估算容纳 DynamoDB 更改数据记录所需的分片数量。它不代表 Kinesis 数据流中所需的分片总数，例如支持额外 Kinesis 数据流使用者所需的分片数量。
+ 如果您未将数据流配置为处理峰值吞吐量，则在预置模式下仍可能遇到读写吞吐量异常的问题。在这种情况下，您必须手动扩展数据流以适应数据流量。
+ 此公式考虑了 DynamoDB 在将更改日志数据记录流式传输到 Kinesis 数据流之前产生的额外膨胀。
要了解有关 Kinesis 数据流容量模式的更多信息，请参阅[选择数据流容量模式](https://docs.aws.amazon.com/streams/latest/dev/how-do-i-size-a-stream.html)。要详细了解不同容量模式之间的定价差异，请参阅 [Amazon Kinesis Data Streams 定价](https://aws.amazon.com/kinesis/data-streams/pricing/)。
## 使用 Kinesis Data Streams 监控更改数据捕获
DynamoDB 提供多个 Amazon CloudWatch 指标，帮助您监控将更改数据捕获到 Kinesis 的复制。有关 CloudWatch 指标的完整列表，请参阅[DynamoDB 指标与维度](metrics-dimensions.md)。
我们建议您在流启用期间和生产中监视以下项目，以确定流是否有足够的容量：
+ `ThrottledPutRecordCount`：由于 Kinesis Data Streams 容量不足而受到 Kinesis 数据流限制的记录数量。异常使用高峰期间可能会遇到一些限制，但 `ThrottledPutRecordCount` 应保持尽可能低。DynamoDB 重试将受限制的记录发送到 Kinesis 数据流，这可能会导致更高的复制延迟。
如果遇到过多和定期的限制，则可能需要按照观察到的表写入吞吐量成比例增加 Kinesis 流分片数量。要了解有关如何确定 Kinesis 数据流的大小的详细信息，请参阅[确定 Kinesis Data Streams 的初始大小](https://docs.aws.amazon.com/streams/latest/dev/amazon-kinesis-streams.html#how-do-i-size-a-stream)。
+ `AgeOfOldestUnreplicatedRecord`：从等待复制的最早的项目级别更改，到 Kinesis 数据流出现在 DynamoDB 表中经过的时间。在正常运行情况下，`AgeOfOldestUnreplicatedRecord` 应该以毫秒为单位。如果失败的尝试由客户控制的配置选项造成，失败的复制尝试次数会增加。
如果 `AgeOfOldestUnreplicatedRecord` 指标超过 168 小时，则将自动禁用从 DynamoDB 表到 Kinesis 数据流的项目级别更改的复制。
例如，可能导致复制尝试失败的客户控制配置包括：预置不足的 Kinesis 数据流容量导致过度限制，或者手动更新 Kinesis 数据流的访问策略阻止 DynamoDB 向数据流添加数据。您可能需要确保预置合适的 Kinesis 数据流容量，并确保未更改 DynamoDB 的权限，才能将该指标保持在尽可能低的水平。
+ `FailedToReplicateRecordCount`：DynamoDB 无法复制到 Kinesis 数据流的记录数。某些大于 34KB 的项目可能会扩增，以更改大于 Kinesis Data Streams 1MB 项目大小限制的数据记录。当大于 34KB 的项目包含大量布尔值或空属性值时，就会出现此扩增现象。布尔值和空属性值在 DynamoDB 中存储为 1 个字节，但在使用标准 JSON 进行 Kinesis Data Streams 复制时，最多可扩展到 5 个字节。DynamoDB 无法将此类更改记录复制到 Kinesis 数据流中。DynamoDB 跳过这些更改数据记录，并自动继续复制后续记录。
您可以创建 Amazon CloudWatch 警报，以便在上述任何指标超过特定阈值时发送 Amazon Simple Notification Service (Amazon SNS) 消息，以便发送通知。
# 使用适用于 Amazon Kinesis Data Streams 和 Amazon DynamoDB 的 IAM 策略
首次启用 Amazon Kinesis Data Streams for Amazon DynamoDB 时，DynamoDB 会自动创建一个 AWS Identity and Access Management (IAM) 服务相关角色。此角色 `AWSServiceRoleForDynamoDBKinesisDataStreamsReplication` 允许 DynamoDB 代表您管理对 Kinesis Data Streams 的项目级别更改的复制。不要删除该服务相关角色。
有关服务相关角色的更多信息，请参见 *IAM 用户指南*中的[使用服务相关角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html)。
**注意**
DynamoDB 不支持基于标签的 IAM 策略条件。
要启用 Amazon Kinesis Data Streams for Amazon DynamoDB，您必须对该表具有以下权限：
+ `dynamodb:EnableKinesisStreamingDestination`
+ `kinesis:ListStreams`
+ `kinesis:PutRecords`
+ `kinesis:DescribeStream`
要为给定的 DynamoDB 表描述 Amazon Kinesis Data Streams for Amazon DynamoDB，您必须对该表具有以下权限。
+ `dynamodb:DescribeKinesisStreamingDestination`
+ `kinesis:DescribeStreamSummary`
+ `kinesis:DescribeStream`
要禁用 Amazon Kinesis Data Streams for Amazon DynamoDB，您必须对该表具有以下权限。
+ `dynamodb:DisableKinesisStreamingDestination`
要更新 Amazon Kinesis Data Streams for Amazon DynamoDB，您必须对该表具有以下权限。
+ `dynamodb:UpdateKinesisStreamingDestination`
以下示例说明如何使用 IAM 策略授予 Amazon Kinesis Data Streams for Amazon DynamoDB 权限。
## 示例：启用 Amazon Kinesis Data Streams for Amazon DynamoDB
以下 IAM 策略授予了为 `Music` 表启用 Amazon Kinesis Data Streams for Amazon DynamoDB 的权限。它不授予为 `Music` 表禁用、更新或描述 Kinesis Data Streams for DynamoDB 的权限。
------
#### [ 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"
}
]
}
```
------
## 示例：更新 Amazon Kinesis Data Streams for Amazon DynamoDB
以下 IAM 策略授予了为 `Music` 表更新 Amazon Kinesis Data Streams for Amazon DynamoDB 的权限。它不授予为 `Music` 表启用、禁用或描述 Amazon Kinesis Data Streams for Amazon DynamoDB 的权限。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:UpdateKinesisStreamingDestination"
],
"Resource": "arn:aws:dynamodb:us-west-2:111122223333:table/Music"
}
]
}
```
------
## 示例：禁用 Amazon Kinesis Data Streams for Amazon DynamoDB
以下 IAM 策略授予了为 `Music` 表禁用 Amazon Kinesis Data Streams for Amazon DynamoDB 的权限。它不授予为 `Music` 表启用、更新或描述 Amazon Kinesis Data Streams for Amazon DynamoDB 的权限。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dynamodb:DisableKinesisStreamingDestination"
],
"Resource": "arn:aws:dynamodb:us-west-2:111122223333:table/Music"
}
]
}
```
------
## 示例：根据资源有选择地应用 Amazon Kinesis Data Streams for Amazon DynamoDB 权限
下面的 IAM 策略授予了为 `Music` 表启用和描述 Amazon Kinesis Data Streams for Amazon DynamoDB 的权限，并且拒绝为 `Orders` 表禁用 Amazon Kinesis Data Streams for Amazon DynamoDB 的权限。
------
#### [ 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"
}
]
}
```
------
## 使用 Kinesis Data Streams for DynamoDB 的服务相关角色
Amazon Kinesis Data Streams for Amazon DynamoDB 使用 AWS Identity and Access Management (IAM) [服务相关角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-service-linked-role)。服务相关角色是一种与 Kinesis Data Streams for DynamoDB 直接关联的独特类型的 IAM 角色。服务相关角色由 Kinesis Data Streams for DynamoDB 预定义，具有服务代表您调用其他 AWS 服务所需的所有权限。
服务相关角色可让您更轻松地设置 Kinesis Data Streams for DynamoDB，因为您不必手动添加必要的权限。Kinesis Data Streams for DynamoDB 定义其服务相关角色的权限，除非另外定义，否则只有 Kinesis Data Streams for DynamoDB 可以代入该角色。定义的权限包括信任策略和权限策略，而且权限策略不能附加到任何其他 IAM 实体。
有关支持服务相关角色的其它服务的信息，请参阅[使用 IAM 的 AWS 服务](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html)并查找**服务相关角色**列中显示为**是**的服务。选择**是**和链接，查看该服务的服务关联角色文档。
### Kinesis Data Streams for DynamoDB 的服务相关角色权限
Kinesis Data Streams for DynamoDB 使用名为 **AWSServiceRoleForDynamoDBKinesisDataStreamsReplication** 的服务相关角色。服务相关角色的目的是允许 Amazon DynamoDB 代表您管理项目级 Kinesis Data Streams 改动的复制。
`AWSServiceRoleForDynamoDBKinesisDataStreamsReplication` 服务相关角色信任以下服务代入该角色：
+ `kinesisreplication.dynamodb.amazonaws.com`
角色权限策略允许 Kinesis Data Streams for DynamoDB 对指定资源完成以下操作：
+ 操作：`Kinesis stream` 上的 `Put records and describe`
+ 操作：`AWS KMS` 上的 `Generate data keys`，以将数据放到使用用户生成的 AWS KMS 密钥加密的 Kinesis 数据流中。
有关该策略文档的确切内容，请参阅 [DynamoDBKinesisReplicationServiceRolePolicy](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/aws-service-role/DynamoDBKinesisReplicationServiceRolePolicy)。
您必须配置权限，允许 IAM 实体（如用户、组或角色）创建、编辑或删除服务关联角色。有关更多信息，请参阅《IAM 用户指南》**中的[服务关联角色权限](https://docs.aws.amazon.com/IAM/latest/UserGuide/contributorinsights-service-linked-roles.html#service-linked-role-permissions)。
### 创建 Kinesis Data Streams for DynamoDB 的服务相关角色
您无需手动创建服务关联角色。在 AWS 管理控制台、AWS CLI 或 AWS API 中启用 Kinesis Data Streams for DynamoDB 后，Kinesis Data Streams for DynamoDB 将为您创建服务相关角色。
如果您删除该服务关联角色，然后需要再次创建，您可以使用相同流程在账户中重新创建此角色。启用 Kinesis Data Streams for DynamoDB 后，Kinesis Data Streams for DynamoDB 将再次为您创建与服务相关的角色。
### 编辑 Kinesis Data Streams for DynamoDB 的服务相关角色
Kinesis Data Streams for DynamoDB 不允许您编辑 `AWSServiceRoleForDynamoDBKinesisDataStreamsReplication` 服务相关角色。创建服务关联角色后，您将无法更改角色的名称，因为可能有多种实体引用该角色。但是可以使用 IAM 编辑角色描述。有关更多信息，请参见 *IAM 用户指南*中的[编辑服务相关角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/contributorinsights-service-linked-roles.html#edit-service-linked-role)。
### 删除 Kinesis Data Streams for DynamoDB 的服务相关角色
还可以使用 IAM 控制台、AWS CLI 或 AWS API 手动删除服务相关角色。为此，必须先手动清除服务相关角色的资源，然后才能手动删除。
**注意**
如果在您试图删除资源时 Kinesis Data Streams for DynamoDB 服务正在使用该角色，则删除操作可能会失败。如果发生这种情况，请等待几分钟后重试。
**使用 IAM 手动删除服务关联角色**
使用 IAM 控制台，即 AWS CLI 或 AWS API 来删除 `AWSServiceRoleForDynamoDBKinesisDataStreamsReplication` 服务相关角色。有关更多信息，请参见 *IAM 用户指南*中的[删除服务相关角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html)。
# 将更改数据捕获用于 DynamoDB Streams
DynamoDB Streams 可在任何 DynamoDB 表中捕获按时间排序的项目级修改序列，并将这类信息存储在日志中长达 24 个小时。应用程序可访问此日志，并在数据项目修改前后近乎实时地查看所显示的数据项目。
静态加密会加密 DynamoDB 流中的数据。有关更多信息，请参阅 [静态 DynamoDB 加密](EncryptionAtRest.md)。
*DynamoDB 流*是一种有关 DynamoDB 表中的项目更改的有序信息流。当您对表启用流时，DynamoDB 将捕获有关对表中的数据项目进行的每项修改的信息。
每当应用程序在表中创建、更新或删除项目时，DynamoDB Streams 都将编写一条具有已修改项目的主键属性的流记录。*流记录*包含有关对 DynamoDB 表中的单个项目所做的数据修改的信息。您可以配置流，以便流记录捕获其他信息，例如已修改项目的“前”和“后”图像。
DynamoDB Streams 可以帮助确保：
+ 每个流记录仅在流中显示一次。
+ 对于 DynamoDB 表中修改的每个项目，流记录将按照对该项目进行的实际修改的顺序显示。
DynamoDB Streams 近乎实时编写流记录，以便您能构建使用这些流并根据内容采取操作的应用程序。
**Topics**
+ [DynamoDB Streams 的端点](#Streams.Endpoints)
+ [启用流](#Streams.Enabling)
+ [读取和处理流](#Streams.Processing)
+ [DynamoDB Streams 和生存时间](time-to-live-ttl-streams.md)
+ [使用 DynamoDB Streams Kinesis Adapter 处理流记录](Streams.KCLAdapter.md)
+ [DynamoDB Streams 低级 API：Java 示例](Streams.LowLevel.Walkthrough.md)
+ [DynamoDB Streams 和 AWS Lambda 触发器](Streams.Lambda.md)
+ [DynamoDB Streams 和 Apache Flink](StreamsApacheFlink.xml.md)
## DynamoDB Streams 的端点
AWS 为 DynamoDB 和 DynamoDB Streams 维护单独的端点。要使用数据库表和索引，您的应用程序必须访问 DynamoDB 端点。要读取和处理 DynamoDB Streams 记录，您的应用程序必须访问相同区域内的 DynamoDB Streams 端点。
DynamoDB Streams 提供两组端点。它们是：
+ **仅 IPv4 的端点**：使用 `streams.dynamodb..amazonaws.com` 命名约定的端点。
+ **双栈端点**：兼容 IPv4 和 IPv6 并遵循 `streams-dynamodb..api.aws` 命名约定的新端点。
**注意**
有关 DynamoDB 和 DynamoDB Streams 区域和端点的完整列表，请参阅《AWS 一般参考》**中的[区域和端点](https://docs.aws.amazon.com/general/latest/gr/rande.html)。
AWS SDK 为 DynamoDB 和 DynamoDB Streams 提供单独的客户端。根据您的要求，您的应用程序可以访问 DynamoDB 端点，DynamoDB Streams 端点或同时访问二者。要连接到两个端点，您的应用程序必须实例化两个客户端 — 一个用于 DynamoDB，另一个用于 DynamoDB Streams。
## 启用流
使用 AWS CLI 或某个 AWS SDK 创建新表时，可以在新表上启用流。还可以对现有表启用或禁用流，或更改流设置。DynamoDB Streams 可异步执行操作，因此在启用流的情况下不会影响表的性能。
管理 DynamoDB Streams 最简单的方法是使用 AWS 管理控制台。
1. 登录 AWS 管理控制台，并打开 DynamoDB 控制台：[https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/)。
1. 在 DynamoDB 控制台控制面板上，选择**表**，然后选择现有表。
1. 选择**导出和流式传输**选项卡。
1. 在 **DynamoDB 流详细信息**部分，选择**开启**。
1. 在**开启 DynamoDB 流**页面中，选择在修改表中的数据时将写入流中的信息：
+ **仅键** — 仅所修改项目的键属性。
+ **新映像** — 修改后的整个项目。
+ **旧映像** — 修改前的整个项目。
+ **新旧映像** — 项目的新旧映像。
根据需要进行设置后，选择**开启流**。
1. （可选）要禁用现有流，请选择 **DynamoDB 流详细信息**下的**关闭**。
您还可以使用 `CreateTable` 或 `UpdateTable` API 操作来启用或修改流。`StreamSpecification` 参数确定如何配置流：
+ `StreamEnabled` — 指定对表启用 (`true`) 或禁用 (`false`) 流。
+ `StreamViewType` — 指定在修改表中的数据时将写入流中的信息：
+ `KEYS_ONLY` — 仅所修改项目的键属性。
+ `NEW_IMAGE` — 整个项目在修改后的显示。
+ `OLD_IMAGE` — 整个项目在修改前的显示。
+ `NEW_AND_OLD_IMAGES` — 项目的新旧映像。
您可以随时启用或禁用流。但是，如果您尝试在已有流的表上启用流，则会收到 `ValidationException`。如果您尝试在没有流的表上禁用流，也会收到 `ValidationException`。
当您将 `StreamEnabled` 设置为 `true` 时，DynamoDB 将创建一个新流，并为其分配一个唯一的流描述符。如果您在表上禁用然后重新启用流，则将创建一个具有不同流描述符的新流。
每个流均由一个 Amazon 资源名称（ARN）进行唯一标识。以下是名为 `TestTable` 的 DynamoDB 表中一个流的示例 ARN。
```
arn:aws:dynamodb:us-west-2:111122223333:table/TestTable/stream/2015-05-11T21:21:33.291
```
要确定表的最新流描述符，请发出一个 DynamoDB `DescribeTable` 请求并在响应中查找 `LatestStreamArn` 元素。
**注意**
一旦设置了流，就无法编辑 `StreamViewType`。如果您需要在设置流后对其进行更改，则必须禁用当前流并创建一个新的流。
## 读取和处理流
要读取和处理流，您的应用程序必须连接到 DynamoDB Streams 端点并发出 API 请求。
流由*流记录* 构成。每条流记录均代表流所在的 DynamoDB 表中的一个数据修改。每条流记录均分配有一个序列号，该序列号反映了将记录发布至流的顺序。
流记录将组织到群组或*分区* 中。每个分区可充当多条流记录的容器，并包含访问和迭代这些记录所需的信息。分区中的流记录将在 24 小时后自动删除。
分区是临时的：将根据需要自动创建和删除它们。此外，任何分区均可拆分为多个新分区；这也是自动进行的。（请注意，父分片还可能只有一个子分片。） 分区可能会在响应其父表上的高级写入活动时拆分，以便应用程序可以并行处理来自多个分区的记录。
如果您禁用流，将关闭已打开的分区。流中的数据在 24 小时内可继续读取。
由于分区存在沿袭 (父分区和子分区)，应用程序必须始终先处理父分区，然后再处理子分区。这可帮助确保流记录也会按正确顺序进行处理。（如果您使用 DynamoDB Streams Kinesis Adapter，则会为您进行处理。您的应用程序按正确顺序处理分片和流记录。它自动处理新分片或过期分片，以及在应用程序运行期间拆分的分片。有关更多信息，请参阅[使用 DynamoDB Streams Kinesis Adapter 处理流记录](Streams.KCLAdapter.md)。）
下图显示流、流中的分区和分区中的流记录之间的关系。
![\[DynamoDB Streams 结构。表示数据修改的流记录以分片的形式加以组织。\]](http://docs.aws.amazon.com/zh_cn/amazondynamodb/latest/developerguide/images/streams-terminology.png)
**注意**
如果您执行的 `PutItem` 或 `UpdateItem` 操作不更改项目中的任何数据，则 DynamoDB Streams *不会*为该操作编写流记录。
要访问流和处理其中的流记录，您必须执行以下操作：
+ 确定您要访问的流的唯一 ARN。
+ 确定流中的哪些分片包含您感兴趣的流记录。
+ 访问分片并检索所需的流记录。
**注意**
从同一流的分片中同时读取的进程最多不得超过 2 个。读取器超过 2 个的分片可能会受到限制。
DynamoDB Streams API 提供以下操作以供应用程序使用：
+ `[ListStreams](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_streams_ListStreams.html)` — 返回当前账户和端点的流描述符列表。(可选) 您可以只请求特定表名称的流描述符。
+ `[DescribeStream](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_streams_DescribeStream.html)`：返回有关流的信息，包括流的当前状态、其 Amazon 资源名称（ARN）、其分片的构成及其相应的 DynamoDB 表。您可以选择使用 `ShardFilter` 字段来检索与父分片关联的现有子分片。
+ `[GetShardIterator](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_streams_GetShardIterator.html)` — 返回一个描述分片中位置的*分片迭代器*。您可以请求该迭代器提供对流中最旧的点、最新的点或某个特定点的访问权。
+ `[GetRecords](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_streams_GetRecords.html)` — 返回来自给定分片中的流记录。您必须提供从 `GetShardIterator` 请求中返回的分区迭代器。
有关这些 API 操作的完整描述（包括示例请求和响应），请参阅[Amazon DynamoDB Streams API 参考](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Operations_Amazon_DynamoDB_Streams.html)。
### 分片发现
使用两种强有力的方法在您的 DynamoDB 流中发现新的分片。作为 Amazon DynamoDB Streams 用户，您可以通过两种有效的方法来跟踪和识别新的分片：
**轮询整个流拓扑**
使用 `DescribeStream` API 定期对流进行轮询。这将返回流中的所有分片，包括已创建的任何新分片。通过比较一段时间内的结果，您可以检测到新添加的分片。
**发现子分片**
使用 `DescribeStream` API 及 `ShardFilter` 参数来查找分片的子集。通过在请求中指定父分片，DynamoDB Streams 将返回其直接子分片。当只需跟踪分片沿袭而不需要扫描整个流时，这种方法很有用。
使用来自 DynamoDB Streams 的数据的应用程序可以使用此 `ShardFilter` 参数，高效地从读取已关闭的分片过渡到其子分片，从而避免重复调用 `DescribeStream` API 来检索和遍历所有已关闭和打开的分片的分片映射。这有助于在父分片关闭后快速发现子分片，从而提高流处理应用程序的响应速度和成本效益。
这两种方法都能让您随时掌握 DynamoDB Streams 不断演变的结构，确保您不会错过任何关键的数据更新或分片修改。
### DynamoDB Streams 的数据留存限制
DynamoDB Streams 中所有数据的生命周期为 24 小时。您可以检索和分析任意给定表过去 24 小时的活动。但是，24 小时之前的数据可能会随时被修剪（删除）。
如果您对某个表禁用一个流，该流中的数据仍在 24 小时内可读。此时间过后，数据将过期，并且流记录将自动被删除。没有手动删除现有流的机制。您必须等待直至保留期限过期（24 小时），然后将删除所有流记录。
# DynamoDB Streams 和生存时间
您可以通过在表中启用 Amazon DynamoDB Streams 并处理已过期项目的流记录来备份或者处理按[生存时间](TTL.md)（TTL）删除的项目。有关更多信息，请参阅 [读取和处理流](Streams.md#Streams.Processing)。
流记录包含用户身份字段`Records[].userIdentity`。
在过期后被生存时间过程删除的项目包含以下字段：
+ `Records[].userIdentity.type`
`"Service"`
+ `Records[