Amazon AWS Athena

This connector allows Turbine to execute queries on AWS Athena.

Asset Setup

This integration authenticates with AWS Athena using the following input values:

Requirements

AWS Access Key ID: A long-term AWS access key ID with access to Athena.

AWS Secret Key ID: A long-term secret access key associated with the above AccessKey ID.

Region Name: The AWS region.

Role ARN: An ARN of an AWS IAM Role to assume. This is optional.

External ID: An External ID to use when assuming the role. This is optional.

Obtaining AWS Credentials

To use this integration, you will need to have an AWS account and obtain the necessary AWS credentials. You can obtain these credentials by following the steps below:

In the left navigation pane, click on the "Users" tab and select the user for which you want to create credentials.

Click on the "Security credentials" tab, and then click on the "Create access key".

Make sure to save the access key ID and secret access key in a secure location, as you will not be able to see the secret access key again after this step.

If you want to use an AWS IAM Role, you will need to have the ARN of the role and an optional External ID, if one was specified by the AWS account administrator.

Notes

AWS Account and Access Keys

Boto3 Athena Documentation

Configurations

Asset

Authenticates using AWS credentials

Configuration Parameters

Parameter	Description	Type	Required
aws_access_key_id	A specific long-term AWS access key ID	string	Required
aws_secret_access_key	A specific long-term AWS secret access key	string	Required
region_name	The AWS Region where you want to create new connections	string	Required
role_arn	Role ARN	string	Optional
external_id	External ID	string	Optional
aws_session_token	Session Token	string	Optional

Actions

Get Query Execution Details

Returns information about a single execution of a query if you have access to the workgroup in which the query ran.

Input

Argument Name	Type	Required	Description
QueryExecutionId	string	Required	Unique identifier

Input Example

{"QueryExecutionId":"string"}

Output

Parameter	Type	Description
QueryExecution	object	Output field: QueryExecution
QueryExecution.EngineVersion	object	Output field: QueryExecution.EngineVersion
QueryExecution.EngineVersion.EffectiveEngineVersion	string	Output field: QueryExecution.EngineVersion.EffectiveEngineVersion
QueryExecution.EngineVersion.SelectedEngineVersion	string	Output field: QueryExecution.EngineVersion.SelectedEngineVersion
QueryExecution.Query	string	Output field: QueryExecution.Query
QueryExecution.QueryExecutionContext	object	Output field: QueryExecution.QueryExecutionContext
QueryExecution.QueryExecutionId	string	Unique identifier
QueryExecution.ResultConfiguration	object	Result of the operation
QueryExecution.ResultConfiguration.OutputLocation	string	Result of the operation
QueryExecution.ResultReuseConfiguration	object	Result of the operation
QueryExecution.ResultReuseConfiguration.ResultReuseByAgeConfiguration	object	Result of the operation
QueryExecution.ResultReuseConfiguration.ResultReuseByAgeConfiguration.Enabled	boolean	Result of the operation
QueryExecution.StatementType	string	Type of the resource
QueryExecution.Statistics	object	Output field: QueryExecution.Statistics
QueryExecution.Statistics.DataScannedInBytes	number	Response data
QueryExecution.Statistics.EngineExecutionTimeInMillis	number	Output field: QueryExecution.Statistics.EngineExecutionTimeInMillis
QueryExecution.Statistics.QueryPlanningTimeInMillis	number	Output field: QueryExecution.Statistics.QueryPlanningTimeInMillis
QueryExecution.Statistics.QueryQueueTimeInMillis	number	Output field: QueryExecution.Statistics.QueryQueueTimeInMillis
QueryExecution.Statistics.ResultReuseInformation	object	Result of the operation
QueryExecution.Statistics.ResultReuseInformation.ReusedPreviousResult	boolean	Result of the operation
QueryExecution.Statistics.ServiceProcessingTimeInMillis	number	Output field: QueryExecution.Statistics.ServiceProcessingTimeInMillis
QueryExecution.Statistics.TotalExecutionTimeInMillis	number	Output field: QueryExecution.Statistics.TotalExecutionTimeInMillis
QueryExecution.Status	object	Status value
QueryExecution.Status.CompletionDateTime	string	Status value
QueryExecution.Status.State	string	Status value

Output Example

