# 在 DynamoDB 中使用生存时间（TTL）
DynamoDB 的生存时间（TTL）是一种经济实惠的方法，用于删除不再相关的项目。通过 TTL，您可以定义每个项目的过期时间戳，指示何时不再需要某个项目。DynamoDB 会在项目过期时间到期后的几天内自动将其删除，而不会消耗写入吞吐量。
要使用 TTL，请先在表上启用它，然后定义一个特定的属性来存储 TTL 过期时间戳。时间戳必须以[数字](HowItWorks.NamingRulesDataTypes.md#HowItWorks.DataTypes)数据类型存储，采用 [Unix 纪元时间格式](https://en.wikipedia.org/wiki/Unix_time)，精确到秒级粒度。如果项目具有非数字类型的 TTL 属性，TTL 流程会忽略该项目。每次创建或更新项目时，您都可以计算过期时间并将其保存在 TTL 属性中。
系统可以随时删除具有有效、已过期 TTL 属性的项目，通常是在过期后的几天内。您仍然可以更新待删除的过期项目，包括更改或删除其 TTL 属性。更新过期项目时，我们建议您使用条件表达式来确保该项目随后未被删除。使用筛选表达式从[扫描](Scan.md#Scan.FilterExpression)和[查询](Query.FilterExpression.md)结果中删除过期的项目。
已删除项目的工作原理与通过典型删除操作删除的项目类似。删除后，项目会以服务删除而不是用户删除的形式进入 DynamoDB Streams，并像其它删除操作一样从本地二级索引和全局二级索引中删除。
如果使用全局表的[全局表版本 2019.11.21（当前版）](GlobalTables.md)，并且还使用生存时间特征，则 DynamoDB 会将 TTL 删除复制到所有副本表。在出现 TTL 到期的区域中，初始 TTL 删除不会消耗写入容量单位（WCU）。但是，在每个副本区域中，当使用预置的容量时，复制到副本表的 TTL 删除将消耗一个复制的写入容量单位，或在使用按需容量模式时消耗一个复制的写入容量单位，并且将收取适用的费用。
有关 TTL 的更多信息，请参阅以下主题：
**Topics**
+ [在 DynamoDB 中启用生存时间（TTL）](time-to-live-ttl-how-to.md)
+ [在 DynamoDB 中计算生存时间（TTL）](time-to-live-ttl-before-you-start.md)
+ [使用过期项目和生存时间（TTL）](ttl-expired-items.md)
# 在 DynamoDB 中启用生存时间（TTL）
**注意**
为了协助调试 TTL 功能和验证该功能是否正常运行，为项目 TTL 提供的值将以纯文本形式记录在 DynamoDB 诊断日志中。
您可以在 Amazon DynamoDB 控制台中，在 AWS Command Line Interface（AWS CLI）中，或者对于任何支持的 AWS SDK 使用 [Amazon DynamoDB API 参考](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/)，来启用 TTL。在所有分区中启用 TTL 大约需要一个小时。
## 使用 AWS 控制台启用 DynamoDB TTL
1. 登录 AWS 管理控制台，打开 DynamoDB 控制台：[https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/)。
1. 选择**表**，然后选择您要修改的表。
1. 在**其它设置**选项卡的**生存时间(TTL)** 部分中，选择**开启**来启用 TTL。
1. 在表上启用 TTL 时，DynamoDB 要求您标识此服务在确定项目是否符合过期条件时将查找的特定属性名称。如下所示的 TTL 属性名称区分大小写，并且必须与读取和写入操作中定义的属性相匹配。不匹配将导致已过期的项目被取消删除。重命名 TTL 属性需要您禁用 TTL，然后使用新属性重新启用它。禁用后，TTL 将在大约 30 分钟内继续处理删除。必须对已恢复的表重新配置 TTL。
![\[区分大小写的 TTL 属性名称，DynamoDB 使用该属性来确定项目是否符合过期条件。\]](http://docs.aws.amazon.com/zh_cn/amazondynamodb/latest/developerguide/images/EnableTTL-Settings.png)
1. （可选）您可以通过模拟过期日期和时间并匹配几个项目来执行测试。这为您提供了项目的样本列表，并确认有些项目包含随过期时间提供的 TTL 属性名称。
TTL 启用后，当您在 DynamoDB 控制台上查看项目时，TTL 属性被标记为 **TTL**。您可以通过将指针悬停在属性上来查看项目过期的日期和时间。
## 使用 API 启用 DynamoDB TTL
------
#### [ Python ]
您可以使用 [UpdateTimeToLive](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb/client/update_time_to_live.html) 操作通过代码启用 TTL。
```
import boto3
def enable_ttl(table_name, ttl_attribute_name):
"""
Enables TTL on DynamoDB table for a given attribute name
on success, returns a status code of 200
on error, throws an exception
:param table_name: Name of the DynamoDB table
:param ttl_attribute_name: The name of the TTL attribute being provided to the table.
"""
try:
dynamodb = boto3.client('dynamodb')
# Enable TTL on an existing DynamoDB table
response = dynamodb.update_time_to_live(
TableName=table_name,
TimeToLiveSpecification={
'Enabled': True,
'AttributeName': ttl_attribute_name
}
)
# In the returned response, check for a successful status code.
if response['ResponseMetadata']['HTTPStatusCode'] == 200:
print("TTL has been enabled successfully.")
else:
print(f"Failed to enable TTL, status code {response['ResponseMetadata']['HTTPStatusCode']}")
except Exception as ex:
print("Couldn't enable TTL in table %s. Here's why: %s" % (table_name, ex))
raise
# your values
enable_ttl('your-table-name', 'expirationDate')
```
您可以使用 [DescribeTimeToLive](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb/client/describe_time_to_live.html) 操作确认 TTL 已启用，该操作描述了表上的 TTL 状态。`TimeToLive` 状态为 `ENABLED` 或 `DISABLED`。
```
# create a DynamoDB client
dynamodb = boto3.client('dynamodb')
# set the table name
table_name = 'YourTable'
# describe TTL
response = dynamodb.describe_time_to_live(TableName=table_name)
```
------
#### [ JavaScript ]
您可以使用 [UpdateTimeToLiveCommand](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-dynamodb/Class/UpdateTimeToLiveCommand/) 操作通过代码启用 TTL。
```
import { DynamoDBClient, UpdateTimeToLiveCommand } from "@aws-sdk/client-dynamodb";
const enableTTL = async (tableName, ttlAttribute) => {
const client = new DynamoDBClient({});
const params = {
TableName: tableName,
TimeToLiveSpecification: {
Enabled: true,
AttributeName: ttlAttribute
}
};
try {
const response = await client.send(new UpdateTimeToLiveCommand(params));
if (response.$metadata.httpStatusCode === 200) {
console.log(`TTL enabled successfully for table ${tableName}, using attribute name ${ttlAttribute}.`);
} else {
console.log(`Failed to enable TTL for table ${tableName}, response object: ${response}`);
}
return response;
} catch (e) {
console.error(`Error enabling TTL: ${e}`);
throw e;
}
};
// call with your own values
enableTTL('ExampleTable', 'exampleTtlAttribute');
```
------
## 使用 AWS CLI 启用生存时间
1. 在 `TTLExample` 表上启用 TTL。
```
aws dynamodb update-time-to-live --table-name TTLExample --time-to-live-specification "Enabled=true, AttributeName=ttl"
```
1. 在 `TTLExample` 表上描述 TTL。
```
aws dynamodb describe-time-to-live --table-name TTLExample
{
"TimeToLiveDescription": {
"AttributeName": "ttl",
"TimeToLiveStatus": "ENABLED"
}
}
```
1. 通过使用 BASH shell 和 `TTLExample` 设置生存时间属性将项目添加至 AWS CLI 表。
```
EXP=`date -d '+5 days' +%s`
aws dynamodb put-item --table-name "TTLExample" --item '{"id": {"N": "1"}, "ttl": {"N": "'$EXP'"}}'
```
此示例从当前日期开始，并在当前日期上增加 5 天来创建过期时间。然后，它将过期时间转换为纪元时间格式，以便最终添加项目到“`TTLExample`”表。
**注意**
为生存时间设置过期值的一种方式是计算添加到过期时间的秒数。例如，5 天是 432000 秒。但是，人们通常习惯于从某个日期算起。
获取当前时间的纪元时间格式非常简单，如下例中所示。
+ Linux 终端：`date +%s`
+ Python：`import time; int(time.time())`
+ Java：`System.currentTimeMillis() / 1000L`
+ JavaScript: `Math.floor(Date.now() / 1000)`
## 使用 CloudFormation 启用 DynamoDB TTL
```
AWSTemplateFormatVersion: "2010-09-09"
Resources:
TTLExampleTable:
Type: AWS::DynamoDB::Table
Description: "A DynamoDB table with TTL Specification enabled"
Properties:
AttributeDefinitions:
- AttributeName: "Album"
AttributeType: "S"
- AttributeName: "Artist"
AttributeType: "S"
KeySchema:
- AttributeName: "Album"
KeyType: "HASH"
- AttributeName: "Artist"
KeyType: "RANGE"
ProvisionedThroughput:
ReadCapacityUnits: "5"
WriteCapacityUnits: "5"
TimeToLiveSpecification:
AttributeName: "TTLExampleAttribute"
Enabled: true
```
可以在[此处](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-dynamodb-table-timetolivespecification.html)找到有关在 CloudFormation 模板中使用 TTL 的更多详细信息。
# 在 DynamoDB 中计算生存时间（TTL）
实现 TTL 的常用方法是根据项目的创建时间或上次更新时间为其设置过期时间。这可以通过在 `createdAt` 和 `updatedAt` 时间戳中添加时间来完成。例如，可以将新创建项目的 TTL 设置为 `createdAt` \$1 90 天。项目更新后，TTL 可以重新计算为 `updatedAt` \$1 90 天。
计算出的过期时间必须采用纪元格式，以秒为单位。考虑到过期和删除的情况，TTL 不能超过过去五年。如果您使用任何其他格式，TTL 进程将忽略该项目。如果您根据需要将过期时间设置为将来的某个时间，则项目会在该时间之后过期。例如，假设您将过期时间设置为 1724241326 [即 2024 年 8 月 21 日星期一 11:55:26（UTC）]。该项目会在指定时间后过期。没有最低 TTL 持续时间。您可以将过期时间设置为任何将来的时间，例如从当前时间起 5 分钟。但是，DynamoDB 通常会在过期项目过期后的 48 小时内将其删除，而不是在项目过期后立即删除。
**Topics**
+ [创建一个项目并设置生存时间](#time-to-live-ttl-before-you-start-create)
+ [更新项目并刷新生存时间](#time-to-live-ttl-before-you-start-update)
## 创建一个项目并设置生存时间
以下示例演示了如何使用 `expireAt` 作为 TTL 属性名称，来计算创建新项目时的过期时间。赋值语句以变量形式获取当前时间。在示例中，过期时间计算为从当前时间起 90 天。然后将时间转换为纪元格式，并在 TTL 属性中保存为整数数据类型。
以下代码示例展示如何创建设置了 TTL 的项目。
------
#### [ Java ]
**适用于 Java 的 SDK 2.x**
```
package com.amazon.samplelib.ttl;
import com.amazon.samplelib.CodeSampleUtils;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
import software.amazon.awssdk.services.dynamodb.model.DynamoDbException;
import software.amazon.awssdk.services.dynamodb.model.PutItemRequest;
import software.amazon.awssdk.services.dynamodb.model.PutItemResponse;
import software.amazon.awssdk.services.dynamodb.model.ResourceNotFoundException;
import java.util.HashMap;
import java.util.Map;
import java.util.Optional;
/**
* Creates an item in a DynamoDB table with TTL attributes.
* This class demonstrates how to add TTL expiration timestamps to DynamoDB items.
*/
public class CreateTTL {
private static final String USAGE =
"""
Usage:
Where:
tableName - The Amazon DynamoDB table being queried.
primaryKey - The name of the primary key. Also known as the hash or partition key.
sortKey - The name of the sort key. Also known as the range attribute.
region (optional) - The AWS region that the Amazon DynamoDB table is located in. (Default: us-east-1)
""";
private static final int DAYS_TO_EXPIRE = 90;
private static final int SECONDS_PER_DAY = 24 * 60 * 60;
private static final String PRIMARY_KEY_ATTR = "primaryKey";
private static final String SORT_KEY_ATTR = "sortKey";
private static final String CREATION_DATE_ATTR = "creationDate";
private static final String EXPIRE_AT_ATTR = "expireAt";
private static final String SUCCESS_MESSAGE = "%s PutItem operation with TTL successful.";
private static final String TABLE_NOT_FOUND_ERROR = "Error: The Amazon DynamoDB table \"%s\" can't be found.";
private final DynamoDbClient dynamoDbClient;
/**
* Constructs a CreateTTL instance with the specified DynamoDB client.
*
* @param dynamoDbClient The DynamoDB client to use
*/
public CreateTTL(final DynamoDbClient dynamoDbClient) {
this.dynamoDbClient = dynamoDbClient;
}
/**
* Constructs a CreateTTL with a default DynamoDB client.
*/
public CreateTTL() {
this.dynamoDbClient = null;
}
/**
* Main method to demonstrate creating an item with TTL.
*
* @param args Command line arguments
*/
public static void main(final String[] args) {
try {
int result = new CreateTTL().processArgs(args);
System.exit(result);
} catch (Exception e) {
System.err.println(e.getMessage());
System.exit(1);
}
}
/**
* Process command line arguments and create an item with TTL.
*
* @param args Command line arguments
* @return 0 if successful, non-zero otherwise
* @throws ResourceNotFoundException If the table doesn't exist
* @throws DynamoDbException If an error occurs during the operation
* @throws IllegalArgumentException If arguments are invalid
*/
public int processArgs(final String[] args) {
// Argument validation (remove or replace this line when reusing this code)
CodeSampleUtils.validateArgs(args, new int[] {3, 4}, USAGE);
final String tableName = args[0];
final String primaryKey = args[1];
final String sortKey = args[2];
final Region region = Optional.ofNullable(args.length > 3 ? args[3] : null)
.map(Region::of)
.orElse(Region.US_EAST_1);
try (DynamoDbClient ddb = dynamoDbClient != null
? dynamoDbClient
: DynamoDbClient.builder().region(region).build()) {
final CreateTTL createTTL = new CreateTTL(ddb);
createTTL.createItemWithTTL(tableName, primaryKey, sortKey);
return 0;
} catch (Exception e) {
throw e;
}
}
/**
* Creates an item in the specified table with TTL attributes.
*
* @param tableName The name of the table
* @param primaryKeyValue The value for the primary key
* @param sortKeyValue The value for the sort key
* @return The response from the PutItem operation
* @throws ResourceNotFoundException If the table doesn't exist
* @throws DynamoDbException If an error occurs during the operation
*/
public PutItemResponse createItemWithTTL(
final String tableName, final String primaryKeyValue, final String sortKeyValue) {
// Get current time in epoch second format
final long createDate = System.currentTimeMillis() / 1000;
// Calculate expiration time 90 days from now in epoch second format
final long expireDate = createDate + (DAYS_TO_EXPIRE * SECONDS_PER_DAY);
final Map itemMap = new HashMap<>();
itemMap.put(
PRIMARY_KEY_ATTR, AttributeValue.builder().s(primaryKeyValue).build());
itemMap.put(SORT_KEY_ATTR, AttributeValue.builder().s(sortKeyValue).build());
itemMap.put(
CREATION_DATE_ATTR,
AttributeValue.builder().n(String.valueOf(createDate)).build());
itemMap.put(
EXPIRE_AT_ATTR,
AttributeValue.builder().n(String.valueOf(expireDate)).build());
final PutItemRequest request =
PutItemRequest.builder().tableName(tableName).item(itemMap).build();
try {
final PutItemResponse response = dynamoDbClient.putItem(request);
System.out.println(String.format(SUCCESS_MESSAGE, tableName));
return response;
} catch (ResourceNotFoundException e) {
System.err.format(TABLE_NOT_FOUND_ERROR, tableName);
throw e;
} catch (DynamoDbException e) {
System.err.println(e.getMessage());
throw e;
}
}
}
```
+ 有关 API 详细信息，请参阅《AWS SDK for Java 2.x API Reference》**中的 [PutItem](https://docs.aws.amazon.com/goto/SdkForJavaV2/dynamodb-2012-08-10/PutItem)。
------
#### [ JavaScript ]
**SDK for JavaScript（v3）**
```
import { DynamoDBClient, PutItemCommand } from "@aws-sdk/client-dynamodb";
export function createDynamoDBItem(table_name, region, partition_key, sort_key) {
const client = new DynamoDBClient({
region: region,
endpoint: `https://dynamodb.${region}.amazonaws.com`
});
// Get the current time in epoch second format
const current_time = Math.floor(new Date().getTime() / 1000);
// Calculate the expireAt time (90 days from now) in epoch second format
const expire_at = Math.floor((new Date().getTime() + 90 * 24 * 60 * 60 * 1000) / 1000);
// Create DynamoDB item
const item = {
'partitionKey': {'S': partition_key},
'sortKey': {'S': sort_key},
'createdAt': {'N': current_time.toString()},
'expireAt': {'N': expire_at.toString()}
};
const putItemCommand = new PutItemCommand({
TableName: table_name,
Item: item,
ProvisionedThroughput: {
ReadCapacityUnits: 1,
WriteCapacityUnits: 1,
},
});
client.send(putItemCommand, function(err, data) {
if (err) {
console.log("Exception encountered when creating item %s, here's what happened: ", data, err);
throw err;
} else {
console.log("Item created successfully: %s.", data);
return data;
}
});
}
// Example usage (commented out for testing)
// createDynamoDBItem('your-table-name', 'us-east-1', 'your-partition-key-value', 'your-sort-key-value');
```
+ 有关 API 详细信息，请参阅《适用于 JavaScript 的 AWS SDK API Reference》**中的 [PutItem](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/dynamodb/command/PutItemCommand)。
------
#### [ Python ]
**适用于 Python 的 SDK（Boto3）**
```
from datetime import datetime, timedelta
import boto3
def create_dynamodb_item(table_name, region, primary_key, sort_key):
"""
Creates a DynamoDB item with an attached expiry attribute.
:param table_name: Table name for the boto3 resource to target when creating an item
:param region: string representing the AWS region. Example: `us-east-1`
:param primary_key: one attribute known as the partition key.
:param sort_key: Also known as a range attribute.
:return: Void (nothing)
"""
try:
dynamodb = boto3.resource("dynamodb", region_name=region)
table = dynamodb.Table(table_name)
# Get the current time in epoch second format
current_time = int(datetime.now().timestamp())
# Calculate the expiration time (90 days from now) in epoch second format
expiration_time = int((datetime.now() + timedelta(days=90)).timestamp())
item = {
"primaryKey": primary_key,
"sortKey": sort_key,
"creationDate": current_time,
"expireAt": expiration_time,
}
response = table.put_item(Item=item)
print("Item created successfully.")
return response
except Exception as e:
print(f"Error creating item: {e}")
raise e
# Use your own values
create_dynamodb_item(
"your-table-name", "us-west-2", "your-partition-key-value", "your-sort-key-value"
)
```
+ 有关 API 详细信息，请参阅《AWS SDK for Python (Boto3) API Reference》**中的 [PutItem](https://docs.aws.amazon.com/goto/boto3/dynamodb-2012-08-10/PutItem)。
------
## 更新项目并刷新生存时间
此示例是[上一节](#time-to-live-ttl-before-you-start-create)所讲示例的延续。如果更新了项目，则可以重新计算过期时间。以下示例将 `expireAt` 时间戳重新计算为自当前时间起 90 天。
以下代码示例演示了如何更新项目的 TTL。
------
#### [ Java ]
**适用于 Java 的 SDK 2.x**
更新表中现有 DynamoDB 项目的 TTL
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
import software.amazon.awssdk.services.dynamodb.model.DynamoDbException;
import software.amazon.awssdk.services.dynamodb.model.ResourceNotFoundException;
import software.amazon.awssdk.services.dynamodb.model.UpdateItemRequest;
import software.amazon.awssdk.services.dynamodb.model.UpdateItemResponse;
import java.util.HashMap;
import java.util.Map;
import java.util.Optional;
public UpdateItemResponse updateItemWithTTL(
final String tableName, final String primaryKeyValue, final String sortKeyValue) {
// Get current time in epoch second format
final long currentTime = System.currentTimeMillis() / 1000;
// Calculate expiration time 90 days from now in epoch second format
final long expireDate = currentTime + (DAYS_TO_EXPIRE * SECONDS_PER_DAY);
// Create the key map for the item to update
final Map keyMap = new HashMap<>();
keyMap.put(PRIMARY_KEY_ATTR, AttributeValue.builder().s(primaryKeyValue).build());
keyMap.put(SORT_KEY_ATTR, AttributeValue.builder().s(sortKeyValue).build());
// Create the expression attribute values
final Map expressionAttributeValues = new HashMap<>();
expressionAttributeValues.put(
":c", AttributeValue.builder().n(String.valueOf(currentTime)).build());
expressionAttributeValues.put(
":e", AttributeValue.builder().n(String.valueOf(expireDate)).build());
final UpdateItemRequest request = UpdateItemRequest.builder()
.tableName(tableName)
.key(keyMap)
.updateExpression(UPDATE_EXPRESSION)
.expressionAttributeValues(expressionAttributeValues)
.build();
try {
final UpdateItemResponse response = dynamoDbClient.updateItem(request);
System.out.println(String.format(SUCCESS_MESSAGE, tableName));
return response;
} catch (ResourceNotFoundException e) {
System.err.format(TABLE_NOT_FOUND_ERROR, tableName);
throw e;
} catch (DynamoDbException e) {
System.err.println(e.getMessage());
throw e;
}
}
```
+ 有关 API 详细信息，请参阅《AWS SDK for Java 2.x API Reference》**中的 [UpdateItem](https://docs.aws.amazon.com/goto/SdkForJavaV2/dynamodb-2012-08-10/UpdateItem)。
------
#### [ JavaScript ]
**SDK for JavaScript（v3）**
```
import { DynamoDBClient, UpdateItemCommand } from "@aws-sdk/client-dynamodb";
import { marshall, unmarshall } from "@aws-sdk/util-dynamodb";
export const updateItem = async (tableName, partitionKey, sortKey, region = 'us-east-1') => {
const client = new DynamoDBClient({
region: region,
endpoint: `https://dynamodb.${region}.amazonaws.com`
});
const currentTime = Math.floor(Date.now() / 1000);
const expireAt = Math.floor((Date.now() + 90 * 24 * 60 * 60 * 1000) / 1000);
const params = {
TableName: tableName,
Key: marshall({
partitionKey: partitionKey,
sortKey: sortKey
}),
UpdateExpression: "SET updatedAt = :c, expireAt = :e",
ExpressionAttributeValues: marshall({
":c": currentTime,
":e": expireAt
}),
};
try {
const data = await client.send(new UpdateItemCommand(params));
const responseData = unmarshall(data.Attributes);
console.log("Item updated successfully: %s", responseData);
return responseData;
} catch (err) {
console.error("Error updating item:", err);
throw err;
}
}
// Example usage (commented out for testing)
// updateItem('your-table-name', 'your-partition-key-value', 'your-sort-key-value');
```
+ 有关 API 详细信息，请参阅《适用于 JavaScript 的 AWS SDK API Reference》**中的 [UpdateItem](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/dynamodb/command/UpdateItemCommand)。
------
#### [ Python ]
**适用于 Python 的 SDK（Boto3）**
```
from datetime import datetime, timedelta
import boto3
def update_dynamodb_item(table_name, region, primary_key, sort_key):
"""
Update an existing DynamoDB item with a TTL.
:param table_name: Name of the DynamoDB table
:param region: AWS Region of the table - example `us-east-1`
:param primary_key: one attribute known as the partition key.
:param sort_key: Also known as a range attribute.
:return: Void (nothing)
"""
try:
# Create the DynamoDB resource.
dynamodb = boto3.resource("dynamodb", region_name=region)
table = dynamodb.Table(table_name)
# Get the current time in epoch second format
current_time = int(datetime.now().timestamp())
# Calculate the expireAt time (90 days from now) in epoch second format
expire_at = int((datetime.now() + timedelta(days=90)).timestamp())
table.update_item(
Key={"partitionKey": primary_key, "sortKey": sort_key},
UpdateExpression="set updatedAt=:c, expireAt=:e",
ExpressionAttributeValues={":c": current_time, ":e": expire_at},
)
print("Item updated successfully.")
except Exception as e:
print(f"Error updating item: {e}")
# Replace with your own values
update_dynamodb_item(
"your-table-name", "us-west-2", "your-partition-key-value", "your-sort-key-value"
)
```
+ 有关 API 详细信息，请参阅《AWS SDK for Python（Boto3）API Reference》**中的 [UpdateItem](https://docs.aws.amazon.com/goto/boto3/dynamodb-2012-08-10/UpdateItem)。
------
本简介中讨论的 TTL 示例演示了一种确保表中仅保留最近更新的项目的方法。更新的项目会延长寿命，而创建后未更新的项目将过期并被免费删除，从而减少存储空间并保持表整洁。
# 使用过期项目和生存时间（TTL）
可以通过读取和写入操作筛选待删除的过期项目。这在过期数据不再有效且不会使用的情况下很有用。如果未将其筛选出来，它们将继续显示在读取和写入操作中，直到它们被后台进程删除。
**注意**
这些项目在被删除之前仍会计入存储和读取费用中。
可以在 DynamoDB Streams 中识别 TTL 删除，但只能在执行删除的区域中识别。对于删除复制到的区域，复制到全局表区域的 TTL 删除在 DynamoDB Streams 中无法识别。
## 从读取操作中筛选过期项目
对于诸如[扫描](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Scan.html)和[查询](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html)之类的读取操作，筛选表达式可以筛选出待删除的过期项目。如下面的代码段所示，筛选表达式可以筛选出 TTL 时间等于或小于当前时间的项目。例如，Python SDK 代码包含一个赋值语句，该语句将当前时间作为变量（`now`）获取，并将其转换为纪元时间格式 `int`。
以下代码示例演示了如何查询 TTL 项目。
------
#### [ Java ]
**SDK for Java 2.x**
查询对表达式进行了筛选，以使用AWS SDK for Java 2.x 在 DynamoDB 表中收集 TTL 项目。
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
import software.amazon.awssdk.services.dynamodb.model.DynamoDbException;
import software.amazon.awssdk.services.dynamodb.model.QueryRequest;
import software.amazon.awssdk.services.dynamodb.model.QueryResponse;
import software.amazon.awssdk.services.dynamodb.model.ResourceNotFoundException;
import java.util.Map;
import java.util.Optional;
final QueryRequest request = QueryRequest.builder()
.tableName(tableName)
.keyConditionExpression(KEY_CONDITION_EXPRESSION)
.filterExpression(FILTER_EXPRESSION)
.expressionAttributeNames(expressionAttributeNames)
.expressionAttributeValues(expressionAttributeValues)
.build();
try (DynamoDbClient ddb = dynamoDbClient != null
? dynamoDbClient
: DynamoDbClient.builder().region(region).build()) {
final QueryResponse response = ddb.query(request);
System.out.println("Query successful. Found " + response.count() + " items that have not expired yet.");
// Print each item
response.items().forEach(item -> {
System.out.println("Item: " + item);
});
return 0;
} catch (ResourceNotFoundException e) {
System.err.format(TABLE_NOT_FOUND_ERROR, tableName);
throw e;
} catch (DynamoDbException e) {
System.err.println(e.getMessage());
throw e;
}
```
+ 有关 API 详细信息，请参阅《AWS SDK for Java 2.x API Reference》**中的 [Query](https://docs.aws.amazon.com/goto/SdkForJavaV2/dynamodb-2012-08-10/Query)。
------
#### [ JavaScript ]
**SDK for JavaScript（v3）**
查询对表达式进行了筛选，以使用适用于 JavaScript 的 AWS SDK 在 DynamoDB 表中收集 TTL 项目。
```
import { DynamoDBClient, QueryCommand } from "@aws-sdk/client-dynamodb";
import { marshall, unmarshall } from "@aws-sdk/util-dynamodb";
export const queryFiltered = async (tableName, primaryKey, region = 'us-east-1') => {
const client = new DynamoDBClient({
region: region,
endpoint: `https://dynamodb.${region}.amazonaws.com`
});
const currentTime = Math.floor(Date.now() / 1000);
const params = {
TableName: tableName,
KeyConditionExpression: "#pk = :pk",
FilterExpression: "#ea > :ea",
ExpressionAttributeNames: {
"#pk": "primaryKey",
"#ea": "expireAt"
},
ExpressionAttributeValues: marshall({
":pk": primaryKey,
":ea": currentTime
})
};
try {
const { Items } = await client.send(new QueryCommand(params));
Items.forEach(item => {
console.log(unmarshall(item))
});
return Items;
} catch (err) {
console.error(`Error querying items: ${err}`);
throw err;
}
}
// Example usage (commented out for testing)
// queryFiltered('your-table-name', 'your-partition-key-value');
```
+ 有关 API 详细信息，请参阅《适用于 JavaScript 的 AWS SDK API Reference》**中的 [Query](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/dynamodb/command/QueryCommand)。
------
#### [ Python ]
**适用于 Python 的 SDK（Boto3）**
查询对表达式进行了筛选，以使用适用于 Python (Boto3) 的 AWS SDK 在 DynamoDB 表中收集 TTL 项目。
```
from datetime import datetime
import boto3
def query_dynamodb_items(table_name, partition_key):
"""
:param table_name: Name of the DynamoDB table
:param partition_key:
:return:
"""
try:
# Initialize a DynamoDB resource
dynamodb = boto3.resource("dynamodb", region_name="us-east-1")
# Specify your table
table = dynamodb.Table(table_name)
# Get the current time in epoch format
current_time = int(datetime.now().timestamp())
# Perform the query operation with a filter expression to exclude expired items
# response = table.query(
# KeyConditionExpression=boto3.dynamodb.conditions.Key('partitionKey').eq(partition_key),
# FilterExpression=boto3.dynamodb.conditions.Attr('expireAt').gt(current_time)
# )
response = table.query(
KeyConditionExpression=dynamodb.conditions.Key("partitionKey").eq(partition_key),
FilterExpression=dynamodb.conditions.Attr("expireAt").gt(current_time),
)
# Print the items that are not expired
for item in response["Items"]:
print(item)
except Exception as e:
print(f"Error querying items: {e}")
# Call the function with your values
query_dynamodb_items("Music", "your-partition-key-value")
```
+ 有关 API 详细信息，请参阅《AWS SDK for Python (Boto3) API Reference》**中的 [Query](https://docs.aws.amazon.com/goto/boto3/dynamodb-2012-08-10/Query)。
------
## 有条件地写入过期项目
条件表达式可用于避免写入过期项目。下面的代码段是一个有条件的更新，用于检查过期时间是否大于当前时间。如果为 true，则写入操作将继续。
以下代码示例演示了如何有条件地更新项目的 TTL。
------
#### [ Java ]
**适用于 Java 的 SDK 2.x**
使用条件更新表中现有 DynamoDB 项目的 TTL。
```
package com.amazon.samplelib.ttl;
import com.amazon.samplelib.CodeSampleUtils;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
import software.amazon.awssdk.services.dynamodb.model.ConditionalCheckFailedException;
import software.amazon.awssdk.services.dynamodb.model.DynamoDbException;
import software.amazon.awssdk.services.dynamodb.model.ResourceNotFoundException;
import software.amazon.awssdk.services.dynamodb.model.UpdateItemRequest;
import software.amazon.awssdk.services.dynamodb.model.UpdateItemResponse;
import java.util.Map;
import java.util.Optional;
/**
* Updates an item in a DynamoDB table with TTL attributes using a conditional expression.
* This class demonstrates how to conditionally update TTL expiration timestamps.
*/
public class UpdateTTLConditional {
private static final String USAGE =
"""
Usage:
Where:
tableName - The Amazon DynamoDB table being queried.
primaryKey - The name of the primary key. Also known as the hash or partition key.
sortKey - The name of the sort key. Also known as the range attribute.
region (optional) - The AWS region that the Amazon DynamoDB table is located in. (Default: us-east-1)
""";
private static final int DAYS_TO_EXPIRE = 90;
private static final int SECONDS_PER_DAY = 24 * 60 * 60;
private static final String PRIMARY_KEY_ATTR = "primaryKey";
private static final String SORT_KEY_ATTR = "sortKey";
private static final String UPDATED_AT_ATTR = "updatedAt";
private static final String EXPIRE_AT_ATTR = "expireAt";
private static final String UPDATE_EXPRESSION = "SET " + UPDATED_AT_ATTR + "=:c, " + EXPIRE_AT_ATTR + "=:e";
private static final String CONDITION_EXPRESSION = "attribute_exists(" + PRIMARY_KEY_ATTR + ")";
private static final String SUCCESS_MESSAGE = "%s UpdateItem operation with TTL successful.";
private static final String CONDITION_FAILED_MESSAGE = "Condition check failed. Item does not exist.";
private static final String TABLE_NOT_FOUND_ERROR = "Error: The Amazon DynamoDB table \"%s\" can't be found.";
private final DynamoDbClient dynamoDbClient;
/**
* Constructs an UpdateTTLConditional with a default DynamoDB client.
*/
public UpdateTTLConditional() {
this.dynamoDbClient = null;
}
/**
* Constructs an UpdateTTLConditional with the specified DynamoDB client.
*
* @param dynamoDbClient The DynamoDB client to use
*/
public UpdateTTLConditional(final DynamoDbClient dynamoDbClient) {
this.dynamoDbClient = dynamoDbClient;
}
/**
* Main method to demonstrate conditionally updating an item with TTL.
*
* @param args Command line arguments
*/
public static void main(final String[] args) {
try {
int result = new UpdateTTLConditional().processArgs(args);
System.exit(result);
} catch (Exception e) {
System.err.println(e.getMessage());
System.exit(1);
}
}
/**
* Process command line arguments and conditionally update an item with TTL.
*
* @param args Command line arguments
* @return 0 if successful, non-zero otherwise
* @throws ResourceNotFoundException If the table doesn't exist
* @throws DynamoDbException If an error occurs during the operation
* @throws IllegalArgumentException If arguments are invalid
*/
public int processArgs(final String[] args) {
// Argument validation (remove or replace this line when reusing this code)
CodeSampleUtils.validateArgs(args, new int[] {3, 4}, USAGE);
final String tableName = args[0];
final String primaryKey = args[1];
final String sortKey = args[2];
final Region region = Optional.ofNullable(args.length > 3 ? args[3] : null)
.map(Region::of)
.orElse(Region.US_EAST_1);
// Get current time in epoch second format
final long currentTime = System.currentTimeMillis() / 1000;
// Calculate expiration time 90 days from now in epoch second format
final long expireDate = currentTime + (DAYS_TO_EXPIRE * SECONDS_PER_DAY);
// Create the key map for the item to update
final Map keyMap = Map.of(
PRIMARY_KEY_ATTR, AttributeValue.builder().s(primaryKey).build(),
SORT_KEY_ATTR, AttributeValue.builder().s(sortKey).build());
// Create the expression attribute values
final Map expressionAttributeValues = Map.of(
":c", AttributeValue.builder().n(String.valueOf(currentTime)).build(),
":e", AttributeValue.builder().n(String.valueOf(expireDate)).build());
final UpdateItemRequest request = UpdateItemRequest.builder()
.tableName(tableName)
.key(keyMap)
.updateExpression(UPDATE_EXPRESSION)
.conditionExpression(CONDITION_EXPRESSION)
.expressionAttributeValues(expressionAttributeValues)
.build();
try (DynamoDbClient ddb = dynamoDbClient != null
? dynamoDbClient
: DynamoDbClient.builder().region(region).build()) {
final UpdateItemResponse response = ddb.updateItem(request);
System.out.println(String.format(SUCCESS_MESSAGE, tableName));
return 0;
} catch (ConditionalCheckFailedException e) {
System.err.println(CONDITION_FAILED_MESSAGE);
throw e;
} catch (ResourceNotFoundException e) {
System.err.format(TABLE_NOT_FOUND_ERROR, tableName);
throw e;
} catch (DynamoDbException e) {
System.err.println(e.getMessage());
throw e;
}
}
}
```
+ 有关 API 详细信息，请参阅《AWS SDK for Java 2.x API Reference》**中的 [UpdateItem](https://docs.aws.amazon.com/goto/SdkForJavaV2/dynamodb-2012-08-10/UpdateItem)。
------
#### [ JavaScript ]
**SDK for JavaScript（v3）**
使用条件更新表中现有 DynamoDB 项目的 TTL。
```
import { DynamoDBClient, UpdateItemCommand } from "@aws-sdk/client-dynamodb";
import { marshall, unmarshall } from "@aws-sdk/util-dynamodb";
export const updateItemConditional = async (tableName, partitionKey, sortKey, region = 'us-east-1', newAttribute = 'default-value') => {
const client = new DynamoDBClient({
region: region,
endpoint: `https://dynamodb.${region}.amazonaws.com`
});
const currentTime = Math.floor(Date.now() / 1000);
const params = {
TableName: tableName,
Key: marshall({
artist: partitionKey,
album: sortKey
}),
UpdateExpression: "SET newAttribute = :newAttribute",
ConditionExpression: "expireAt > :expiration",
ExpressionAttributeValues: marshall({
':newAttribute': newAttribute,
':expiration': currentTime
}),
ReturnValues: "ALL_NEW"
};
try {
const response = await client.send(new UpdateItemCommand(params));
const responseData = unmarshall(response.Attributes);
console.log("Item updated successfully: ", responseData);
return responseData;
} catch (error) {
if (error.name === "ConditionalCheckFailedException") {
console.log("Condition check failed: Item's 'expireAt' is expired.");
} else {
console.error("Error updating item: ", error);
}
throw error;
}
};
// Example usage (commented out for testing)
// updateItemConditional('your-table-name', 'your-partition-key-value', 'your-sort-key-value');
```
+ 有关 API 详细信息，请参阅《适用于 JavaScript 的 AWS SDK API Reference》**中的 [UpdateItem](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/dynamodb/command/UpdateItemCommand)。
------
#### [ Python ]
**适用于 Python 的 SDK（Boto3）**
使用条件更新表中现有 DynamoDB 项目的 TTL。
```
from datetime import datetime, timedelta
import boto3
from botocore.exceptions import ClientError
def update_dynamodb_item_ttl(table_name, region, primary_key, sort_key, ttl_attribute):
"""
Updates an existing record in a DynamoDB table with a new or updated TTL attribute.
:param table_name: Name of the DynamoDB table
:param region: AWS Region of the table - example `us-east-1`
:param primary_key: one attribute known as the partition key.
:param sort_key: Also known as a range attribute.
:param ttl_attribute: name of the TTL attribute in the target DynamoDB table
:return:
"""
try:
dynamodb = boto3.resource("dynamodb", region_name=region)
table = dynamodb.Table(table_name)
# Generate updated TTL in epoch second format
updated_expiration_time = int((datetime.now() + timedelta(days=90)).timestamp())
# Define the update expression for adding/updating a new attribute
update_expression = "SET newAttribute = :val1"
# Define the condition expression for checking if 'expireAt' is not expired
condition_expression = "expireAt > :val2"
# Define the expression attribute values
expression_attribute_values = {":val1": ttl_attribute, ":val2": updated_expiration_time}
response = table.update_item(
Key={"primaryKey": primary_key, "sortKey": sort_key},
UpdateExpression=update_expression,
ConditionExpression=condition_expression,
ExpressionAttributeValues=expression_attribute_values,
)
print("Item updated successfully.")
return response["ResponseMetadata"]["HTTPStatusCode"] # Ideally a 200 OK
except ClientError as e:
if e.response["Error"]["Code"] == "ConditionalCheckFailedException":
print("Condition check failed: Item's 'expireAt' is expired.")
else:
print(f"Error updating item: {e}")
except Exception as e:
print(f"Error updating item: {e}")
# replace with your values
update_dynamodb_item_ttl(
"your-table-name",
"us-east-1",
"your-partition-key-value",
"your-sort-key-value",
"your-ttl-attribute-value",
)
```
+ 有关 API 详细信息，请参阅《AWS SDK for Python（Boto3）API Reference》**中的 [UpdateItem](https://docs.aws.amazon.com/goto/boto3/dynamodb-2012-08-10/UpdateItem)。
------
## 识别 DynamoDB Streams 中已删除的项目
流记录包含用户身份字段`Records[].userIdentity`。被 TTL 过程删除的项目包含以下字段：
```
Records[].userIdentity.type
"Service"
Records[].userIdentity.principalId
"dynamodb.amazonaws.com"
```
以下 JSON 显示单个流记录的相关部分：
```
"Records": [
{
...
"userIdentity": {
"type": "Service",
"principalId": "dynamodb.amazonaws.com"
}
...
}
]
```