# Configure pre-warming for tables in Amazon Keyspaces Amazon Keyspaces automatically scales storage partitions based on on-demand or provisioned throughput, but for new tables or sudden throughput peaks, it can take longer to allocate the required storage partitions. To insure that a new or existing table has enough capacity to support anticipated peak throughput, you can manually set specific *warm throughput* values to *pre-warm* your table. *Warm throughput* refers to the number of read and write operations your Amazon Keyspaces table can instantaneously support. These values are available by default for all new and existing tables. If you are using on-demand mode, or if you update your provisioned throughput, Amazon Keyspaces ensures that your application is able to issue requests up to those values instantly. Amazon Keyspaces automatically adjusts warm throughput values as your usage increases. To adjust throughput capacity for upcoming peak events, for example when you're migrating data from another database, which may require loading terabytes of data in a short period of time, you can manually increase your tables warm throughput values. This is useful for planned peak events where request rates might increase by 10x, 100x, or more. First, assess whether the current warm throughput is sufficient to handle the expected traffic. Then, if you need to pre-warm the table for the planned peak workload, you can increase the warm throughput value manually without changing your throughput settings or [capacity mode](ReadWriteCapacityMode.md). You can pre-warm tables for read operations, write operations, or both. You can increase this value for new and existing single-Region tables and multi-Region tables and the warm throughput settings you set apply automatically to all replicas of the multi-Region tables. There is no limit to the number of Amazon Keyspaces tables you can pre-warm at any time. The time to complete pre-warming depends on the values you set and the size of the table. You can submit simultaneous pre-warm requests and these requests don't interfere with any table operations. You can pre-warm your table up to the table quota limit for your account in that Region. Use the [Service Quotas console](https://console.aws.amazon.com/servicequotas) to check your current quotas and increase them if needed. The warm throughput values that Amazon Keyspaces adjusts based on your on-demand usage or provisioned capacity are available by default for all tables without additional charges. However, if you manually increase the default warm throughput values to pre-warm tables for peak traffic events, additional charges apply. For more information, see [Amazon Keyspaces pricing](https://aws.amazon.com/keyspaces/pricing/). Here are some different scenarios and best practices you might consider when pre-warming Amazon Keyspaces tables. ## Warm throughput and uneven access patterns A table might have a warm throughput of 30,000 read units per second and 10,000 write units per second, but you could still experience capacity exceeded events on reads or writes before hitting those values. This is likely due to a hot partition. While Amazon Keyspaces can keep scaling to support virtually unlimited throughput, each individual partition is limited to 1,000 write units per second and 3,000 read units per second. If your application drives too much traffic to a small portion of the table’s partitions, capacity exceeded events can occur even before you reach the table's warm throughput values. We recommend following [Amazon Keyspaces best practices](bp-partition-key-design.md) to ensure seamless scalability and avoid hot partitions. ## Warm throughput for a provisioned table Consider a provisioned table that has a warm throughput of 30,000 read units per second and 10,000 write units per second but currently has a provisioned throughput of 4,000 RCUs and 8,000 WCUs. You can instantly scale the table's provisioned throughput up to 30,000 RCUs or 10,000 WCUs by updating your provisioned throughput settings. As you increase the provisioned throughput beyond these values, the warm throughput adjusts automatically to the new higher values, because you have established a new peak throughput. For example, if you set the provisioned throughput to 50,000 RCU, the warm throughput increases to 50,000 read units per second. ``` "ProvisionedThroughput": { "ReadCapacityUnits": 4000, "WriteCapacityUnits": 8000 } "WarmThroughput": { "ReadUnitsPerSecond": 30000, "WriteUnitsPerSecond": 10000 } ``` ## Warm throughput for an on-demand table A new on-demand table starts with a warm throughput of 12,000 read units per second and 4,000 write units per second. Your table can instantly accommodate sustained traffic up to these levels. When your requests exceed 12,000 read units per second or 4,000 write units per second, the warm throughput adjusts automatically to the higher values. ``` "WarmThroughput": { "ReadUnitsPerSecond": 12000, "WriteUnitsPerSecond": 4000 } ``` ## Best practices for pre-warming Amazon Keyspaces tables Follow these best practices when implementing pre-warming for your Amazon Keyspaces tables: Accurately estimate the required capacity Because pre-warming incurs a one-time cost, carefully calculate the throughput needed based on expected workload to avoid over-provisioning. Consider the table's schema Tables with larger rows may require more partitions for the same throughput. Factor in your average row size when estimating pre-warming requirements. Monitor table performance After pre-warming, use CloudWatch metrics to verify that your table is handling the load as expected. For more information, see [Monitor the performance of a pre-warmed table using Amazon CloudWatch](monitor-prewarming-cloudwatch.md). Manage quotas If your application requires higher throughput than the default quotas allow (40,000 RCUs/WCUs or 2,000 partitions), request quota increases well in advance of your high-traffic event. To request a quota increase, use the [Service Quotas console](https://console.aws.amazon.com/servicequotas). Optimize costs For temporary high-traffic events, consider using pre-warming instead of switching to provisioned mode with high capacity, as it may be more cost-effective for short duration events. For more information about pricing, see [Amazon Keyspaces pricing](https://aws.amazon.com/keyspaces/pricing/). **Note** Monitor your application's performance metrics during the test phase to validate that your pre-warming configuration adequately supports your workload requirements. **Topics** + [Warm throughput and uneven access patterns](#warm-throughput-scenarios-uneven) + [Warm throughput for a provisioned table](#warm-throughput-scenarios-provisioned) + [Warm throughput for an on-demand table](#warm-throughput-scenarios-ondemand) + [Best practices for pre-warming Amazon Keyspaces tables](#prewarming-best-practices) + [Create a new Amazon Keyspaces table with higher warm throughput](create-table-warm-throughput.md) + [Increase your existing Amazon Keyspaces table's warm throughput](update-warm-throughput.md) + [View warm throughput of an Amazon Keyspaces table](view-warm-throughput.md) + [Monitor the performance of a pre-warmed table using Amazon CloudWatch](monitor-prewarming-cloudwatch.md) # Create a new Amazon Keyspaces table with higher warm throughput You can adjust the warm throughput values when you create your Amazon Keyspaces table by using the console, CQL, or the AWS CLI. ------ #### [ Console ] **How to create a new table with warm-throughput settings** 1. Sign in to the AWS Management Console, and open the Amazon Keyspaces console at [https://console.aws.amazon.com/keyspaces/home](https://console.aws.amazon.com/keyspaces/home). 1. In the navigation pane, choose **Tables**, and then choose **Create table**. 1. On the **Create table** page in the **Table details** section, select a keyspace and provide a name for the new table. 1. In the **Columns** section, create the schema for your table. 1. In the **Primary key** section, define the primary key of the table and select optional clustering columns. 1. In the **Table settings** section, choose **Customize settings**. 1. Continue to **Read/write capacity settings**. 1. For **Capacity mode**, you can choose either **On-demand** or **Provisioned**. 1. In the **Pre-warming for tables** section, you can increase the values for **Read units per second** and **Write units per second** as needed to prepare your table to handle planned peak events. The warm throughput values that Amazon Keyspaces adjusts based on your on-demand usage or provisioned capacity are available by default for all tables without additional charges. Note that if you manually increase the default warm throughput values to pre-warm the table for peak traffic events, additional charges apply. 1. Configure other optional table features as needed. Then choose **Create table**. ------ #### [ Cassandra Query Language (CQL) ] + Create a table with warm throughput using one of the following methods: + For provisioned mode, create a table and specify the expected peak capacity for reads and writes using the following CQL syntax: ``` CREATE TABLE catalog.book_awards ( year int, award text, rank int, category text, book_title text, author text, publisher text, PRIMARY KEY ((year, award), category, rank)) WITH CUSTOM_PROPERTIES = { 'capacity_mode': { 'throughput_mode': 'PROVISIONED', 'read_capacity_units': 20000, 'write_capacity_units': 10000 }, 'warm_throughput': { 'read_units_per_second': 40000, 'write_units_per_second': 20000 } }; ``` + For on-demand mode, create a table and specify the expected peak capacity for reads and writes using the following CQL syntax: ``` CREATE TABLE catalog.book_awards ( year int, award text, rank int, category text, book_title text, author text, publisher text, PRIMARY KEY ((year, award), category, rank)) WITH CUSTOM_PROPERTIES = { 'capacity_mode': { 'throughput_mode': 'PAY_PER_REQUEST' }, 'warm_throughput': { 'read_units_per_second': 40000, 'write_units_per_second': 20000 } }; ``` To confirm the capacity settings of the table, see [View warm throughput of an Amazon Keyspaces table](view-warm-throughput.md). ------ #### [ CLI ] 1. Create a table with warm throughput using one of the following methods using the AWS CLI + Create a new table in provisioned mode and specify the expected peak capacity values for reads and writes for the new table. The following statement is an example of this. ``` aws keyspaces create-table \ --keyspace-name 'catalog' \ --table-name 'book_awards' \ --schema-definition 'allColumns=[{name=year,type=int},{name=award,type=text},{name=rank,type=int},{name=category,type=text},{name=book_title,type=text},{name=author,type=text},{name=publisher,type=text}],partitionKeys=[{name=year},{name=award}],clusteringKeys=[{name=category,orderBy=ASC},{name=rank,orderBy=ASC}]' \ --capacity-specification throughputMode=PROVISIONED,readCapacityUnits=20000,writeCapacityUnits=10000 \ --warm-throughput-specification readUnitsPerSecond=40000,writeUnitsPerSecond=20000 ``` + Create a new table in on-demand mode and specify the expected peak capacity values for reads and writes for the new table. The following statement is an example of this. ``` aws keyspaces create-table \ --keyspace-name 'catalog' \ --table-name 'book_awards' \ --schema-definition 'allColumns=[{name=year,type=int},{name=award,type=text},{name=rank,type=int},{name=category,type=text},{name=book_title,type=text},{name=author,type=text},{name=publisher,type=text}],partitionKeys=[{name=year},{name=award}],clusteringKeys=[{name=category,orderBy=ASC},{name=rank,orderBy=ASC}]' \ --warmThroughputSpecification readUnitsPerSecond=40000,writeUnitsPerSecond=20000 ``` 1. The output of the command returns the ARN of the table as shown in the following example. ``` { "resourceArn": "arn:aws::cassandra:us-east-1:111122223333:/keyspace/catalog/table/book_awards>" } ``` To confirm the capacity settings of the table, see [View warm throughput of an Amazon Keyspaces table](view-warm-throughput.md). ------ #### [ Java ] **Create a new table using the SDK for Java.** + Create a new table in provisioned mode and specify the expected peak capacity values for reads and writes for the new table. The following code example is an example of this. ``` import software.amazon.awssdk.services.keyspaces.KeyspacesClient; import software.amazon.awssdk.services.keyspaces.model.*; public class PreWarmingExample { public static void main(String[] args) { KeyspacesClient keyspacesClient = KeyspacesClient.builder().build(); // Define schema List columns = Arrays.asList( ColumnDefinition.builder().name("year").type("int").build(), ColumnDefinition.builder().name("award").type("text").build(), ColumnDefinition.builder().name("rank").type("int").build(), ColumnDefinition.builder().name("category").type("text").build(), ColumnDefinition.builder().name("book_title").type("text").build(), ColumnDefinition.builder().name("author").type("text").build(), ColumnDefinition.builder().name("publisher").type("text").build() ); List partitionKeys = Arrays.asList( PartitionKey.builder().name("year").build(), PartitionKey.builder().name("award").build() ); List clusteringKeys = Arrays.asList( ClusteringKey.builder().name("category").orderBy("ASC").build(), ClusteringKey.builder().name("rank").orderBy("ASC").build() ); SchemaDefinition schema = SchemaDefinition.builder() .allColumns(columns) .partitionKeys(partitionKeys) .clusteringKeys(clusteringKeys) .build(); // Define capacity specification CapacitySpecification capacitySpec = CapacitySpecification.builder() .throughputMode(ThroughputMode.PROVISIONED) .readCapacityUnits(20000) .writeCapacityUnits(10000) .build(); // Define warm throughput specification WarmThroughputSpecification warmThroughput = WarmThroughputSpecification.builder() .readUnitsPerSecond(40000L) .writeUnitsPerSecond(20000L) .build(); // Create table with PreWarming CreateTableRequest request = CreateTableRequest.builder() .keyspaceName("catalog") .tableName("book_awards") .schemaDefinition(schema) .capacitySpecification(capacitySpec) .warmThroughputSpecification(warmThroughput) .build(); CreateTableResponse response = keyspacesClient.createTable(request); System.out.println("Table created with ARN: " + response.resourceArn()); } } ``` ------ # Increase your existing Amazon Keyspaces table's warm throughput You can increase your Amazon Keyspaces table's current warm throughput values using the console, CQL, or the AWS CLI. ------ #### [ Console ] **How to increase pre-warm settings of a table using the console** 1. Sign in to the AWS Management Console, and open the Amazon Keyspaces console at [https://console.aws.amazon.com/keyspaces/home](https://console.aws.amazon.com/keyspaces/home). 1. In the navigation pane, choose **Tables**, and then choose the table that you want to update. 1. On the **Capacity** tab of the table, continue to **Pre-warming for tables**. 1. In the **Pre-warming for tables** section, choose **Edit**. 1. On the **Edit pre-warming for tables** page, you can updated the values for **Read units per second** and for **Write units per second**. 1. Choose **Save changes**. Your table is getting updated with the specified pre-warming settings. ------ #### [ Cassandra Query Language (CQL) ] **Increase the warm throughput settings of a table using CQL** + Use the `ALTER TABLE`statement to increase warm-throughput of a table. The following statement is an example of this. ``` ALTER TABLE catalog.book_awards WITH CUSTOM_PROPERTIES = { 'warm_throughput': { 'read_units_per_second': 60000, 'write_units_per_second': 30000 } }; ``` To confirm the updated capacity settings of the table, see [View warm throughput of an Amazon Keyspaces table](view-warm-throughput.md). ------ #### [ CLI ] **Increase the pre-warming settings of a table using the AWS CLI** + To increase the warm-throughput of table, you can use the `update-table` command. The following statement is an example of this. ``` aws keyspaces update-table \ --keyspace-name 'catalog' \ --table-name 'book_awards' \ --warmThroughputSpecification readUnitsPerSecond=60000,writeUnitsPerSecond=30000 ``` To confirm the updated capacity settings of the table, see [View warm throughput of an Amazon Keyspaces table](view-warm-throughput.md). ------ #### [ Java ] **Update the pre-warming settings of a table using the SDK for Java.** + Update the warm-throughput settings for a table. The following code example is an example of this. ``` import software.amazon.awssdk.services.keyspaces.KeyspacesClient; import software.amazon.awssdk.services.keyspaces.model.*; public class UpdatePreWarmingExample { public static void main(String[] args) { KeyspacesClient keyspacesClient = KeyspacesClient.builder().build(); // Define new warm throughput specification WarmThroughputSpecification warmThroughput = WarmThroughputSpecification.builder() .readUnitsPerSecond(60000L) .writeUnitsPerSecond(30000L) .build(); // Update table with new PreWarming settings UpdateTableRequest request = UpdateTableRequest.builder() .keyspaceName("catalog") .tableName("book_awards") .warmThroughputSpecification(warmThroughput) .build(); UpdateTableResponse response = keyspacesClient.updateTable(request); System.out.println("Table update requested: " + response.resourceArn()); } } ``` ------ # View warm throughput of an Amazon Keyspaces table You can view your Amazon Keyspaces table's current warm throughput values using the console, CQL, or the AWS CLI. ------ #### [ Console ] **How to view your table's pre-warming settings using the console.** 1. Sign in to the AWS Management Console, and open the Amazon Keyspaces console at [https://console.aws.amazon.com/keyspaces/home](https://console.aws.amazon.com/keyspaces/home). 1. In the navigation pane, choose **Tables**, and then choose the table that you want to review. 1. On the **Capacity** tab of the table, continue to **Pre-warming for tables**. ------ #### [ Cassandra Query Language (CQL) ] **View the warm-throughput settings of a table using CQL** + To view the warm-throughput settings of a table, you can use the following CQL statement. ``` SELECT custom_properties FROM system_schema_mcs.tables WHERE keyspace_name='catalog' and table_name='book_awards'; // Output: ... custom_properties ---------------------------------------------------------------------------------- { 'warm_throughput': { 'read_units_per_second': '40000', 'write_units_per_second': '20000', 'status': 'AVAILABLE' } } ... ``` ------ #### [ CLI ] **View the warm-throughput settings of a table using the AWS CLI** + You can view the warm-throughput settings of a table using the `get-table` command as shown in the following example. ``` aws keyspaces get-table \ --keyspace-name 'catalog' \ --table-name 'book_awards' ``` The following is showing the example output of the `get-table` command for a single-Region table in provisioned mode. ``` { "keyspaceName": "catalog", "tableName": "book_awards", ... Existing Fields ..., "capacitySpecificationSummary": { "throughputMode": "PROVISIONED", "readCapacityUnits": 20000, "writeCapacityUnits": 10000 }, "warmThroughputSpecificationSummary": { "readUnitsPerSecond": 40000, "writeUnitsPerSecond": 20000, "status": "AVAILABLE" } } ``` The following is showing the example output for a single-Region table in on-demand mode. ``` { "keyspaceName": "catalog", "tableName": "book_awards_ondemand", ... Existing Fields ..., "capacitySpecification": { "throughputMode": "PAY_PER_REQUEST" }, "warmThroughputSpecificationSummary": { "readUnitsPerSecond": 40000, "writeUnitsPerSecond": 20000, "status": "AVAILABLE" } } ``` ------ #### [ Java ] **Read the pre-warming settings of a table using the SDK for Java.** + Read the warm-throughput values of a table using `get-table`. The following code example is an example of this. ``` import software.amazon.awssdk.services.keyspaces.KeyspacesClient; import software.amazon.awssdk.services.keyspaces.model.*; public class GetTableWithPreWarmingExample { public static void main(String[] args) { KeyspacesClient keyspacesClient = KeyspacesClient.builder().build(); // Get table details including PreWarming specification GetTableRequest request = GetTableRequest.builder() .keyspaceName("catalog") .tableName("book_awards") .build(); GetTableResponse response = keyspacesClient.getTable(request); // Access PreWarming details if (response.warmThroughputSpecification() != null) { WarmThroughputSpecificationSummary warmThroughputSummary = response.warmThroughputSpecification(); System.out.println("PreWarming Status: " + warmThroughputSummary.status()); System.out.println("Read Units: " + warmThroughputSummary.readUnitsPerSecond()); System.out.println("Write Units: " + warmThroughputSummary.writeUnitsPerSecond()); // Check if PreWarming is active if (warmThroughputSummary.status().equals("AVAILABLE")) { System.out.println("Table is fully pre-warmed and ready for high throughput"); } else if (warmThroughputSummary.status().equals("UPDATING")) { System.out.println("Table PreWarming is currently being updated"); } } else { System.out.println("Table does not have PreWarming enabled"); } } } ``` ------ # Monitor the performance of a pre-warmed table using Amazon CloudWatch Amazon Keyspaces pre-warming doesn't introduce new CloudWatch metrics, but you can monitor the performance of pre-warmed tables using existing Amazon Keyspaces metrics: SuccessfulRequestLatency Monitor this metric to verify that the pre-warmed table is handling requests with expected latency. WriteThrottleEvents and ReadThrottleEvents These metrics should remain low for a properly pre-warmed table. If you see insufficient capacity errors despite pre-warming, you might need to adjust your warm-throughput values. ConsumedReadCapacityUnits and ConsumedWriteCapacityUnits These metrics show the actual consumption of capacity, which can help validate if your pre-warming configuration is appropriate. ProvisionedReadCapacityUnits and ProvisionedWriteCapacityUnits For provisioned tables, these metrics show the currently allocated capacity. These metrics can be viewed in the CloudWatch console or queried using the CloudWatch API. For more information, see [Monitoring Amazon Keyspaces with Amazon CloudWatch](monitoring-cloudwatch.md).