Changing Athena engine versions - Amazon Athena

Changing Athena engine versions

Athena occasionally releases a new engine version to provide improved performance, functionality, and code fixes. When a new engine version is available, Athena notifies you in the console. You can choose to let Athena decide when to upgrade, or manually specify an Athena engine version per workgroup.

Finding the query engine version for a workgroup

You can use the Workgroups page to find the current engine version for any workgroup.

To find the current engine version for any workgroup
  1. Open the Athena console at https://console.aws.amazon.com/athena/.

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

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

  4. On the Workgroups page, find the workgroup that you want. The Query engine version column for the workgroup displays the query engine version.

Changing the engine version in the Athena console

When a new engine version is available, you can choose to let Athena decide when to upgrade the workgroup, or manually specify the Athena engine version that the workgroup uses. If only one version is currently available, manually specifying a different version is not possible.

Note

To change the engine version for a workgroup, you must have permission to perform the athena:ListEngineVersions action on the workgroup. For IAM policy examples, see Workgroup example policies.

To let Athena decide when to upgrade the workgroup
  1. Open the Athena console at https://console.aws.amazon.com/athena/.

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

  3. In the console navigation pane, choose Workgroups.

  4. In the list of workgroups, choose the link for the workgroup that you want to configure.

  5. Choose Edit.

  6. In the Query engine version section, for Update query engine, choose Automatic to let Athena choose when to upgrade your workgroup. This is the default setting.

  7. Choose Save changes.

    In the list of workgroups, the Query engine update status for the workgroup shows Automatic.

To manually choose an engine version
  1. Open the Athena console at https://console.aws.amazon.com/athena/.

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

  3. In the console navigation pane, choose Workgroups.

  4. In the list of workgroups, choose the link for the workgroup that you want to configure.

  5. Choose Edit.

  6. In the Query engine version section, for Update query engine, choose Manual to manually choose an engine version.

  7. Use the Query engine version option to choose the engine version that you want the workgroup to use. If a different engine version is unavailable, a different engine version cannot be specified.

  8. Choose Save changes.

    In the list of workgroups, the Query engine update status for the workgroup shows Manual.

Changing the engine version using the AWS CLI

To change the engine version using the AWS CLI, use the syntax in the following example.

aws athena update-work-group --work-group workgroup-name --configuration-updates EngineVersion={SelectedEngineVersion='Athena engine version 3'}

Specifying the engine version when you create a workgroup

When you create a workgroup, you can specify the engine version that the workgroup uses or let Athena decide when to upgrade the workgroup. If a new engine version is available, a best practice is to create a workgroup to test the new engine before you upgrade your other workgroups. To specify the engine version for a workgroup, you must have the athena:ListEngineVersions permission on the workgroup. For IAM policy examples, see Workgroup example policies.

To specify the engine version when you create a workgroup
  1. Open the Athena console at https://console.aws.amazon.com/athena/.

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

  3. In the console navigation pane, choose Workgroups.

  4. On the Workgroups page, choose Create workgroup.

  5. On the Create workgroup page, in the Query engine version section, do one of the following:

    • Choose Automatic to let Athena choose when to upgrade your workgroup. This is the default setting.

    • Choose Manual to manually choose a different engine version if one is available.

  6. Enter information for the other fields as necessary. For information about the other fields, see Create a workgroup.

  7. Choose Create workgroup.

Testing queries in advance of an engine version upgrade

When a workgroup is upgraded to a new engine version, some of your queries can break due to incompatibilities. To make sure that your engine version upgrade goes smoothly, you can test your queries in advance.

To test your queries prior to an engine version upgrade
  1. Verify the engine version of the workgroup that you are using. The engine version that you are using is displayed on the Workgroups page in the Query engine version column for for the workgroup. For more information, see Finding the query engine version for a workgroup.

  2. Create a test workgroup that uses the new engine version. For more information, see Specifying the engine version when you create a workgroup.

  3. Use the new workgroup to run the queries that you want to test.

  4. If a query fails, use the Athena engine version reference to check for breaking changes that might be affecting the query. Some changes may require you to update the syntax of your queries.

  5. If your queries still fail, contact AWS Support for assistance. In the AWS Management Console, choose Support, Support Center, or ask a question on AWS re:Post using the Amazon Athena tag.

Troubleshooting queries that fail

If a query fails after an engine version upgrade, use the Athena engine version reference to check for breaking changes, including changes that may affect the syntax in your queries.

If your queries still fail, contact AWS Support for assistance. In the AWS Management Console, choose Support, Support Center, or ask a question on AWS re:Post using the Amazon Athena tag.