# Manage query processing capacity
You can use capacity reservations to get dedicated serverless processing capacity for the queries you run in Athena. With capacity reservations, you can take advantage of workload management capabilities that help you prioritize, control, and scale your most important workloads. For example, you can add capacity to control the number of queries you can run at the same time, choose which workloads can use the capacity, and share capacity among workloads. Capacity is serverless and fully-managed by Athena and held for you as long as you need it. Setup is easy and no changes to your SQL queries are required.
To get processing capacity for your queries, you create a capacity reservation, specify the number of Data Processing Units (DPUs) that you require, and assign one or more workgroups to the reservation.
Workgroups play an important role when you use capacity reservations. Workgroups allow you to organize queries into logical groupings or use cases. With capacity reservations, you selectively assign capacity to workgroups so that you control how the queries for each workgroup behave and how they are billed. For more information about workgroups, see [Use workgroups to control query access and costs](workgroups-manage-queries-control-costs.md).
Assigning workgroups to capacity reservations lets you give priority to these queries because they run on your reserved capacity and do not count towards your DDL and DML query quota. For example, you can allocate capacity to a workgroup used for time-sensitive financial reporting queries to isolate those queries from less critical queries in another workgroup. This gives you predictable query execution for critical workloads while allowing other workloads to run independently.
You can use capacity reservations and workgroups together to meet different requirements. The following are some example scenarios:
+ **Isolate important queries** – To ensure that an important workload has the capacity it needs when you need it, create a capacity reservation and assign its workgroup to the reservation. Only queries from the assigned workgroup use the processing capacity from your reservation. For example, to ensure reliable execution of queries that support a production application, assign the production workgroup for those queries to a capacity reservation. When developing queries, use a separate workgroup that is not associated with a reservation and move the queries to the production workgroup when ready.
+ **Share capacity across similar workloads** – Multiple workloads can share capacity from one reservation. This allows you to achieve a predictable cost for these workloads and control their concurrency. For example, if you have scheduled workloads that are tolerant to delayed query execution start times, you can assign their workgroups to a single reservation. This frees up your DDL and DML query quota for interactive queries that run in the same account, ensuring these queries start with minimal delay.
## Understand DPUs
Capacity is measured in Data Processing Units (DPUs). DPUs represent the serverless compute and memory resources used by Athena to access and process data on your behalf. One DPU typically provides 4 vCPUs and 16 GB of memory. The number of DPUs that you hold influences the number of queries that you can run concurrently. For example, a reservation with 256 DPUs can support approximately twice the number of concurrent queries than a reservation with 128 DPUs.
For information about estimating your capacity requirements, see [Determine capacity requirements](capacity-management-requirements.md). For pricing information, see [Amazon Athena pricing](https://aws.amazon.com/athena/pricing/).
## Considerations and limitations
+ You can use capacity reservations and per-query billing, based on data scanned, at the same time in the same account.
+ Queries run on capacity reservations do not count towards your DDL and DML query quota.
+ If your capacity is busy serving other queries, newly submitted queries are queued until capacity is available. The maximum allowed time in queue is 10 hours.
+ A workgroup can be assigned to one capacity reservation at a time. You can assign a total of 20 workgroups to a single reservation. When you assign multiple workgroups to a reservation, capacity is shared across workgroups and allocated to queries based on their submission order. There may be variation in execution order due to how Athena dynamically allocates capacity to queries.
+ Athena automatically allocates between 4 and 124 DPUs to DML queries based on their complexity. DDL queries consume 4 DPUs each. Refer to the following topics for more information:
+ [Determine capacity requirements](capacity-management-requirements.md)
+ [Control capacity usage](capacity-management-control-capacity-usage.md)
+ The minimum number of DPUs required with each capacity reservation is 4. For pricing information, see [Amazon Athena pricing](https://aws.amazon.com/athena/pricing/).
+ You can create up to 100 capacity reservations with up to 1,000 total DPUs per account and region. If you require more than 1,000 DPUs for your use case, please reach out to [athena-feedback@amazon.com](mailto:athena-feedback@amazon.com?subject=Athena Provisioned Capacity DPU Limit Request).
+ Requests for capacity are not guaranteed and can take up to 30 minutes to complete. Capacity is not transferable to another capacity reservation, AWS account, or AWS Region.
+ The `DPUConsumed` CloudWatch metric is per-workgroup rather than per-reservation. Thus, if you move a workgroup from one reservation to another, the `DPUConsumed` metric includes data from the time when the workgroup belonged to the first reservation. For more information about using CloudWatch metrics in Athena, see [Monitor Athena query metrics with CloudWatch](query-metrics-viewing.md).
+ To delete a workgroup that has been assigned to a reservation, remove the workgroup from the reservation first.
+ Workgroups configured to use Apache Spark are not supported.
+ Capacity reservations is not available in the following commercial AWS Regions:
+ Israel (Tel Aviv)
+ Middle East (UAE)
+ Middle East (Bahrain)
+ Asia Pacific (New Zealand)
**Topics**
+ [Understand DPUs](#capacity-management-understanding-dpus)
+ [Considerations and limitations](#capacity-management-considerations-limitations)
+ [Determine capacity requirements](capacity-management-requirements.md)
+ [Create capacity reservations](capacity-management-creating-capacity-reservations.md)
+ [Control capacity usage](capacity-management-control-capacity-usage.md)
+ [Automatically adjust capacity](capacity-management-automatically-adjust-capacity.md)
+ [Manage reservations](capacity-management-managing-reservations.md)
+ [IAM policies for capacity reservations](capacity-reservations-iam-policy.md)
+ [Athena capacity reservation APIs](capacity-management-api-list.md)
# Determine capacity requirements
Before you create a capacity reservation, you can estimate the capacity required so that you can assign it the correct number of DPUs. And, after a reservation is in use, you might want to check the reservation for insufficient or excess capacity. This topic describes techniques that you can use to make these estimates and also describes some AWS tools for assessing usage and cost.
**Topics**
+ [Estimate required capacity](#capacity-management-requirements-estimating)
+ [Signs that more capacity is required](#capacity-management-requirements-insufficient-capacity)
+ [Check for idle capacity](#capacity-management-requirements-idle-capacity)
+ [Monitoring DPU consumption](#capacity-management-requirements-monitoring-dpu-consumption)
## Estimate required capacity
When estimating capacity requirements, it is useful to consider two perspectives: how much capacity a particular query might require, and how much capacity you might need in general.
### Estimate per-query capacity requirements
To determine the number of DPUs that a query might would require, you can use the following guidelines:
+ DDL queries consume 4 DPUs.
+ DML queries consume between 4 and 124 DPUs.
Athena determines the number of DPUs required by a DML query when the query is submitted. The number varies based on data size, storage format, query construction, and other factors. Generally, Athena tries to select the lowest, most efficient DPU number. If Athena determines that more computational power is required for the query to complete successfully, it increases the number of DPUs assigned to the query.
### Estimate workload specific capacity requirements
To determine how much capacity you might require to run multiple queries at the same time, consider the general guidelines in the following table:
****
| Concurrent queries | DPUs required |
| --- | --- |
| 10 | 40 or more |
| 20 | 96 or more |
| 30 or more | 240 or more |
Note that the actual number of DPUs that you need depends on your goals and analysis patterns. For example, if you want queries to start immediately without queuing, determine your peak concurrent query demand, and then provision the number of DPUs accordingly.
You can provision fewer DPUs than your peak demand, but queuing may result when peak demand occurs. When queuing occurs, Athena holds your queries in a queue and runs them when capacity becomes available.
If your goal is to run queries within a fixed budget, you can use the [AWS Pricing Calculator](https://calculator.aws/#/addService/Athena) to determine the number of DPUs that fit your budget.
Lastly, remember that data size, storage format, and how a query is written influence the DPUs that a query requires. To increase query performance, you can compress or partition your data or convert it into columnar formats. For more information, see [Optimize Athena performance](performance-tuning.md).
## Signs that more capacity is required
Insufficient capacity error messages and query queuing are two indications that your assigned capacity is inadequate.
If your queries fail with an insufficient capacity error message, your capacity reservation's DPU count is too low for your query. For example, if you have a reservation with 24 DPUs and run a query that requires more than 24 DPUs, the query will fail. To monitor for this query error, you can use Athena's [EventBridge events](athena-events.md). Try adding more DPUs and re-running your query.
If many queries are queued, it means your capacity is fully utilized by other queries. To reduce the queuing, do one of the following:
+ Add DPUs to your reservation to increase query concurrency.
+ Remove workgroups from your reservation to free up capacity for other queries.
To check for excessive query queuing, use the Athena query queue time [CloudWatch metric](query-metrics-viewing.md) for the workgroups in your capacity reservation. If the value is above your preferred threshold, you can add DPUs to the capacity reservation.
## Check for idle capacity
To check for idle capacity, you can either decrease the number of DPUs in the reservation or increase its workload, and then observe the results.
**To check for idle capacity**
1. Do one of the following:
+ Reduce the number of DPUs in your reservation (reduce the resources available)
+ Add workgroups to your reservation (increase the workload)
1. Use [CloudWatch](query-metrics-viewing.md) to measure the query queue time.
1. If the queue time increases beyond a desirable level, do one of the following
+ Remove workgroups
+ Add DPUs to your capacity reservation
1. After each change, check the performance and query queue time.
1. Continue to adjust the workload and/or DPU count to attain the desired balance.
If you do not want to maintain capacity outside a preferred time period, you can [cancel](capacity-management-cancelling-a-capacity-reservation.md) the reservation and create another reservation later. However, even if you recently cancelled capacity from another reservation, requests for new capacity are not guaranteed, and new reservations take time to create.
## Monitoring DPU consumption
After your queries run, you can view the DPU consumed by your queries to help refine your capacity estimates. Athena provides DPU consumption metrics through the console, API operations, and CloudWatch. This information helps you identify queries that consume more or fewer resources than expected and optimize your capacity allocation based on real-world data. For detailed information about viewing and tracking DPU consumption, see [Monitor DPU usage](capacity-management-control-capacity-usage.md#capacity-management-monitor-dpu-usage).
## Tools for assessing capacity requirements and cost
You can use the following services and features in AWS to measure your Athena usage and costs.
### CloudWatch metrics
You can configure Athena to publish query-related metrics to Amazon CloudWatch at the workgroup level. After you enable metrics for the workgroup, the metrics for the workgroup's queries are displayed in the Athena console on the workgroup's details page.
For information about the Athena metrics published to CloudWatch and their dimensions, see [Monitor Athena query metrics with CloudWatch](query-metrics-viewing.md).
### CloudWatch usage metrics
You can use CloudWatch usage metrics to provide visibility into your how your account uses resources by displaying your current service usage on CloudWatch graphs and dashboards. For Athena, usage availability metrics correspond to AWS [service quotas](service-limits.md) for Athena. You can configure alarms that alert you when your usage approaches a service quota.
For more information, see [Monitor Athena usage metrics with CloudWatch](monitoring-athena-usage-metrics.md).
### Amazon EventBridge events
You can use Amazon Athena with Amazon EventBridge to receive real-time notifications regarding the state of your queries. When a query you have submitted changes states, Athena publishes an event to EventBridge that contains information about the query state transition. You can write simple rules for events that are of interest to you and take automated actions when an event matches a rule.
For more information, see the following resources.
+ [Monitor Athena query events with EventBridge](athena-events.md)
+ [What Is Amazon EventBridge?](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-what-is.html)
+ [Amazon EventBridge events](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events.html)
### Tags
In Athena, capacity reservations support tags. A tag consists of a key and a value. To track your costs in Athena, you can use AWS-generated cost allocation tags. AWS uses the cost allocation tags to organize your resource costs on your [Cost and Usage Report](https://docs.aws.amazon.com/cur/latest/userguide/what-is-cur.html). This makes it easier for you to categorize and track your AWS costs. To activate cost allocation tags for Athena, you use the [AWS Billing and Cost Management console](https://console.aws.amazon.com/billing/).
For more information, see the following resources.
+ [Tag Athena resources](tags.md)
+ [Activating the AWS-generated cost allocation tags](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/activate-built-in-tags.html)
+ [Using AWS cost allocation tags](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/cost-alloc-tags.html)
# Create capacity reservations
To get started, you create a capacity reservation that has the number of DPUs that you require, and then assign one or more workgroups that will use that capacity for their queries. You can adjust your capacity later as needed to provide more consistent performance or better manage costs. For information about estimating your capacity requirements, see [Determine capacity requirements](capacity-management-requirements.md).
**Important**
Requests for capacity are not guaranteed and can take up to 30 minutes to complete.
**To create a capacity reservation**
1. Open the Athena console at [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home).
1. If the console navigation pane is not visible, choose the expansion menu on the left.
1. Choose **Administration**, **Capacity reservations**.
1. Choose **Create capacity reservation**.
1. On the **Create capacity reservation** page, for **Capacity reservation name**, enter name. The name must be unique, from 1 to 128 characters long, and use only the characters a-z, A-Z, 0-9, \$1(underscore), .(period) and -(hyphen).You cannot change the name after you create the reservation.
1. For **DPU**, choose or enter the number of data processing units (DPUs) that you want in increments of 4. For more information, see [Understand DPUs](capacity-management.md#capacity-management-understanding-dpus).
1. (Optional) Expand the **Tags** option, and then choose **Add new tag** to add one or more custom key/value pairs to associate with the capacity reservation resource. For more information, see [Tag Athena resources](tags.md).
1. Choose **Review**.
1. At the **Confirm create capacity reservation** prompt, confirm the number of DPUs, AWS Region, and other information. If you accept, choose **Submit**.
On the details page, your capacity reservation's **Status** shows as **Pending**. When your reservation capacity is available to run queries, its status shows as **Active**.
At this point, you are ready to add one or more workgroups to your reservation. For steps, see [Add workgroups to a reservation](capacity-management-adding-workgroups-to-a-reservation.md).
# Control capacity usage
You can control the number of DPU that Athena allocates to your queries by setting maximum or minimum DPU controls. You can configure these at the workgroup level to establish baseline controls for all queries, or at the individual query level for fine-grained control. This gives you direct control over query performance, workload concurrency, and cost.
+ When you set a maximum number of DPU, queries are prevented from consuming more capacity than you specify. This makes it simple to control cost and workload concurrency. For example, if your capacity reservation has 200 DPU, setting the maximum DPU per query to 8 allows you to run 25 queries concurrently. If you increase your reservation to 400 DPU, you can run 50 queries concurrently.
+ When you set a minimum number of DPU, you ensure queries are executed with a desired minimum number of DPU. This is helpful when you know the typical capacity usage profile for your queries in advance.
**Note**
DPU usage controls only apply to queries executed with capacity reservations.
**Note**
To use the same number of DPU for all queries, use the same value for the minimum and maximum DPU.
## Set DPU controls at the workgroup level
Set DPU controls at the workgroup level to manage costs and control workload performance for the workgroup that you choose. DPU controls set at the workgroup level apply to all queries when **Override client-side settings** is enabled.
**To set DPU controls using the console**
1. Open the Athena console at [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home).
1. In the navigation pane, choose **Workgroups**.
1. Select a workgroup that uses a capacity reservation.
1. On the **Execution controls** tab, choose **Edit controls**.
1. Configure the following:
+ For **Min DPU per query**, enter a value between 4 and 124 in increments of 4.
+ For **Max DPU per query**, enter a value between 4 and 124 in increments of 4.
1. Choose **Save**.
1. (Optional) Select **Override client-side settings** to enforce these settings and ignore query-level DPU configurations.
**To set DPU controls using the AWS CLI**
+ Use the `update-work-group` command to set DPU controls for a workgroup:
```
aws athena update-work-group \
--work-group my_workgroup \
--configuration-updates '{
"EngineConfiguration": {
"Classifications": [
{
"Name": "athena-query-engine-properties",
"Properties": {
"max-dpu-count" : "24",
"min-dpu-count" : "12"
}
}
]
}}'
```
If you set `EnforceWorkGroupConfiguration` to `true`, the workgroup settings override any DPU controls specified at the query level when submitted via [StartQueryExecution](https://docs.aws.amazon.com/athena/latest/APIReference/API_StartQueryExecution.html). This ensures consistent resource allocation across all queries in the workgroup.
## Set DPU controls with individual queries
Set query-level DPU controls when you need fine-grained control with queries that have different resource requirements. Query-level DPU controls take precedence over workgroup-level settings unless the workgroup has **Override client-side settings** enabled.
**To set DPU controls for a query using the console**
1. Open the Athena console at [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home).
1. In the navigation pane, choose **Query editor**.
1. Select a workgroup that uses a capacity reservation.
1. Choose the **Query settings** tab.
1. In the **Execution controls** section, choose **Edit controls**.
1. Configure the following:
+ For **Min DPU per query**, enter a value between 4 and 124 in increments of 4.
+ For **Max DPU per query**, enter a value between 4 and 124 in increments of 4.
1. Choose **Save**.
**To set DPU controls for a query using the AWS CLI**
+ Use the `start-query-execution` command with the `engine-configuration` parameter:
```
aws athena start-query-execution \
--query-string "SELECT * FROM my_table LIMIT 10" \
--work-group "my_workgroup" \
--engine-configuration '{
"Classifications": [ {
"Name": "athena-query-engine-properties",
"Properties": {
"max-dpu-count" : "32",
"min-dpu-count" : "8"
}
}
]}'
```
The relationship between query-level and workgroup-level DPU settings depends on your workgroup configuration:
+ When **Override client-side settings** is enabled, workgroup-level DPU controls take precedence over any query-level settings. This ensures consistent resource usage for all queries in the specified workgroup.
+ When **Override client-side settings** is not enabled, query-level DPU controls take precedence over workgroup-level settings. This allows flexibility for optimizing individual queries.
If you don't specify DPU controls at either level, Athena automatically allocates capacity based on query complexity.
**Note**
For DDL queries, the maximum value for minimum DPUs is 4. Setting a higher minimum for DDL queries results in an error.
## Monitor DPU usage
After your queries complete, you can view its DPU usage. Athena provides DPU usage metrics through the console, API operations, and CloudWatch.
**To view DPU consumption in the console**
1. Open the Athena console at [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home).
1. In the navigation pane, choose **Query editor**.
1. After a query completes, view its **Consumed DPU** value in the query results container.
1. To view DPU consumption for past queries:
1. Choose **Recent queries** in the navigation pane.
1. Select the settings icon to add the **Consumed DPU** column to the table if not already displayed.
1. Review the DPU consumption for each completed query.
1. Optionally, from the **Query editor**, choose the **Query stats** tab and review the **Consumed DPU**.
**To retrieve DPU consumption using the API**
1. Use the following API operations to retrieve DPU consumption programmatically:
+ `GetQueryExecution` - Returns execution details for a specific query
+ `BatchGetQueryExecution` - Returns execution details for multiple queries
1. Example using the AWS CLI:
```
aws athena get-query-execution \
--query-execution-id "123e4567-e89b-12d3-a456-426614174000"
```
The response includes the `DpuCount` field in the `Statistics` object:
```
{
"QueryExecution": {
"Statistics": {
"DpuCount": 8
}
}
}
```
**To monitor DPU usage with CloudWatch**
+ Athena publishes query-related metrics to CloudWatch that help you monitor capacity utilization and other performance data. To learn more, see [Monitor Athena query metrics with CloudWatch](query-metrics-viewing.md).
# Automatically adjust capacity
You can automatically adjust the capacity of your reservation in response to workload utilization using Athena's auto-scaling solution. It automatically adds capacity when utilization exceeds your configured threshold and removes capacity during periods of low utilization to reduce costs. You can customize its behavior by setting different utilization thresholds, minimum and maximum DPU quantities, scaling increments, and utilization evaluation frequency. This eliminates manual capacity adjustments while helping you balance performance requirements with cost optimization.
You deploy this serverless solution using a CloudFormation template. It creates a Step Functions state machine which monitors utilization metrics and makes scaling decisions. You can further customize the template or state machine to meet your specific needs.
To get started, use the Athena console and choose **Set up auto-scaling** on your capacity reservation detail page, which redirects you to CloudFormation with the template pre-loaded. Alternatively, follow the procedure below.
## Prerequisites
+ An active capacity reservation is required
+ Required IAM permissions for deploying CloudFormation stacks and creating Step Functions resources
## Launch the CloudFormation stack
This automated CloudFormation template deploys the Athena Capacity Reservation auto-scaling solution. You must complete the applicable steps in [Prerequisites](#capacity-management-auto-scaling-prerequisites) before launching the stack.
[https://console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/new?&templateURL=https:%2F%2Fathena-downloads.s3.us-east-1.amazonaws.com%2F%2Ftemplates%2F%2Fcapacity-reservation-scaling%2F%2Fstate-machine%2F%2Fathena-capacity-reservation-scaling-template-v1.1.yaml](https://console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/new?&templateURL=https:%2F%2Fathena-downloads.s3.us-east-1.amazonaws.com%2F%2Ftemplates%2F%2Fcapacity-reservation-scaling%2F%2Fstate-machine%2F%2Fathena-capacity-reservation-scaling-template-v1.1.yaml)
**To launch the auto-scaling solution**
1. Sign into [AWS Management Console](https://console.aws.amazon.com/) and select the button to launch the `AWSAccelerator-InstallerStack` CloudFormation template.
1. The template launches in the US East (N. Virginia) by default. To launch the solution in a different AWS Region, use the Region selector in the console navigation bar.
1. On the **Create stack** page, verify that the template URL is in the **Amazon S3 URL** text box and choose **Next**.
1. On the **Specify stack details** page, assign a name to your solution stack.
1. Under **Parameters**, review the parameters for this solution template and modify them as necessary. This solution uses the following default values.
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/athena/latest/ug/capacity-management-automatically-adjust-capacity.html)
**Note**
All DPU values must be multiples of 4 to comply with Athena's capacity reservation requirements.
1. Choose **Next**.
1. On the **Configure stack options** page, choose **Next**.
1. On the **Review and create** page, review and confirm the settings. Select the box acknowledging that the template might create IAM resources.
1. Choose **Submit** to deploy the stack.
You can view the status of the stack in the CloudFormation console in the **Status** column. You should receive a `CREATE_COMPLETE` status in a few minutes.
# Manage reservations
You can view and manage your capacity reservations on the **Capacity reservations** page. You can perform management tasks like adding or reducing DPUs, modifying workgroup assignments, and tagging or cancelling reservations.
**To view and manage capacity reservations**
1. Open the Athena console at [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home).
1. If the console navigation pane is not visible, choose the expansion menu on the left.
1. Choose **Administration**, **Capacity reservations**.
1. On the capacity reservations page, you can perform the following tasks:
+ To create a capacity reservation, choose **Create capacity reservation**.
+ Use the search box to filter reservations by name or number of DPUs.
+ Choose the status drop-down menu to filter by capacity reservation status (for example, **Active** or **Cancelled**). For information about reservation status, see [Understand reservation status](#capacity-management-understanding-reservation-status).
+ To view details for a capacity reservation, choose the link for the reservation. The details page for the reservation includes options for [editing capacity](capacity-management-editing-capacity-reservations.md), [adding workgroups](capacity-management-adding-workgroups-to-a-reservation.md), [removing workgroups](capacity-management-removing-a-workgroup-from-a-reservation.md), and for [cancelling](capacity-management-cancelling-a-capacity-reservation.md) the reservation.
+ To edit a reservation (for example, by adding or removing DPUs), select the button for the reservation, and then choose **Edit**.
+ To cancel a reservation, select the button for the reservation, and then choose **Cancel**.
## Understand reservation status
The following table describes the possible status values for a capacity reservation.
****
| Status | Description |
| --- | --- |
| Pending | Athena is processing your capacity request. Capacity is not ready to run queries. |
| Active | Capacity is available to run queries. |
| Failed | Your request for capacity was not completed successfully. Note that fulfillment of capacity requests is not guaranteed. Failed reservations count towards your account DPU limits. To release the usage, you must cancel the reservation. |
| Update pending | Athena is processing a change to the reservation. For example, this status occurs after you edit the reservation to add or remove DPUs. |
| Cancelling | Athena is processing a request to cancel the reservation. Queries that are still running in the workgroups that were using the reservation are allowed to finish, but other queries in the workgroup will use on-demand (non-provisioned) capacity. |
| Cancelled | The capacity reservation cancellation is complete. Cancelled reservations remain in the console for 45 days. After 45 days, Athena will delete the reservation. During the 45 days, you cannot re-purpose or reuse the reservation, but you can refer to its tags and view its details for historical reference. Cancelled capacity is not guaranteed to be re-reservable at a future date. Capacity cannot be transferred to another reservation, AWS account or AWS Region. |
## Understand Active DPUs and Target DPUs
In the list of capacity reservations in the Athena console, your reservation displays two DPU values: **Active DPU** and **Target DPU**.
+ **Active DPU** – The number of DPUs that are available in your reservation to run queries. For example, if you request 100 DPUs, and your request is fulfilled, **Active DPU** displays **100**.
+ **Target DPU** – The number of DPUs that your reservation is in the process of moving to. **Target DPU** displays a value different than **Active DPU** when a reservation is being created, or an increase or decrease in the number of DPUs is pending.
For example, after you submit a request to create a reservation with 24 DPUs, the reservation **Status** will be **Pending**, **Active DPU** will be **0**, and the **Target DPU** will be **24**.
If you have a reservation with 100 DPUs, and edit your reservation to request an increase of 20 DPUs, the **Status** will be **Update pending**, **Active DPU** will be **100**, and **Target DPU** will be **120**.
If you have a reservation with 100 DPUs, and edit your reservation to request a decrease of 20 DPUs, the **Status** will be **Update pending**, **Active DPU** will be **100**, and **Target DPU** will be **80**.
During these transitions, Athena is actively working to acquire or reduce the number of DPUs based on your request. When **Active DPU** becomes equal to **Target DPU**, the target number has been reached and no changes are pending.
To retrieve these values programmatically, you can call the [GetCapacityReservation](https://docs.aws.amazon.com/athena/latest/APIReference/API_GetCapacityReservation.html) API action. The API refers to **Active DPU** and **Target DPU** as `AllocatedDpus` and `TargetDpus`.
**Topics**
+ [Understand reservation status](#capacity-management-understanding-reservation-status)
+ [Understand Active DPUs and Target DPUs](#capacity-management-understanding-dpu-status)
+ [Edit capacity reservations](capacity-management-editing-capacity-reservations.md)
+ [Add workgroups to a reservation](capacity-management-adding-workgroups-to-a-reservation.md)
+ [Remove a workgroup from a reservation](capacity-management-removing-a-workgroup-from-a-reservation.md)
+ [Cancel a capacity reservation](capacity-management-cancelling-a-capacity-reservation.md)
+ [Delete a capacity reservation](capacity-management-deleting-a-capacity-reservation.md)
# Edit capacity reservations
After you create a capacity reservation, you can adjust its number of DPUs and add or remove its custom tags.
**To edit a capacity reservation**
1. Open the Athena console at [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home).
1. If the console navigation pane is not visible, choose the expansion menu on the left.
1. Choose **Administration**, **Capacity reservations**.
1. In the list of capacity reservations, do one of the following:
+ Select the button next to the reservation, and then choose **Edit**.
+ Choose the reservation link, and then choose **Edit**.
1. For **DPU**, choose or enter the number of data processing units that you want. For more information, see [Understand DPUs](capacity-management.md#capacity-management-understanding-dpus).
**Note**
You can request to add DPUs to an active capacity reservation at any time.
You can request to decrease DPUs from an active capacity reservation when 1 minute has passed since the reservation became active or when DPUs were last added.
When you request to decrease DPUs, Athena prioritizes removing idle DPUs over active DPUs. If queries are consuming DPUs that are marked for removal, Athena waits for queries to complete before removing the DPUs.
1. (Optional) For **Tags**, choose **Remove** to remove a tag, or choose **Add new tag** to add a new tag.
1. Choose **Submit**. The details page for the reservation shows the updated configuration.
# Add workgroups to a reservation
After you create a capacity reservation, you can add up to 20 workgroups to the reservation. Adding a workgroup to a reservation tells Athena which queries should execute on your reserved capacity. Queries from workgroups that are not associated with a reservation continue to run using the default per terabyte (TB) scanned pricing model.
When a reservation has two or more workgroups, queries from those workgroups can use the reservation's capacity. You can add and remove workgroups at any time. When you add or remove workgroups, queries that are running are not interrupted.
When your reservation is in a pending state, queries from workgroups that you have added continue to run using the default per terabyte (TB) scanned pricing model until the reservation becomes active.
**To add one or more workgroups to your capacity reservation**
1. On the details page for the capacity reservation, choose **Add workgroups**.
1. On the **Add workgroups** page, select the workgroups that you want to add, and then choose **Add workgroups**. You cannot assign a workgroup to more than one reservation.
The details page for your capacity reservation lists the workgroups that you added. Queries that run in those workgroups will use the capacity that you reserved when the reservation is active.
# Remove a workgroup from a reservation
If you no longer require dedicated capacity for a workgroup or want to move a workgroup to its own reservation, you can remove it at any time. Removing a workgroup from a reservation is a straightforward process. After you remove a workgroup from a reservation, queries from the removed workgroup return to using on-demand capacity and are billed based on terabytes (TB) scanned.
**To remove one or more workgroups from a reservation**
1. On the details page for the capacity reservation, select the workgroups that you want to remove.
1. Choose **Remove workgroups**. The **Remove workgroups?** prompt informs you that all currently active queries will finish before the workgroup is removed from the reservation..
1. Choose **Remove**. The details page for your capacity reservation show that the removed workgroups are no longer present.
# Cancel a capacity reservation
If you no longer want to use a capacity reservation, you can cancel it. Queries that are still running in the workgroups that were using the reservation will be allowed to finish, but other queries in the workgroup will no longer use the reservation.
**Note**
Cancelled capacity is not guaranteed to be re-reservable at a future date. Capacity cannot be transferred to another reservation, AWS account or AWS Region.
**To cancel a capacity reservation**
1. Open the Athena console at [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home).
1. If the console navigation pane is not visible, choose the expansion menu on the left.
1. Choose **Administration**, **Capacity reservations**.
1. In the list of capacity reservations, do one of the following:
+ Select the button next to the reservation, and then choose **Cancel**.
+ Choose the reservation link, and then choose **Cancel capacity reservation**.
1. At the **Cancel capacity reservation?** prompt, enter **cancel**, and then choose **Cancel capacity reservation**.
The reservation's status changes to **Cancelling**, and a progress banner informs you that the cancellation is in progress.
When the cancellation is complete, the capacity reservation remains, but its status shows as **Cancelled**. The reservation will be deleted 45 days after cancellation. During the 45 days, you cannot re-purpose or reuse a reservation that has been cancelled, but you can refer to its tags and view it for historical reference.
# Delete a capacity reservation
If you want to remove all references to a cancelled capacity reservation, you can delete the reservation. A reservation must be cancelled before it can be deleted. A deleted reservation is immediately removed from your account and can no longer be referenced, including by its ARN.
**To delete a capacity reservation**
1. Open the Athena console at [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home).
1. If the console navigation pane is not visible, choose the expansion menu on the left.
1. Choose **Administration**, **Capacity reservations**.
1. In the list of capacity reservations, do one of the following:
+ Select the button next to the cancelled reservation, and then choose **Actions**, **Delete**.
+ Choose the reservation link, and then choose **Delete**.
1. At the **Delete capacity reservation?** prompt, choose **Delete**.
A banner informs you that the capacity reservation has been successfully deleted. The deleted reservation no longer appears in the list of capacity reservations.
# IAM policies for capacity reservations
To control access to capacity reservations, use resource-level IAM permissions or identity-based IAM policies. Whenever you use IAM policies, make sure that you follow IAM best practices. For more information, see [Security best practices in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the *IAM User Guide*.
The following procedure is specific to Athena.
For IAM-specific information, see the links listed at the end of this section. For information about example JSON capacity reservations policies, see [Example capacity reservation policies](example-policies-capacity-reservations.md).
**To use the visual editor in the IAM console to create a capacity reservation policy**
1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. In the navigation pane on the left, choose **Policies**, and then choose **Create policy**.
1. On the **Visual editor** tab, choose **Choose a service**. Then choose Athena to add to the policy.
1. Choose **Select actions**, and then choose the actions to add to the policy. The visual editor shows the actions available in Athena. For more information, see [Actions, resources, and condition keys for Amazon Athena](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonathena.html) in the *Service Authorization Reference*.
1. Choose **add actions** to type a specific action or use wild card characters (\$1) to specify multiple actions.
By default, the policy that you are creating allows the actions that you choose. If you chose one or more actions that support resource-level permissions to the `capacity-reservation` resource in Athena, then the editor lists the `capacity-reservation` resource.
1. Choose **Resources** to specify the specific capacity reservations for your policy. For example JSON capacity reservation policies, see [Example capacity reservation policies](example-policies-capacity-reservations.md).
1. Specify the `capacity-reservation` resource as follows:
```
arn:aws:athena:::capacity-reservation/
```
1. Choose **Review policy**, and then type a **Name** and a **Description** (optional) for the policy that you are creating. Review the policy summary to make sure that you granted the intended permissions.
1. Choose **Create policy** to save your new policy.
1. Attach this identity-based policy to a user, a group, or role.
For more information, see the following topics in the *Service Authorization Reference* and *IAM User Guide*:
+ [Actions, resources, and condition keys for Amazon Athena](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonathena.html)
+ [Creating policies with the visual editor](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-visual-editor)
+ [Adding and removing IAM policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)
+ [Controlling access to resources](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_controlling.html#access_controlling-resources)
For example JSON capacity reservation policies, see [Example capacity reservation policies](example-policies-capacity-reservations.md).
For a complete list of Amazon Athena actions, see the API action names in the [Amazon Athena API Reference](https://docs.aws.amazon.com/athena/latest/APIReference/).
# Example capacity reservation policies
This section includes example policies you can use to enable various actions on capacity reservations. Whenever you use IAM policies, make sure that you follow IAM best practices. For more information, see [Security best practices in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the *IAM User Guide*.
A capacity reservation is an IAM resource managed by Athena. Therefore, if your capacity reservation policy uses actions that take `capacity-reservation` as an input, you must specify the capacity reservation's ARN as follows:
```
"Resource": [arn:aws:athena:::capacity-reservation/]
```
Where `` is the name of your capacity reservation. For example, for a capacity reservation named `test_capacity_reservation`, specify it as a resource as follows:
```
"Resource": ["arn:aws:athena:us-east-1:123456789012:capacity-reservation/test_capacity_reservation"]
```
For a complete list of Amazon Athena actions, see the API action names in the [Amazon Athena API Reference](https://docs.aws.amazon.com/athena/latest/APIReference/). For more information about IAM policies, see [Creating policies with the visual editor](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-visual-editor) in the *IAM User Guide*.
**Example policy to list capacity reservations**
The following policy allows all users to list all capacity reservations.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"athena:ListCapacityReservations"
],
"Resource": "*"
}
]
}
```
**Example policy for management operations**
The following policy allows a user to create, cancel, obtain details, and update the capacity reservation `test_capacity_reservation`. The policy also allows a user to assign `workgroupA` and `workgroupB` to `test_capacity_reservation`.
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect": "Allow",
"Action": [
"athena:CreateCapacityReservation",
"athena:GetCapacityReservation",
"athena:CancelCapacityReservation",
"athena:UpdateCapacityReservation",
"athena:GetCapacityAssignmentConfiguration",
"athena:PutCapacityAssignmentConfiguration"
],
"Resource": [
"arn:aws:athena:us-east-1:123456789012:capacity-reservation/test_capacity_reservation",
"arn:aws:athena:us-east-1:123456789012:workgroup/workgroupA",
"arn:aws:athena:us-east-1:123456789012:workgroup/workgroupB"
]
}
]
}
```
# Athena capacity reservation APIs
The following list contains reference links to Athena capacity reservation API actions. For data structures and other Athena API actions, see the [https://docs.aws.amazon.com/athena/latest/APIReference/](https://docs.aws.amazon.com/athena/latest/APIReference/).
+ [CancelCapacityReservation](https://docs.aws.amazon.com/athena/latest/APIReference/API_CancelCapacityReservation.html)
+ [CreateCapacityReservation](https://docs.aws.amazon.com/athena/latest/APIReference/API_CreateCapacityReservation.html)
+ [DeleteCapacityReservation](https://docs.aws.amazon.com/athena/latest/APIReference/API_DeleteCapacityReservation.html)
+ [GetCapacityAssignmentConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_GetCapacityAssignmentConfiguration.html)
+ [GetCapacityReservation](https://docs.aws.amazon.com/athena/latest/APIReference/API_GetCapacityReservation.html)
+ [ListCapacityReservations](https://docs.aws.amazon.com/athena/latest/APIReference/API_ListCapacityReservations.html)
+ [PutCapacityAssignmentConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_PutCapacityAssignmentConfiguration.html)
+ [UpdateCapacityReservation](https://docs.aws.amazon.com/athena/latest/APIReference/API_UpdateCapacityReservation.html)