Amazon Athena
User Guide

Managing Workgroups

In the https://console.aws.amazon.com/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, and encryption. 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 between Workgroups

Switch between workgroups to which you have access.

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 a Workgroup

Creating a workgroup requires permissions to CreateWorkgroup API actions. See Access to Athena Workgroups and IAM Policies for Accessing Workgroups. If you are adding tags, you also need to add permissions to TagResource. See Tag Policy Examples.

To create a workgroup in the console

  1. In the Athena console, choose the Workgroup:<workgroup_name> tab. A Workgroups panel displays.

  2. In the Workgroups panel, choose Create workgroup.

    
                     The screenshot that shows how to create a workgroup.
  3. In the Create workgroup dialog box, 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.
    Query result location

    Optional. Enter a path to an Amazon S3 bucket or prefix. This bucket and prefix must exist before you 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.

    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 AWS KMS console to create it. For more information, see Creating Keys in the AWS Key Management Service Developer Guide.

    Publish to CloudWatch This field is selected by default. Publish query metrics to Amazon CloudWatch. See Viewing Query 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.
    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 best practices for AWS tagging strategies 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 Workgroups.
    Requester Pays S3 buckets

    Optional. Choose Enable 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 Developer Guide.

  4. Choose Create workgroup. The workgroup appears in the list in the Workgroups panel.

Alternatively, use the API operations to create a workgroup.

Important

After you create workgroups, create IAM Policies for 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 Athena Workgroups 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.

To edit a workgroup in the console

  1. In the Athena console, choose the Workgroup:<workgroup_name> tab. A Workgroups panel displays, listing all of the workgroups in the account.

    
                     Workgroups list
  2. In the Workgroups panel, choose the workgroup that you want to edit. The View details panel for the workgroup displays, with the Overview tab selected.

  3. Choose Edit workgroup.

    
                     Workgroup actions
  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. The updated workgroup appears in the list in the Workgroups panel.

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 and encryption configuration. If a workgroup has data usage limits, they are also displayed.

To view the workgroup's details

  • In the Workgroups panel, choose the workgroup that you want to edit. The View details panel for the workgroup displays, with the Overview tab selected. The workgroup details display, as in the following example:

    
                     The workgroup details screen.

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, choose the Workgroup:<workgroup_name> tab. A Workgroups panel displays.

  2. In the Workgroups panel, choose the workgroup that you want to delete. The View details panel for the workgroup displays, with the Overview tab selected.

  3. Choose Delete workgroup, and confirm the deletion.

To delete a workgroup with the API operation, use the DeleteWorkGroup action.

Switch between 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 between workgroups

  1. In the Athena console, choose the Workgroup:<workgroup_name> tab. A Workgroups panel displays.

  2. In the Workgroups panel, choose the workgroup that you want to switch to, and then choose Switch workgroup.

    
                     Switching workgroups screenshot.
  3. Choose Switch. The console shows the Workgroup: <workgroup_name> tab with the name of the workgroup that you switched to. You can now run queries in this workgroup.

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, choose the Workgroup:<workgroup_name> tab. A Workgroups panel displays.

  2. In the Workgroups panel, choose the workgroup, and then choose Enable workgroup or Disable workgroup. 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

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

To specify a workgroup to Athena

  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 to Athena, use one of these options:

    • If you are accessing Athena via the 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>;

      For more information, search for "Workgroup" in the driver documentation link included in JDBC Driver Documentation.