Managing 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).

Managing workgroups

In the https://console.amazonaws.cn/athena/, you can perform the following tasks:

Statement Description
Create a workgroup

Create a new workgroup.

Edit a workgroup 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.
View the workgroup's details 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.
Delete a workgroup

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.

Switch workgroups

Switch between workgroups to which you have access.

Copy a saved query between workgroups 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.
Enable and disable a workgroup

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.

Specify a workgroup in which to run queries

Before you can run queries, you must specify to Athena which workgroup to use. You must have permissions to the workgroup.

Create an Athena workgroup that uses IAM Identity Center authentication 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.

Create a workgroup

Creating a workgroup requires permissions to CreateWorkgroup API actions. See Access to workgroups and tags and IAM policies for accessing workgroups. If you are adding tags, you also need to add permissions to TagResource. See Tag policy examples for workgroups.

To create a workgroup in the console
  1. If the console navigation pane is not visible, choose the expansion menu on the left.

    
                            Choose the expansion menu.
  2. In the Athena console navigation pane, choose Workgroups.

  3. On the Workgroups page, choose Create workgroup.

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

    Field Description
    Workgroup name Required. Enter a unique name for your workgroup. Use 1 - 128 characters. (A-Z,a-z,0-9,_,-,.). This name cannot be changed.
    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 Creating 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 mode 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 Trusted identity propagation across applications in the Amazon IAM Identity Center User Guide.
    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

    Optional. Enter a path to an Amazon S3 bucket or prefix. This bucket and prefix must exist before you can specify them.

    Note

    If you run queries in the console, specifying the query results location is optional. If you don't specify it for the workgroup or in Settings, Athena uses the default query result location. If you run queries with the API or the drivers, you must specify query results location in at least one of the 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. Encrypt results stored in Amazon S3. If selected, all queries in the workgroup are encrypted.

    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 Configuring 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.
    Publish query metrics to CloudWatch This field is selected by default. Publish query metrics to CloudWatch. See Monitoring Athena queries with CloudWatch metrics.
    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 Workgroup settings override client-side settings.
    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.

    Manage 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 Setting data usage control limits.
    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 Tagging Athena resources.
  5. Choose Create workgroup. The workgroup appears in the list on the Workgroups page.

You can also use the CreateWorkGroup API operation to create a workgroup.

Important

After you create workgroups, create IAM policies for accessing workgroups IAM that allow you to run workgroup-related actions.

Edit a workgroup

Editing a workgroup requires permissions to UpdateWorkgroup API operations. See Access to workgroups and tags and IAM policies for accessing workgroups. If you are adding or editing tags, you also need to have permissions to TagResource. See Tag policy examples for workgroups.

To edit a workgroup in the console
  1. In the Athena console navigation pane, choose Workgroups.

  2. On the Workgroups page, select the button for the workgroup that you want to edit.

  3. Choose Actions, Edit.

  4. Change the fields as needed. For the list of fields, see Create workgroup. 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.

  5. Choose Save changes. The updated workgroup appears in the list on the Workgroups page.

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.

  2. On the Workgroups page, choose the link of the workgroup that you want to view. The Overview Details page for the workgroup displays.

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.

To delete a workgroup in the console
  1. In the Athena console navigation pane, choose Workgroups.

  2. On the Workgroups page, select the button for the workgroup that you want to delete.

  3. Choose Actions, Delete.

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

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.

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

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.

  2. Choose the link of the saved query that you want to copy. Athena opens the query in the query editor.

  3. In the query editor, select the query text, and then press Ctrl+C to copy it.

  4. Switch to the destination workgroup, or create a workgroup, and then switch to it.

  5. Open a new tab in the query editor, and then press Ctrl+V to paste the text into the new tab.

  6. In the query editor, choose Save as to save the query in the destination workgroup.

  7. In the Choose a name dialog box, enter a name for the query and an optional description.

  8. Choose Save.

Enable and 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.

  2. On the Workgroups page, choose the link for the workgroup.

  3. On the upper right, choose Enable workgroup or Disable workgroup.

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

Specify a workgroup in which to run 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 IAM policies for accessing workgroups.

  2. To specify the workgroup, use one of these options:

    • If you are using the Athena console, set the workgroup by switching workgroups.

    • 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, 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=<AWSREGION>;UID=<ACCESSKEY>; PWD=<SECRETKEY>;S3OutputLocation=s3://<athena-output>-<AWSREGION>/; Workgroup=<WORKGROUPNAME>;

Configuring minimum encryption for a workgroup

As an administrator of an Athena SQL workgroup, you can enforce a minimal level of encryption in Amazon S3 for all query results from the workgroup. You can use this feature to ensure that query results are never stored in an Amazon S3 bucket in an unencrypted state.

When users in a workgroup with minimum encryption enabled submit a query, they can only set the encryption to the minimum level that you configure, or to a higher level if one is available. Athena encrypts query results at either the level specified when the user runs the query or at the level set in the workgroup.

The following levels are available:

  • Basic – Amazon S3 server side encryption with Amazon S3 managed keys (SSE_S3).

  • Intermediate – Server Side encryption with KMS managed keys (SSE_KMS).

  • Advanced – Client side encryption with KMS managed keys (CSE_KMS).

Considerations and limitations

  • The minimum encryption feature is not available for Apache Spark enabled workgroups.

  • The minimum encryption feature is functional only when the workgroup does not enable the Override client-side settings option.

  • If the workgroup has the Override client-side settings option enabled, the workgroup encryption setting prevails, and the minimum encryption setting has no effect.

  • There is no cost to enable this feature.

Enabling minimum encryption for a workgroup

You can enable a minimum encryption level for the query results from your Athena SQL workgroup when you create or update the workgroup. To do this, you can use the Athena console, Athena API, or Amazon CLI.

Using the Athena console to enable minimum encryption

To get started creating or editing your workgroup using the Athena console, see Create a workgroup or Edit a workgroup. When configuring your workgroup, use the following steps to enable minimum encryption.

To configure the minimum encryption level for workgroup query results
  1. In the Additional configurations section, expand Settings.

  2. Clear the Override client-side settings option, or verify that it is not selected.

  3. In the Additional configurations section, expand Query result configuration.

  4. Select the Encrypt query results option.

  5. For Encryption type, select the encryption method that you want Athena to use for your workgroup's query results (SSE_S3, SSE_KMS, or CSE_KMS). These encryption types correspond to basic, intermediate, and advanced security levels.

  6. To enforce the encryption method that you chose as the minimum level of encryption for all users, select Set encryption_method as minimum encryption.

    When you select this option, a table shows the encryption hierarchy and encryption levels that users will be allowed when the encryption type that you choose becomes the minimum.

  7. After you create your workgroup or update your workgroup configuration, choose Create workgroup or Save changes.

Using the Athena API or Amazon CLI to enable minimum encryption

When you use the CreateWorkGroup or UpdateWorkGroup API to create or update an Athena SQL workgroup, set EnforceWorkGroupConfiguration to false, EnableMinimumEncryptionConfiguration to true, and use the EncryptionOption to specify the type of encryption.

In the Amazon CLI, use the create-work-group or update-work-group command with the --configuration or --configuration-updates parameters and specify the options corresponding to those for the API.