--- title: AWS Athena actions source: https://docs.newrelic.com/docs/workflow-automation/setup-and-configure/actions-catalog/aws/athena/aws-athena --- This page provides a reference for AWS Athena actions available in the workflow automation actions catalog. Use these actions to run SQL queries against Amazon Athena, check their execution status, and retrieve results directly from a workflow definition. ## Prerequisites For prerequisites and credentials setup, see [Set up AWS credentials](https://docs.newrelic.com/docs/workflow-automation/setup-and-configure/set-up-aws-credentials). ## Start a query execution [#start-query-execution] The action identifier is `aws.athena.startQueryExecution`. Runs a SQL query against Amazon Athena and returns the query execution ID. This action does not wait for the query to complete — use `aws.athena.getQueryExecution` to poll for status and `aws.athena.getQueryResults` to retrieve results. The following table describes the input fields for this action. | **Input** | **Type** | **Description** | **Example** | | ---------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | `region` | String | **Required.** AWS region of the Athena workgroup. | `us-east-2` | | `queryString` | String | **Required.** The SQL statement to execute. Length: 1–262,144 characters. | `"SELECT * FROM my_table LIMIT 10"` | | `awsRoleArn` | String | **Optional.** IAM role ARN to assume for AWS API calls. | `arn:aws:iam::123456789012:role/my-workflow-role` | | `awsAccessKeyId` | String | **Optional.** AWS access key ID. Pass as a secret. | `${{ :secrets:awsAccessKeyId }}` | | `awsSecretAccessKey` | String | **Optional.** AWS secret access key. Pass as a secret. | `${{ :secrets:awsSecretAccessKey }}` | | `awsSessionToken` | String | **Optional.** Temporary session token for STS authentication. Pass as a secret. | `${{ :secrets:awsSessionToken }}` | | `database` | String | **Optional.** Athena database to run the query against. Length: 1–255 characters. | `"my-database"` | | `catalog` | String | **Optional.** Data catalog name. Length: 1–256 characters. | `"AwsDataCatalog"` | | `outputLocation` | String | **Optional.** S3 URI for query results. Required if the workgroup has no default output location. | `"s3://my-athena-results-bucket/path/"` | | `encryptionOption` | String | **Optional.** Encryption for result files. Allowed values: `SSE_S3`, `SSE_KMS`, `CSE_KMS`. | `"SSE_S3"` | | `kmsKey` | String | **Optional.** KMS key ARN or ID. Required when `encryptionOption` is `SSE_KMS` or `CSE_KMS`. | `"arn:aws:kms:us-east-2:123456789012:key/abc123"` | | `expectedBucketOwner` | String | **Optional.** 12-digit AWS account ID that must own the output S3 bucket. | `"111122223333"` | | `aclS3Option` | String | **Optional.** Canned ACL applied to result objects. Allowed value: `BUCKET_OWNER_FULL_CONTROL`. | `"BUCKET_OWNER_FULL_CONTROL"` | | `workGroup` | String | **Optional.** Athena workgroup to run the query in. Defaults to `primary` if omitted. Length: 1–128 characters. | `"primary"` | | `clientRequestToken` | String | **Optional.** Idempotency token for retries. Length: 32–128 characters. | `"3f2504e0-4f89-41d3-9a0c-0305e82c3301"` | | `executionParameters` | List | **Optional.** Parameter values for a parameterized query, applied in positional order. Each value: 1–1,024 characters. | `["value1", "value2"]` | | `resultReuseEnabled` | Boolean | **Optional.** If `true`, reuses a previous query's results if they are within `resultReuseMaxAgeInMinutes`. | `true` | | `resultReuseMaxAgeInMinutes` | Integer | **Optional.** Maximum age in minutes of results that can be reused. Range: 0–10,080. | `60` | | `selectors` | List | **Optional.** JQ selectors to extract specific fields from the action output. | `[{"name": "queryExecutionId", "expression": ".response.QueryExecutionId"}]` | The following table describes the output fields for this action. | **Output** | **Type** | **Example** | | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `response` | Object | `{"QueryExecutionId": "ef4a125f-9e79-466d-bae5-d6d36536fbee"}`. See the [StartQueryExecution API reference](https://docs.aws.amazon.com/athena/latest/APIReference/API_StartQueryExecution.html). | | `success` | Boolean | `true` or `false` | | `errorMessage` | String | `"An error occurred (InvalidRequestException) when calling the StartQueryExecution operation: ..."` | **Example** ```yaml name: start-athena-query description: Run a SQL query against Athena steps: - name: startQuery type: action action: aws.athena.startQueryExecution version: '1' inputs: awsRoleArn: ${{ :secrets:awsRoleArn }} region: us-east-2 queryString: "SELECT * FROM my_table LIMIT 10" database: "my-database" catalog: "AwsDataCatalog" outputLocation: "s3://my-athena-results-bucket/path/" workGroup: "primary" selectors: - name: queryExecutionId expression: ".response.QueryExecutionId" next: end ``` ## Get a query execution [#get-query-execution] The action identifier is `aws.athena.getQueryExecution`. Returns the details and current status of a single Athena query execution by its execution ID. Use this to poll a query started by `aws.athena.startQueryExecution` until it reaches a terminal state (`SUCCEEDED`, `FAILED`, or `CANCELLED`). The following table describes the input fields for this action. | **Input** | **Type** | **Description** | **Example** | | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | `region` | String | **Required.** AWS region of the Athena workgroup. | `us-east-2` | | `queryExecutionId` | String | **Required.** UUID of the query execution returned by `aws.athena.startQueryExecution`. Length: 1–128 characters. | `"ef4a125f-9e79-466d-bae5-d6d36536fbee"` | | `awsRoleArn` | String | **Optional.** IAM role ARN to assume for AWS API calls. | `arn:aws:iam::123456789012:role/my-workflow-role` | | `awsAccessKeyId` | String | **Optional.** AWS access key ID. Pass as a secret. | `${{ :secrets:awsAccessKeyId }}` | | `awsSecretAccessKey` | String | **Optional.** AWS secret access key. Pass as a secret. | `${{ :secrets:awsSecretAccessKey }}` | | `awsSessionToken` | String | **Optional.** Temporary session token for STS authentication. Pass as a secret. | `${{ :secrets:awsSessionToken }}` | | `selectors` | List | **Optional.** JQ selectors to extract specific fields from the action output. | `[{"name": "state", "expression": ".response.QueryExecution.Status.State"}]` | The following table describes the output fields for this action. | **Output** | **Type** | **Example** | | -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `response` | Object | Contains `QueryExecution` with `Status` (`State`, `StateChangeReason`, timestamps, `AthenaError`), `Statistics`, `ResultConfiguration`, `QueryExecutionContext`, `WorkGroup`, and `EngineVersion`. See the [GetQueryExecution API reference](https://docs.aws.amazon.com/athena/latest/APIReference/API_GetQueryExecution.html). | | `success` | Boolean | `true` or `false` | | `errorMessage` | String | `"An error occurred (InvalidRequestException) when calling the GetQueryExecution operation: ..."` | **Example** ```yaml name: get-athena-query-execution description: Check the status of an Athena query execution steps: - name: getExecution type: action action: aws.athena.getQueryExecution version: '1' inputs: awsRoleArn: ${{ :secrets:awsRoleArn }} region: us-east-2 queryExecutionId: "ef4a125f-9e79-466d-bae5-d6d36536fbee" selectors: - name: state expression: ".response.QueryExecution.Status.State" - name: stateChangeReason expression: ".response.QueryExecution.Status.StateChangeReason" next: end ``` ## Get query results [#get-query-results] The action identifier is `aws.athena.getQueryResults`. Returns the rows and column metadata of a completed Athena query execution. Results are paginated — when the response includes a `NextToken`, pass it as `nextToken` on the next call to retrieve the following page. The first row of `ResultSet.Rows` is always the header row (column names). The following table describes the input fields for this action. | **Input** | **Type** | **Description** | **Example** | | -------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `region` | String | **Required.** AWS region of the Athena workgroup. | `us-east-2` | | `queryExecutionId` | String | **Required.** UUID of the completed query execution. Length: 1–128 characters. | `"8d0105c1-30b5-4b8f-a23e-a1b60047c43f"` | | `awsRoleArn` | String | **Optional.** IAM role ARN to assume for AWS API calls. | `arn:aws:iam::123456789012:role/my-workflow-role` | | `awsAccessKeyId` | String | **Optional.** AWS access key ID. Pass as a secret. | `${{ :secrets:awsAccessKeyId }}` | | `awsSecretAccessKey` | String | **Optional.** AWS secret access key. Pass as a secret. | `${{ :secrets:awsSecretAccessKey }}` | | `awsSessionToken` | String | **Optional.** Temporary session token for STS authentication. Pass as a secret. | `${{ :secrets:awsSessionToken }}` | | `nextToken` | String | **Optional.** Pagination token from a previous truncated response. Omit to start from the first page. Length: 1–1,024 characters. | `"${{ .steps.getResults.outputs.nextToken }}"` | | `maxResults` | Integer | **Optional.** Maximum number of rows to return per page. Range: 1–1,000. | `100` | | `queryResultType` | String | **Optional.** Result type to return. Allowed values: `DATA_ROWS` (default), `DATA_MANIFEST`. | `"DATA_ROWS"` | | `selectors` | List | **Optional.** JQ selectors to extract specific fields from the action output. | `[{"name": "rows", "expression": ".response.ResultSet.Rows"}, {"name": "nextToken", "expression": ".response.NextToken"}]` | The following table describes the output fields for this action. | **Output** | **Type** | **Example** | | -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `response` | Object | Contains `UpdateCount`, `ResultSet` (with `Rows` and `ResultSetMetadata.ColumnInfo`), and `NextToken` when more pages exist. The first row of `Rows` is always the header row. See the [GetQueryResults API reference](https://docs.aws.amazon.com/athena/latest/APIReference/API_GetQueryResults.html). | | `success` | Boolean | `true` or `false` | | `errorMessage` | String | `"An error occurred (InvalidRequestException) when calling the GetQueryResults operation: ..."` | **Example** ```yaml name: get-athena-query-results description: Fetch results of a completed Athena query steps: - name: getResults type: action action: aws.athena.getQueryResults version: '1' inputs: awsRoleArn: ${{ :secrets:awsRoleArn }} region: us-east-2 queryExecutionId: "8d0105c1-30b5-4b8f-a23e-a1b60047c43f" maxResults: 100 selectors: - name: rows expression: ".response.ResultSet.Rows" - name: columnInfo expression: ".response.ResultSet.ResultSetMetadata.ColumnInfo" - name: nextToken expression: ".response.NextToken" next: end ```