AWS Athena actions

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.

Start a 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.
`success`	Boolean	`true` or `false`
`errorMessage`	String	`"An error occurred (InvalidRequestException) when calling the StartQueryExecution operation: ..."`

Example

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

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.
`success`	Boolean	`true` or `false`
`errorMessage`	String	`"An error occurred (InvalidRequestException) when calling the GetQueryExecution operation: ..."`

Example

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

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.
`success`	Boolean	`true` or `false`
`errorMessage`	String	`"An error occurred (InvalidRequestException) when calling the GetQueryResults operation: ..."`

Example

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

Prerequisites.css-21sua1{background:none;border:none;width:0;padding:0;}

Start a query execution

Get a query execution

Get query results

Prerequisites