本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 認識 DynamoDB 暖輸送量
*暖輸送量*指 DynamoDB 資料表可即時支援的讀取與寫入操作次數。根據預設，這些值適用於所有資料表與全域次要索引 (GSI)，並反映其根據歷史用量調整的擴展程度。若您使用隨需模式，或將佈建輸送量更新為這些值，應用程式即可即時處理達該值上限的請求。
當用量增加時，DynamoDB 會自動調整暖輸送量值。您也可以在需要時主動增加這些值，這對於即將推出的尖峰事件特別有用，例如產品推出或銷售。對於預先規劃的尖峰活動，若 DynamoDB 資料表的請求率可能提升 10 倍、100 倍或更高，您可評估當前暖輸送量是否足以應付預期流量。若不足，您可提升暖輸送量值，而不需變更輸送量設定或[計費模式](capacity-mode.md)。此程序稱為*預熱*資料表，讓您可設定資料表可即時支援的基準值。這可確保應用程式能自請求高峰發生之時起即處理更高的請求率。一旦增加，就無法減少暖輸送量值。
您可提升讀取、寫入或兩者的暖輸送量值。此值可套用於新建或現有的單一區域資料表、全域資料表與 GSIs。對全域資料表而言，此功能適用於 [2019.11.21 版 (目前)](GlobalTables.md)，您設定的暖輸送量將自動套用至全域資料表的所有複本資料表。您可隨時預熱任意數量的 DynamoDB 資料表。完成預熱所需時間取決於設定的值與資料表或索引的大小。您可同時提交多個預熱請求，且不會干擾任何資料表操作。您可將資料表預熱至該區域帳戶的資料表或索引配額上限。使用 [Service Quotas 主控台](https://console.aws.amazon.com/servicequotas)檢查目前的限制，並視需要提高配額。
根據預設，所有資料表與次要索引皆可免費使用暖輸送量值。然而，若您主動提升預設暖輸送量值以預熱資料表，將需支付相關請求的費用。如需詳細資訊，請參閱 [Amazon DynamoDB](https://aws.amazon.com/dynamodb/pricing/) 定價。
如需暖輸送量的詳細資訊，請參閱以下主題。
**Topics**
+ [檢查 DynamoDB 資料表的目前暖輸送量](check-warm-throughput.md)
+ [提高現有 DynamoDB 資料表的暖輸送量](update-warm-throughput.md)
+ [建立暖輸送量較高的新 DynamoDB 資料表](create-table-warm-throughput.md)
+ [了解不同情境下的 DynamoDB 暖輸送量](warm-throughput-scenarios.md)
# 檢查 DynamoDB 資料表的目前暖輸送量
使用下列 AWS CLI 和 AWS 主控台指示來檢查資料表或索引目前的暖輸送量值。
## AWS 管理主控台
若要透過 DynamoDB 主控台檢查 DynamoDB 資料表的暖輸送量：
1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/) 開啟 DynamoDB 主控台。
1. 在左側導覽窗格中，選擇 Tables (資料表)。
1. 在**資料表**頁面上，選取目標資料表。
1. 選取**其他設定**以檢視目前的暖輸送量值。此值顯示為每秒讀取單位與每秒寫入單位。
## AWS CLI
下列 AWS CLI 範例示範如何檢查 DynamoDB 資料表的暖輸送量。
1. 在 DynamoDB 資料表上執行 `describe-table` 操作。
```
aws dynamodb describe-table --table-name GameScores
```
1. 系統會傳回類似下列的回應。`WarmThroughput` 設定會顯示為 `ReadUnitsPerSecond` 和 `WriteUnitsPerSecond`。當暖輸送量值正在更新時，`Status` 會顯示為 `UPDATING`；當設定完成後，則顯示為 `ACTIVE`。
```
{
"Table": {
"AttributeDefinitions": [
{
"AttributeName": "GameTitle",
"AttributeType": "S"
},
{
"AttributeName": "TopScore",
"AttributeType": "N"
},
{
"AttributeName": "UserId",
"AttributeType": "S"
}
],
"TableName": "GameScores",
"KeySchema": [
{
"AttributeName": "UserId",
"KeyType": "HASH"
},
{
"AttributeName": "GameTitle",
"KeyType": "RANGE"
}
],
"TableStatus": "ACTIVE",
"CreationDateTime": 1726128388.729,
"ProvisionedThroughput": {
"NumberOfDecreasesToday": 0,
"ReadCapacityUnits": 0,
"WriteCapacityUnits": 0
},
"TableSizeBytes": 0,
"ItemCount": 0,
"TableArn": "arn:aws:dynamodb:us-east-1:XXXXXXXXXXXX:table/GameScores",
"TableId": "XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"BillingModeSummary": {
"BillingMode": "PAY_PER_REQUEST",
"LastUpdateToPayPerRequestDateTime": 1726128388.729
},
"GlobalSecondaryIndexes": [
{
"IndexName": "GameTitleIndex",
"KeySchema": [
{
"AttributeName": "GameTitle",
"KeyType": "HASH"
},
{
"AttributeName": "TopScore",
"KeyType": "RANGE"
}
],
"Projection": {
"ProjectionType": "INCLUDE",
"NonKeyAttributes": [
"UserId"
]
},
"IndexStatus": "ACTIVE",
"ProvisionedThroughput": {
"NumberOfDecreasesToday": 0,
"ReadCapacityUnits": 0,
"WriteCapacityUnits": 0
},
"IndexSizeBytes": 0,
"ItemCount": 0,
"IndexArn": "arn:aws:dynamodb:us-east-1:XXXXXXXXXXXX:table/GameScores/index/GameTitleIndex",
"WarmThroughput": {
"ReadUnitsPerSecond": 12000,
"WriteUnitsPerSecond": 4000,
"Status": "ACTIVE"
}
}
],
"DeletionProtectionEnabled": false,
"WarmThroughput": {
"ReadUnitsPerSecond": 12000,
"WriteUnitsPerSecond": 4000,
"Status": "ACTIVE"
}
}
}
```
# 提高現有 DynamoDB 資料表的暖輸送量
檢查完 DynamoDB 資料表目前的暖輸送量值後，請依下列步驟進行更新：
## AWS 管理主控台
若要透過 DynamoDB 主控台檢查 DynamoDB 資料表的暖輸送量值：
1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/) 開啟 DynamoDB 主控台。
1. 在左側導覽窗格中，選擇 Tables (資料表)。
1. 在**資料表**頁面上，選取目標資料表。
1. 在**暖輸送量**欄位中，選取**編輯**。
1. 在**編輯暖輸送量**頁面上，選擇**提高暖輸送量**。
1. 調整**每秒讀取單位**與**每秒寫入單位**。這兩個設定決定資料表可立即處理的輸送量上限。
1. 選取**儲存**。
1. 當請求處理完成後，**暖輸送量**欄位會更新**每秒讀取單位**和**每秒寫入單位**的最新值。
**注意**
更新暖輸送量值為非同步作業。當更新完成時，`Status` 會從 `UPDATING` 變更為 `ACTIVE`。
## AWS CLI
下列 AWS CLI 範例示範如何更新 DynamoDB 資料表的暖輸送量值。
1. 在 DynamoDB 資料表上執行 `update-table` 操作。
```
aws dynamodb update-table \
--table-name GameScores \
--warm-throughput ReadUnitsPerSecond=12345,WriteUnitsPerSecond=4567 \
--global-secondary-index-updates \
"[
{
\"Update\": {
\"IndexName\": \"GameTitleIndex\",
\"WarmThroughput\": {
\"ReadUnitsPerSecond\": 88,
\"WriteUnitsPerSecond\": 77
}
}
}
]" \
--region us-east-1
```
1. 系統會傳回類似下列的回應。`WarmThroughput` 設定會顯示為 `ReadUnitsPerSecond` 和 `WriteUnitsPerSecond`。當暖輸送量值正在更新時，`Status` 會顯示為 `UPDATING`；當設定完成後，則顯示為 `ACTIVE`。
```
{
"TableDescription": {
"AttributeDefinitions": [
{
"AttributeName": "GameTitle",
"AttributeType": "S"
},
{
"AttributeName": "TopScore",
"AttributeType": "N"
},
{
"AttributeName": "UserId",
"AttributeType": "S"
}
],
"TableName": "GameScores",
"KeySchema": [
{
"AttributeName": "UserId",
"KeyType": "HASH"
},
{
"AttributeName": "GameTitle",
"KeyType": "RANGE"
}
],
"TableStatus": "ACTIVE",
"CreationDateTime": 1730242189.965,
"ProvisionedThroughput": {
"NumberOfDecreasesToday": 0,
"ReadCapacityUnits": 20,
"WriteCapacityUnits": 10
},
"TableSizeBytes": 0,
"ItemCount": 0,
"TableArn": "arn:aws:dynamodb:us-east-1:XXXXXXXXXXXX:table/GameScores",
"TableId": "XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"GlobalSecondaryIndexes": [
{
"IndexName": "GameTitleIndex",
"KeySchema": [
{
"AttributeName": "GameTitle",
"KeyType": "HASH"
},
{
"AttributeName": "TopScore",
"KeyType": "RANGE"
}
],
"Projection": {
"ProjectionType": "INCLUDE",
"NonKeyAttributes": [
"UserId"
]
},
"IndexStatus": "ACTIVE",
"ProvisionedThroughput": {
"NumberOfDecreasesToday": 0,
"ReadCapacityUnits": 50,
"WriteCapacityUnits": 25
},
"IndexSizeBytes": 0,
"ItemCount": 0,
"IndexArn": "arn:aws:dynamodb:us-east-1:XXXXXXXXXXXX:table/GameScores/index/GameTitleIndex",
"WarmThroughput": {
"ReadUnitsPerSecond": 50,
"WriteUnitsPerSecond": 25,
"Status": "UPDATING"
}
}
],
"DeletionProtectionEnabled": false,
"WarmThroughput": {
"ReadUnitsPerSecond": 12300,
"WriteUnitsPerSecond": 4500,
"Status": "UPDATING"
}
}
}
```
## AWS 開發套件
下列 SDK 範例示範如何更新 DynamoDB 資料表的暖輸送量設定。
------
#### [ Java ]
```
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.DynamoDbException;
import software.amazon.awssdk.services.dynamodb.model.GlobalSecondaryIndexUpdate;
import software.amazon.awssdk.services.dynamodb.model.UpdateGlobalSecondaryIndexAction;
import software.amazon.awssdk.services.dynamodb.model.UpdateTableRequest;
import software.amazon.awssdk.services.dynamodb.model.WarmThroughput;
...
public static WarmThroughput buildWarmThroughput(final Long readUnitsPerSecond,
final Long writeUnitsPerSecond) {
return WarmThroughput.builder()
.readUnitsPerSecond(readUnitsPerSecond)
.writeUnitsPerSecond(writeUnitsPerSecond)
.build();
}
public static void updateDynamoDBTable(DynamoDbClient ddb,
String tableName,
Long tableReadUnitsPerSecond,
Long tableWriteUnitsPerSecond,
String globalSecondaryIndexName,
Long globalSecondaryIndexReadUnitsPerSecond,
Long globalSecondaryIndexWriteUnitsPerSecond) {
final WarmThroughput tableWarmThroughput = buildWarmThroughput(tableReadUnitsPerSecond, tableWriteUnitsPerSecond);
final WarmThroughput gsiWarmThroughput = buildWarmThroughput(globalSecondaryIndexReadUnitsPerSecond, globalSecondaryIndexWriteUnitsPerSecond);
final GlobalSecondaryIndexUpdate globalSecondaryIndexUpdate = GlobalSecondaryIndexUpdate.builder()
.update(UpdateGlobalSecondaryIndexAction.builder()
.indexName(globalSecondaryIndexName)
.warmThroughput(gsiWarmThroughput)
.build()
).build();
final UpdateTableRequest request = UpdateTableRequest.builder()
.tableName(tableName)
.globalSecondaryIndexUpdates(globalSecondaryIndexUpdate)
.warmThroughput(tableWarmThroughput)
.build();
try {
ddb.updateTable(request);
} catch (DynamoDbException e) {
System.err.println(e.getMessage());
System.exit(1);
}
System.out.println("Done!");
}
```
------
#### [ Python ]
```
from boto3 import resource
from botocore.exceptions import ClientError
def update_dynamodb_table_warm_throughput(table_name, table_read_units, table_write_units, gsi_name, gsi_read_units, gsi_write_units, region_name="us-east-1"):
"""
Updates the warm throughput of a DynamoDB table and a global secondary index.
:param table_name: The name of the table to update.
:param table_read_units: The new read units per second for the table's warm throughput.
:param table_write_units: The new write units per second for the table's warm throughput.
:param gsi_name: The name of the global secondary index to update.
:param gsi_read_units: The new read units per second for the GSI's warm throughput.
:param gsi_write_units: The new write units per second for the GSI's warm throughput.
:param region_name: The AWS Region name to target. defaults to us-east-1
"""
try:
ddb = resource('dynamodb', region_name)
# Update the table's warm throughput
table_warm_throughput = {
"ReadUnitsPerSecond": table_read_units,
"WriteUnitsPerSecond": table_write_units
}
# Update the global secondary index's warm throughput
gsi_warm_throughput = {
"ReadUnitsPerSecond": gsi_read_units,
"WriteUnitsPerSecond": gsi_write_units
}
# Construct the global secondary index update
global_secondary_index_update = [
{
"Update": {
"IndexName": gsi_name,
"WarmThroughput": gsi_warm_throughput
}
}
]
# Construct the update table request
update_table_request = {
"TableName": table_name,
"GlobalSecondaryIndexUpdates": global_secondary_index_update,
"WarmThroughput": table_warm_throughput
}
# Update the table
ddb.update_table(**update_table_request)
print("Table updated successfully!")
except ClientError as e:
print(f"Error updating table: {e}")
raise e
```
------
#### [ Javascript ]
```
import { DynamoDBClient, UpdateTableCommand } from "@aws-sdk/client-dynamodb";
async function updateDynamoDBTableWarmThroughput(
tableName,
tableReadUnits,
tableWriteUnits,
gsiName,
gsiReadUnits,
gsiWriteUnits,
region = "us-east-1"
) {
try {
const ddbClient = new DynamoDBClient({ region: region });
// Construct the update table request
const updateTableRequest = {
TableName: tableName,
GlobalSecondaryIndexUpdates: [
{
Update: {
IndexName: gsiName,
WarmThroughput: {
ReadUnitsPerSecond: gsiReadUnits,
WriteUnitsPerSecond: gsiWriteUnits,
},
},
},
],
WarmThroughput: {
ReadUnitsPerSecond: tableReadUnits,
WriteUnitsPerSecond: tableWriteUnits,
},
};
const command = new UpdateTableCommand(updateTableRequest);
const response = await ddbClient.send(command);
console.log(`Table updated successfully! Response: ${response}`);
} catch (error) {
console.error(`Error updating table: ${error}`);
throw error;
}
}
```
------
# 建立暖輸送量較高的新 DynamoDB 資料表
建立 DynamoDB 資料表時，可依下列步驟調整暖輸送量設定。這些步驟同樣適用於建立[全域資料表](GlobalTables.md)或[次要索引](SecondaryIndexes.md)。
## AWS 管理主控台
若要透過主控台建立 DynamoDB 資料表並設定暖輸送量：
1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/) 開啟 DynamoDB 主控台。
1. 選取**建立資料表**。
1. 選取**資料表名稱**、**分割區索引鍵**和**排序索引鍵 (選用)**。
1. 在**資料表設定**中，選取**自訂設定**。
1. 在**暖輸送量**欄位中，選取**增加暖輸送量**。
1. 調整**每秒讀取單位**與**每秒寫入單位**。這兩個設定定義了資料表可即時處理的最大輸送量。
1. 完成其他資料表詳細設定後，選取**建立資料表**。
## AWS CLI
下列 AWS CLI 範例說明如何建立具有自訂暖輸送量值的 DynamoDB 資料表。
1. 執行 `create-table` 以建立下列 DynamoDB 資料表。
```
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=20,WriteCapacityUnits=10 \
--global-secondary-indexes \
"[
{
\"IndexName\": \"GameTitleIndex\",
\"KeySchema\": [{\"AttributeName\":\"GameTitle\",\"KeyType\":\"HASH\"},
{\"AttributeName\":\"TopScore\",\"KeyType\":\"RANGE\"}],
\"Projection\":{
\"ProjectionType\":\"INCLUDE\",
\"NonKeyAttributes\":[\"UserId\"]
},
\"ProvisionedThroughput\": {
\"ReadCapacityUnits\": 50,
\"WriteCapacityUnits\": 25
},\"WarmThroughput\": {
\"ReadUnitsPerSecond\": 1987,
\"WriteUnitsPerSecond\": 543
}
}
]" \
--warm-throughput ReadUnitsPerSecond=12345,WriteUnitsPerSecond=4567 \
--region us-east-1
```
1. 系統會傳回類似下列的回應。`WarmThroughput` 設定會顯示為 `ReadUnitsPerSecond` 和 `WriteUnitsPerSecond`。當暖輸送量值正在更新時，`Status` 會顯示為 `UPDATING`；當設定完成後，則顯示為 `ACTIVE`。
```
{
"TableDescription": {
"AttributeDefinitions": [
{
"AttributeName": "GameTitle",
"AttributeType": "S"
},
{
"AttributeName": "TopScore",
"AttributeType": "N"
},
{
"AttributeName": "UserId",
"AttributeType": "S"
}
],
"TableName": "GameScores",
"KeySchema": [
{
"AttributeName": "UserId",
"KeyType": "HASH"
},
{
"AttributeName": "GameTitle",
"KeyType": "RANGE"
}
],
"TableStatus": "CREATING",
"CreationDateTime": 1730241788.779,
"ProvisionedThroughput": {
"NumberOfDecreasesToday": 0,
"ReadCapacityUnits": 20,
"WriteCapacityUnits": 10
},
"TableSizeBytes": 0,
"ItemCount": 0,
"TableArn": "arn:aws:dynamodb:us-east-1:XXXXXXXXXXXX:table/GameScores",
"TableId": "XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"GlobalSecondaryIndexes": [
{
"IndexName": "GameTitleIndex",
"KeySchema": [
{
"AttributeName": "GameTitle",
"KeyType": "HASH"
},
{
"AttributeName": "TopScore",
"KeyType": "RANGE"
}
],
"Projection": {
"ProjectionType": "INCLUDE",
"NonKeyAttributes": [
"UserId"
]
},
"IndexStatus": "CREATING",
"ProvisionedThroughput": {
"NumberOfDecreasesToday": 0,
"ReadCapacityUnits": 50,
"WriteCapacityUnits": 25
},
"IndexSizeBytes": 0,
"ItemCount": 0,
"IndexArn": "arn:aws:dynamodb:us-east-1:XXXXXXXXXXXX:table/GameScores/index/GameTitleIndex",
"WarmThroughput": {
"ReadUnitsPerSecond": 1987,
"WriteUnitsPerSecond": 543,
"Status": "UPDATING"
}
}
],
"DeletionProtectionEnabled": false,
"WarmThroughput": {
"ReadUnitsPerSecond": 12345,
"WriteUnitsPerSecond": 4567,
"Status": "UPDATING"
}
}
}
```
## AWS 開發套件
下列 SDK 範例示範如何建立具自訂暖輸送量設定的 DynamoDB 資料表。
------
#### [ Java ]
```
import software.amazon.awscdk.services.dynamodb.ProjectionType;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.CreateTableResponse;
import software.amazon.awssdk.services.dynamodb.model.CreateTableRequest;
import software.amazon.awssdk.services.dynamodb.model.KeySchemaElement;
import software.amazon.awssdk.services.dynamodb.model.KeyType;
import software.amazon.awssdk.services.dynamodb.model.ProvisionedThroughput;
import software.amazon.awssdk.services.dynamodb.model.Projection;
import software.amazon.awssdk.services.dynamodb.model.GlobalSecondaryIndex;
import software.amazon.awssdk.services.dynamodb.model.AttributeDefinition;
import software.amazon.awssdk.services.dynamodb.model.ScalarAttributeType;
import software.amazon.awssdk.services.dynamodb.model.WarmThroughput;
...
public static WarmThroughput buildWarmThroughput(final Long readUnitsPerSecond,
final Long writeUnitsPerSecond) {
return WarmThroughput.builder()
.readUnitsPerSecond(readUnitsPerSecond)
.writeUnitsPerSecond(writeUnitsPerSecond)
.build();
}
private static AttributeDefinition buildAttributeDefinition(final String attributeName,
final ScalarAttributeType scalarAttributeType) {
return AttributeDefinition.builder()
.attributeName(attributeName)
.attributeType(scalarAttributeType)
.build();
}
private static KeySchemaElement buildKeySchemaElement(final String attributeName,
final KeyType keyType) {
return KeySchemaElement.builder()
.attributeName(attributeName)
.keyType(keyType)
.build();
}
public static void createDynamoDBTable(DynamoDbClient ddb,
String tableName,
String partitionKey,
String sortKey,
String miscellaneousKeyAttribute,
String nonKeyAttribute,
Long tableReadCapacityUnits,
Long tableWriteCapacityUnits,
Long tableWarmReadUnitsPerSecond,
Long tableWarmWriteUnitsPerSecond,
String globalSecondaryIndexName,
Long globalSecondaryIndexReadCapacityUnits,
Long globalSecondaryIndexWriteCapacityUnits,
Long globalSecondaryIndexWarmReadUnitsPerSecond,
Long globalSecondaryIndexWarmWriteUnitsPerSecond) {
// Define the table attributes
final AttributeDefinition partitionKeyAttribute = buildAttributeDefinition(partitionKey, ScalarAttributeType.S);
final AttributeDefinition sortKeyAttribute = buildAttributeDefinition(sortKey, ScalarAttributeType.S);
final AttributeDefinition miscellaneousKeyAttributeDefinition = buildAttributeDefinition(miscellaneousKeyAttribute, ScalarAttributeType.N);
final AttributeDefinition[] attributeDefinitions = {partitionKeyAttribute, sortKeyAttribute, miscellaneousKeyAttributeDefinition};
// Define the table key schema
final KeySchemaElement partitionKeyElement = buildKeySchemaElement(partitionKey, KeyType.HASH);
final KeySchemaElement sortKeyElement = buildKeySchemaElement(sortKey, KeyType.RANGE);
final KeySchemaElement[] keySchema = {partitionKeyElement, sortKeyElement};
// Define the provisioned throughput for the table
final ProvisionedThroughput provisionedThroughput = ProvisionedThroughput.builder()
.readCapacityUnits(tableReadCapacityUnits)
.writeCapacityUnits(tableWriteCapacityUnits)
.build();
// Define the Global Secondary Index (GSI)
final KeySchemaElement globalSecondaryIndexPartitionKeyElement = buildKeySchemaElement(sortKey, KeyType.HASH);
final KeySchemaElement globalSecondaryIndexSortKeyElement = buildKeySchemaElement(miscellaneousKeyAttribute, KeyType.RANGE);
final KeySchemaElement[] gsiKeySchema = {globalSecondaryIndexPartitionKeyElement, globalSecondaryIndexSortKeyElement};
final Projection gsiProjection = Projection.builder()
.projectionType(String.valueOf(ProjectionType.INCLUDE))
.nonKeyAttributes(nonKeyAttribute)
.build();
final ProvisionedThroughput gsiProvisionedThroughput = ProvisionedThroughput.builder()
.readCapacityUnits(globalSecondaryIndexReadCapacityUnits)
.writeCapacityUnits(globalSecondaryIndexWriteCapacityUnits)
.build();
// Define the warm throughput for the Global Secondary Index (GSI)
final WarmThroughput gsiWarmThroughput = buildWarmThroughput(globalSecondaryIndexWarmReadUnitsPerSecond, globalSecondaryIndexWarmWriteUnitsPerSecond);
final GlobalSecondaryIndex globalSecondaryIndex = GlobalSecondaryIndex.builder()
.indexName(globalSecondaryIndexName)
.keySchema(gsiKeySchema)
.projection(gsiProjection)
.provisionedThroughput(gsiProvisionedThroughput)
.warmThroughput(gsiWarmThroughput)
.build();
// Define the warm throughput for the table
final WarmThroughput tableWarmThroughput = buildWarmThroughput(tableWarmReadUnitsPerSecond, tableWarmWriteUnitsPerSecond);
final CreateTableRequest request = CreateTableRequest.builder()
.tableName(tableName)
.attributeDefinitions(attributeDefinitions)
.keySchema(keySchema)
.provisionedThroughput(provisionedThroughput)
.globalSecondaryIndexes(globalSecondaryIndex)
.warmThroughput(tableWarmThroughput)
.build();
CreateTableResponse response = ddb.createTable(request);
System.out.println(response);
}
```
------
#### [ Python ]
```
from boto3 import resource
from botocore.exceptions import ClientError
def create_dynamodb_table_warm_throughput(table_name, partition_key, sort_key, misc_key_attr, non_key_attr, table_provisioned_read_units, table_provisioned_write_units, table_warm_reads, table_warm_writes, gsi_name, gsi_provisioned_read_units, gsi_provisioned_write_units, gsi_warm_reads, gsi_warm_writes, region_name="us-east-1"):
"""
Creates a DynamoDB table with a warm throughput setting configured.
:param table_name: The name of the table to be created.
:param partition_key: The partition key for the table being created.
:param sort_key: The sort key for the table being created.
:param misc_key_attr: A miscellaneous key attribute for the table being created.
:param non_key_attr: A non-key attribute for the table being created.
:param table_provisioned_read_units: The newly created table's provisioned read capacity units.
:param table_provisioned_write_units: The newly created table's provisioned write capacity units.
:param table_warm_reads: The read units per second setting for the table's warm throughput.
:param table_warm_writes: The write units per second setting for the table's warm throughput.
:param gsi_name: The name of the Global Secondary Index (GSI) to be created on the table.
:param gsi_provisioned_read_units: The configured Global Secondary Index (GSI) provisioned read capacity units.
:param gsi_provisioned_write_units: The configured Global Secondary Index (GSI) provisioned write capacity units.
:param gsi_warm_reads: The read units per second setting for the Global Secondary Index (GSI)'s warm throughput.
:param gsi_warm_writes: The write units per second setting for the Global Secondary Index (GSI)'s warm throughput.
:param region_name: The AWS Region name to target. defaults to us-east-1
"""
try:
ddb = resource('dynamodb', region_name)
# Define the table attributes
attribute_definitions = [
{ "AttributeName": partition_key, "AttributeType": "S" },
{ "AttributeName": sort_key, "AttributeType": "S" },
{ "AttributeName": misc_key_attr, "AttributeType": "N" }
]
# Define the table key schema
key_schema = [
{ "AttributeName": partition_key, "KeyType": "HASH" },
{ "AttributeName": sort_key, "KeyType": "RANGE" }
]
# Define the provisioned throughput for the table
provisioned_throughput = {
"ReadCapacityUnits": table_provisioned_read_units,
"WriteCapacityUnits": table_provisioned_write_units
}
# Define the global secondary index
gsi_key_schema = [
{ "AttributeName": sort_key, "KeyType": "HASH" },
{ "AttributeName": misc_key_attr, "KeyType": "RANGE" }
]
gsi_projection = {
"ProjectionType": "INCLUDE",
"NonKeyAttributes": [non_key_attr]
}
gsi_provisioned_throughput = {
"ReadCapacityUnits": gsi_provisioned_read_units,
"WriteCapacityUnits": gsi_provisioned_write_units
}
gsi_warm_throughput = {
"ReadUnitsPerSecond": gsi_warm_reads,
"WriteUnitsPerSecond": gsi_warm_writes
}
global_secondary_indexes = [
{
"IndexName": gsi_name,
"KeySchema": gsi_key_schema,
"Projection": gsi_projection,
"ProvisionedThroughput": gsi_provisioned_throughput,
"WarmThroughput": gsi_warm_throughput
}
]
# Define the warm throughput for the table
warm_throughput = {
"ReadUnitsPerSecond": table_warm_reads,
"WriteUnitsPerSecond": table_warm_writes
}
# Create the DynamoDB client and create the table
response = ddb.create_table(
TableName=table_name,
AttributeDefinitions=attribute_definitions,
KeySchema=key_schema,
ProvisionedThroughput=provisioned_throughput,
GlobalSecondaryIndexes=global_secondary_indexes,
WarmThroughput=warm_throughput
)
print(response)
except ClientError as e:
print(f"Error creating table: {e}")
raise e
```
------
#### [ Javascript ]
```
import { DynamoDBClient, CreateTableCommand } from "@aws-sdk/client-dynamodb";
async function createDynamoDBTableWithWarmThroughput(
tableName,
partitionKey,
sortKey,
miscKeyAttr,
nonKeyAttr,
tableProvisionedReadUnits,
tableProvisionedWriteUnits,
tableWarmReads,
tableWarmWrites,
indexName,
indexProvisionedReadUnits,
indexProvisionedWriteUnits,
indexWarmReads,
indexWarmWrites,
region = "us-east-1"
) {
try {
const ddbClient = new DynamoDBClient({ region: region });
const command = new CreateTableCommand({
TableName: tableName,
AttributeDefinitions: [
{ AttributeName: partitionKey, AttributeType: "S" },
{ AttributeName: sortKey, AttributeType: "S" },
{ AttributeName: miscKeyAttr, AttributeType: "N" },
],
KeySchema: [
{ AttributeName: partitionKey, KeyType: "HASH" },
{ AttributeName: sortKey, KeyType: "RANGE" },
],
ProvisionedThroughput: {
ReadCapacityUnits: tableProvisionedReadUnits,
WriteCapacityUnits: tableProvisionedWriteUnits,
},
WarmThroughput: {
ReadUnitsPerSecond: tableWarmReads,
WriteUnitsPerSecond: tableWarmWrites,
},
GlobalSecondaryIndexes: [
{
IndexName: indexName,
KeySchema: [
{ AttributeName: sortKey, KeyType: "HASH" },
{ AttributeName: miscKeyAttr, KeyType: "RANGE" },
],
Projection: {
ProjectionType: "INCLUDE",
NonKeyAttributes: [nonKeyAttr],
},
ProvisionedThroughput: {
ReadCapacityUnits: indexProvisionedReadUnits,
WriteCapacityUnits: indexProvisionedWriteUnits,
},
WarmThroughput: {
ReadUnitsPerSecond: indexWarmReads,
WriteUnitsPerSecond: indexWarmWrites,
},
},
],
});
const response = await ddbClient.send(command);
console.log(response);
} catch (error) {
console.error(`Error creating table: ${error}`);
throw error;
}
}
```
------
# 了解不同情境下的 DynamoDB 暖輸送量
以下列出在使用 DynamoDB 暖輸送量時可能遇到的多種情境。
**Topics**
+ [暖輸送量與非均勻存取模式](#warm-throughput-scenarios-uneven)
+ [佈建資料表的暖輸送量](#warm-throughput-scenarios-provisioned)
+ [隨需資料表的暖輸送量](#warm-throughput-scenarios-ondemand)
+ [已設定最大輸送量的隨需資料表暖輸送量](#warm-throughput-scenarios-max)
## 暖輸送量與非均勻存取模式
資料表的暖輸送量可能為每秒 30,000 個讀取單位與每秒 10,000 個寫入單位，但在達到此上限前，仍可能在讀取或寫入操作中遭遇限流。這通常是因為存在熱分割區造成。雖然 DynamoDB 可持續擴展以支援幾乎無限制的輸送量，但每個分割區的限制為每秒 1,000 個寫入單位及每秒 3,000 個讀取單位。若應用程式對資料表少部分分割區發送過多流量，即便尚未達到資料表的暖輸送量上限，也可能遭遇限流。建議遵循 [DynamoDB 最佳實務](bp-partition-key-design.md)，以確保系統具備無縫可擴展性並避免產生熱分割區。
## 佈建資料表的暖輸送量
假設某個佈建資料表的暖輸送量為每秒 30,000 個讀取單位與每秒 10,000 個寫入單位，但目前的佈建輸送量僅為 4,000 個 RCU 和 8,000 個 WCU。您可透過更新佈建輸送量設定，立即將資料表的佈建輸送量擴展至 30,000 個 RCU 或 10,000 個 WCU。當您將佈建輸送量提升至超過上述數值時，暖輸送量會自動調整為新的更高值，因為這代表系統已建立新的峰值輸送量。例如，若將佈建輸送量設定為 50,000 RCU，暖輸送量將隨之提升至每秒 50,000 個讀取單位。
```
"ProvisionedThroughput":
{
"ReadCapacityUnits": 4000,
"WriteCapacityUnits": 8000
}
"WarmThroughput":
{
"ReadUnitsPerSecond": 30000,
"WriteUnitsPerSecond": 10000
}
```
## 隨需資料表的暖輸送量
新建立的隨需資料表初始暖輸送量為每秒 12,000 個讀取單位與每秒 4,000 個寫入單位。資料表可立即支援持續流量，最高可達上述層級。當請求量超過每秒 12,000 個讀取單位或 4,000 個寫入單位時，暖輸送量會自動提升至更高等級。
```
"WarmThroughput":
{
"ReadUnitsPerSecond": 12000,
"WriteUnitsPerSecond": 4000
}
```
## 已設定最大輸送量的隨需資料表暖輸送量
假設某個隨需資料表的暖輸送量為每秒 30,000 個讀取單位，但[最大輸送量](on-demand-capacity-mode-max-throughput.md)設定為 5,000 個讀取請求單位 (RRU)。在此情境中，資料表的輸送量將受限於您設定的 5,000 個 RRU 上限。任何超出該上限的輸送量請求都會遭到限流。不過，您可依應用程式需求，隨時調整該資料表的專屬最大輸送量。
```
"OnDemandThroughput":
{
"MaxReadRequestUnits": 5000,
"MaxWriteRequestUnits": 4000
}
"WarmThroughput":
{
"ReadUnitsPerSecond": 30000,
"WriteUnitsPerSecond": 10000
}
```