Create a workgroup

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.

   • 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.

2. If the console navigation pane is not visible, choose the expansion menu on the left.

   

3. In the Athena console navigation pane, choose Workgroups.

4. On the Workgroups page, choose Create workgroup.

5. On the Create workgroup page, fill in the fields as follows:

   Field	Description
   Workgroup name	Required. Enter a unique name for your workgroup. The name can contain from 1 to 128 characters, including alphanumeric characters, dashes, and underscores. After you create a workgroup, you cannot change its name.
   Description	Optional. Enter a description for your workgroup. It can contain up to 1024 characters.
   Choose the type of engine	Choose Athena SQL if you want to run ad-hoc SQL queries on data in Amazon S3 or use a prebuilt data source connector to run federated queries on a variety of data sources external to Amazon S3. You can run queries using the Athena query editor, Amazon CLI, or Athena APIs. Choose Apache Spark if you want to create, edit, and run Jupyter notebook applications using Python and Apache Spark. Jupyter notebooks contain a list of cells that can include code, text, Markdown, mathematics, plots and rich media. Cells are run in order as calculations in an interactive notebook session in Athena. For information about creating and configuring a Spark-enabled workgroup, see Step 1: Create a Spark enabled workgroup in Athena. After you create a workgroup, its analytics engine can be upgraded (for example, from Athena engine version 2 to Athena engine version 3), but its engine type cannot be changed. For example, an Athena engine version 3 workgroup cannot be changed to a PySpark engine version 3 workgroup.
   Update query engine	Choose how you want to update your workgroup when a new Athena engine version is released. You can let Athena decide when to update your workgroup or manually choose an engine version. For more information, see Athena engine versioning.
   Authentication	Choose Amazon Identity and Access Management (IAM) to use IAM authentication or federation for the workgroup. Choose IAM Identity Center if you want to support workforce identities such as users and groups from SAML 2.0 identity providers such as Microsoft Active Directory. For more information, see Use IAM Identity Center enabled Athena workgroups and Trusted identity propagation across applications in the Amazon IAM Identity Center User Guide. You cannot change the type of authentication for the workgroup after the workgroup is created.
   Service role for IAM Identity Center access	Athena requires IAM permissions to access IAM Identity Center on your behalf. For more information about IAM service roles, see Creating a role to delegate permissions to an Amazon service in the IAM User Guide.
   Location of query result	Enter a path to an Amazon S3 bucket or prefix. This bucket and prefix must exist before you can specify them. For information about creating an Amazon S3 bucket, see Create a bucket. Note If you don't specify a query results location for the workgroup or in Settings, the Athena query will fail. If you run queries with the API or the drivers, you must specify query results location in at least one of two places: for individual queries with OutputLocation, or for the workgroup, with WorkGroupConfiguration.
   Expected bucket owner	Optional. Enter the ID of the Amazon Web Services account that you expect to be the owner of the output location bucket. This is an added security measure. If the account ID of the bucket owner does not match the ID that you specify here, attempts to output to the bucket will fail. For in-depth information, see Verifying bucket ownership with bucket owner condition in the Amazon S3 User Guide. Note The expected bucket owner setting applies only to the Amazon S3 output location that you specify for Athena query results. It does not apply to other Amazon S3 locations like data source locations in external Amazon S3 buckets, CTAS and INSERT INTO destination table locations, UNLOAD statement output locations, operations to spill buckets for federated queries, or SELECT queries run against a table in another account.
   Assign bucket owner full control over query results	This field is unselected by default. If you select it and ACLs are enabled for the query result location bucket, you grant full control access over query results to the bucket owner. For example, if your query result location is owned by another account, you can use this option to grant ownership and full control over your query results to the other account. If the bucket's S3 Object Ownership setting is Bucket owner preferred, the bucket owner also owns all query result objects written from this workgroup. For example, if an external account's workgroup enables this option and sets its query result location to your account's Amazon S3 bucket which has an S3 Object Ownership setting of Bucket owner preferred, you own and have full control access over the external workgroup's query results. Selecting this option when the query result bucket's S3 Object Ownership setting is Bucket owner enforced has no effect. For more information, see Object ownership settings in the Amazon S3 User Guide.
   Encrypt query results	Optional. For all workgroup queries, encrypt the query results in Amazon S3. Because you must encrypt all queries in a workgroup or none, we recommend that you create separate workgroups for encrypted and non-encrypted queries. If selected, you can select the Encryption type, the Encryption key and enter the KMS Key ARN. If you don't have the key, open the Amazon KMS console to create it. For more information, see Creating keys in the Amazon Key Management Service Developer Guide.
   Set encryption_type as minimum encryption	Optional. Select this option to enforce a minimum type of encryption for query results for all users of the workgroup. Selecting this option shows you a table with the hierarchy of encryption types. The table also shows you which encryption types workgroup users will be allowed to use when you specify a particular encryption type as the minimum. To use this option, the Override client-side settings must not be selected. For more information, see Configure minimum encryption for a workgroup.
   Enable S3 Access Grants	This field is selected by default when you choose IAM Identity Center as the authentication mode. When selected, this option applies IAM Identity Center user or group based permissions to Amazon S3 locations.
   Create user identity based S3 prefix	When this option is selected, Athena creates an Amazon S3 prefix when it stores query results. The prefix is based on the user's IAM Identity Center user identity.
   Override client-side settings	This field is unselected by default. If you select it, workgroup settings apply to all queries in the workgroup and override client-side settings. For more information, see Override client-side settings.
   Publish query metrics to CloudWatch	This field is selected by default. Publish query metrics to CloudWatch. See Monitor Athena query metrics with CloudWatch.
   Requester Pays S3 buckets	Optional. Choose Turn on queries on requester pays buckets in Amazon S3 if workgroup users will run queries on data stored in Amazon S3 buckets that are configured as Requester Pays. The account of the user running the query is charged for applicable data access and data transfer fees associated with the query. For more information, see Requester Pays buckets in the Amazon Simple Storage Service User Guide.
   Per query data usage control	Optional. Sets the limit for the maximum amount of data a query is allowed to scan. You can set only one per query limit for a workgroup. The limit applies to all queries in the workgroup and if query exceeds the limit, it will be cancelled. For more information, see Configure per-query and per-workgroup data usage controls.
   Workgroup data usage alerts	Optional. Set multiple alert thresholds when queries running in this workgroup scan a specified amount of data within a specific period. Alerts are implemented using Amazon CloudWatch alarms and applies to all queries in the workgroup. For more information, see Using Amazon CloudWatch alarms in the Amazon CloudWatch User Guide.
   Tags	Optional. Add one or more tags to a workgroup. A tag is a label that you assign to an Athena workgroup resource. It consists of a key and a value. Use Amazon tagging best practices to create a consistent set of tags and categorize workgroups by purpose, owner, or environment. You can also use tags in IAM policies, and to control billing costs. Do not use duplicate tag keys the same workgroup. For more information, see Tag Athena resources.

6. 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.

7. 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. For example JSON policies, see Configure access to workgroups and tags.

8. (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.

9. (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.

10. (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 in the Amazon Billing User Guide.

11. (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.