Athena API
Athena API
Athena API
Amazon's trademarks and trade dress may not be used in connection with any product or service that is not
Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or
discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may
or may not be affiliated with, connected to, or sponsored by Amazon.
Athena Amazon Athena Documentation
Table of Contents
Welcome ........................................................................................................................................... 1
Actions ............................................................................................................................................. 2
BatchGetNamedQuery ................................................................................................................ 3
Request Syntax .................................................................................................................. 3
Request Parameters ............................................................................................................ 3
Response Syntax ................................................................................................................ 3
Response Elements ............................................................................................................. 4
Errors ............................................................................................................................... 4
See Also ............................................................................................................................ 4
BatchGetQueryExecution ............................................................................................................. 5
Request Syntax .................................................................................................................. 5
Request Parameters ............................................................................................................ 5
Response Syntax ................................................................................................................ 5
Response Elements ............................................................................................................. 6
Errors ............................................................................................................................... 6
See Also ............................................................................................................................ 7
CreateDataCatalog ..................................................................................................................... 8
Request Syntax .................................................................................................................. 8
Request Parameters ............................................................................................................ 8
Response Elements ............................................................................................................. 9
Errors ............................................................................................................................... 9
See Also .......................................................................................................................... 10
CreateNamedQuery .................................................................................................................. 11
Request Syntax ................................................................................................................ 11
Request Parameters .......................................................................................................... 11
Response Syntax .............................................................................................................. 12
Response Elements ........................................................................................................... 12
Errors .............................................................................................................................. 12
See Also .......................................................................................................................... 13
CreatePreparedStatement .......................................................................................................... 14
Request Syntax ................................................................................................................ 14
Request Parameters .......................................................................................................... 14
Response Elements ........................................................................................................... 15
Errors .............................................................................................................................. 15
See Also .......................................................................................................................... 15
CreateWorkGroup ..................................................................................................................... 16
Request Syntax ................................................................................................................ 16
Request Parameters .......................................................................................................... 16
Response Elements ........................................................................................................... 17
Errors .............................................................................................................................. 17
See Also .......................................................................................................................... 17
DeleteDataCatalog .................................................................................................................... 19
Request Syntax ................................................................................................................ 19
Request Parameters .......................................................................................................... 19
Response Elements ........................................................................................................... 19
Errors .............................................................................................................................. 19
See Also .......................................................................................................................... 19
DeleteNamedQuery .................................................................................................................. 21
Request Syntax ................................................................................................................ 21
Request Parameters .......................................................................................................... 21
Response Elements ........................................................................................................... 21
Errors .............................................................................................................................. 21
See Also .......................................................................................................................... 21
DeletePreparedStatement .......................................................................................................... 23
Errors .............................................................................................................................. 64
See Also .......................................................................................................................... 64
ListTagsForResource .................................................................................................................. 65
Request Syntax ................................................................................................................ 65
Request Parameters .......................................................................................................... 65
Response Syntax .............................................................................................................. 65
Response Elements ........................................................................................................... 66
Errors .............................................................................................................................. 66
See Also .......................................................................................................................... 66
ListWorkGroups ........................................................................................................................ 68
Request Syntax ................................................................................................................ 68
Request Parameters .......................................................................................................... 68
Response Syntax .............................................................................................................. 68
Response Elements ........................................................................................................... 69
Errors .............................................................................................................................. 69
See Also .......................................................................................................................... 69
StartQueryExecution ................................................................................................................. 71
Request Syntax ................................................................................................................ 71
Request Parameters .......................................................................................................... 71
Response Syntax .............................................................................................................. 72
Response Elements ........................................................................................................... 72
Errors .............................................................................................................................. 72
See Also .......................................................................................................................... 73
StopQueryExecution ................................................................................................................. 74
Request Syntax ................................................................................................................ 74
Request Parameters .......................................................................................................... 74
Response Elements ........................................................................................................... 74
Errors .............................................................................................................................. 74
See Also .......................................................................................................................... 74
TagResource ............................................................................................................................ 76
Request Syntax ................................................................................................................ 76
Request Parameters .......................................................................................................... 76
Response Elements ........................................................................................................... 76
Errors .............................................................................................................................. 76
See Also .......................................................................................................................... 77
UntagResource ......................................................................................................................... 78
Request Syntax ................................................................................................................ 78
Request Parameters .......................................................................................................... 78
Response Elements ........................................................................................................... 78
Errors .............................................................................................................................. 78
See Also .......................................................................................................................... 79
UpdateDataCatalog .................................................................................................................. 80
Request Syntax ................................................................................................................ 80
Request Parameters .......................................................................................................... 80
Response Elements ........................................................................................................... 81
Errors .............................................................................................................................. 81
See Also .......................................................................................................................... 81
UpdateNamedQuery ................................................................................................................. 83
Request Syntax ................................................................................................................ 83
Request Parameters .......................................................................................................... 83
Response Elements ........................................................................................................... 84
Errors .............................................................................................................................. 84
See Also .......................................................................................................................... 84
UpdatePreparedStatement ........................................................................................................ 85
Request Syntax ................................................................................................................ 85
Request Parameters .......................................................................................................... 85
Response Elements ........................................................................................................... 86
Errors .............................................................................................................................. 86
See Also .......................................................................................................................... 86
UpdateWorkGroup .................................................................................................................... 87
Request Syntax ................................................................................................................ 87
Request Parameters .......................................................................................................... 87
Response Elements ........................................................................................................... 88
Errors .............................................................................................................................. 88
See Also .......................................................................................................................... 88
Data Types ...................................................................................................................................... 89
AclConfiguration ...................................................................................................................... 91
Contents ......................................................................................................................... 91
See Also .......................................................................................................................... 91
AthenaError ............................................................................................................................. 92
Contents ......................................................................................................................... 92
See Also .......................................................................................................................... 92
BatchGetNamedQueryInput ....................................................................................................... 93
Contents ......................................................................................................................... 93
See Also .......................................................................................................................... 93
BatchGetQueryExecutionInput .................................................................................................... 94
Contents ......................................................................................................................... 94
See Also .......................................................................................................................... 94
Column ................................................................................................................................... 95
Contents ......................................................................................................................... 95
See Also .......................................................................................................................... 95
ColumnInfo .............................................................................................................................. 96
Contents ......................................................................................................................... 96
See Also .......................................................................................................................... 97
Database ................................................................................................................................. 98
Contents ......................................................................................................................... 98
See Also .......................................................................................................................... 98
DataCatalog ............................................................................................................................. 99
Contents ......................................................................................................................... 99
See Also ........................................................................................................................ 100
DataCatalogSummary ............................................................................................................. 101
Contents ........................................................................................................................ 101
See Also ........................................................................................................................ 101
Datum ................................................................................................................................... 102
Contents ........................................................................................................................ 102
See Also ........................................................................................................................ 102
EncryptionConfiguration .......................................................................................................... 103
Contents ........................................................................................................................ 103
See Also ........................................................................................................................ 103
EngineVersion ........................................................................................................................ 104
Contents ........................................................................................................................ 104
See Also ........................................................................................................................ 104
ListNamedQueriesInput ........................................................................................................... 105
Contents ........................................................................................................................ 105
See Also ........................................................................................................................ 105
ListQueryExecutionsInput ........................................................................................................ 106
Contents ........................................................................................................................ 106
See Also ........................................................................................................................ 106
NamedQuery .......................................................................................................................... 107
Contents ........................................................................................................................ 107
See Also ........................................................................................................................ 108
PreparedStatement ................................................................................................................. 109
Contents ........................................................................................................................ 109
See Also ........................................................................................................................ 109
Welcome
Amazon Athena is an interactive query service that lets you use standard SQL to analyze data directly
in Amazon S3. You can point Athena at your data in Amazon S3 and run ad-hoc queries and get results
in seconds. Athena is serverless, so there is no infrastructure to set up or manage. You pay only for the
queries you run. Athena scales automatically—executing queries in parallel—so results are fast, even
with large datasets and complex queries. For more information, see What is Amazon Athena in the
Amazon Athena User Guide.
If you connect to Athena using the JDBC driver, use version 1.1.0 of the driver or later with the Amazon
Athena API. Earlier version drivers do not support the API. For more information and to download the
driver, see Accessing Amazon Athena with JDBC.
For code samples using the AWS SDK for Java, see Examples and Code Samples in the Amazon Athena
User Guide.
Actions
The following actions are supported:
• BatchGetNamedQuery (p. 3)
• BatchGetQueryExecution (p. 5)
• CreateDataCatalog (p. 8)
• CreateNamedQuery (p. 11)
• CreatePreparedStatement (p. 14)
• CreateWorkGroup (p. 16)
• DeleteDataCatalog (p. 19)
• DeleteNamedQuery (p. 21)
• DeletePreparedStatement (p. 23)
• DeleteWorkGroup (p. 25)
• GetDatabase (p. 27)
• GetDataCatalog (p. 29)
• GetNamedQuery (p. 31)
• GetPreparedStatement (p. 33)
• GetQueryExecution (p. 35)
• GetQueryResults (p. 38)
• GetTableMetadata (p. 41)
• GetWorkGroup (p. 44)
• ListDatabases (p. 46)
• ListDataCatalogs (p. 49)
• ListEngineVersions (p. 51)
• ListNamedQueries (p. 53)
• ListPreparedStatements (p. 56)
• ListQueryExecutions (p. 59)
• ListTableMetadata (p. 62)
• ListTagsForResource (p. 65)
• ListWorkGroups (p. 68)
• StartQueryExecution (p. 71)
• StopQueryExecution (p. 74)
• TagResource (p. 76)
• UntagResource (p. 78)
• UpdateDataCatalog (p. 80)
• UpdateNamedQuery (p. 83)
• UpdatePreparedStatement (p. 85)
• UpdateWorkGroup (p. 87)
BatchGetNamedQuery
Returns the details of a single named query or a list of up to 50 queries, which you provide as an array
of query ID strings. Requires you to have access to the workgroup in which the queries were saved.
Use ListNamedQueriesInput (p. 105) to get the list of named query IDs in the specified workgroup. If
information could not be retrieved for a submitted query ID, information about the query ID submitted
is listed under UnprocessedNamedQueryId (p. 129). Named queries differ from executed queries.
Use BatchGetQueryExecutionInput (p. 94) to get details about each unique query execution, and
ListQueryExecutionsInput (p. 106) to get a list of query execution IDs.
Request Syntax
{
"NamedQueryIds": [ "string" ]
}
Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 139).
NamedQueryIds (p. 3)
Required: Yes
Response Syntax
{
"NamedQueries": [
{
"Database": "string",
"Description": "string",
"Name": "string",
"NamedQueryId": "string",
"QueryString": "string",
"WorkGroup": "string"
}
],
"UnprocessedNamedQueryIds": [
{
"ErrorCode": "string",
"ErrorMessage": "string",
"NamedQueryId": "string"
}
]
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
NamedQueries (p. 3)
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates that something is wrong with the input to the request. For example, a required parameter
may be missing or out of range.
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
BatchGetQueryExecution
Returns the details of a single query execution or a list of up to 50 query executions, which you provide
as an array of query execution ID strings. Requires you to have access to the workgroup in which the
queries ran. To get a list of query execution IDs, use ListQueryExecutions:WorkGroup (p. 59). Query
executions differ from named (saved) queries. Use BatchGetNamedQueryInput (p. 93) to get details
about named queries.
Request Syntax
{
"QueryExecutionIds": [ "string" ]
}
Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 139).
QueryExecutionIds (p. 5)
Required: Yes
Response Syntax
{
"QueryExecutions": [
{
"EngineVersion": {
"EffectiveEngineVersion": "string",
"SelectedEngineVersion": "string"
},
"Query": "string",
"QueryExecutionContext": {
"Catalog": "string",
"Database": "string"
},
"QueryExecutionId": "string",
"ResultConfiguration": {
"AclConfiguration": {
"S3AclOption": "string"
},
"EncryptionConfiguration": {
"EncryptionOption": "string",
"KmsKey": "string"
},
"ExpectedBucketOwner": "string",
"OutputLocation": "string"
},
"StatementType": "string",
"Statistics": {
"DataManifestLocation": "string",
"DataScannedInBytes": number,
"EngineExecutionTimeInMillis": number,
"QueryPlanningTimeInMillis": number,
"QueryQueueTimeInMillis": number,
"ServiceProcessingTimeInMillis": number,
"TotalExecutionTimeInMillis": number
},
"Status": {
"AthenaError": {
"ErrorCategory": number,
"ErrorType": number
},
"CompletionDateTime": number,
"State": "string",
"StateChangeReason": "string",
"SubmissionDateTime": number
},
"WorkGroup": "string"
}
],
"UnprocessedQueryExecutionIds": [
{
"ErrorCode": "string",
"ErrorMessage": "string",
"QueryExecutionId": "string"
}
]
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
QueryExecutions (p. 5)
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
InvalidRequestException
Indicates that something is wrong with the input to the request. For example, a required parameter
may be missing or out of range.
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
CreateDataCatalog
Creates (registers) a data catalog with the specified name and properties. Catalogs created are visible to
all users of the same AWS account.
Request Syntax
{
"Description": "string",
"Name": "string",
"Parameters": {
"string" : "string"
},
"Tags": [
{
"Key": "string",
"Value": "string"
}
],
"Type": "string"
}
Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 139).
Description (p. 8)
Type: String
Required: No
Name (p. 8)
The name of the data catalog to create. The catalog name must be unique for the AWS account and
can use a maximum of 127 alphanumeric, underscore, at sign, or hyphen characters. The remainder
of the length constraint of 256 is reserved for use by Athena.
Type: String
Pattern: [\u0020-\uD7FF\uE000-\uFFFD\uD800\uDC00-\uDBFF\uDFFF\t]*
Required: Yes
Parameters (p. 8)
Specifies the Lambda function or functions to use for creating the data catalog. This is a mapping
whose values depend on the catalog type.
• For the HIVE data catalog type, use the following syntax. The metadata-function parameter
is required. The sdk-version parameter is optional and defaults to the currently supported
version.
metadata-function=lambda_arn, sdk-version=version_number
• For the LAMBDA data catalog type, use one of the following sets of required parameters, but not
both.
• If you have one Lambda function that processes metadata and another for reading the actual
data, use the following syntax. Both parameters are required.
metadata-function=lambda_arn, record-function=lambda_arn
• If you have a composite Lambda function that processes both metadata and data, use the
following syntax to specify your Lambda function.
function=lambda_arn
• The GLUE type takes a catalog ID parameter and is required. The catalog_id is the account ID
of the AWS account to which the AWS Glue Data Catalog belongs.
catalog-id=catalog_id
• The GLUE data catalog type also applies to the default AwsDataCatalog that already exists in
your account, of which you can have only one and cannot modify.
• Queries that specify a AWS Glue Data Catalog other than the default AwsDataCatalog must be
run on Athena engine version 2.
• In Regions where Athena engine version 2 is not available, creating new AWS Glue data catalogs
results in an INVALID_INPUT error.
Required: No
Tags (p. 8)
A list of comma separated tags to add to the data catalog that is created.
Required: No
Type (p. 8)
The type of data catalog to create: LAMBDA for a federated catalog, HIVE for an external hive
metastore, or GLUE for an AWS Glue Data Catalog.
Type: String
Required: Yes
Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates that something is wrong with the input to the request. For example, a required parameter
may be missing or out of range.
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
CreateNamedQuery
Creates a named query in the specified workgroup. Requires that you have access to the workgroup.
For code samples using the AWS SDK for Java, see Examples and Code Samples in the Amazon Athena
User Guide.
Request Syntax
{
"ClientRequestToken": "string",
"Database": "string",
"Description": "string",
"Name": "string",
"QueryString": "string",
"WorkGroup": "string"
}
Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 139).
A unique case-sensitive string used to ensure the request to create the query is idempotent (executes
only once). If another CreateNamedQuery request is received, the same response is returned and
another query is not created. If a parameter has changed, for example, the QueryString, an error is
returned.
Important
This token is listed as not required because AWS SDKs (for example the AWS SDK for Java)
auto-generate the token for users. If you are not using the AWS SDK or the AWS CLI, you
must provide this token or the action will fail.
Type: String
Required: No
Database (p. 11)
Type: String
Required: Yes
Description (p. 11)
Type: String
Required: No
Name (p. 11)
Type: String
Required: Yes
QueryString (p. 11)
Type: String
Required: Yes
WorkGroup (p. 11)
The name of the workgroup in which the named query is being created.
Type: String
Pattern: [a-zA-Z0-9._-]{1,128}
Required: No
Response Syntax
{
"NamedQueryId": "string"
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
Type: String
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
InvalidRequestException
Indicates that something is wrong with the input to the request. For example, a required parameter
may be missing or out of range.
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
CreatePreparedStatement
Creates a prepared statement for use with SQL queries in Athena.
Request Syntax
{
"Description": "string",
"QueryStatement": "string",
"StatementName": "string",
"WorkGroup": "string"
}
Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 139).
Type: String
Required: No
QueryStatement (p. 14)
Type: String
Required: Yes
StatementName (p. 14)
Type: String
Pattern: [a-zA-Z_][a-zA-Z0-9_@:]{1,256}
Required: Yes
WorkGroup (p. 14)
Type: String
Pattern: [a-zA-Z0-9._-]{1,128}
Required: Yes
Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates that something is wrong with the input to the request. For example, a required parameter
may be missing or out of range.
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
CreateWorkGroup
Creates a workgroup with the specified name.
Request Syntax
{
"Configuration": {
"BytesScannedCutoffPerQuery": number,
"EnforceWorkGroupConfiguration": boolean,
"EngineVersion": {
"EffectiveEngineVersion": "string",
"SelectedEngineVersion": "string"
},
"PublishCloudWatchMetricsEnabled": boolean,
"RequesterPaysEnabled": boolean,
"ResultConfiguration": {
"AclConfiguration": {
"S3AclOption": "string"
},
"EncryptionConfiguration": {
"EncryptionOption": "string",
"KmsKey": "string"
},
"ExpectedBucketOwner": "string",
"OutputLocation": "string"
}
},
"Description": "string",
"Name": "string",
"Tags": [
{
"Key": "string",
"Value": "string"
}
]
}
Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 139).
The configuration for the workgroup, which includes the location in Amazon S3 where query results
are stored, the encryption configuration, if any, used for encrypting query results, whether the
Amazon CloudWatch Metrics are enabled for the workgroup, the limit for the amount of bytes
scanned (cutoff) per query, if it is specified, and whether workgroup's settings (specified with
EnforceWorkGroupConfiguration) in the WorkGroupConfiguration override client-side
settings. See WorkGroupConfiguration:EnforceWorkGroupConfiguration (p. 133).
Required: No
Description (p. 16)
Type: String
Required: No
Name (p. 16)
Type: String
Pattern: [a-zA-Z0-9._-]{1,128}
Required: Yes
Tags (p. 16)
Required: No
Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates that something is wrong with the input to the request. For example, a required parameter
may be missing or out of range.
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
DeleteDataCatalog
Deletes a data catalog.
Request Syntax
{
"Name": "string"
}
Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 139).
Type: String
Pattern: [\u0020-\uD7FF\uE000-\uFFFD\uD800\uDC00-\uDBFF\uDFFF\t]*
Required: Yes
Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates that something is wrong with the input to the request. For example, a required parameter
may be missing or out of range.
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
DeleteNamedQuery
Deletes the named query if you have access to the workgroup in which the query was saved.
For code samples using the AWS SDK for Java, see Examples and Code Samples in the Amazon Athena
User Guide.
Request Syntax
{
"NamedQueryId": "string"
}
Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 139).
Type: String
Required: Yes
Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates that something is wrong with the input to the request. For example, a required parameter
may be missing or out of range.
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
DeletePreparedStatement
Deletes the prepared statement with the specified name from the specified workgroup.
Request Syntax
{
"StatementName": "string",
"WorkGroup": "string"
}
Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 139).
Type: String
Pattern: [a-zA-Z_][a-zA-Z0-9_@:]{1,256}
Required: Yes
WorkGroup (p. 23)
Type: String
Pattern: [a-zA-Z0-9._-]{1,128}
Required: Yes
Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates that something is wrong with the input to the request. For example, a required parameter
may be missing or out of range.
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
DeleteWorkGroup
Deletes the workgroup with the specified name. The primary workgroup cannot be deleted.
Request Syntax
{
"RecursiveDeleteOption": boolean,
"WorkGroup": "string"
}
Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 139).
The option to delete the workgroup and its contents even if the workgroup contains any named
queries or query executions.
Type: Boolean
Required: No
WorkGroup (p. 25)
Type: String
Pattern: [a-zA-Z0-9._-]{1,128}
Required: Yes
Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates that something is wrong with the input to the request. For example, a required parameter
may be missing or out of range.
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
GetDatabase
Returns a database object for the specified database and data catalog.
Request Syntax
{
"CatalogName": "string",
"DatabaseName": "string"
}
Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 139).
The name of the data catalog that contains the database to return.
Type: String
Pattern: [\u0020-\uD7FF\uE000-\uFFFD\uD800\uDC00-\uDBFF\uDFFF\t]*
Required: Yes
DatabaseName (p. 27)
Type: String
Required: Yes
Response Syntax
{
"Database": {
"Description": "string",
"Name": "string",
"Parameters": {
"string" : "string"
}
}
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates that something is wrong with the input to the request. For example, a required parameter
may be missing or out of range.
An exception that Athena received when it called a custom metastore. Occurs if the error
is not caused by user input (InvalidRequestException) or from the Athena platform
(InternalServerException). For example, if a user-created Lambda function is missing
permissions, the Lambda 4XX exception is returned in a MetadataException.
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
GetDataCatalog
Returns the specified data catalog.
Request Syntax
{
"Name": "string"
}
Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 139).
Type: String
Pattern: [\u0020-\uD7FF\uE000-\uFFFD\uD800\uDC00-\uDBFF\uDFFF\t]*
Required: Yes
Response Syntax
{
"DataCatalog": {
"Description": "string",
"Name": "string",
"Parameters": {
"string" : "string"
},
"Type": "string"
}
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates that something is wrong with the input to the request. For example, a required parameter
may be missing or out of range.
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
GetNamedQuery
Returns information about a single query. Requires that you have access to the workgroup in which the
query was saved.
Request Syntax
{
"NamedQueryId": "string"
}
Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 139).
The unique ID of the query. Use ListNamedQueries (p. 53) to get query IDs.
Type: String
Required: Yes
Response Syntax
{
"NamedQuery": {
"Database": "string",
"Description": "string",
"Name": "string",
"NamedQueryId": "string",
"QueryString": "string",
"WorkGroup": "string"
}
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates that something is wrong with the input to the request. For example, a required parameter
may be missing or out of range.
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
GetPreparedStatement
Retrieves the prepared statement with the specified name from the specified workgroup.
Request Syntax
{
"StatementName": "string",
"WorkGroup": "string"
}
Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 139).
Type: String
Pattern: [a-zA-Z_][a-zA-Z0-9_@:]{1,256}
Required: Yes
WorkGroup (p. 33)
Type: String
Pattern: [a-zA-Z0-9._-]{1,128}
Required: Yes
Response Syntax
{
"PreparedStatement": {
"Description": "string",
"LastModifiedTime": number,
"QueryStatement": "string",
"StatementName": "string",
"WorkGroupName": "string"
}
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates that something is wrong with the input to the request. For example, a required parameter
may be missing or out of range.
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
GetQueryExecution
Returns information about a single execution of a query if you have access to the workgroup in which the
query ran. Each time a query executes, information about the query execution is saved with a unique ID.
Request Syntax
{
"QueryExecutionId": "string"
}
Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 139).
Type: String
Required: Yes
Response Syntax
{
"QueryExecution": {
"EngineVersion": {
"EffectiveEngineVersion": "string",
"SelectedEngineVersion": "string"
},
"Query": "string",
"QueryExecutionContext": {
"Catalog": "string",
"Database": "string"
},
"QueryExecutionId": "string",
"ResultConfiguration": {
"AclConfiguration": {
"S3AclOption": "string"
},
"EncryptionConfiguration": {
"EncryptionOption": "string",
"KmsKey": "string"
},
"ExpectedBucketOwner": "string",
"OutputLocation": "string"
},
"StatementType": "string",
"Statistics": {
"DataManifestLocation": "string",
"DataScannedInBytes": number,
"EngineExecutionTimeInMillis": number,
"QueryPlanningTimeInMillis": number,
"QueryQueueTimeInMillis": number,
"ServiceProcessingTimeInMillis": number,
"TotalExecutionTimeInMillis": number
},
"Status": {
"AthenaError": {
"ErrorCategory": number,
"ErrorType": number
},
"CompletionDateTime": number,
"State": "string",
"StateChangeReason": "string",
"SubmissionDateTime": number
},
"WorkGroup": "string"
}
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates that something is wrong with the input to the request. For example, a required parameter
may be missing or out of range.
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
GetQueryResults
Streams the results of a single query execution specified by QueryExecutionId from the Athena query
results location in Amazon S3. For more information, see Query Results in the Amazon Athena User
Guide. This request does not execute the query but returns results. Use StartQueryExecution (p. 71) to
run a query.
To stream query results successfully, the IAM principal with permission to call GetQueryResults also
must have permissions to the Amazon S3 GetObject action for the Athena query results location.
Important
IAM principals with permission to the Amazon S3 GetObject action for the query results
location are able to retrieve query results from Amazon S3 even if permission to the
GetQueryResults action is denied. To restrict user or role access, ensure that Amazon S3
permissions to the Athena query location are denied.
Request Syntax
{
"MaxResults": number,
"NextToken": "string",
"QueryExecutionId": "string"
}
Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 139).
Type: Integer
Required: No
NextToken (p. 38)
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.
Type: String
Required: No
QueryExecutionId (p. 38)
Type: String
Required: Yes
Response Syntax
{
"NextToken": "string",
"ResultSet": {
"ResultSetMetadata": {
"ColumnInfo": [
{
"CaseSensitive": boolean,
"CatalogName": "string",
"Label": "string",
"Name": "string",
"Nullable": "string",
"Precision": number,
"Scale": number,
"SchemaName": "string",
"TableName": "string",
"Type": "string"
}
]
},
"Rows": [
{
"Data": [
{
"VarCharValue": "string"
}
]
}
]
},
"UpdateCount": number
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
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.
Type: String
Type: Long
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates that something is wrong with the input to the request. For example, a required parameter
may be missing or out of range.
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
GetTableMetadata
Returns table metadata for the specified catalog, database, and table.
Request Syntax
{
"CatalogName": "string",
"DatabaseName": "string",
"TableName": "string"
}
Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 139).
The name of the data catalog that contains the database and table metadata to return.
Type: String
Pattern: [\u0020-\uD7FF\uE000-\uFFFD\uD800\uDC00-\uDBFF\uDFFF\t]*
Required: Yes
DatabaseName (p. 41)
The name of the database that contains the table metadata to return.
Type: String
Required: Yes
TableName (p. 41)
Type: String
Required: Yes
Response Syntax
{
"TableMetadata": {
"Columns": [
{
"Comment": "string",
"Name": "string",
"Type": "string"
}
],
"CreateTime": number,
"LastAccessTime": number,
"Name": "string",
"Parameters": {
"string" : "string"
},
"PartitionKeys": [
{
"Comment": "string",
"Name": "string",
"Type": "string"
}
],
"TableType": "string"
}
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates that something is wrong with the input to the request. For example, a required parameter
may be missing or out of range.
An exception that Athena received when it called a custom metastore. Occurs if the error
is not caused by user input (InvalidRequestException) or from the Athena platform
(InternalServerException). For example, if a user-created Lambda function is missing
permissions, the Lambda 4XX exception is returned in a MetadataException.
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
GetWorkGroup
Returns information about the workgroup with the specified name.
Request Syntax
{
"WorkGroup": "string"
}
Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 139).
Type: String
Pattern: [a-zA-Z0-9._-]{1,128}
Required: Yes
Response Syntax
{
"WorkGroup": {
"Configuration": {
"BytesScannedCutoffPerQuery": number,
"EnforceWorkGroupConfiguration": boolean,
"EngineVersion": {
"EffectiveEngineVersion": "string",
"SelectedEngineVersion": "string"
},
"PublishCloudWatchMetricsEnabled": boolean,
"RequesterPaysEnabled": boolean,
"ResultConfiguration": {
"AclConfiguration": {
"S3AclOption": "string"
},
"EncryptionConfiguration": {
"EncryptionOption": "string",
"KmsKey": "string"
},
"ExpectedBucketOwner": "string",
"OutputLocation": "string"
}
},
"CreationTime": number,
"Description": "string",
"Name": "string",
"State": "string"
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates that something is wrong with the input to the request. For example, a required parameter
may be missing or out of range.
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
ListDatabases
Lists the databases in the specified data catalog.
Request Syntax
{
"CatalogName": "string",
"MaxResults": number,
"NextToken": "string"
}
Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 139).
The name of the data catalog that contains the databases to return.
Type: String
Pattern: [\u0020-\uD7FF\uE000-\uFFFD\uD800\uDC00-\uDBFF\uDFFF\t]*
Required: Yes
MaxResults (p. 46)
Type: Integer
Required: No
NextToken (p. 46)
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.
Type: String
Required: No
Response Syntax
{
"DatabaseList": [
{
"Description": "string",
"Name": "string",
"Parameters": {
"string" : "string"
}
}
],
"NextToken": "string"
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
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.
Type: String
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates that something is wrong with the input to the request. For example, a required parameter
may be missing or out of range.
An exception that Athena received when it called a custom metastore. Occurs if the error
is not caused by user input (InvalidRequestException) or from the Athena platform
(InternalServerException). For example, if a user-created Lambda function is missing
permissions, the Lambda 4XX exception is returned in a MetadataException.
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
ListDataCatalogs
Lists the data catalogs in the current AWS account.
Request Syntax
{
"MaxResults": number,
"NextToken": "string"
}
Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 139).
Type: Integer
Required: No
NextToken (p. 49)
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.
Type: String
Required: No
Response Syntax
{
"DataCatalogsSummary": [
{
"CatalogName": "string",
"Type": "string"
}
],
"NextToken": "string"
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
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.
Type: String
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates that something is wrong with the input to the request. For example, a required parameter
may be missing or out of range.
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
ListEngineVersions
Returns a list of engine versions that are available to choose from, including the Auto option.
Request Syntax
{
"MaxResults": number,
"NextToken": "string"
}
Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 139).
Type: Integer
Required: No
NextToken (p. 51)
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.
Type: String
Required: No
Response Syntax
{
"EngineVersions": [
{
"EffectiveEngineVersion": "string",
"SelectedEngineVersion": "string"
}
],
"NextToken": "string"
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
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.
Type: String
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates that something is wrong with the input to the request. For example, a required parameter
may be missing or out of range.
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
ListNamedQueries
Provides a list of available query IDs only for queries saved in the specified workgroup. Requires that you
have access to the specified workgroup. If a workgroup is not specified, lists the saved queries for the
primary workgroup.
For code samples using the AWS SDK for Java, see Examples and Code Samples in the Amazon Athena
User Guide.
Request Syntax
{
"MaxResults": number,
"NextToken": "string",
"WorkGroup": "string"
}
Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 139).
Type: Integer
Required: No
NextToken (p. 53)
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.
Type: String
Required: No
WorkGroup (p. 53)
The name of the workgroup from which the named queries are being returned. If a workgroup is not
specified, the saved queries for the primary workgroup are returned.
Type: String
Pattern: [a-zA-Z0-9._-]{1,128}
Required: No
Response Syntax
{
"NamedQueryIds": [ "string" ],
"NextToken": "string"
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
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.
Type: String
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates that something is wrong with the input to the request. For example, a required parameter
may be missing or out of range.
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
ListPreparedStatements
Lists the prepared statements in the specfied workgroup.
Request Syntax
{
"MaxResults": number,
"NextToken": "string",
"WorkGroup": "string"
}
Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 139).
Type: Integer
Required: No
NextToken (p. 56)
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.
Type: String
Required: No
WorkGroup (p. 56)
Type: String
Pattern: [a-zA-Z0-9._-]{1,128}
Required: Yes
Response Syntax
{
"NextToken": "string",
"PreparedStatements": [
{
"LastModifiedTime": number,
"StatementName": "string"
}
]
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
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.
Type: String
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates that something is wrong with the input to the request. For example, a required parameter
may be missing or out of range.
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
ListQueryExecutions
Provides a list of available query execution IDs for the queries in the specified workgroup. If a workgroup
is not specified, returns a list of query execution IDs for the primary workgroup. Requires you to have
access to the workgroup in which the queries ran.
For code samples using the AWS SDK for Java, see Examples and Code Samples in the Amazon Athena
User Guide.
Request Syntax
{
"MaxResults": number,
"NextToken": "string",
"WorkGroup": "string"
}
Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 139).
Type: Integer
Required: No
NextToken (p. 59)
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.
Type: String
Required: No
WorkGroup (p. 59)
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.
Type: String
Pattern: [a-zA-Z0-9._-]{1,128}
Required: No
Response Syntax
{
"NextToken": "string",
"QueryExecutionIds": [ "string" ]
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
Type: String
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates that something is wrong with the input to the request. For example, a required parameter
may be missing or out of range.
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
ListTableMetadata
Lists the metadata for the tables in the specified data catalog database.
Request Syntax
{
"CatalogName": "string",
"DatabaseName": "string",
"Expression": "string",
"MaxResults": number,
"NextToken": "string"
}
Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 139).
The name of the data catalog for which table metadata should be returned.
Type: String
Pattern: [\u0020-\uD7FF\uE000-\uFFFD\uD800\uDC00-\uDBFF\uDFFF\t]*
Required: Yes
DatabaseName (p. 62)
The name of the database for which table metadata should be returned.
Type: String
Required: Yes
Expression (p. 62)
A regex filter that pattern-matches table names. If no expression is supplied, metadata for all tables
are listed.
Type: String
Required: No
MaxResults (p. 62)
Type: Integer
Required: No
NextToken (p. 62)
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.
Type: String
Required: No
Response Syntax
{
"NextToken": "string",
"TableMetadataList": [
{
"Columns": [
{
"Comment": "string",
"Name": "string",
"Type": "string"
}
],
"CreateTime": number,
"LastAccessTime": number,
"Name": "string",
"Parameters": {
"string" : "string"
},
"PartitionKeys": [
{
"Comment": "string",
"Name": "string",
"Type": "string"
}
],
"TableType": "string"
}
]
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
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.
Type: String
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates that something is wrong with the input to the request. For example, a required parameter
may be missing or out of range.
An exception that Athena received when it called a custom metastore. Occurs if the error
is not caused by user input (InvalidRequestException) or from the Athena platform
(InternalServerException). For example, if a user-created Lambda function is missing
permissions, the Lambda 4XX exception is returned in a MetadataException.
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
ListTagsForResource
Lists the tags associated with an Athena workgroup or data catalog resource.
Request Syntax
{
"MaxResults": number,
"NextToken": "string",
"ResourceARN": "string"
}
Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 139).
The maximum number of results to be returned per request that lists the tags for the resource.
Type: Integer
Required: No
NextToken (p. 65)
The token for the next set of results, or null if there are no additional results for this request, where
the request lists the tags for the resource with the specified ARN.
Type: String
Required: No
ResourceARN (p. 65)
Lists the tags for the resource with the specified ARN.
Type: String
Required: Yes
Response Syntax
{
"NextToken": "string",
"Tags": [
{
"Key": "string",
"Value": "string"
}
]
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
Type: String
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates that something is wrong with the input to the request. For example, a required parameter
may be missing or out of range.
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
ListWorkGroups
Lists available workgroups for the account.
Request Syntax
{
"MaxResults": number,
"NextToken": "string"
}
Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 139).
Type: Integer
Required: No
NextToken (p. 68)
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.
Type: String
Required: No
Response Syntax
{
"NextToken": "string",
"WorkGroups": [
{
"CreationTime": number,
"Description": "string",
"EngineVersion": {
"EffectiveEngineVersion": "string",
"SelectedEngineVersion": "string"
},
"Name": "string",
"State": "string"
}
]
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
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.
Type: String
A list of WorkGroupSummary (p. 137) objects that include the names, descriptions, creation times,
and states for each workgroup.
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates that something is wrong with the input to the request. For example, a required parameter
may be missing or out of range.
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
StartQueryExecution
Runs the SQL query statements contained in the Query. Requires you to have access to the workgroup
in which the query ran. Running queries against an external catalog requires GetDataCatalog (p. 29)
permission to the catalog. For code samples using the AWS SDK for Java, see Examples and Code
Samples in the Amazon Athena User Guide.
Request Syntax
{
"ClientRequestToken": "string",
"QueryExecutionContext": {
"Catalog": "string",
"Database": "string"
},
"QueryString": "string",
"ResultConfiguration": {
"AclConfiguration": {
"S3AclOption": "string"
},
"EncryptionConfiguration": {
"EncryptionOption": "string",
"KmsKey": "string"
},
"ExpectedBucketOwner": "string",
"OutputLocation": "string"
},
"WorkGroup": "string"
}
Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 139).
A unique case-sensitive string used to ensure the request to create the query is idempotent (executes
only once). If another StartQueryExecution request is received, the same response is returned
and another query is not created. If a parameter has changed, for example, the QueryString, an
error is returned.
Important
This token is listed as not required because AWS SDKs (for example the AWS SDK for Java)
auto-generate the token for users. If you are not using the AWS SDK or the AWS CLI, you
must provide this token or the action will fail.
Type: String
Required: No
QueryExecutionContext (p. 71)
Required: No
QueryString (p. 71)
Type: String
Required: Yes
ResultConfiguration (p. 71)
Specifies information about where and how to save the results of the query execution. If
the query runs in a workgroup, then workgroup's settings may override query settings.
This affects the query results location. The workgroup settings override is specified
in EnforceWorkGroupConfiguration (true/false) in the WorkGroupConfiguration. See
WorkGroupConfiguration:EnforceWorkGroupConfiguration (p. 133).
Required: No
WorkGroup (p. 71)
Type: String
Pattern: [a-zA-Z0-9._-]{1,128}
Required: No
Response Syntax
{
"QueryExecutionId": "string"
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
Type: String
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates that something is wrong with the input to the request. For example, a required parameter
may be missing or out of range.
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
StopQueryExecution
Stops a query execution. Requires you to have access to the workgroup in which the query ran.
For code samples using the AWS SDK for Java, see Examples and Code Samples in the Amazon Athena
User Guide.
Request Syntax
{
"QueryExecutionId": "string"
}
Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 139).
Type: String
Required: Yes
Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates that something is wrong with the input to the request. For example, a required parameter
may be missing or out of range.
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
TagResource
Adds one or more tags to an Athena resource. A tag is a label that you assign to a resource. In Athena, a
resource can be a workgroup or data catalog. Each tag consists of a key and an optional value, both of
which you define. For example, you can use tags to categorize Athena workgroups or data catalogs by
purpose, owner, or environment. Use a consistent set of tag keys to make it easier to search and filter
workgroups or data catalogs in your account. For best practices, see Tagging Best Practices. Tag keys
can be from 1 to 128 UTF-8 Unicode characters, and tag values can be from 0 to 256 UTF-8 Unicode
characters. Tags can use letters and numbers representable in UTF-8, and the following characters: + - = .
_ : / @. Tag keys and values are case-sensitive. Tag keys must be unique per resource. If you specify more
than one tag, separate them by commas.
Request Syntax
{
"ResourceARN": "string",
"Tags": [
{
"Key": "string",
"Value": "string"
}
]
}
Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 139).
Specifies the ARN of the Athena resource (workgroup or data catalog) to which tags are to be added.
Type: String
Required: Yes
Tags (p. 76)
A collection of one or more tags, separated by commas, to be added to an Athena workgroup or data
catalog resource.
Required: Yes
Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates that something is wrong with the input to the request. For example, a required parameter
may be missing or out of range.
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
UntagResource
Removes one or more tags from a data catalog or workgroup resource.
Request Syntax
{
"ResourceARN": "string",
"TagKeys": [ "string" ]
}
Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 139).
Specifies the ARN of the resource from which tags are to be removed.
Type: String
Required: Yes
TagKeys (p. 78)
A comma-separated list of one or more tag keys whose tags are to be removed from the specified
resource.
Required: Yes
Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates that something is wrong with the input to the request. For example, a required parameter
may be missing or out of range.
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
UpdateDataCatalog
Updates the data catalog that has the specified name.
Request Syntax
{
"Description": "string",
"Name": "string",
"Parameters": {
"string" : "string"
},
"Type": "string"
}
Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 139).
Type: String
Required: No
Name (p. 80)
The name of the data catalog to update. The catalog name must be unique for the AWS account and
can use a maximum of 127 alphanumeric, underscore, at sign, or hyphen characters. The remainder
of the length constraint of 256 is reserved for use by Athena.
Type: String
Pattern: [\u0020-\uD7FF\uE000-\uFFFD\uD800\uDC00-\uDBFF\uDFFF\t]*
Required: Yes
Parameters (p. 80)
Specifies the Lambda function or functions to use for updating the data catalog. This is a mapping
whose values depend on the catalog type.
• For the HIVE data catalog type, use the following syntax. The metadata-function parameter
is required. The sdk-version parameter is optional and defaults to the currently supported
version.
metadata-function=lambda_arn, sdk-version=version_number
• For the LAMBDA data catalog type, use one of the following sets of required parameters, but not
both.
• If you have one Lambda function that processes metadata and another for reading the actual
data, use the following syntax. Both parameters are required.
metadata-function=lambda_arn, record-function=lambda_arn
• If you have a composite Lambda function that processes both metadata and data, use the
following syntax to specify your Lambda function.
function=lambda_arn
Required: No
Type (p. 80)
Specifies the type of data catalog to update. Specify LAMBDA for a federated catalog, HIVE for an
external hive metastore, or GLUE for an AWS Glue Data Catalog.
Type: String
Required: Yes
Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates that something is wrong with the input to the request. For example, a required parameter
may be missing or out of range.
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
UpdateNamedQuery
Updates a NamedQuery (p. 107) object. The database or workgroup cannot be updated.
Request Syntax
{
"Description": "string",
"Name": "string",
"NamedQueryId": "string",
"QueryString": "string"
}
Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 139).
Type: String
Required: No
Name (p. 83)
Type: String
Required: Yes
NamedQueryId (p. 83)
Type: String
Required: Yes
QueryString (p. 83)
Type: String
Required: Yes
Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates that something is wrong with the input to the request. For example, a required parameter
may be missing or out of range.
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
UpdatePreparedStatement
Updates a prepared statement.
Request Syntax
{
"Description": "string",
"QueryStatement": "string",
"StatementName": "string",
"WorkGroup": "string"
}
Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 139).
Type: String
Required: No
QueryStatement (p. 85)
Type: String
Required: Yes
StatementName (p. 85)
Type: String
Pattern: [a-zA-Z_][a-zA-Z0-9_@:]{1,256}
Required: Yes
WorkGroup (p. 85)
Type: String
Pattern: [a-zA-Z0-9._-]{1,128}
Required: Yes
Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates that something is wrong with the input to the request. For example, a required parameter
may be missing or out of range.
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
UpdateWorkGroup
Updates the workgroup with the specified name. The workgroup's name cannot be changed.
Request Syntax
{
"ConfigurationUpdates": {
"BytesScannedCutoffPerQuery": number,
"EnforceWorkGroupConfiguration": boolean,
"EngineVersion": {
"EffectiveEngineVersion": "string",
"SelectedEngineVersion": "string"
},
"PublishCloudWatchMetricsEnabled": boolean,
"RemoveBytesScannedCutoffPerQuery": boolean,
"RequesterPaysEnabled": boolean,
"ResultConfigurationUpdates": {
"AclConfiguration": {
"S3AclOption": "string"
},
"EncryptionConfiguration": {
"EncryptionOption": "string",
"KmsKey": "string"
},
"ExpectedBucketOwner": "string",
"OutputLocation": "string",
"RemoveAclConfiguration": boolean,
"RemoveEncryptionConfiguration": boolean,
"RemoveExpectedBucketOwner": boolean,
"RemoveOutputLocation": boolean
}
},
"Description": "string",
"State": "string",
"WorkGroup": "string"
}
Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 139).
The workgroup configuration that will be updated for the given workgroup.
Required: No
Description (p. 87)
Type: String
Required: No
State (p. 87)
The workgroup state that will be updated for the given workgroup.
Type: String
Required: No
WorkGroup (p. 87)
Type: String
Pattern: [a-zA-Z0-9._-]{1,128}
Required: Yes
Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates that something is wrong with the input to the request. For example, a required parameter
may be missing or out of range.
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
Data Types
The Amazon Athena API contains several data types that various actions use. This section describes each
data type in detail.
Note
The order of each element in a data type structure is not guaranteed. Applications should not
assume a particular order.
AclConfiguration
Indicates that an Amazon S3 canned ACL should be set to control ownership of stored query results.
When Athena stores query results in Amazon S3, the canned ACL is set with the x-amz-acl request
header. For more information about S3 Object Ownership, see Object Ownership settings in the Amazon
S3 User Guide.
Contents
S3AclOption
The Amazon S3 canned ACL that Athena should specify when storing query results. Currently the
only supported canned ACL is BUCKET_OWNER_FULL_CONTROL. If a query runs in a workgroup
and the workgroup overrides client-side settings, then the Amazon S3 canned ACL specified in the
workgroup's settings is used for all queries that run in the workgroup. For more information about
Amazon S3 canned ACLs, see Canned ACL in the Amazon S3 User Guide.
Type: String
Required: Yes
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
AthenaError
Provides information about an Athena query error. The AthenaError feature provides standardized
error information to help you understand failed queries and take steps after a query failure occurs.
AthenaError includes an ErrorCategory field that specifies whether the cause of the failed query is
due to system error, user error, or other error.
Contents
ErrorCategory
An integer value that specifies the category of a query failure error. The following list shows the
category for each integer value.
1 - System
2 - User
3 - Other
Type: Integer
Required: No
ErrorType
An integer value that provides specific information about an Athena query error. For the meaning of
specific values, see the Error Type Reference in the Amazon Athena User Guide.
Type: Integer
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
BatchGetNamedQueryInput
Contents
NamedQueryIds
Required: Yes
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
BatchGetQueryExecutionInput
Contents
QueryExecutionIds
Required: Yes
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
Column
Contains metadata for a column in a table.
Contents
Comment
Type: String
Pattern: [\u0020-\uD7FF\uE000-\uFFFD\uD800\uDC00-\uDBFF\uDFFF\t]*
Required: No
Name
Type: String
Required: Yes
Type
Type: String
Pattern: [\u0020-\uD7FF\uE000-\uFFFD\uD800\uDC00-\uDBFF\uDFFF\t]*
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
ColumnInfo
Information about the columns in a query execution result.
Contents
CaseSensitive
Type: Boolean
Required: No
CatalogName
Type: String
Required: No
Label
A column label.
Type: String
Required: No
Name
Type: String
Required: Yes
Nullable
Type: String
Required: No
Precision
For DECIMAL data types, specifies the total number of digits, up to 38. For performance reasons, we
recommend up to 18 digits.
Type: Integer
Required: No
Scale
For DECIMAL data types, specifies the total number of digits in the fractional part of the value.
Defaults to 0.
Type: Integer
Required: No
SchemaName
The schema name (database name) to which the query results belong.
Type: String
Required: No
TableName
Type: String
Required: No
Type
Type: String
Required: Yes
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
Database
Contains metadata information for a database in a data catalog.
Contents
Description
Type: String
Required: No
Name
Type: String
Required: Yes
Parameters
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
DataCatalog
Contains information about a data catalog in an AWS account.
Contents
Description
Type: String
Required: No
Name
The name of the data catalog. The catalog name must be unique for the AWS account and can use
a maximum of 127 alphanumeric, underscore, at sign, or hyphen characters. The remainder of the
length constraint of 256 is reserved for use by Athena.
Type: String
Pattern: [\u0020-\uD7FF\uE000-\uFFFD\uD800\uDC00-\uDBFF\uDFFF\t]*
Required: Yes
Parameters
Specifies the Lambda function or functions to use for the data catalog. This is a mapping whose
values depend on the catalog type.
• For the HIVE data catalog type, use the following syntax. The metadata-function parameter
is required. The sdk-version parameter is optional and defaults to the currently supported
version.
metadata-function=lambda_arn, sdk-version=version_number
• For the LAMBDA data catalog type, use one of the following sets of required parameters, but not
both.
• If you have one Lambda function that processes metadata and another for reading the actual
data, use the following syntax. Both parameters are required.
metadata-function=lambda_arn, record-function=lambda_arn
• If you have a composite Lambda function that processes both metadata and data, use the
following syntax to specify your Lambda function.
function=lambda_arn
• The GLUE type takes a catalog ID parameter and is required. The catalog_id is the account ID
of the AWS account to which the AWS Glue catalog belongs.
catalog-id=catalog_id
• The GLUE data catalog type also applies to the default AwsDataCatalog that already exists in
your account, of which you can have only one and cannot modify.
• Queries that specify a AWS Glue Data Catalog other than the default AwsDataCatalog must be
run on Athena engine version 2.
Required: No
Type
The type of data catalog to create: LAMBDA for a federated catalog, HIVE for an external hive
metastore, or GLUE for an AWS Glue Data Catalog.
Type: String
Required: Yes
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
DataCatalogSummary
The summary information for the data catalog, which includes its name and type.
Contents
CatalogName
The name of the data catalog. The catalog name is unique for the AWS account and can use a
maximum of 127 alphanumeric, underscore, at sign, or hyphen characters. The remainder of the
length constraint of 256 is reserved for use by Athena.
Type: String
Pattern: [\u0020-\uD7FF\uE000-\uFFFD\uD800\uDC00-\uDBFF\uDFFF\t]*
Required: No
Type
Type: String
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
Datum
A piece of data (a field in the table).
Contents
VarCharValue
Type: String
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
EncryptionConfiguration
If query results are encrypted in Amazon S3, indicates the encryption option used (for example, SSE_KMS
or CSE_KMS) and key information.
Contents
EncryptionOption
Indicates whether Amazon S3 server-side encryption with Amazon S3-managed keys (SSE_S3),
server-side encryption with KMS-managed keys (SSE_KMS), or client-side encryption with KMS-
managed keys (CSE_KMS) is used.
If a query runs in a workgroup and the workgroup overrides client-side settings, then the
workgroup's setting for encryption is used. It specifies whether query results must be encrypted, for
all queries that run in this workgroup.
Type: String
Required: Yes
KmsKey
For SSE_KMS and CSE_KMS, this is the KMS key ARN or ID.
Type: String
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
EngineVersion
The Athena engine version for running queries.
Contents
EffectiveEngineVersion
Read only. The engine version on which the query runs. If the user requests a valid engine version
other than Auto, the effective engine version is the same as the engine version that the user
requested. If the user requests Auto, the effective engine version is chosen by Athena. When a
request to update the engine version is made by a CreateWorkGroup or UpdateWorkGroup
operation, the EffectiveEngineVersion field is ignored.
Type: String
Required: No
SelectedEngineVersion
The engine version requested by the user. Possible values are determined by the output of
ListEngineVersions, including Auto. The default is Auto.
Type: String
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
ListNamedQueriesInput
Contents
MaxResults
Type: Integer
Required: No
NextToken
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.
Type: String
Required: No
WorkGroup
The name of the workgroup from which the named queries are being returned. If a workgroup is not
specified, the saved queries for the primary workgroup are returned.
Type: String
Pattern: [a-zA-Z0-9._-]{1,128}
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
ListQueryExecutionsInput
Contents
MaxResults
Type: Integer
Required: No
NextToken
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.
Type: String
Required: No
WorkGroup
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.
Type: String
Pattern: [a-zA-Z0-9._-]{1,128}
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
NamedQuery
A query, where QueryString contains the SQL statements that make up the query.
Contents
Database
Type: String
Required: Yes
Description
Type: String
Required: No
Name
Type: String
Required: Yes
NamedQueryId
Type: String
Required: No
QueryString
Type: String
Required: Yes
WorkGroup
Type: String
Pattern: [a-zA-Z0-9._-]{1,128}
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
PreparedStatement
A prepared SQL statement for use with Athena.
Contents
Description
Type: String
Required: No
LastModifiedTime
Type: Timestamp
Required: No
QueryStatement
Type: String
Required: No
StatementName
Type: String
Pattern: [a-zA-Z_][a-zA-Z0-9_@:]{1,256}
Required: No
WorkGroupName
Type: String
Pattern: [a-zA-Z0-9._-]{1,128}
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
PreparedStatementSummary
The name and last modified time of the prepared statement.
Contents
LastModifiedTime
Type: Timestamp
Required: No
StatementName
Type: String
Pattern: [a-zA-Z_][a-zA-Z0-9_@:]{1,256}
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
QueryExecution
Information about a single instance of a query execution.
Contents
EngineVersion
Required: No
Query
Type: String
Required: No
QueryExecutionContext
Required: No
QueryExecutionId
Type: String
Required: No
ResultConfiguration
The location in Amazon S3 where query results were stored and the encryption option, if any, used
for query results. These are known as "client-side settings". If workgroup settings override client-side
settings, then the query uses the location for the query results and the encryption configuration that
are specified for the workgroup.
Required: No
StatementType
The type of query statement that was run. DDL indicates DDL query statements. DML indicates DML
(Data Manipulation Language) query statements, such as CREATE TABLE AS SELECT. UTILITY
indicates query statements other than DDL and DML, such as SHOW CREATE TABLE, or DESCRIBE
TABLE.
Type: String
Required: No
Statistics
Query execution statistics, such as the amount of data scanned, the amount of time that the query
took to process, and the type of statement that was run.
Required: No
Status
The completion date, current state, submission time, and state change reason (if applicable) for the
query execution.
Required: No
WorkGroup
Type: String
Pattern: [a-zA-Z0-9._-]{1,128}
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
QueryExecutionContext
The database and data catalog context in which the query execution occurs.
Contents
Catalog
Type: String
Pattern: [\u0020-\uD7FF\uE000-\uFFFD\uD800\uDC00-\uDBFF\uDFFF\t]*
Required: No
Database
The name of the database used in the query execution. The database must exist in the catalog.
Type: String
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
QueryExecutionStatistics
The amount of data scanned during the query execution and the amount of time that it took to execute,
and the type of statement that was run.
Contents
DataManifestLocation
The location and file name of a data manifest file. The manifest file is saved to the Athena query
results location in Amazon S3. The manifest file tracks files that the query wrote to Amazon S3.
If the query fails, the manifest file also tracks files that the query intended to write. The manifest
is useful for identifying orphaned files resulting from a failed query. For more information, see
Working with Query Results, Output Files, and Query History in the Amazon Athena User Guide.
Type: String
Required: No
DataScannedInBytes
Type: Long
Required: No
EngineExecutionTimeInMillis
Type: Long
Required: No
QueryPlanningTimeInMillis
The number of milliseconds that Athena took to plan the query processing flow. This includes the
time spent retrieving table partitions from the data source. Note that because the query engine
performs the query planning, query planning time is a subset of engine processing time.
Type: Long
Required: No
QueryQueueTimeInMillis
The number of milliseconds that the query was in your query queue waiting for resources. Note that
if transient errors occur, Athena might automatically add the query back to the queue.
Type: Long
Required: No
ServiceProcessingTimeInMillis
The number of milliseconds that Athena took to finalize and publish the query results after the
query engine finished running the query.
Type: Long
Required: No
TotalExecutionTimeInMillis
Type: Long
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
QueryExecutionStatus
The completion date, current state, submission time, and state change reason (if applicable) for the
query execution.
Contents
AthenaError
Required: No
CompletionDateTime
Type: Timestamp
Required: No
State
The state of query execution. QUEUED indicates that the query has been submitted to the service,
and Athena will execute the query as soon as resources are available. RUNNING indicates that the
query is in execution phase. SUCCEEDED indicates that the query completed without errors. FAILED
indicates that the query experienced an error and did not complete processing. CANCELLED indicates
that a user input interrupted query execution.
Note
Athena automatically retries your queries in cases of certain transient errors. As a result, you
may see the query state transition from RUNNING or FAILED to QUEUED.
Type: String
Required: No
StateChangeReason
Type: String
Required: No
SubmissionDateTime
Type: Timestamp
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
ResultConfiguration
The location in Amazon S3 where query results are stored and the encryption option, if any, used for
query results. These are known as "client-side settings". If workgroup settings override client-side
settings, then the query uses the workgroup settings.
Contents
AclConfiguration
Indicates that an Amazon S3 canned ACL should be set to control ownership of stored
query results. Currently the only supported canned ACL is BUCKET_OWNER_FULL_CONTROL.
This is a client-side setting. If workgroup settings override client-side settings, then the
query uses the ACL configuration that is specified for the workgroup, and also uses the
location for storing query results specified in the workgroup. For more information, see
WorkGroupConfiguration:EnforceWorkGroupConfiguration (p. 133) and Workgroup Settings
Override Client-Side Settings.
Required: No
EncryptionConfiguration
If query results are encrypted in Amazon S3, indicates the encryption option used (for example,
SSE_KMS or CSE_KMS) and key information. This is a client-side setting. If workgroup settings
override client-side settings, then the query uses the encryption configuration that is specified
for the workgroup, and also uses the location for storing query results specified in the workgroup.
See WorkGroupConfiguration:EnforceWorkGroupConfiguration (p. 133) and Workgroup Settings
Override Client-Side Settings.
Required: No
ExpectedBucketOwner
The AWS account ID that you expect to be the owner of the Amazon S3 bucket specified
by ResultConfiguration:OutputLocation (p. 119). If set, Athena uses the value for
ExpectedBucketOwner when it makes Amazon S3 calls to your specified output location. If the
ExpectedBucketOwner AWS account ID does not match the actual owner of the Amazon S3
bucket, the call fails with a permissions error.
This is a client-side setting. If workgroup settings override client-side settings, then the
query uses the ExpectedBucketOwner setting that is specified for the workgroup,
and also uses the location for storing query results specified in the workgroup. See
WorkGroupConfiguration:EnforceWorkGroupConfiguration (p. 133) and Workgroup Settings
Override Client-Side Settings.
Type: String
Required: No
OutputLocation
The location in Amazon S3 where your query results are stored, such as s3://path/to/
query/bucket/. To run the query, you must specify the query results location using one of
the ways: either for individual queries using either this setting (client-side), or in the workgroup,
using WorkGroupConfiguration (p. 133). If none of them is set, Athena issues an error that
no output location is provided. For more information, see Query Results. If workgroup settings
override client-side settings, then the query uses the settings specified for the workgroup. See
WorkGroupConfiguration:EnforceWorkGroupConfiguration (p. 133).
Type: String
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
ResultConfigurationUpdates
The information about the updates in the query results, such as output location and encryption
configuration for the query results.
Contents
AclConfiguration
Required: No
EncryptionConfiguration
Required: No
ExpectedBucketOwner
The AWS account ID that you expect to be the owner of the Amazon S3 bucket specified
by ResultConfiguration:OutputLocation (p. 119). If set, Athena uses the value for
ExpectedBucketOwner when it makes Amazon S3 calls to your specified output location. If the
ExpectedBucketOwner AWS account ID does not match the actual owner of the Amazon S3
bucket, the call fails with a permissions error.
If workgroup settings override client-side settings, then the query uses the ExpectedBucketOwner
setting that is specified for the workgroup, and also uses the location for storing query results
specified in the workgroup. See WorkGroupConfiguration:EnforceWorkGroupConfiguration (p. 133)
and Workgroup Settings Override Client-Side Settings.
Type: String
Required: No
OutputLocation
The location in Amazon S3 where your query results are stored, such as s3://path/to/
query/bucket/. For more information, see Query Results If workgroup settings override
client-side settings, then the query uses the location for the query results and the encryption
configuration that are specified for the workgroup. The "workgroup settings override" is specified
in EnforceWorkGroupConfiguration (true/false) in the WorkGroupConfiguration. See
WorkGroupConfiguration:EnforceWorkGroupConfiguration (p. 133).
Type: String
Required: No
RemoveAclConfiguration
If set to true, indicates that the previously-specified ACL configuration for queries in this
workgroup should be ignored and set to null. If set to false or not set, and a value is present in
the AclConfiguration of ResultConfigurationUpdates, the AclConfiguration in the
workgroup's ResultConfiguration is updated with the new value. For more information, see
Workgroup Settings Override Client-Side Settings.
Type: Boolean
Required: No
RemoveEncryptionConfiguration
If set to "true", indicates that the previously-specified encryption configuration (also known
as the client-side setting) for queries in this workgroup should be ignored and set to null.
If set to "false" or not set, and a value is present in the EncryptionConfiguration in
ResultConfigurationUpdates (the client-side setting), the EncryptionConfiguration in the
workgroup's ResultConfiguration will be updated with the new value. For more information, see
Workgroup Settings Override Client-Side Settings.
Type: Boolean
Required: No
RemoveExpectedBucketOwner
Type: Boolean
Required: No
RemoveOutputLocation
If set to "true", indicates that the previously-specified query results location (also known as a client-
side setting) for queries in this workgroup should be ignored and set to null. If set to "false" or not
set, and a value is present in the OutputLocation in ResultConfigurationUpdates (the client-
side setting), the OutputLocation in the workgroup's ResultConfiguration will be updated
with the new value. For more information, see Workgroup Settings Override Client-Side Settings.
Type: Boolean
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
ResultSet
The metadata and rows that make up a query result set. The metadata describes the column structure
and data types. To return a ResultSet object, use GetQueryResults (p. 38).
Contents
ResultSetMetadata
The metadata that describes the column structure and data types of a table of query results.
Required: No
Rows
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
ResultSetMetadata
The metadata that describes the column structure and data types of a table of query results. To return a
ResultSetMetadata object, use GetQueryResults (p. 38).
Contents
ColumnInfo
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
Row
The rows that make up a query result table.
Contents
Data
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
TableMetadata
Contains metadata for a table.
Contents
Columns
Required: No
CreateTime
Type: Timestamp
Required: No
LastAccessTime
Type: Timestamp
Required: No
Name
Type: String
Required: Yes
Parameters
Required: No
PartitionKeys
Required: No
TableType
Type: String
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
Tag
A label that you assign to a resource. In Athena, a resource can be a workgroup or data catalog. Each
tag consists of a key and an optional value, both of which you define. For example, you can use tags to
categorize Athena workgroups or data catalogs by purpose, owner, or environment. Use a consistent set
of tag keys to make it easier to search and filter workgroups or data catalogs in your account. For best
practices, see Tagging Best Practices. Tag keys can be from 1 to 128 UTF-8 Unicode characters, and tag
values can be from 0 to 256 UTF-8 Unicode characters. Tags can use letters and numbers representable
in UTF-8, and the following characters: + - = . _ : / @. Tag keys and values are case-sensitive. Tag keys
must be unique per resource. If you specify more than one tag, separate them by commas.
Contents
Key
A tag key. The tag key length is from 1 to 128 Unicode characters in UTF-8. You can use letters and
numbers representable in UTF-8, and the following characters: + - = . _ : / @. Tag keys are case-
sensitive and must be unique per resource.
Type: String
Required: No
Value
A tag value. The tag value length is from 0 to 256 Unicode characters in UTF-8. You can use letters
and numbers representable in UTF-8, and the following characters: + - = . _ : / @. Tag values are
case-sensitive.
Type: String
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
UnprocessedNamedQueryId
Information about a named query ID that could not be processed.
Contents
ErrorCode
The error code returned when the processing request for the named query failed, if applicable.
Type: String
Required: No
ErrorMessage
The error message returned when the processing request for the named query failed, if applicable.
Type: String
Required: No
NamedQueryId
Type: String
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
UnprocessedQueryExecutionId
Describes a query execution that failed to process.
Contents
ErrorCode
The error code returned when the query execution failed to process, if applicable.
Type: String
Required: No
ErrorMessage
The error message returned when the query execution failed to process, if applicable.
Type: String
Required: No
QueryExecutionId
Type: String
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
WorkGroup
A workgroup, which contains a name, description, creation time, state, and other configuration, listed
under WorkGroup:Configuration (p. 131). Each workgroup enables you to isolate queries for you or
your group of users from other queries in the same account, to configure the query results location and
the encryption configuration (known as workgroup settings), to enable sending query metrics to Amazon
CloudWatch, and to establish per-query data usage control limits for all queries in a workgroup. The
workgroup settings override is specified in EnforceWorkGroupConfiguration (true/false) in the
WorkGroupConfiguration. See WorkGroupConfiguration:EnforceWorkGroupConfiguration (p. 133).
Contents
Configuration
The configuration of the workgroup, which includes the location in Amazon S3 where query
results are stored, the encryption configuration, if any, used for query results; whether
the Amazon CloudWatch Metrics are enabled for the workgroup; whether workgroup
settings override client-side settings; and the data usage limits for the amount of data
scanned per query or per workgroup. The workgroup settings override is specified in
EnforceWorkGroupConfiguration (true/false) in the WorkGroupConfiguration. See
WorkGroupConfiguration:EnforceWorkGroupConfiguration (p. 133).
Required: No
CreationTime
Type: Timestamp
Required: No
Description
Type: String
Required: No
Name
Type: String
Pattern: [a-zA-Z0-9._-]{1,128}
Required: Yes
State
Type: String
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
WorkGroupConfiguration
The configuration of the workgroup, which includes the location in Amazon S3 where query results are
stored, the encryption option, if any, used for query results, whether the Amazon CloudWatch Metrics are
enabled for the workgroup and whether workgroup settings override query settings, and the data usage
limits for the amount of data scanned per query or per workgroup. The workgroup settings override is
specified in EnforceWorkGroupConfiguration (true/false) in the WorkGroupConfiguration. See
WorkGroupConfiguration:EnforceWorkGroupConfiguration (p. 133).
Contents
BytesScannedCutoffPerQuery
The upper data usage limit (cutoff) for the amount of bytes a single query in a workgroup is allowed
to scan.
Type: Long
Required: No
EnforceWorkGroupConfiguration
If set to "true", the settings for the workgroup override client-side settings. If set to "false", client-
side settings are used. For more information, see Workgroup Settings Override Client-Side Settings.
Type: Boolean
Required: No
EngineVersion
The engine version that all queries running on the workgroup use. Queries on the
AmazonAthenaPreviewFunctionality workgroup run on the preview engine regardless of this
setting.
Required: No
PublishCloudWatchMetricsEnabled
Indicates that the Amazon CloudWatch metrics are enabled for the workgroup.
Type: Boolean
Required: No
RequesterPaysEnabled
If set to true, allows members assigned to a workgroup to reference Amazon S3 Requester Pays
buckets in queries. If set to false, workgroup members cannot query data from Requester Pays
buckets, and queries that retrieve data from Requester Pays buckets cause an error. The default
is false. For more information about Requester Pays buckets, see Requester Pays Buckets in the
Amazon Simple Storage Service Developer Guide.
Type: Boolean
Required: No
ResultConfiguration
The configuration for the workgroup, which includes the location in Amazon S3 where query results
are stored and the encryption option, if any, used for query results. To run the query, you must
specify the query results location using one of the ways: either in the workgroup using this setting,
or for individual queries (client-side), using ResultConfiguration:OutputLocation (p. 119). If none of
them is set, Athena issues an error that no output location is provided. For more information, see
Query Results.
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
WorkGroupConfigurationUpdates
The configuration information that will be updated for this workgroup, which includes the location in
Amazon S3 where query results are stored, the encryption option, if any, used for query results, whether
the Amazon CloudWatch Metrics are enabled for the workgroup, whether the workgroup settings
override the client-side settings, and the data usage limit for the amount of bytes scanned per query, if it
is specified.
Contents
BytesScannedCutoffPerQuery
The upper limit (cutoff) for the amount of bytes a single query in a workgroup is allowed to scan.
Type: Long
Required: No
EnforceWorkGroupConfiguration
If set to "true", the settings for the workgroup override client-side settings. If set to "false" client-side
settings are used. For more information, see Workgroup Settings Override Client-Side Settings.
Type: Boolean
Required: No
EngineVersion
The engine version requested when a workgroup is updated. After the update, all queries on the
workgroup run on the requested engine version. If no value was previously set, the default is Auto.
Queries on the AmazonAthenaPreviewFunctionality workgroup run on the preview engine
regardless of this setting.
Required: No
PublishCloudWatchMetricsEnabled
Type: Boolean
Required: No
RemoveBytesScannedCutoffPerQuery
Indicates that the data usage control limit per query is removed.
WorkGroupConfiguration:BytesScannedCutoffPerQuery (p. 133)
Type: Boolean
Required: No
RequesterPaysEnabled
If set to true, allows members assigned to a workgroup to specify Amazon S3 Requester Pays
buckets in queries. If set to false, workgroup members cannot query data from Requester Pays
buckets, and queries that retrieve data from Requester Pays buckets cause an error. The default
is false. For more information about Requester Pays buckets, see Requester Pays Buckets in the
Amazon Simple Storage Service Developer Guide.
Type: Boolean
Required: No
ResultConfigurationUpdates
The result configuration information about the queries in this workgroup that will be updated.
Includes the updated results location and an updated option for encrypting query results.
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
WorkGroupSummary
The summary information for the workgroup, which includes its name, state, description, and the date
and time it was created.
Contents
CreationTime
Type: Timestamp
Required: No
Description
Type: String
Required: No
EngineVersion
The engine version setting for all queries on the workgroup. Queries on the
AmazonAthenaPreviewFunctionality workgroup run on the preview engine regardless of this
setting.
Required: No
Name
Type: String
Pattern: [a-zA-Z0-9._-]{1,128}
Required: No
State
Type: String
Required: No
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
Common Parameters
The following list contains the parameters that all actions use for signing Signature Version 4 requests
with a query string. Any action-specific parameters are listed in the topic for that action. For more
information about Signature Version 4, see Signature Version 4 Signing Process in the Amazon Web
Services General Reference.
Action
Type: string
Required: Yes
Version
The API version that the request is written for, expressed in the format YYYY-MM-DD.
Type: string
Required: Yes
X-Amz-Algorithm
The hash algorithm that you used to create the request signature.
Condition: Specify this parameter when you include authentication information in a query string
instead of in the HTTP authorization header.
Type: string
Required: Conditional
X-Amz-Credential
The credential scope value, which is a string that includes your access key, the date, the region you
are targeting, the service you are requesting, and a termination string ("aws4_request"). The value is
expressed in the following format: access_key/YYYYMMDD/region/service/aws4_request.
For more information, see Task 2: Create a String to Sign for Signature Version 4 in the Amazon Web
Services General Reference.
Condition: Specify this parameter when you include authentication information in a query string
instead of in the HTTP authorization header.
Type: string
Required: Conditional
X-Amz-Date
The date that is used to create the signature. The format must be ISO 8601 basic format
(YYYYMMDD'T'HHMMSS'Z'). For example, the following date time is a valid X-Amz-Date value:
20120325T120000Z.
Condition: X-Amz-Date is optional for all requests; it can be used to override the date used for
signing requests. If the Date header is specified in the ISO 8601 basic format, X-Amz-Date is
not required. When X-Amz-Date is used, it always overrides the value of the Date header. For
more information, see Handling Dates in Signature Version 4 in the Amazon Web Services General
Reference.
Type: string
Required: Conditional
X-Amz-Security-Token
The temporary security token that was obtained through a call to AWS Security Token Service (AWS
STS). For a list of services that support temporary security credentials from AWS Security Token
Service, go to AWS Services That Work with IAM in the IAM User Guide.
Condition: If you're using temporary security credentials from the AWS Security Token Service, you
must include the security token.
Type: string
Required: Conditional
X-Amz-Signature
Specifies the hex-encoded signature that was calculated from the string to sign and the derived
signing key.
Condition: Specify this parameter when you include authentication information in a query string
instead of in the HTTP authorization header.
Type: string
Required: Conditional
X-Amz-SignedHeaders
Specifies all the HTTP headers that were included as part of the canonical request. For more
information about specifying signed headers, see Task 1: Create a Canonical Request For Signature
Version 4 in the Amazon Web Services General Reference.
Condition: Specify this parameter when you include authentication information in a query string
instead of in the HTTP authorization header.
Type: string
Required: Conditional
Common Errors
This section lists the errors common to the API actions of all AWS services. For errors specific to an API
action for this service, see the topic for that API action.
AccessDeniedException
The request processing has failed because of an unknown error, exception or failure.
The action or operation requested is invalid. Verify that the action is typed correctly.
The X.509 certificate or AWS access key ID provided does not exist in our records.
The AWS query string is malformed or does not adhere to AWS standards.
MissingAuthenticationToken
The request must contain either a valid (registered) AWS access key ID or X.509 certificate.
The request reached the service more than 15 minutes after the date stamp on the request or more
than 15 minutes after the request expiration date (such as for pre-signed URLs), or the date stamp
on the request is more than 15 minutes in the future.