Request Parameters
For information about the parameters that are common to all actions, see Common Parameters (p. 139).
The request accepts the following data in JSON format.
CatalogName (p. 27)
The name of the data catalog that contains the database to return.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 256.
Pattern: [\u0020-\uD7FF\uE000-\uFFFD\uD800\uDC00-\uDBFF\uDFFF\t]*
Required: Yes DatabaseName (p. 27)
The name of the database to return.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 128.
Required: Yes
Response Syntax
{
"Database": {
"Description": "string", "Name": "string",
If the action is successful, the service sends back an HTTP 200 response.
Errors
The following data is returned in JSON format by the service.
Database (p. 27)
The database returned.
Type: Database (p. 98) object
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates a platform issue, which may be due to a transient condition or outage.
HTTP Status Code: 500 InvalidRequestException
Indicates that something is wrong with the input to the request. For example, a required parameter may be missing or out of range.
HTTP Status Code: 400 MetadataException
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.
HTTP Status Code: 400
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
GetDataCatalog
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).
The request accepts the following data in JSON format.
Name (p. 29)
The name of the data catalog to return.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 256.
Pattern: [\u0020-\uD7FF\uE000-\uFFFD\uD800\uDC00-\uDBFF\uDFFF\t]*
Required: Yes
Response Syntax
{
"DataCatalog": {
"Description": "string", "Name": "string",
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
DataCatalog (p. 29)
The data catalog returned.
Type: DataCatalog (p. 99) object
Errors
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates a platform issue, which may be due to a transient condition or outage.
HTTP Status Code: 500 InvalidRequestException
Indicates that something is wrong with the input to the request. For example, a required parameter may be missing or out of range.
HTTP Status Code: 400
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3
GetNamedQuery
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 request accepts the following data in JSON format.
NamedQueryId (p. 31)
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.
The following data is returned in JSON format by the service.
NamedQuery (p. 31)
Information about the query.
Type: NamedQuery (p. 107) object
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
See Also
InternalServerException
Indicates a platform issue, which may be due to a transient condition or outage.
HTTP Status Code: 500 InvalidRequestException
Indicates that something is wrong with the input to the request. For example, a required parameter may be missing or out of range.
HTTP Status Code: 400
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3
GetPreparedStatement
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).
The request accepts the following data in JSON format.
StatementName (p. 33)
The name of the prepared statement to retrieve.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 256.
Pattern: [a-zA-Z_][a-zA-Z0-9_@:]{1,256}
Required: Yes WorkGroup (p. 33)
The workgroup to which the statement to be retrieved belongs.
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
The following data is returned in JSON format by the service.
PreparedStatement (p. 33)
The name of the prepared statement that was retrieved.
Type: PreparedStatement (p. 109) object
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates a platform issue, which may be due to a transient condition or outage.
HTTP Status Code: 500 InvalidRequestException
Indicates that something is wrong with the input to the request. For example, a required parameter may be missing or out of range.
HTTP Status Code: 400 ResourceNotFoundException
A resource, such as a workgroup, was not found.
HTTP Status Code: 400
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3
GetQueryExecution
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).
The request accepts the following data in JSON format.
QueryExecutionId (p. 35)
The unique ID of the query execution.
Type: String Required: Yes
Response Syntax
{ "QueryExecution": { "EngineVersion": {
"EffectiveEngineVersion": "string", "SelectedEngineVersion": "string"
},
"QueryExecutionId": "string", "ResultConfiguration": {
"ExpectedBucketOwner": "string", "OutputLocation": "string"
},
"StatementType": "string", "Statistics": {
"DataManifestLocation": "string", "DataScannedInBytes": number,
"EngineExecutionTimeInMillis": number, "QueryPlanningTimeInMillis": number,
Response Elements
"QueryQueueTimeInMillis": number, "ServiceProcessingTimeInMillis": number, "TotalExecutionTimeInMillis": number },
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
QueryExecution (p. 35)
Information about the query execution.
Type: QueryExecution (p. 112) object
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates a platform issue, which may be due to a transient condition or outage.
HTTP Status Code: 500 InvalidRequestException
Indicates that something is wrong with the input to the request. For example, a required parameter may be missing or out of range.
HTTP Status Code: 400
See Also
See Also
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3
GetQueryResults
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).
The request accepts the following data in JSON format.
MaxResults (p. 38)
The maximum number of results (rows) to return in this request.
Type: Integer
Valid Range: Minimum value of 1. Maximum value of 1000.
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.
Response Syntax
Required: Yes
Response Syntax
{ "NextToken": "string", "ResultSet": {
"UpdateCount": number }
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
NextToken (p. 39)
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
Length Constraints: Minimum length of 1. Maximum length of 1024.
ResultSet (p. 39)
The results of the query execution.
Type: ResultSet (p. 123) object UpdateCount (p. 39)
The number of rows inserted with a CREATE TABLE AS SELECT statement.
Errors
Type: Long
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates a platform issue, which may be due to a transient condition or outage.
HTTP Status Code: 500 InvalidRequestException
Indicates that something is wrong with the input to the request. For example, a required parameter may be missing or out of range.
HTTP Status Code: 400
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3
GetTableMetadata
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 request accepts the following data in JSON format.
CatalogName (p. 41)
The name of the data catalog that contains the database and table metadata to return.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 256.
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
Length Constraints: Minimum length of 1. Maximum length of 128.
Required: Yes TableName (p. 41)
The name of the table for which metadata is returned.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 128.
Required: Yes
Response Syntax
{
"TableMetadata": { "Columns": [
Response Elements "LastAccessTime": number, "Name": "string",
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
TableMetadata (p. 41)
An object that contains table metadata.
Type: TableMetadata (p. 126) object
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates a platform issue, which may be due to a transient condition or outage.
HTTP Status Code: 500 InvalidRequestException
Indicates that something is wrong with the input to the request. For example, a required parameter
See Also
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3
GetWorkGroup
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).
The request accepts the following data in JSON format.
WorkGroup (p. 44)
The name of the workgroup.
Type: String
"BytesScannedCutoffPerQuery": number, "EnforceWorkGroupConfiguration": boolean, "EngineVersion": {
"EffectiveEngineVersion": "string", "SelectedEngineVersion": "string"
},
"PublishCloudWatchMetricsEnabled": boolean, "RequesterPaysEnabled": boolean,
Response Elements
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
WorkGroup (p. 44)
Information about the workgroup.
Type: WorkGroup (p. 131) object
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates a platform issue, which may be due to a transient condition or outage.
HTTP Status Code: 500 InvalidRequestException
Indicates that something is wrong with the input to the request. For example, a required parameter may be missing or out of range.
HTTP Status Code: 400
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3
ListDatabases
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 request accepts the following data in JSON format.
CatalogName (p. 46)
The name of the data catalog that contains the databases to return.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 256.
Pattern: [\u0020-\uD7FF\uE000-\uFFFD\uD800\uDC00-\uDBFF\uDFFF\t]*
Required: Yes MaxResults (p. 46)
Specifies the maximum number of results to return.
Type: Integer
Valid Range: Minimum value of 1. Maximum value of 50.
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
Response Elements
"NextToken": "string"
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
DatabaseList (p. 46)
A list of databases from a data catalog.
Type: Array of Database (p. 98) objects 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
Length Constraints: Minimum length of 1. Maximum length of 1024.
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates a platform issue, which may be due to a transient condition or outage.
HTTP Status Code: 500 InvalidRequestException
Indicates that something is wrong with the input to the request. For example, a required parameter may be missing or out of range.
HTTP Status Code: 400 MetadataException
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.
HTTP Status Code: 400
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
See Also
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3
ListDataCatalogs
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).
The request accepts the following data in JSON format.
MaxResults (p. 49)
Specifies the maximum number of data catalogs to return.
Type: Integer
Valid Range: Minimum value of 2. Maximum value of 50.
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
Length Constraints: Minimum length of 1. Maximum length of 1024.
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.
Errors
The following data is returned in JSON format by the service.
DataCatalogsSummary (p. 49) A summary list of data catalogs.
Type: Array of DataCatalogSummary (p. 101) objects 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
Length Constraints: Minimum length of 1. Maximum length of 1024.
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates a platform issue, which may be due to a transient condition or outage.
HTTP Status Code: 500 InvalidRequestException
Indicates that something is wrong with the input to the request. For example, a required parameter may be missing or out of range.
HTTP Status Code: 400
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
ListEngineVersions
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).
The request accepts the following data in JSON format.
MaxResults (p. 51)
The maximum number of engine versions to return in this request.
Type: Integer
Valid Range: Minimum value of 1. Maximum value of 10.
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
Length Constraints: Minimum length of 1. Maximum length of 1024.
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.
Errors
The following data is returned in JSON format by the service.
EngineVersions (p. 51)
A list of engine versions that are available to choose from.
Type: Array of EngineVersion (p. 104) objects
Array Members: Minimum number of 0 items. Maximum number of 10 items.
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
Length Constraints: Minimum length of 1. Maximum length of 1024.
Errors
For information about the errors that are common to all actions, see Common Errors (p. 141).
InternalServerException
Indicates a platform issue, which may be due to a transient condition or outage.
HTTP Status Code: 500 InvalidRequestException
Indicates that something is wrong with the input to the request. For example, a required parameter may be missing or out of range.
HTTP Status Code: 400
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Go