Setting up workgroups - Amazon Athena
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Setting up workgroups

Setting up workgroups involves creating them and establishing permissions for their usage. First, decide which workgroups your organization needs, and create them. Next, set up IAM workgroup policies that control user access and actions on a workgroup resource. Users with access to these workgroups can now run queries in them.

Note

Use these tasks for setting up workgroups when you begin to use them for the first time. If your Athena account already uses workgroups, each account's user requires permissions to run queries in one or more workgroups in the account. Before you run queries, check your IAM policy to see which workgroups you can access, adjust your policy if needed, and switch to a workgroup you intend to use.

By default, if you have not created any workgroups, all queries in your account run in the primary workgroup.

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. 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 the JDBC or ODBC driver. 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.

To set up workgroups

  1. Decide which workgroups to create. For example, you can decide the following:

    • Who can run queries in each workgroup, and who owns workgroup configuration. This determines IAM policies you create. For more information, see IAM policies for accessing workgroups.

    • Which locations in Amazon S3 to use for the query results for queries that run in each workgroup. A location must exist in Amazon S3 before you can specify it for the workgroup query results. All users who use a workgroup must have access to this location. For more information, see Workgroup settings.

    • Whether the owner of the Amazon S3 query results bucket has full control over new objects that are written to the bucket. For example, if your query result location is owned by another account, you can grant ownership and full control over your query results to the other account. For more information, see AclConfiguration.

    • Specify the ID of the Amazon Web Services account that you expect to be the owner of the output location bucket. This is an optional 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 more information, see Verifying bucket ownership with bucket owner condition in the Amazon S3 User Guide. This setting does not apply to CTAS, INSERT INTO, or UNLOAD statements.

    • Which encryption settings are required, and which workgroups have queries that must be encrypted. We recommend that you create separate workgroups for encrypted and non-encrypted queries. That way, you can enforce encryption for a workgroup that applies to all queries that run in it. For more information, see Encrypting Athena query results stored in Amazon S3.

  2. Create workgroups as needed, and add tags to them. For steps, see Create a workgroup.

  3. 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 detailed steps, see IAM policies for accessing workgroups. For example JSON policies, see Access to workgroups and tags.

  4. Set workgroup settings. Specify a location in Amazon S3 for query results and optionally specify the expected bucket owner, encryption settings, and control of objects written to the query results bucket. You can enforce workgroup settings. For more information, see workgroup settings.

    Important

    If you override client-side settings, Athena will use the workgroup's settings. This affects queries that you run in the console, by using the drivers, the command line interface, or the API operations.

    While queries continue to run, automation built based on availability of results in a certain Amazon S3 bucket may break. We recommend that you inform your users before overriding. After workgroup settings are set to override, you can omit specifying client-side settings in the drivers or the API.

  5. Notify users which workgroups to use for running queries. Send an email to inform your account's users about workgroup names that they can use, the required IAM policies, and the workgroup settings.

  6. Configure cost control limits, also known as data usage control limits, for queries and workgroups. To notify you when a threshold is breached, create an Amazon SNS topic and configure subscriptions. For detailed steps, see Setting data usage control limits and Getting started with Amazon SNS in the Amazon Simple Notification Service Developer Guide.

  7. Switch to the workgroup so that you can run queries.To run queries, switch to the appropriate workgroup. For detailed steps, see Specify a workgroup in which to run queries.