# Use workgroups to control query access and costs
You can use Athena workgroups to separate workloads, control team access, enforce configuration, and track query metrics and control costs.
**Separate your workloads**
You can use workgroups to separate workloads. For example, you can create two independent workgroups, one for automated scheduled applications, such as report generation, and another for ad-hoc usage by analysts.
**Control access by teams**
Because workgroups act as IAM resources, you can use resource-level identity-based policies to control who can access a workgroup and run queries in it. To isolate queries for two different teams in your organization, you can create a separate workgroup for each team. Each workgroup has its own query history and a list of saved queries for the queries in that workgroup, and not for all queries in the account. For more information, see [Use IAM policies to control workgroup access](workgroups-iam-policy.md).
**Enforce configuration**
You can optionally enforce the same workgroup-wide settings for all queries that run in the workgroup. These settings include query results location in Amazon S3, expected bucket owner, encryption, and control of objects written to the query results bucket. For more information, see [Override client-side settings](workgroups-settings-override.md).
**Track query metrics, query events, and control costs**
To track query metrics, query events, and control costs for each Athena workgroup, you can use the following features:
+ **Publish query metrics** – Publish the query metrics for your workgroup to CloudWatch. In the Athena console, you can view query metrics for each workgroup. In CloudWatch, you can create custom dashboards, and set thresholds and alarms on these metrics. For more information, see [Enable CloudWatch query metrics in Athena](athena-cloudwatch-metrics-enable.md) and [Monitor Athena query metrics with CloudWatch](query-metrics-viewing.md).
+ **Monitor Athena usage metrics** – See how your account uses resources by displaying your current service usage through CloudWatch graphs and dashboards. For more information, see [Monitor Athena usage metrics with CloudWatch](monitoring-athena-usage-metrics.md)
+ **Monitor query events** – Use Amazon EventBridge to receive real-time notifications regarding the state of your queries. For more information, see [Monitor Athena query events with EventBridge](athena-events.md).
+ **Create data usage controls** – In Athena, you can configure per-query and per-workgroup data usage controls. Athena cancels queries when they exceed the specified threshold or activates an Amazon SNS alarm when a workgroup threshold is breached. For more information, see [Configure per-query and per-workgroup data usage controls](workgroups-setting-control-limits-cloudwatch.md).
+ **Use cost allocation tags** – Use the Billing and Cost Management console to tag workgroups with cost allocation tags. The costs associated with running queries in the workgroup appear in your Cost and Usage Reports with the corresponding cost allocation tag. For more information, see [Using user-defined cost allocation tags](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/custom-tags.html) in the *AWS Billing User Guide*.
+ **Use capacity reservations** – You can create capacity reservations with the number of data processing units that you specify and add one or more workgroups to the reservation. For more information, see [Manage query processing capacity](capacity-management.md).
For additional information about using Athena workgroups to separate workloads, control user access, and manage query usage and costs, see the AWS Big Data Blog post [Separate queries and managing costs using Amazon Athena workgroups](https://aws.amazon.com/blogs/big-data/separating-queries-and-managing-costs-using-amazon-athena-workgroups/).
**Note**
Amazon Athena resources can now be accessed within Amazon SageMaker Unified Studio (Preview), which helps you access your organization's data and act on it with the best tools. You can migrate saved queries from an Athena workgroup to a SageMaker Unified Studio project, configure projects with existing Athena workgroups, and maintain necessary permissions through IAM role updates. For more information, see [Migrating Amazon Athena resources to Amazon SageMaker Unified Studio (Preview)](https://github.com/aws/Unified-Studio-for-Amazon-Sagemaker/tree/main/migration/athena).
## Considerations and limitations
When you use workgroups in Athena, keep in mind the following points:
+ Each account has a primary workgroup. By default, if you have not created any workgroups, all queries in your account run in the primary workgroup. The primary workgroup cannot be deleted. The default permissions allow all authenticated users access to this workgroup.
+ When you have access to a workgroup, you can view the workgroup's settings, metrics, and data usage control limits. With additional permissions, you can edit the settings and data usage control limits.
+ When you run queries, they run in the current workgroup. You can run queries in the context of a workgroup in the console, through API operations, through the command line interface, or through a client application by using a JDBC or ODBC driver.
+ In the Athena console query editor, you can open up to ten query tabs within each workgroup. When you switch between workgroups, your query tabs remain open for a maximum of three workgroups.
+ You can create up to 1000 workgroups per AWS Region in your account.
+ Workgroups can be disabled. Disabling a workgroup prevents queries from running in the workgroup until you re-enable the workgroup.
+ Athena warns you if you attempt to delete a workgroup that contains saved queries. Before you delete a workgroup to which other users have access, make sure they have access to another workgroup that they can use to run queries.
**Topics**
+ [Considerations and limitations](#workgroups-considerations-limitations)
+ [Create a workgroup](creating-workgroups.md)
+ [Manage workgroups](workgroups-create-update-delete.md)
+ [Use CloudWatch and EventBridge to monitor queries](workgroups-control-limits.md)
+ [Use Athena workgroup APIs](workgroups-api-list.md)
+ [Troubleshoot workgroups](workgroups-troubleshooting.md)
# Create a workgroup
Creating a workgroup requires permissions to `CreateWorkgroup` API actions. See [Configure access to workgroups and tags](workgroups-access.md) and [Use IAM policies to control workgroup access](workgroups-iam-policy.md). If you are adding tags, you also need to add permissions to `TagResource`. See [Tag policy examples for workgroups](tags-access-control.md#tag-policy-examples-workgroups).
The following procedure shows how to use the Athena console to create a workgroup. To create a workgroup using the Athena API, see [CreateWorkGroup](https://docs.aws.amazon.com/athena/latest/APIReference/API_CreateWorkGroup.html).
**To create a workgroup in the Athena console**
1. Decide which workgroups to create. A few factors to consider include:
+ Who can run queries in each workgroup, and who owns workgroup configuration. Use IAM policies to enforce workgroup permissions. For more information, see [Use IAM policies to control workgroup access](workgroups-iam-policy.md).
+ The location in Amazon S3 to use for the query results for the workgroup. All users of the workgroup must have access to this location.
+ Whether the workgroup query results must be encrypted. Because encryption is per-workgroup (not per query), you should create separate workgroups for encrypted and non-encrypted query results. For more information, see [Encrypt Athena query results stored in Amazon S3](encrypting-query-results-stored-in-s3.md).
1. If the console navigation pane is not visible, choose the expansion menu on the left.
![\[Choose the expansion menu.\]](http://docs.aws.amazon.com/athena/latest/ug/images/nav-pane-expansion.png)
1. In the Athena console navigation pane, choose **Workgroups**.
1. On the **Workgroups** page, choose **Create workgroup**.
1. On the **Create workgroup** page, fill in the fields as follows:
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/athena/latest/ug/creating-workgroups.html)
1. Choose **Create workgroup**. The workgroup appears in the list on the **Workgroups** page.
In the query editor, Athena displays the current workgroup in the **Workgroup** option on the upper right of the console. You can use this option to switch workgroups. When you run queries, they run in the current workgroup.
1. Create IAM policies for your users, groups, or roles to enable their access to workgroups. The policies establish the workgroup membership and access to actions on a `workgroup` resource. For more information, see [Use IAM policies to control workgroup access](workgroups-iam-policy.md). For example JSON policies, see [Configure access to workgroups and tags](workgroups-access.md).
1. (Optional) Configure a minimal level of encryption in Amazon S3 for all query results from the workgroup when workgroup-wide encryption is not enforced by the override client-side settings option. You can use this feature to ensure that query results are never stored in an Amazon S3 bucket in an unencrypted state. For more information, see [Configure minimum encryption for a workgroup](workgroups-minimum-encryption.md).
1. (Optional) Use Amazon CloudWatch and Amazon EventBridge to monitor your workgroup's queries and control costs. For more information, see [Use CloudWatch and EventBridge to monitor queries and control costs](workgroups-control-limits.md).
1. (Optional) Use the Billing and Cost Management console to tag the workgroup with cost allocation tags. For more information, see [Using user-defined cost allocation tags](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/custom-tags.html) in the *AWS Billing User Guide*.
1. (Optional) To get dedicated processing capacity for the queries in the workgroup, add the workgroup to a capacity reservation. You can assign one or more workgroups to a reservation. For more information, see [Manage query processing capacity](capacity-management.md).
# Override client-side settings
When you create or edit a workgroup, you can choose the option **Override client-side settings**. This option is not selected by default. Depending on whether you select it, Athena does the following:
+ If **Override client-side settings** is not selected, workgroup settings are not enforced at the client level. When the override client-side settings option is not selected for the workgroup, Athena uses the client's settings for all queries that run in the workgroup, including the settings for query results location, expected bucket owner, encryption, and control of objects written to the query results bucket. Each user can specify their own settings in the **Settings** menu on the console. If the client-side settings are not set, the workgroup-wide settings apply. If you use the AWS CLI, API actions, or JDBC and ODBC drivers to run queries in a workgroup that does not override client-side settings, your queries use the settings that you specify in your queries.
+ If **Override client-side settings** is selected, workgroup settings are enforced at the workgroup level for all clients in the workgroup. When the override client-side settings option is selected for the workgroup, Athena uses the workgroup's settings for all queries that run in the workgroup, including the settings for query results location, expected bucket owner, encryption, and control of objects written to the query results bucket. Workgroup settings override any client-side settings that you specify for a query when you use the console, API actions, or JDBC or ODBC drivers. After workgroup settings are set to override client-side settings, client-side settings in the drivers or the API can be omitted.
If you override client-side settings, then the next time that you or any workgroup user opens the Athena console, Athena notifies you that queries in the workgroup use the workgroup's settings, and prompts you to acknowledge this change.
**Note**
Because overriding client-side settings can break custom automation that is based on the availability of results in an arbitrary Amazon S3 bucket, we recommend that you inform your users before overriding.
**Important**
If you use API actions, the AWS CLI, or the JDBC and ODBC drivers to run queries in a workgroup that overrides client-side settings, make sure that you either omit the client-side settings in your queries or update them to match the settings of the workgroup.
If you specify client-side settings in your queries but run them in a workgroup that overrides the settings, the queries will run, but the workgroup settings will be used. For information about viewing the settings for a workgroup, see [View the workgroup's details](viewing-details-workgroups.md).
# Manage workgroups
In the Athena console at [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home), you can perform the following tasks:
| Statement | Description |
| --- | --- |
| [Create a workgroup](creating-workgroups.md) | Create a new workgroup. |
| [View the workgroup's details](viewing-details-workgroups.md) | View the workgroup's details, such as its name, description, data usage limits, location of query results, expected query results bucket owner, encryption, and control of objects written to the query results bucket. You can also verify whether this workgroup enforces its settings, if Override client-side settings is checked. |
| [Specify a workgroup for queries](specify-wkgroup-to-athena-in-which-to-run-queries.md) | Before you can run queries, you must specify to Athena which workgroup to use. You must have permissions to the workgroup. |
| [Switch workgroups](switching-workgroups.md) | Switch between workgroups to which you have access. |
| [Edit a workgroup](editing-workgroups.md) | Edit a workgroup and change its settings. You cannot change a workgroup's name, but you can create a new workgroup with the same settings and a different name. |
| [Enable or disable a workgroup](workgroups-enabled-disabled.md) | Enable or disable a workgroup. When a workgroup is disabled, its users cannot run queries, or create new named queries. If you have access to it, you can still view metrics, data usage limit controls, workgroup's settings, query history, and saved queries. |
| [Copy a saved query between workgroups](copy-a-query-between-workgroups.md) | Copy a saved query between workgroups. You might want to do this if, for example, you created a query in a preview workgroup and you want to make it available in a nonpreview workgroup. |
| [Delete a workgroup](deleting-workgroups.md) | Delete a workgroup. If you delete a workgroup, query history, saved queries, the workgroup's settings and per-query data limit controls are deleted. The workgroup-wide data limit controls remain in CloudWatch, and you can delete them individually. The primary workgroup cannot be deleted. |
| [Use IAM policies to control workgroup access](workgroups-iam-policy.md) | Use IAM policies to control workgroup access. For example workgroup policies, see [Example workgroup policies](example-policies-workgroup.md). |
| [Create an Athena workgroup that uses IAM Identity Center authentication](workgroups-identity-center.md) | To use IAM Identity Center identities with Athena, you must create an IAM Identity Center enabled workgroup. After you create the workgroup, you can use the IAM Identity Center console or API to assign IAM Identity Center users or groups to the workgroup. |
| [Configure minimum encryption for a workgroup](workgroups-minimum-encryption.md) | Enforce a minimal level of encryption in Amazon S3 for all query results from the workgroup. Use this feature to ensure that query results are never stored in an Amazon S3 bucket in an unencrypted state. |
# View the workgroup's details
For each workgroup, you can view its details. The details include the workgroup's name, description, whether it is enabled or disabled, and the settings used for queries that run in the workgroup, which include the location of the query results, expected bucket owner, encryption, and control of objects written to the query results bucket. If a workgroup has data usage limits, they are also displayed.
**To view the workgroup's details**
1. In the Athena console navigation pane, choose **Workgroups**.
1. On the **Workgroups** page, choose the link of the workgroup that you want to view. The **Overview Details** page for the workgroup displays.
# Specify a workgroup for queries
To specify a workgroup to use, you must have permissions to the workgroup.
**To specify the workgroup to use**
1. Make sure your permissions allow you to run queries in a workgroup that you intend to use. For more information, see [Use IAM policies to control workgroup access](workgroups-iam-policy.md).
1. To specify the workgroup, use one of these options:
+ If you are using the Athena console, set the workgroup by [switching workgroups](switching-workgroups.md).
+ If you are using the Athena API operations, specify the workgroup name in the API action. For example, you can set the workgroup name in [StartQueryExecution](https://docs.aws.amazon.com/athena/latest/APIReference/API_StartQueryExecution.html), as follows:
```
StartQueryExecutionRequest startQueryExecutionRequest = new StartQueryExecutionRequest()
.withQueryString(ExampleConstants.ATHENA_SAMPLE_QUERY)
.withQueryExecutionContext(queryExecutionContext)
.withWorkGroup(WorkgroupName)
```
+ If you are using the JDBC or ODBC driver, set the workgroup name in the connection string using the `Workgroup` configuration parameter. The driver passes the workgroup name to Athena. Specify the workgroup parameter in the connection string as in the following example:
```
jdbc:awsathena://AwsRegion=;UID=;
PWD=;S3OutputLocation=s3://amzn-s3-demo-bucket/-/;
Workgroup=;
```
# Switch workgroups
You can switch from one workgroup to another if you have permissions to both of them.
You can open up to ten query tabs within each workgroup. When you switch between workgroups, your query tabs remain open for up to three workgroups.
**To switch workgroups**
1. In the Athena console, use the **Workgroup** option on the upper right to choose a workgroup.
1. If the **Workgroup *workgroup-name* settings** dialog box appears, choose **Acknowledge**.
The **Workgroup** option shows the name of the workgroup that you switched to. You can now run queries in this workgroup.
# Edit a workgroup
Editing a workgroup requires permissions to `UpdateWorkgroup` API operations. See [Configure access to workgroups and tags](workgroups-access.md) and [Use IAM policies to control workgroup access](workgroups-iam-policy.md). If you are adding or editing tags, you also need to have permissions to `TagResource`. See [Tag policy examples for workgroups](tags-access-control.md#tag-policy-examples-workgroups).
**To edit a workgroup in the console**
1. In the Athena console navigation pane, choose **Workgroups**.
1. On the **Workgroups** page, select the button for the workgroup that you want to edit.
1. Choose **Actions**, **Edit**.
1. Change the fields as needed. For the list of fields, see [Create workgroup](creating-workgroups.md). You can change all fields except for the workgroup's name. If you need to change the name, create another workgroup with the new name and the same settings.
1. Choose **Save changes**. The updated workgroup appears in the list on the **Workgroups** page.
# Enable or disable a workgroup
If you have permissions to do so, you can enable or disable workgroups in the console, by using the API operations, or with the JDBC and ODBC drivers.
**To enable or disable a workgroup**
1. In the Athena console navigation pane, choose **Workgroups**.
1. On the **Workgroups** page, choose the link for the workgroup.
1. On the upper right, choose **Enable workgroup** or **Disable workgroup**.
1. At the confirmation prompt, choose **Enable** or **Disable**. If you disable a workgroup, its users cannot run queries in it, or create new named queries. If you enable a workgroup, users can use it to run queries.
# Copy a saved query between workgroups
Currently, the Athena console does not have an option to to copy a saved query from one workgroup to another directly, but you can perform the same task manually by using the following procedure.
**To copy a saved query between workgroups**
1. In the Athena console, from the workgroup that you want to copy the query from, choose the **Saved queries** tab.
1. Choose the link of the saved query that you want to copy. Athena opens the query in the query editor.
1. In the query editor, select the query text, and then press **Ctrl\$1C** to copy it.
1. [Switch](switching-workgroups.md) to the destination workgroup, or [create a workgroup](creating-workgroups.md), and then switch to it.
1. Open a new tab in the query editor, and then press **Ctrl\$1V** to paste the text into the new tab.
1. In the query editor, choose **Save as** to save the query in the destination workgroup.
1. In the **Choose a name** dialog box, enter a name for the query and an optional description.
1. Choose **Save**.
# Delete a workgroup
You can delete a workgroup if you have permissions to do so. The primary workgroup cannot be deleted.
If you have permissions, you can delete an empty workgroup at any time. You can also delete a workgroup that contains saved queries. In this case, before proceeding to delete a workgroup, Athena warns you that saved queries are deleted.
If you delete a workgroup while you are in it, the console switches focus to the primary workgroup. If you have access to it, you can run queries and view its settings.
If you delete a workgroup, its settings and per-query data limit controls are deleted. The workgroup-wide data limit controls remain in CloudWatch, and you can delete them there if needed.
**Important**
Before deleting a workgroup, ensure that its users also belong to other workgroups where they can continue to run queries. If the users' IAM policies allowed them to run queries *only* in this workgroup, and you delete it, they no longer have permissions to run queries. For more information, see [Example policy for running queries in the primary workgroup](example-policies-workgroup.md#example4-run-in-primary-access).
**To delete a workgroup in the console**
1. In the Athena console navigation pane, choose **Workgroups**.
1. On the **Workgroups** page, select the button for the workgroup that you want to delete.
1. Choose **Actions**, **Delete**.
1. At the **Delete workgroup** confirmation prompt, enter the name of the workgroup, and then choose **Delete**.
To delete a workgroup with the API operation, use the `DeleteWorkGroup` action.
# Use CloudWatch and EventBridge to monitor queries and control costs
Workgroups allow you to set data usage control limits per query or per workgroup, set up alarms when those limits are exceeded, and publish query metrics to CloudWatch.
In each workgroup, you can:
+ Configure **Data usage controls** per query and per workgroup, and establish actions that will be taken if queries breach the thresholds.
+ View and analyze query metrics, and publish them to CloudWatch. If you create a workgroup in the console, the setting for publishing the metrics to CloudWatch is selected for you. If you use the API operations, you must [enable publishing the metrics](athena-cloudwatch-metrics-enable.md). When metrics are published, they are displayed under the **Metrics** tab in the **Workgroups** panel. Metrics are disabled by default for the primary workgroup.
## Video
The following video shows how to create custom dashboards and set alarms and triggers on metrics in CloudWatch. You can use pre-populated dashboards directly from the Athena console to consume these query metrics.
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/x1V_lhkdKCg)
**Topics**
+ [Video](#athena-cloudwatch-metrics-video)
+ [Enable query metrics](athena-cloudwatch-metrics-enable.md)
+ [Monitor query metrics with CloudWatch](query-metrics-viewing.md)
+ [Monitor usage metrics with CloudWatch](monitoring-athena-usage-metrics.md)
+ [Monitor query events with EventBridge](athena-events.md)
+ [Configure data usage controls](workgroups-setting-control-limits-cloudwatch.md)
# Enable CloudWatch query metrics in Athena
When you create a workgroup in the console, the setting for publishing query metrics to CloudWatch is selected by default.
**To enable or disable query metrics in the Athena console for a workgroup**
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.
![\[Choose the expansion menu.\]](http://docs.aws.amazon.com/athena/latest/ug/images/nav-pane-expansion.png)
1. In the navigation pane, choose **Workgroups**.
1. Choose the link of the workgroup that you want to modify.
1. On the details page for the workgroup, choose **Edit**.
1. In the **Settings** section, select or clear **Publish query metrics to AWS CloudWatch**.
If you use API operations, the command line interface, or the client application with the JDBC driver to create workgroups, to enable publishing of query metrics, set `PublishCloudWatchMetricsEnabled` to `true` in [WorkGroupConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_WorkGroupConfiguration.html). The following example shows only the metrics configuration and omits other configuration:
```
"WorkGroupConfiguration": {
"PublishCloudWatchMetricsEnabled": "true"
....
}
```
# Monitor Athena query metrics with CloudWatch
Athena publishes query-related metrics to Amazon CloudWatch, when the [publish query metrics to CloudWatch](athena-cloudwatch-metrics-enable.md) option is selected. You can create custom dashboards, set alarms and triggers on metrics in CloudWatch, or use pre-populated dashboards directly from the Athena console.
When you enable query metrics for queries in workgroups, the metrics are displayed within the **Metrics** tab in the **Workgroups** panel, for each workgroup in the Athena console.
Athena publishes the following metrics to the CloudWatch console:
+ `DPUAllocated` – The total number of DPUs (data processing units) provisioned in a capacity reservation to run queries.
+ `DPUConsumed` – The number of DPUs actively consumed by queries in a `RUNNING` state at a given time in a reservation. Metric emitted only when workgroup is associated with a capacity reservation and includes all workgroups associated with a reservation.
+ `DPUCount` – The maximum number of DPUs consumed by your query, published exactly once as the query completes.
+ `EngineExecutionTime` – The number of milliseconds that the query took to run.
+ `ProcessedBytes` – The number of bytes that Athena scanned per DML query.
+ `QueryPlanningTime` – The number of milliseconds that Athena took to plan the query processing flow.
+ `QueryQueueTime` – The number of milliseconds that the query was in the query queue waiting for resources.
+ `ServicePreProcessingTime` – The number of milliseconds that Athena took to preprocess the query before submitting the query to the query engine.
+ `ServiceProcessingTime` – The number of milliseconds that Athena took to process the query results after the query engine finished running the query.
+ `TotalExecutionTime` – The number of milliseconds that Athena took to run a DDL or DML query.
For more complete descriptions, see the [List of CloudWatch metrics and dimensions for Athena](#athena-cloudwatch-metrics-table) later in this document.
These metrics have the following dimensions:
+ `CapacityReservation` – The name of the capacity reservation used to execute the query, if applicable.
+ `QueryState` – `SUCCEEDED`, `FAILED`, or `CANCELED`
+ `QueryType` – `DML`, `DDL`, or `UTILITY`
+ `WorkGroup` – name of the workgroup
Athena publishes the following metric to the CloudWatch console under the `AmazonAthenaForApacheSpark` namespace:
+ `DPUCount` – number of DPUs consumed during the session to execute the calculations.
This metric has the following dimensions:
+ `SessionId` – The ID of the session in which the calculations are submitted.
+ `WorkGroup` – Name of the workgroup.
For more information, see the [List of CloudWatch metrics and dimensions for Athena](#athena-cloudwatch-metrics-table) later in this topic. For information about Athena usage metrics, see [Monitor Athena usage metrics with CloudWatch](monitoring-athena-usage-metrics.md).
You can view query metrics in the Athena console or in the CloudWatch console.
## View query metrics in the Athena console
**To view query metrics for a workgroup in the Athena console**
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.
![\[Choose the expansion menu.\]](http://docs.aws.amazon.com/athena/latest/ug/images/nav-pane-expansion.png)
1. In the navigation pane, choose **Workgroups**.
1. Choose the workgroup that you want from the list, and then choose the **Metrics** tab.
The metrics dashboard displays.
**Note**
If you just recently enabled metrics for the workgroup and/or there has been no recent query activity, the graphs on the dashboard may be empty. Query activity is retrieved from CloudWatch depending on the interval that you specify in the next step.
1. In the **Metrics** section, choose the metrics interval that Athena should use to fetch the query metrics from CloudWatch, or specify a custom interval.
![\[Specifying the metrics retrieval interval for a workgroup in the Athena console.\]](http://docs.aws.amazon.com/athena/latest/ug/images/wg-custom-interval.png)
1. To refresh the displayed metrics, choose the refresh icon.
![\[Choose the refresh icon.\]](http://docs.aws.amazon.com/athena/latest/ug/images/wg-refresh-metrics.png)
1. Click the arrow next to the refresh icon to choose how frequently you want the metrics display to be updated.
![\[Choosing a refresh interval for the workgroup metrics display in the Athena console.\]](http://docs.aws.amazon.com/athena/latest/ug/images/wg-choose-refresh-interval.png)
## View query metrics in the CloudWatch console
**To view metrics in the Amazon CloudWatch console**
1. Open the CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. In the navigation pane, choose **Metrics**, **All metrics**.
1. Select the **AWS/Athena** namespace.
## View query metrics with the AWS CLI
**To view metrics with the AWS CLI**
+ Do one of the following:
+ To list the metrics for Athena, open a command prompt, and use the following command:
```
aws cloudwatch list-metrics --namespace "AWS/Athena"
```
+ To list all available metrics, use the following command:
```
aws cloudwatch list-metrics"
```
## List of CloudWatch metrics and dimensions for Athena
If you've enabled CloudWatch metrics in Athena, it sends the following metrics to CloudWatch per workgroup. The following metrics use the `AWS/Athena` namespace.
| Metric name | Description |
| --- | --- |
| DPUAllocated | The total number of DPUs (data processing units) provisioned in a capacity reservation to run queries. |
| DPUConsumed | The number of DPUs actively consumed by queries in a RUNNING state at a given time in a reservation. This metric is emitted only when workgroup is associated with a capacity reservation and includes all workgroups associated with a reservation. If you move a workgroup from one reservation to another, the metric includes data from the time when the workgroup belonged to the first reservation. For more information about capacity reservations, see [Manage query processing capacity](capacity-management.md). |
| DPUCount | The maximum number of DPUs consumed by your query, published exactly once as the query completes. This metric is emitted only for workgroups that are attached to a capacity reservation. |
| EngineExecutionTime | The number of milliseconds that the query took to run. |
| ProcessedBytes | The number of bytes that Athena scanned per DML query. For queries that were canceled (either by the users, or automatically, if they reached the limit), this includes the amount of data scanned before the cancellation time. This metric is not reported for DDL queries. |
| QueryPlanningTime | The number of milliseconds that Athena took to plan the query processing flow. This includes the time spent retrieving table partitions from the data source. Note that because the query engine performs the query planning, query planning time is a subset of EngineExecutionTime. |
| QueryQueueTime | The number of milliseconds that the query was in the query queue waiting for resources. Note that if transient errors occur, the query can be automatically added back to the queue. |
| ServicePreProcessingTime | The number of milliseconds that Athena took to preprocess the query before submitting the query to the query engine. |
| ServiceProcessingTime | The number of milliseconds that Athena took to process the query results after the query engine finished running the query. |
| TotalExecutionTime | The number of milliseconds that Athena took to run a DDL or DML query. TotalExecutionTime includes QueryQueueTime, QueryPlanningTime, EngineExecutionTime, and ServiceProcessingTime. |
These metrics for Athena have the following dimensions.
| Dimension | Description |
| --- | --- |
| CapacityReservation | The name of the capacity reservation that was used to execute the query, if applicable. When a capacity reservation is not used, this dimension returns no data. |
| QueryState | The query state. Valid statistics: SUCCEEDED, FAILED, or CANCELED. |
| QueryType | The query type. Valid statistics: `DDL`, `DML`, or `UTILITY`. The type of query statement that was run. `DDL` indicates DDL (Data Definition Language) query statements. `DML` indicates DML (Data Manipulation Language) query statements, such as `CREATE TABLE AS SELECT`. `UTILITY` indicates query statements other than DDL and DML, such as `SHOW CREATE TABLE`, or `DESCRIBE TABLE`. |
| WorkGroup | The name of the workgroup. |
# Monitor Athena usage metrics with CloudWatch
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 for Athena. You can configure alarms that alert you when your usage approaches a service quota. For more information about Athena service quotas, see [Service Quotas](service-limits.md). For more information about AWS usage metrics, see [AWS usage metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Service-Quota-Integration.html) in the *Amazon CloudWatch User Guide*.
Athena publishes the following metrics in the `AWS/Usage` namespace.
| Metric name | Description |
| --- | --- |
| `ResourceCount` | The sum of all queued and executing queries per AWS Region per account, separated by query type (DML or DDL). Maximum is the only useful statistic for this metric. This metric publishes periodically every minute. If you are not running any queries, the metric reports nothing (not even 0). The metric publishes only if active queries are running at the time the metric is taken. |
The following dimensions are used to refine the usage metrics that are published by Athena.
| Dimension | Description |
| --- | --- |
| `Service` | The name of the AWS service containing the resource. For Athena, the value for this dimension is `Athena`. |
| `Resource` | The type of resource that is running. The resource value for Athena query usage is `ActiveQueryCount`. |
| `Type` | The type of entity that's being reported. Currently, the only valid value for Athena usage metrics is `Resource`. |
| `Class` | The class of resource being tracked. For Athena, `Class` can be `DML` or `DDL`. |
## View Athena resource usage metrics in the CloudWatch console
You can use the CloudWatch console to see a graph of Athena usage metrics and configure alarms that alert you when your usage approaches a service quota.
**To view Athena resource usage metrics**
1. Open the CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. In the navigation pane, choose **Metrics**, **All metrics**.
1. Choose **Usage**, and then choose **By AWS Resource**.
The list of service quota usage metrics appears.
1. Select the check box that is next to **Athena** and **ActiveQueryCount**.
1. Choose the **Graphed metrics** tab.
The graph above displays your current usage of the AWS resource.
For information about adding service quotas to the graph and setting an alarm that notifies you if you approach the service quota, see [Visualizing your service quotas and setting alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Quotas-Visualize-Alarms.html) in the *Amazon CloudWatch User Guide*. For information about setting usage limits per workgroup, see [Configure per-query and per-workgroup data usage controls](workgroups-setting-control-limits-cloudwatch.md).
# Monitor Athena query events with EventBridge
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 transitions states, Athena publishes an event to EventBridge containing information about that 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 example, you can create a rule that invokes an AWS Lambda function when a query reaches a terminal state. Events are emitted on a best effort basis.
Before you create event rules for Athena, you should do the following:
+ Familiarize yourself with events, rules, and targets in EventBridge. For more information, see [What Is Amazon EventBridge?](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-what-is.html) For more information about how to set up rules, see [Getting started with Amazon EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-get-started.html).
+ Create the target or targets to use in your event rules.
**Note**
Athena currently offers one type of event, Athena Query State Change, but may add other event types and details. If you are programmatically deserializing event JSON data, make sure that your application is prepared to handle unknown properties if additional properties are added.
## Athena event format
The following is the basic pattern for an Amazon Athena event.
```
{
"source":[
"aws.athena"
],
"detail-type":[
"Athena Query State Change"
],
"detail":{
"currentState":[
"SUCCEEDED"
]
}
}
```
## Athena query state change event
The following example shows an Athena Query State Change event with the `currentState` value of `SUCCEEDED`.
```
{
"version":"0",
"id":"abcdef00-1234-5678-9abc-def012345678",
"detail-type":"Athena Query State Change",
"source":"aws.athena",
"account":"123456789012",
"time":"2019-10-06T09:30:10Z",
"region":"us-east-1",
"resources":[
],
"detail":{
"versionId":"0",
"currentState":"SUCCEEDED",
"previousState":"RUNNING",
"statementType":"DDL",
"queryExecutionId":"01234567-0123-0123-0123-012345678901",
"workgroupName":"primary",
"sequenceNumber":"3"
}
}
```
The following example shows an Athena Query State Change event with the `currentState` value of `FAILED`. The `athenaError` block appears only when `currentState` is `FAILED`. For information about the values for `errorCategory` and `errorType`, see [Athena error catalog](error-reference.md).
```
{
"version":"0",
"id":"abcdef00-1234-5678-9abc-def012345678",
"detail-type":"Athena Query State Change",
"source":"aws.athena",
"account":"123456789012",
"time":"2019-10-06T09:30:10Z",
"region":"us-east-1",
"resources":[
],
"detail":{
"athenaError": {
"errorCategory": 2.0, //Value depends on nature of exception
"errorType": 1306.0, //Type depends on nature of exception
"errorMessage": "Amazon S3 bucket not found", //Message depends on nature of exception
"retryable":false //Retryable value depends on nature of exception
},
"versionId":"0",
"currentState": "FAILED",
"previousState": "RUNNING",
"statementType":"DML",
"queryExecutionId":"01234567-0123-0123-0123-012345678901",
"workgroupName":"primary",
"sequenceNumber":"3"
}
}
```
### Output properties
The JSON output includes the following properties.
****
| Property | Description |
| --- | --- |
| athenaError | Appears only when currentState is FAILED. Contains information about the error that occurred, including the error category, error type, error message, and whether the action that led to the error can be retried. Values for each of these fields depend on the nature of the error. For information about the values for errorCategory and errorType, see [Athena error catalog](error-reference.md). |
| versionId | The version number for the detail object's schema. |
| currentState | The state that the query transitioned to at the time of the event. |
| previousState | The state that the query transitioned from at the time of the event. |
| statementType | The type of query statement that was run. |
| queryExecutionId | The unique identifier for the query that ran. |
| workgroupName | The name of the workgroup in which the query ran. |
| sequenceNumber | A monotonically increasing number that allows for deduplication and ordering of incoming events that involve a single query that ran. When duplicate events are published for the same state transition, the sequenceNumber value is the same. When a query experiences a state transition more than once, such as queries that experience rare requeuing, you can use sequenceNumber to order events with identical currentState and previousState values. |
## Example
The following example publishes events to an Amazon SNS topic to which you have subscribed. When Athena is queried, you receive an email. The example assumes that the Amazon SNS topic exists and that you have subscribed to it.
**To publish Athena events to an Amazon SNS topic**
1. Create the target for your Amazon SNS topic. Give the EventBridge events Service Principal `events.amazonaws.com` permission to publish to your Amazon SNS topic, as in the following example.
```
{
"Effect":"Allow",
"Principal":{
"Service":"events.amazonaws.com"
},
"Action":"sns:Publish",
"Resource":"arn:aws:sns:us-east-1:111111111111:your-sns-topic"
}
```
1. Use the AWS CLI `events put-rule` command to create a rule for Athena events, as in the following example.
```
aws events put-rule --name {ruleName} --event-pattern '{"source": ["aws.athena"]}'
```
1. Use the AWS CLI `events put-targets` command to attach the Amazon SNS topic target to the rule, as in the following example.
```
aws events put-targets --rule {ruleName} --targets Id=1,Arn=arn:aws:sns:us-east-1:111111111111:your-sns-topic
```
1. Query Athena and observe the target being invoked. You should receive corresponding emails from the Amazon SNS topic.
## Use AWS User Notifications with Amazon Athena
You can use [AWS User Notifications](https://docs.aws.amazon.com/notifications/latest/userguide/what-is.html) to set up delivery channels to get notified about Amazon Athena events. You receive a notification when an event matches a rule that you specify. You can receive notifications for events through multiple channels, including email, [Amazon Q Developer in chat applications](https://docs.aws.amazon.com/chatbot/latest/adminguide/what-is.html) chat notifications, or [AWS Console Mobile Application](https://docs.aws.amazon.com/consolemobileapp/latest/userguide/what-is-consolemobileapp.html) push notifications. You can also see notifications in the [Console Notifications Center](https://console.aws.amazon.com/notifications/). User Notifications supports aggregation, which can reduce the number of notifications you receive during specific events.
For more information, see the [https://docs.aws.amazon.com/notifications/latest/userguide/what-is.html](https://docs.aws.amazon.com/notifications/latest/userguide/what-is.html).
# Configure per-query and per-workgroup data usage controls
Athena allows you to set two types of cost controls: per-query limit and per-workgroup limit. For each workgroup, you can set only one per-query limit and multiple per-workgroup limits.
+ The **per-query control limit** specifies the total amount of data scanned per query. If any query that runs in the workgroup exceeds the limit, it is canceled. You can create only one per-query control limit in a workgroup and it applies to each query that runs in it. Edit the limit if you need to change it. For detailed steps, see [To create a per-query data usage control](#configure-control-limit-per-query).
+ The **workgroup-wide data usage control limit** specifies the total amount of data scanned for all queries that run in this workgroup during the specified time period. You can create multiple limits per workgroup. The workgroup-wide query limit allows you to set multiple thresholds on hourly or daily aggregates on data scanned by queries running in the workgroup.
If the aggregate amount of data scanned exceeds the threshold, you can push a notification to an Amazon SNS topic. To do this, you configure an Amazon SNS alarm and an action in the Athena console to notify an administrator when the limit is breached. For detailed steps, see [To create a per-workgroup data usage control](#configure-control-limit-per-workgroup). You can also create an alarm and an action on any metric that Athena publishes from the CloudWatch console. For example, you can set an alert on a number of failed queries. This alert can trigger an email to an administrator if the number crosses a certain threshold. If the limit is exceeded, an action sends an Amazon SNS alarm notification to the specified users.
Other actions you can take:
+ Invoke a Lambda function. For more information, see [Invoking Lambda functions using Amazon SNS notifications](https://docs.aws.amazon.com/sns/latest/dg/sns-lambda-as-subscriber.html) in the *Amazon Simple Notification Service Developer Guide*.
+ Disable the workgroup to stop any further queries from running. For steps, see [Enable or disable a workgroup](workgroups-enabled-disabled.md).
The per-query and per-workgroup limits are independent of each other. A specified action is taken whenever either limit is exceeded. If two or more users run queries at the same time in the same workgroup, it is possible that each query does not exceed any of the specified limits, but the total sum of data scanned exceeds the data usage limit per workgroup. In this case, an Amazon SNS alarm is sent to the user.
## Create a per-query data usage control
**To create a per-query data usage control**
The per-query control limit specifies the total amount of data scanned per query. If any query that runs in the workgroup exceeds the limit, it is canceled. Canceled queries are charged according to [Amazon Athena pricing](https://aws.amazon.com/athena/pricing/).
**Note**
In the case of canceled or failed queries, Athena may have already written partial results to Amazon S3. In such cases, Athena does not delete partial results from the Amazon S3 prefix where results are stored. You must remove the Amazon S3 prefix with partial results. Athena uses Amazon S3 multipart uploads to write data Amazon S3. We recommend that you set the bucket lifecycle policy to end multipart uploads in cases when queries fail. For more information, see [Aborting incomplete multipart uploads using a bucket lifecycle policy](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html#mpu-abort-incomplete-mpu-lifecycle-config) in the *Amazon Simple Storage Service User Guide*.
Under certain conditions, Athena may automatically retry query executions. In most cases, these queries are able to complete successfully and the query ID is marked as `Completed`. These queries might have written partial results during the initial attempts and may generate incomplete multipart uploads.
You can create only one per-query control limit in a workgroup and it applies to each query that runs in it. Edit the limit if you need to change it.
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. Choose the name of the workgroup from the list.
1. On the **Execution controls** tab, choose **Edit controls**.
1. Edit the value for **Data scanned limit**.
+ Specify a value between 10 MB (minimum) and 7 EB (maximum).
+ Select a unit value from the drop-down list (for example, **Kilobytes KB** or **Exabytes EB**).
**Note**
The default action is to cancel the query if it exceeds the limit. This setting cannot be changed.
1. Choose **Save** to immediatly apply your changes.
## Create or edit a per-workgroup data usage alert
**To create or edit a per-workgroup data usage alert**
You can set multiple alert thresholds when queries running in a workgroup scan a specified amount of data within a specific period. Alerts are implemented using Amazon CloudWatch alarms and apply to all queries in the workgroup. When a threshold is reached, you can have Amazon SNS send an email to users that you specify. Queries are not automatically canceled when a threshold is reached.
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. In the navigation pane, choose **Workgroups**.
1. Choose the name of the workgroup from the list.
1. Choose **Edit** to edit the workgroup's settings.
1. Scroll down to and expand **Workgroup data usage alerts - optional**.
1. Choose **Add alert**.
1. For **Data usage threshold configuration**, specify values as follows:
+ For **Data threshold**, specify a number, and then select a unit value from the drop-down list.
+ **For Time period**, choose a time period from the drop-down list.
+ For **SNS topic selection**, choose an Amazon SNS topic from the drop-down list. Or, choose **Create SNS topic** to go directly to the [Amazon SNS console](https://console.aws.amazon.com/sns/v2/home), create the Amazon SNS topic, and set up a subscription for it for one of the users in your Athena account. For more information, see [Getting started with Amazon SNS](https://docs.aws.amazon.com/sns/latest/dg/sns-getting-started.html) in the *Amazon Simple Notification Service Developer Guide*.
1. Choose **Add alert** if you are creating a new alert, or **Save** to save an existing alert.
# Use Athena workgroup APIs
The following are some of the REST API operations used for Athena workgroups. In all of the following operations except for `ListWorkGroups`, you must specify a workgroup. In other operations, such as `StartQueryExecution`, the workgroup parameter is optional and the operations are not listed here. For the full list of operations, see [Amazon Athena API Reference](https://docs.aws.amazon.com/athena/latest/APIReference/).
+ [CreateWorkGroup](https://docs.aws.amazon.com/athena/latest/APIReference/API_CreateWorkGroup.html)
+ [DeleteWorkGroup](https://docs.aws.amazon.com/athena/latest/APIReference/API_DeleteWorkGroup.html)
+ [GetWorkGroup](https://docs.aws.amazon.com/athena/latest/APIReference/API_GetWorkGroup.html)
+ [ListWorkGroups](https://docs.aws.amazon.com/athena/latest/APIReference/API_ListWorkGroups.html)
+ [UpdateWorkGroup](https://docs.aws.amazon.com/athena/latest/APIReference/API_UpdateWorkGroup.html)
# Troubleshoot workgroup errors
Use the following tips to troubleshoot workgroups.
+ Check permissions for individual users in your account. They must have access to the location for query results, and to the workgroup in which they want to run queries. If they want to switch workgroups, they too need permissions to both workgroups. For information, see [Use IAM policies to control workgroup access](workgroups-iam-policy.md).
+ Pay attention to the context in the Athena console, to see in which workgroup you are going to run queries. If you use the driver, make sure to set the workgroup to the one you need. For information, see [Specify a workgroup for queries](specify-wkgroup-to-athena-in-which-to-run-queries.md).
+ If you use the API or the drivers to run queries, you must specify the query results location using one of the following ways: for individual queries, use [OutputLocation](https://docs.aws.amazon.com/athena/latest/APIReference/API_ResultConfiguration.html#athena-Type-ResultConfiguration-OutputLocation) (client-side). In the workgroup, use [WorkGroupConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_WorkGroupConfiguration.html). If the location is not specified in either way, Athena issues an error at query runtime.
+ If you override client-side settings with workgroup settings, you may encounter errors with query result location. For example, a workgroup's user may not have permissions to the workgroup's location in Amazon S3 for storing query results. In this case, add the necessary permissions.
+ Workgroups introduce changes in the behavior of the API operations. Calls to the following existing API operations require that users in your account have resource-based permissions in IAM to the workgroups in which they make them. If no permissions to the workgroup and to workgroup actions exist, the following API actions throw `AccessDeniedException`: **CreateNamedQuery**, **DeleteNamedQuery**, **GetNamedQuery**, **ListNamedQueries**, **StartQueryExecution**, **StopQueryExecution**, **ListQueryExecutions**, **GetQueryExecution**, **GetQueryResults**, and **GetQueryResultsStream** (this API action is only available for use with the driver and is not exposed otherwise for public use). 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*.
Calls to the **BatchGetQueryExecution** and **BatchGetNamedQuery** API operations return information only about queries that run in workgroups to which users have access. If the user has no access to the workgroup, these API operations return the unauthorized query IDs as part of the unprocessed IDs list. For more information, see [Use Athena workgroup APIs](workgroups-api-list.md).
+ If the workgroup in which a query will run is configured with an [enforced query results location](workgroups-settings-override.md), do not specify an `external_location` for the CTAS query. Athena issues an error and fails a query that specifies an `external_location` in this case. For example, this query fails, if you override client-side settings for query results location, enforcing the workgroup to use its own location: `CREATE TABLE . WITH (format='Parquet', external_location='s3://amzn-s3-demo-bucket/test/') AS SELECT * FROM . LIMIT 10;`
You may see the following errors. This table provides a list of some of the errors related to workgroups and suggests solutions.
**Workgroup errors**
| Error | Occurs when... |
| --- | --- |
| query state CANCELED. Bytes scanned limit was exceeded. | A query hits a per-query data limit and is canceled. Consider rewriting the query so that it reads less data, or contact your account administrator. |
| User: arn:aws:iam::123456789012:user/abc is not authorized to perform: athena:StartQueryExecution on resource: arn:aws:athena:us-east-1:123456789012:workgroup/workgroupname | A user runs a query in a workgroup, but does not have access to it. Update your policy to have access to the workgroup. |
| INVALID\$1INPUT. WorkGroup is disabled. | A user runs a query in a workgroup, but the workgroup is disabled. Your workgroup could be disabled by your administrator. It is possible also that you don't have access to it. In both cases, contact an administrator who has access to modify workgroups. |
| INVALID\$1INPUT. WorkGroup is not found. | A user runs a query in a workgroup, but the workgroup does not exist. This could happen if the workgroup was deleted. Switch to another workgroup to run your query. |
| InvalidRequestException: when calling the StartQueryExecution operation: No output location provided. An output location is required either through the Workgroup result configuration setting or as an API input. | A user runs a query with the API without specifying the location for query results. You must set the output location for query results using one of the two ways: either for individual queries, using [OutputLocation](https://docs.aws.amazon.com/athena/latest/APIReference/API_ResultConfiguration.html#athena-Type-ResultConfiguration-OutputLocation) (client-side), or in the workgroup, using [WorkGroupConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_WorkGroupConfiguration.html). |
| The Create Table As Select query failed because it was submitted with an 'external\$1location' property to an Athena Workgroup that enforces a centralized output location for all queries. Please remove the 'external\$1location' property and resubmit the query. | If the workgroup in which a query runs is configured with an [enforced query results location](workgroups-settings-override.md), and you specify an external\$1location for the CTAS query. In this case, remove the external\$1location and rerun the query. |
| Cannot create prepared statement prepared\$1statement\$1name. The number of prepared statements in this workgroup exceeds the limit of 1000. | The workgroup contains more than the limit of 1000 prepared statements. To work around this issue, use [DEALLOCATE PREPARE](sql-deallocate-prepare.md) to remove one or more prepared statements from the workgroup. Alternatively, create a new workgroup. |