{"QueryExecution":{"EngineVersion":{"EffectiveEngineVersion":"Athena engine version 3","SelectedEngineVersion":"AUTO"},"Query":"SELECT * FROM \"amazon_security_lake_glue_db_us_east_1\".\"amazon_security_lake_tab...","QueryExecutionContext":{},"QueryExecutionId":"777fd206-3500-4e05-8d8a-ab46e13b44e3","ResultConfiguration":{"OutputLocation":"s3://sif-athena-query-results-us-east-1/some/777fd206-3500-4e05-8d8a-ab46e13b44e..."},"ResultReuseConfiguration":{"ResultReuseByAgeConfiguration":{}},"Stateme...

Get Query Results

Get results of a single query execution specified by QueryExecutionId from the Athena query results location in Amazon S3.

Input

Argument Name	Type	Required	Description
QueryExecutionId	string	Required	The unique ID of the query execution.
NextToken	string	Optional	A token generated by the Athena service that specifies where to continue pagination if a previous request was truncated. To obtain the next set of pages, pass in the NextToken from the response object of the previous page call.
MaxResults	number	Optional	The maximum number of results (rows) to return in this request.

Input Example

{"QueryExecutionId":"string","NextToken":"string","MaxResults":123}

Output

Parameter	Type	Description
ResponseMetadata	object	Response data
ResponseMetadata.HTTPHeaders	object	Response data
ResponseMetadata.HTTPHeaders.connection	string	Response data
ResponseMetadata.HTTPHeaders.content-length	string	Response data
ResponseMetadata.HTTPHeaders.content-type	string	Response data
ResponseMetadata.HTTPHeaders.date	string	Response data
ResponseMetadata.HTTPHeaders.x-amzn-requestid	string	Response data
ResponseMetadata.HTTPStatusCode	number	Response data
ResponseMetadata.RequestId	string	Response data
ResponseMetadata.RetryAttempts	number	Response data
ResultSet	object	Result of the operation
ResultSet.ResultSetMetadata	object	Response data
ResultSet.ResultSetMetadata.ColumnInfo	array	Response data
ResultSet.Rows	array	Result of the operation
UpdateCount	number	Count value
NextToken	string	Output field: NextToken

Output Example

{"ResponseMetadata":{"HTTPHeaders":{"connection":"keep-alive","content-length":"34116","content-type":"application/x-amz-json-1.1","date":"Wed, 06 Sep 2023 16:14:05 GMT","x-amzn-requestid":"515cc1d7-ce9b-4679-97de-beefcfb5bd75"},"HTTPStatusCode":200,"RequestId":"515cc1d7-ce9b-4679-97de-beefcfb5bd75","RetryAttempts":0},"ResultSet":{"ResultSetMetadata":{"ColumnInfo":[]},"Rows":[{}]},"UpdateCount":0}

List Query Executions

Get a list of available query execution IDs for the queries in the specified workgroup.

Input

Argument Name	Type	Required	Description
WorkGroup	string	Optional	The name of the workgroup from which queries are being returned. If a workgroup is not specified, a list of available query execution IDs for the queries in the primary workgroup is returned.
NextToken	string	Optional	A token generated by the Athena service that specifies where to continue pagination if a previous request was truncated. To obtain the next set of pages, pass in the NextToken from the response object of the previous page call.
MaxResults	number	Optional	The maximum number of query executions to return in this request.

Input Example

{"WorkGroup":"string","NextToken":"string","MaxResults":123}

Output

Parameter	Type	Description
QueryExecutionIds	array	Unique identifier
ResponseMetadata	object	Response data
ResponseMetadata.HTTPHeaders	object	Response data
ResponseMetadata.HTTPHeaders.connection	string	Response data
ResponseMetadata.HTTPHeaders.content-length	string	Response data
ResponseMetadata.HTTPHeaders.content-type	string	Response data
ResponseMetadata.HTTPHeaders.date	string	Response data
ResponseMetadata.HTTPHeaders.x-amzn-requestid	string	Response data
ResponseMetadata.HTTPStatusCode	number	Response data
ResponseMetadata.RequestId	string	Response data
ResponseMetadata.RetryAttempts	number	Response data
NextToken	string	Output field: NextToken

Output Example

{"QueryExecutionIds":["aab18033-4d65-44b2-ad5c-5f8997d33a53","88998526-fff7-41d7-b113-9734dda00e65","777fd206-3500-4e05-8d8a-ab46e13b44e3"],"ResponseMetadata":{"HTTPHeaders":{"connection":"keep-alive","content-length":"257","content-type":"application/x-amz-json-1.1","date":"Wed, 06 Sep 2023 16:11:29 GMT","x-amzn-requestid":"7bce08ab-4013-44ba-8a75-051800fc243c"},"HTTPStatusCode":200,"RequestId":"7bce08ab-4013-44ba-8a75-051800fc243c","RetryAttempts":0}}

Start Query Execution

Runs the SQL query statements and returns an execution ID.

Input

Argument Name	Type	Required	Description
QueryString	string	Required	The SQL query statements to be executed.
ClientRequestToken	string	Optional	A unique case-sensitive string used to ensure the request to create the query is idempotent (executes only once). This parameter is autopopulated if not provided.
QueryExecutionContext	object	Optional	The database within which the query executes.
QueryExecutionContext.Database	string	Optional	The name of the database used in the query execution. The database must exist in the catalog.
QueryExecutionContext.Catalog	string	Optional	The name of the data catalog used in the query execution.
ResultConfiguration	object	Optional	Specifies information about where and how to save the results of the query execution.
ResultConfiguration.OutputLocation	string	Optional	The location in Amazon S3 where your query and calculation results are stored, such as s3://path/to/query/bucket/.
ResultConfiguration.EncryptionConfiguration	object	Optional	If query and calculation results are encrypted in Amazon S3, indicates the encryption option used (for example, SSE_KMS or CSE_KMS) and key information.
ResultConfiguration.EncryptionConfiguration.EncryptionOption	string	Optional	Result of the operation
ResultConfiguration.EncryptionConfiguration.KmsKey	string	Optional	For SSE_KMS and CSE_KMS, this is the KMS key ARN or ID.
ResultConfiguration.ExpectedBucketOwner	string	Optional	Result of the operation
ResultConfiguration.AclConfiguration	object	Optional	Indicates that an Amazon S3 canned ACL should be set to control ownership of stored query results.
ResultConfiguration.AclConfiguration.S3AclOption	string	Optional	The Amazon S3 canned ACL that Athena should specify when storing query results.
WorkGroup	string	Optional	The name of the workgroup in which the query is being started.
ExecutionParameters	array	Optional	A list of values for the parameters in a query. The values are applied sequentially to the parameters in the query in the order in which the parameters occur.
ResultReuseConfiguration	object	Optional	Specifies the query result reuse behavior for the query.
ResultReuseConfiguration.ResultReuseByAgeConfiguration	object	Optional	Result of the operation
ResultReuseConfiguration.ResultReuseByAgeConfiguration.Enabled	boolean	Optional	Result of the operation
ResultReuseConfiguration.ResultReuseByAgeConfiguration.MaxAgeInMinutes	number	Optional	Result of the operation

Input Example

{"QueryString":"string","ClientRequestToken":"string","QueryExecutionContext":{"Database":"string","Catalog":"string"},"ResultConfiguration":{"OutputLocation":"string","EncryptionConfiguration":{"EncryptionOption":"string","KmsKey":"string"},"ExpectedBucketOwner":"string","AclConfiguration":{"S3AclOption":"string"}},"WorkGroup":"string","ExecutionParameters":["string"],"ResultReuseConfiguration":{"ResultReuseByAgeConfiguration":{"Enabled":true,"MaxAgeInMinutes":60}}}

Output

Parameter	Type	Description
QueryExecutionId	string	Unique identifier
ResponseMetadata	object	Response data
ResponseMetadata.HTTPHeaders	object	Response data
ResponseMetadata.HTTPHeaders.connection	string	Response data
ResponseMetadata.HTTPHeaders.content-length	string	Response data
ResponseMetadata.HTTPHeaders.content-type	string	Response data
ResponseMetadata.HTTPHeaders.date	string	Response data
ResponseMetadata.HTTPHeaders.x-amzn-requestid	string	Response data
ResponseMetadata.HTTPStatusCode	number	Response data
ResponseMetadata.RequestId	string	Response data
ResponseMetadata.RetryAttempts	number	Response data

Output Example

{"QueryExecutionId":"a437228e-bd40-460f-9d1b-a3f6be415920","ResponseMetadata":{"HTTPHeaders":{"connection":"keep-alive","content-length":"59","content-type":"application/x-amz-json-1.1","date":"Wed, 06 Sep 2023 16:24:19 GMT","x-amzn-requestid":"3b906e8b-4f70-428b-9369-49f0fcc3a0fc"},"HTTPStatusCode":200,"RequestId":"3b906e8b-4f70-428b-9369-49f0fcc3a0fc","RetryAttempts":0}}

Response Headers

Header	Description	Example
Content-Type	The media type of the resource	application/json
Date	The date and time at which the message was originated	Thu, 01 Jan 2024 00:00:00 GMT