Help Center/ GeminiDB/ GeminiDB DynamoDB-Compatible API/ FAQs/ Instructions for Use/ How Can I Use TTL?
Updated on 2025-12-30 GMT+08:00
View PDF

How Can I Use TTL?

Time to live (TTL) of GeminiDB DynamoDB-Compatible API is used to periodically delete unnecessary data rows. You can specify an expiration timestamp for each row in a table. GeminiDB DynamoDB-Compatible API automatically deletes the rows within a period of time after they are expired.

Configuring TTL

You can call the UpdateTimeToLive API to enable or disable table-level TTL and set a column name for table-level TTL. The column stores the expiration timestamps.

// Enables TTL for a specified table and specifies TTL timestamps for a column.
UpdateTimeToLiveRequest request1 = new UpdateTimeToLiveRequest()
                .withTableName("$tableName")
                .withTimeToLiveSpecification(new TimeToLiveSpecification()
                        .withAttributeName("$ttlAttr")
                        .withEnabled(true)
                );
// Updates values in the TTL column through APIs such as UpdateItem.
UpdateItemRequest request2 = new UpdateItemRequest()
                .withTableName("$tableName")
                .withKey(keyMap)
                .withUpdateExpression("SET $ttlAttr = :$ttlVal")
                .withExpressionAttributeValues(valueMap);
// Disables TTL for a specified table.
UpdateTimeToLiveRequest request1 = new UpdateTimeToLiveRequest()
                .withTableName("$tableName")
                .withTimeToLiveSpecification(new TimeToLiveSpecification()
                        .withEnabled(false)
                );

You can call the DescribeTimeToLive API to query table-level TTL configurations, including whether TTL is enabled and the TTL column name.

// Queries TTL configurations of a specified table.
DescribeTimeToLiveRequest request1 = new DescribeTimeToLiveRequest().withTableName("$tableName");
  • The TTL column must store the Number (N) data type.
  • TTL column values are converted to Unix timestamps (in seconds) in the GMT+0 time zone and compared with the current time to determine the expiration status.
  • TTL runs in the background as a scheduled task. Therefore, the actual deletion time is different from the configured expiration timestamp. The offset is related to the task execution period.
  • All user tables with TTL enabled are scanned in the background. You can also disable TTL for a table.
  • TTL of GeminiDB DynamoDB-Compatible API is compatible with DynamoDB Streams. Rows that exceed the TTL value are inserted into Dynamo Streams records at the time when they are actually deleted.
Parent Topic: Instructions for Use