AWS SDK for PHP 3.x

Service ID: athena

Version: 2017-05-18

This page describes the parameters and results for the operations of the Amazon Athena (2017-05-18), and shows how to use the Aws\Athena\AthenaClient object to call the described operations. This documentation is specific to the 2017-05-18 API version of the service.

Operation Summary

Each of the following operations can be created from a client using $client->getCommand('CommandName'), where "CommandName" is the name of one of the following operations. Note: a command is a value that encapsulates an operation and the parameters used to create an HTTP request.

You can also create and send a command immediately using the magic methods available on a client object: $client->commandName(/* parameters */). You can send the command asynchronously (returning a promise) by appending the word "Async" to the operation name: $client->commandNameAsync(/* parameters */).

BatchGetNamedQuery ( array $params = [] )
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.
BatchGetQueryExecution ( array $params = [] )
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.
CreateNamedQuery ( array $params = [] )
Creates a named query in the specified workgroup.
CreateWorkGroup ( array $params = [] )
Creates a workgroup with the specified name.
DeleteNamedQuery ( array $params = [] )
Deletes the named query if you have access to the workgroup in which the query was saved.
DeleteWorkGroup ( array $params = [] )
Deletes the workgroup with the specified name.
GetNamedQuery ( array $params = [] )
Returns information about a single query.
GetQueryExecution ( array $params = [] )
Returns information about a single execution of a query if you have access to the workgroup in which the query ran.
GetQueryResults ( array $params = [] )
Returns the results of a single query execution specified by QueryExecutionId if you have access to the workgroup in which the query ran.
GetWorkGroup ( array $params = [] )
Returns information about the workgroup with the specified name.
ListNamedQueries ( array $params = [] )
Provides a list of available query IDs only for queries saved in the specified workgroup.
ListQueryExecutions ( array $params = [] )
Provides a list of available query execution IDs for the queries in the specified workgroup.
ListTagsForResource ( array $params = [] )
Lists the tags associated with this workgroup.
ListWorkGroups ( array $params = [] )
Lists available workgroups for the account.
StartQueryExecution ( array $params = [] )
Runs the SQL query statements contained in the Query.
StopQueryExecution ( array $params = [] )
Stops a query execution.
TagResource ( array $params = [] )
Adds one or more tags to the resource, such as a workgroup.
UntagResource ( array $params = [] )
Removes one or more tags from the workgroup resource.
UpdateWorkGroup ( array $params = [] )
Updates the workgroup with the specified name.

Paginators

Paginators handle automatically iterating over paginated API results. Paginators are associated with specific API operations, and they accept the parameters that the corresponding API operation accepts. You can get a paginator from a client class using getPaginator($paginatorName, $operationParameters). This client supports the following paginators:

GetQueryResults
ListNamedQueries
ListQueryExecutions
ListWorkGroups

Operations

BatchGetNamedQuery

$result = $client->batchGetNamedQuery([/* ... */]);
$promise = $client->batchGetNamedQueryAsync([/* ... */]);

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 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. Named queries differ from executed queries. Use BatchGetQueryExecutionInput to get details about each unique query execution, and ListQueryExecutionsInput to get a list of query execution IDs.

Parameter Syntax

$result = $client->batchGetNamedQuery([
    'NamedQueryIds' => ['<string>', ...], // REQUIRED
]);

Parameter Details

Members

NamedQueryIds

Required: Yes
Type: Array of strings

An array of query IDs.

Result Syntax

[
    'NamedQueries' => [
        [
            'Database' => '<string>',
            'Description' => '<string>',
            'Name' => '<string>',
            'NamedQueryId' => '<string>',
            'QueryString' => '<string>',
            'WorkGroup' => '<string>',
        ],
        // ...
    ],
    'UnprocessedNamedQueryIds' => [
        [
            'ErrorCode' => '<string>',
            'ErrorMessage' => '<string>',
            'NamedQueryId' => '<string>',
        ],
        // ...
    ],
]

Result Details

Members

NamedQueries

Type: Array of NamedQuery structures

Information about the named query IDs submitted.

UnprocessedNamedQueryIds

Type: Array of UnprocessedNamedQueryId structures

Information about provided query IDs.

Errors

InternalServerException:
Indicates a platform issue, which may be due to a transient condition or outage.
InvalidRequestException:
Indicates that something is wrong with the input to the request. For example, a required parameter may be missing or out of range.

BatchGetQueryExecution

$result = $client->batchGetQueryExecution([/* ... */]);
$promise = $client->batchGetQueryExecutionAsync([/* ... */]);

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 ListQueryExecutionsInput$WorkGroup. Query executions differ from named (saved) queries. Use BatchGetNamedQueryInput to get details about named queries.

Parameter Syntax

$result = $client->batchGetQueryExecution([
    'QueryExecutionIds' => ['<string>', ...], // REQUIRED
]);

Parameter Details

Members

QueryExecutionIds

Required: Yes
Type: Array of strings

An array of query execution IDs.

Result Syntax

[
    'QueryExecutions' => [
        [
            'Query' => '<string>',
            'QueryExecutionContext' => [
                'Database' => '<string>',
            ],
            'QueryExecutionId' => '<string>',
            'ResultConfiguration' => [
                'EncryptionConfiguration' => [
                    'EncryptionOption' => 'SSE_S3|SSE_KMS|CSE_KMS',
                    'KmsKey' => '<string>',
                ],
                'OutputLocation' => '<string>',
            ],
            'StatementType' => 'DDL|DML|UTILITY',
            'Statistics' => [
                'DataScannedInBytes' => <integer>,
                'EngineExecutionTimeInMillis' => <integer>,
            ],
            'Status' => [
                'CompletionDateTime' => <DateTime>,
                'State' => 'QUEUED|RUNNING|SUCCEEDED|FAILED|CANCELLED',
                'StateChangeReason' => '<string>',
                'SubmissionDateTime' => <DateTime>,
            ],
            'WorkGroup' => '<string>',
        ],
        // ...
    ],
    'UnprocessedQueryExecutionIds' => [
        [
            'ErrorCode' => '<string>',
            'ErrorMessage' => '<string>',
            'QueryExecutionId' => '<string>',
        ],
        // ...
    ],
]

Result Details

Members

QueryExecutions

Type: Array of QueryExecution structures

Information about a query execution.

UnprocessedQueryExecutionIds

Type: Array of UnprocessedQueryExecutionId structures

Information about the query executions that failed to run.

Errors

InternalServerException:
Indicates a platform issue, which may be due to a transient condition or outage.
InvalidRequestException:
Indicates that something is wrong with the input to the request. For example, a required parameter may be missing or out of range.

CreateNamedQuery

$result = $client->createNamedQuery([/* ... */]);
$promise = $client->createNamedQueryAsync([/* ... */]);

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.

Parameter Syntax

$result = $client->createNamedQuery([
    'ClientRequestToken' => '<string>',
    'Database' => '<string>', // REQUIRED
    'Description' => '<string>',
    'Name' => '<string>', // REQUIRED
    'QueryString' => '<string>', // REQUIRED
    'WorkGroup' => '<string>',
]);

Parameter Details

Members

ClientRequestToken

Type: string

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.

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.

Database

Required: Yes
Type: string

The database to which the query belongs.

Description

Type: string

The query description.

Name

Required: Yes
Type: string

The query name.

QueryString

Required: Yes
Type: string

The contents of the query with all query statements.

WorkGroup

Type: string

The name of the workgroup in which the named query is being created.

Result Syntax

[
    'NamedQueryId' => '<string>',
]

Result Details

Members

NamedQueryId

Type: string

The unique ID of the query.

Errors

InternalServerException:
Indicates a platform issue, which may be due to a transient condition or outage.
InvalidRequestException:
Indicates that something is wrong with the input to the request. For example, a required parameter may be missing or out of range.

CreateWorkGroup

$result = $client->createWorkGroup([/* ... */]);
$promise = $client->createWorkGroupAsync([/* ... */]);

Creates a workgroup with the specified name.

Parameter Syntax

$result = $client->createWorkGroup([
    'Configuration' => [
        'BytesScannedCutoffPerQuery' => <integer>,
        'EnforceWorkGroupConfiguration' => true || false,
        'PublishCloudWatchMetricsEnabled' => true || false,
        'ResultConfiguration' => [
            'EncryptionConfiguration' => [
                'EncryptionOption' => 'SSE_S3|SSE_KMS|CSE_KMS', // REQUIRED
                'KmsKey' => '<string>',
            ],
            'OutputLocation' => '<string>',
        ],
    ],
    'Description' => '<string>',
    'Name' => '<string>', // REQUIRED
    'Tags' => [
        [
            'Key' => '<string>',
            'Value' => '<string>',
        ],
        // ...
    ],
]);

Parameter Details

Members

Configuration

Type: WorkGroupConfiguration structure

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.

Description

Type: string

The workgroup description.

Name

Required: Yes
Type: string

The workgroup name.

Tags

Type: Array of Tag structures

One or more tags, separated by commas, that you want to attach to the workgroup as you create it.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalServerException:
Indicates a platform issue, which may be due to a transient condition or outage.
InvalidRequestException:
Indicates that something is wrong with the input to the request. For example, a required parameter may be missing or out of range.

DeleteNamedQuery

$result = $client->deleteNamedQuery([/* ... */]);
$promise = $client->deleteNamedQueryAsync([/* ... */]);

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.

Parameter Syntax

$result = $client->deleteNamedQuery([
    'NamedQueryId' => '<string>', // REQUIRED
]);

Parameter Details

Members

NamedQueryId

Required: Yes
Type: string

The unique ID of the query to delete.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalServerException:
Indicates a platform issue, which may be due to a transient condition or outage.
InvalidRequestException:
Indicates that something is wrong with the input to the request. For example, a required parameter may be missing or out of range.

DeleteWorkGroup

$result = $client->deleteWorkGroup([/* ... */]);
$promise = $client->deleteWorkGroupAsync([/* ... */]);

Deletes the workgroup with the specified name. The primary workgroup cannot be deleted.

Parameter Syntax

$result = $client->deleteWorkGroup([
    'RecursiveDeleteOption' => true || false,
    'WorkGroup' => '<string>', // REQUIRED
]);

Parameter Details

Members

RecursiveDeleteOption

Type: boolean

The option to delete the workgroup and its contents even if the workgroup contains any named queries.

WorkGroup

Required: Yes
Type: string

The unique name of the workgroup to delete.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalServerException:
Indicates a platform issue, which may be due to a transient condition or outage.
InvalidRequestException:
Indicates that something is wrong with the input to the request. For example, a required parameter may be missing or out of range.

GetNamedQuery

$result = $client->getNamedQuery([/* ... */]);
$promise = $client->getNamedQueryAsync([/* ... */]);

Returns information about a single query. Requires that you have access to the workgroup in which the query was saved.

Parameter Syntax

$result = $client->getNamedQuery([
    'NamedQueryId' => '<string>', // REQUIRED
]);

Parameter Details

Members

NamedQueryId

Required: Yes
Type: string

The unique ID of the query. Use ListNamedQueries to get query IDs.

Result Syntax

[
    'NamedQuery' => [
        'Database' => '<string>',
        'Description' => '<string>',
        'Name' => '<string>',
        'NamedQueryId' => '<string>',
        'QueryString' => '<string>',
        'WorkGroup' => '<string>',
    ],
]

Result Details

Members

NamedQuery

Type: NamedQuery structure

Information about the query.

Errors

InternalServerException:
Indicates a platform issue, which may be due to a transient condition or outage.
InvalidRequestException:
Indicates that something is wrong with the input to the request. For example, a required parameter may be missing or out of range.

GetQueryExecution

$result = $client->getQueryExecution([/* ... */]);
$promise = $client->getQueryExecutionAsync([/* ... */]);

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.

Parameter Syntax

$result = $client->getQueryExecution([
    'QueryExecutionId' => '<string>', // REQUIRED
]);

Parameter Details

Members

QueryExecutionId

Required: Yes
Type: string

The unique ID of the query execution.

Result Syntax

[
    'QueryExecution' => [
        'Query' => '<string>',
        'QueryExecutionContext' => [
            'Database' => '<string>',
        ],
        'QueryExecutionId' => '<string>',
        'ResultConfiguration' => [
            'EncryptionConfiguration' => [
                'EncryptionOption' => 'SSE_S3|SSE_KMS|CSE_KMS',
                'KmsKey' => '<string>',
            ],
            'OutputLocation' => '<string>',
        ],
        'StatementType' => 'DDL|DML|UTILITY',
        'Statistics' => [
            'DataScannedInBytes' => <integer>,
            'EngineExecutionTimeInMillis' => <integer>,
        ],
        'Status' => [
            'CompletionDateTime' => <DateTime>,
            'State' => 'QUEUED|RUNNING|SUCCEEDED|FAILED|CANCELLED',
            'StateChangeReason' => '<string>',
            'SubmissionDateTime' => <DateTime>,
        ],
        'WorkGroup' => '<string>',
    ],
]

Result Details

Members

QueryExecution

Type: QueryExecution structure

Information about the query execution.

Errors

InternalServerException:
Indicates a platform issue, which may be due to a transient condition or outage.
InvalidRequestException:
Indicates that something is wrong with the input to the request. For example, a required parameter may be missing or out of range.

GetQueryResults

$result = $client->getQueryResults([/* ... */]);
$promise = $client->getQueryResultsAsync([/* ... */]);

Returns the results of a single query execution specified by QueryExecutionId if you have access to the workgroup in which the query ran. This request does not execute the query but returns results. Use StartQueryExecution to run a query.

Parameter Syntax

$result = $client->getQueryResults([
    'MaxResults' => <integer>,
    'NextToken' => '<string>',
    'QueryExecutionId' => '<string>', // REQUIRED
]);

Parameter Details

Members

MaxResults

Type: int

The maximum number of results (rows) to return in this request.

NextToken

Type: string

The token that specifies where to start pagination if a previous request was truncated.

QueryExecutionId

Required: Yes
Type: string

The unique ID of the query execution.

Result Syntax

[
    'NextToken' => '<string>',
    'ResultSet' => [
        'ResultSetMetadata' => [
            'ColumnInfo' => [
                [
                    'CaseSensitive' => true || false,
                    'CatalogName' => '<string>',
                    'Label' => '<string>',
                    'Name' => '<string>',
                    'Nullable' => 'NOT_NULL|NULLABLE|UNKNOWN',
                    'Precision' => <integer>,
                    'Scale' => <integer>,
                    'SchemaName' => '<string>',
                    'TableName' => '<string>',
                    'Type' => '<string>',
                ],
                // ...
            ],
        ],
        'Rows' => [
            [
                'Data' => [
                    [
                        'VarCharValue' => '<string>',
                    ],
                    // ...
                ],
            ],
            // ...
        ],
    ],
    'UpdateCount' => <integer>,
]

Result Details

Members

NextToken

Type: string

A token to be used by the next request if this request is truncated.

ResultSet

Type: ResultSet structure

The results of the query execution.

UpdateCount

Type: long (int|float)

The number of rows inserted with a CREATE TABLE AS SELECT statement.

Errors

InternalServerException:
Indicates a platform issue, which may be due to a transient condition or outage.
InvalidRequestException:
Indicates that something is wrong with the input to the request. For example, a required parameter may be missing or out of range.

GetWorkGroup

$result = $client->getWorkGroup([/* ... */]);
$promise = $client->getWorkGroupAsync([/* ... */]);

Returns information about the workgroup with the specified name.

Parameter Syntax

$result = $client->getWorkGroup([
    'WorkGroup' => '<string>', // REQUIRED
]);

Parameter Details

Members

WorkGroup

Required: Yes
Type: string

The name of the workgroup.

Result Syntax

[
    'WorkGroup' => [
        'Configuration' => [
            'BytesScannedCutoffPerQuery' => <integer>,
            'EnforceWorkGroupConfiguration' => true || false,
            'PublishCloudWatchMetricsEnabled' => true || false,
            'ResultConfiguration' => [
                'EncryptionConfiguration' => [
                    'EncryptionOption' => 'SSE_S3|SSE_KMS|CSE_KMS',
                    'KmsKey' => '<string>',
                ],
                'OutputLocation' => '<string>',
            ],
        ],
        'CreationTime' => <DateTime>,
        'Description' => '<string>',
        'Name' => '<string>',
        'State' => 'ENABLED|DISABLED',
    ],
]

Result Details

Members

WorkGroup

Type: WorkGroup structure

Information about the workgroup.

Errors

InternalServerException:
Indicates a platform issue, which may be due to a transient condition or outage.
InvalidRequestException:
Indicates that something is wrong with the input to the request. For example, a required parameter may be missing or out of range.

ListNamedQueries

$result = $client->listNamedQueries([/* ... */]);
$promise = $client->listNamedQueriesAsync([/* ... */]);

Provides a list of available query IDs only for queries saved 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.

Parameter Syntax

$result = $client->listNamedQueries([
    'MaxResults' => <integer>,
    'NextToken' => '<string>',
    'WorkGroup' => '<string>',
]);

Parameter Details

Members

MaxResults

Type: int

The maximum number of queries to return in this request.

NextToken

Type: string

The token that specifies where to start pagination if a previous request was truncated.

WorkGroup

Type: string

The name of the workgroup from which the named queries are being returned.

Result Syntax

[
    'NamedQueryIds' => ['<string>', ...],
    'NextToken' => '<string>',
]

Result Details

Members

NamedQueryIds

Type: Array of strings

The list of unique query IDs.

NextToken

Type: string

A token to be used by the next request if this request is truncated.

Errors

InternalServerException:
Indicates a platform issue, which may be due to a transient condition or outage.
InvalidRequestException:
Indicates that something is wrong with the input to the request. For example, a required parameter may be missing or out of range.

ListQueryExecutions

$result = $client->listQueryExecutions([/* ... */]);
$promise = $client->listQueryExecutionsAsync([/* ... */]);

Provides a list of available query execution IDs for the queries in the specified 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.

Parameter Syntax

$result = $client->listQueryExecutions([
    'MaxResults' => <integer>,
    'NextToken' => '<string>',
    'WorkGroup' => '<string>',
]);

Parameter Details

Members

MaxResults

Type: int

The maximum number of query executions to return in this request.

NextToken

Type: string

The token that specifies where to start pagination if a previous request was truncated.

WorkGroup

Type: string

The name of the workgroup from which queries are being returned.

Result Syntax

[
    'NextToken' => '<string>',
    'QueryExecutionIds' => ['<string>', ...],
]

Result Details

Members

NextToken

Type: string

A token to be used by the next request if this request is truncated.

QueryExecutionIds

Type: Array of strings

The unique IDs of each query execution as an array of strings.

Errors

InternalServerException:
Indicates a platform issue, which may be due to a transient condition or outage.
InvalidRequestException:
Indicates that something is wrong with the input to the request. For example, a required parameter may be missing or out of range.

ListTagsForResource

$result = $client->listTagsForResource([/* ... */]);
$promise = $client->listTagsForResourceAsync([/* ... */]);

Lists the tags associated with this workgroup.

Parameter Syntax

$result = $client->listTagsForResource([
    'MaxResults' => <integer>,
    'NextToken' => '<string>',
    'ResourceARN' => '<string>', // REQUIRED
]);

Parameter Details

Members

MaxResults

Type: int

The maximum number of results to be returned per request that lists the tags for the workgroup resource.

NextToken

Type: string

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 workgroup resource with the specified ARN.

ResourceARN

Required: Yes
Type: string

Lists the tags for the workgroup resource with the specified ARN.

Result Syntax

[
    'NextToken' => '<string>',
    'Tags' => [
        [
            'Key' => '<string>',
            'Value' => '<string>',
        ],
        // ...
    ],
]

Result Details

Members

NextToken

Type: string

A token to be used by the next request if this request is truncated.

Tags

Type: Array of Tag structures

The list of tags associated with this workgroup.

Errors

InternalServerException:
Indicates a platform issue, which may be due to a transient condition or outage.
InvalidRequestException:
Indicates that something is wrong with the input to the request. For example, a required parameter may be missing or out of range.
ResourceNotFoundException:
A resource, such as a workgroup, was not found.

ListWorkGroups

$result = $client->listWorkGroups([/* ... */]);
$promise = $client->listWorkGroupsAsync([/* ... */]);

Lists available workgroups for the account.

Parameter Syntax

$result = $client->listWorkGroups([
    'MaxResults' => <integer>,
    'NextToken' => '<string>',
]);

Parameter Details

Members

MaxResults

Type: int

The maximum number of workgroups to return in this request.

NextToken

Type: string

A token to be used by the next request if this request is truncated.

Result Syntax

[
    'NextToken' => '<string>',
    'WorkGroups' => [
        [
            'CreationTime' => <DateTime>,
            'Description' => '<string>',
            'Name' => '<string>',
            'State' => 'ENABLED|DISABLED',
        ],
        // ...
    ],
]

Result Details

Members

NextToken

Type: string

A token to be used by the next request if this request is truncated.

WorkGroups

Type: Array of WorkGroupSummary structures

The list of workgroups, including their names, descriptions, creation times, and states.

Errors

InternalServerException:
Indicates a platform issue, which may be due to a transient condition or outage.
InvalidRequestException:
Indicates that something is wrong with the input to the request. For example, a required parameter may be missing or out of range.

StartQueryExecution

$result = $client->startQueryExecution([/* ... */]);
$promise = $client->startQueryExecutionAsync([/* ... */]);

Runs the SQL query statements contained in the Query. 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.

Parameter Syntax

$result = $client->startQueryExecution([
    'ClientRequestToken' => '<string>',
    'QueryExecutionContext' => [
        'Database' => '<string>',
    ],
    'QueryString' => '<string>', // REQUIRED
    'ResultConfiguration' => [
        'EncryptionConfiguration' => [
            'EncryptionOption' => 'SSE_S3|SSE_KMS|CSE_KMS', // REQUIRED
            'KmsKey' => '<string>',
        ],
        'OutputLocation' => '<string>',
    ],
    'WorkGroup' => '<string>',
]);

Parameter Details

Members

ClientRequestToken

Type: string

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.

QueryExecutionContext

Type: QueryExecutionContext structure

The database within which the query executes.

QueryString

Required: Yes
Type: string

The SQL query statements to be executed.

ResultConfiguration

Type: ResultConfiguration structure

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.

WorkGroup

Type: string

The name of the workgroup in which the query is being started.

Result Syntax

[
    'QueryExecutionId' => '<string>',
]

Result Details

Members

QueryExecutionId

Type: string

The unique ID of the query that ran as a result of this request.

Errors

InternalServerException:
Indicates a platform issue, which may be due to a transient condition or outage.
InvalidRequestException:
Indicates that something is wrong with the input to the request. For example, a required parameter may be missing or out of range.
TooManyRequestsException:
Indicates that the request was throttled.

StopQueryExecution

$result = $client->stopQueryExecution([/* ... */]);
$promise = $client->stopQueryExecutionAsync([/* ... */]);

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.

Parameter Syntax

$result = $client->stopQueryExecution([
    'QueryExecutionId' => '<string>', // REQUIRED
]);

Parameter Details

Members

QueryExecutionId

Required: Yes
Type: string

The unique ID of the query execution to stop.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalServerException:
Indicates a platform issue, which may be due to a transient condition or outage.
InvalidRequestException:
Indicates that something is wrong with the input to the request. For example, a required parameter may be missing or out of range.

TagResource

$result = $client->tagResource([/* ... */]);
$promise = $client->tagResourceAsync([/* ... */]);

Adds one or more tags to the resource, such as a workgroup. A tag is a label that you assign to an AWS Athena resource (a workgroup). Each tag consists of a key and an optional value, both of which you define. Tags enable you to categorize resources (workgroups) in Athena, for example, by purpose, owner, or environment. Use a consistent set of tag keys to make it easier to search and filter workgroups in your account. For best practices, see AWS Tagging Strategies. The key length is from 1 (minimum) to 128 (maximum) Unicode characters in UTF-8. The tag value length is from 0 (minimum) to 256 (maximum) Unicode characters in UTF-8. You 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, separate them by commas.

Parameter Syntax

$result = $client->tagResource([
    'ResourceARN' => '<string>', // REQUIRED
    'Tags' => [ // REQUIRED
        [
            'Key' => '<string>',
            'Value' => '<string>',
        ],
        // ...
    ],
]);

Parameter Details

Members

ResourceARN

Required: Yes
Type: string

Requests that one or more tags are added to the resource (such as a workgroup) for the specified ARN.

Tags

Required: Yes
Type: Array of Tag structures

One or more tags, separated by commas, to be added to the resource, such as a workgroup.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalServerException:
Indicates a platform issue, which may be due to a transient condition or outage.
InvalidRequestException:
Indicates that something is wrong with the input to the request. For example, a required parameter may be missing or out of range.
ResourceNotFoundException:
A resource, such as a workgroup, was not found.

UntagResource

$result = $client->untagResource([/* ... */]);
$promise = $client->untagResourceAsync([/* ... */]);

Removes one or more tags from the workgroup resource. Takes as an input a list of TagKey Strings separated by commas, and removes their tags at the same time.

Parameter Syntax

$result = $client->untagResource([
    'ResourceARN' => '<string>', // REQUIRED
    'TagKeys' => ['<string>', ...], // REQUIRED
]);

Parameter Details

Members

ResourceARN

Required: Yes
Type: string

Removes one or more tags from the workgroup resource for the specified ARN.

TagKeys

Required: Yes
Type: Array of strings

Removes the tags associated with one or more tag keys from the workgroup resource.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalServerException:
Indicates a platform issue, which may be due to a transient condition or outage.
InvalidRequestException:
Indicates that something is wrong with the input to the request. For example, a required parameter may be missing or out of range.
ResourceNotFoundException:
A resource, such as a workgroup, was not found.

UpdateWorkGroup

$result = $client->updateWorkGroup([/* ... */]);
$promise = $client->updateWorkGroupAsync([/* ... */]);

Updates the workgroup with the specified name. The workgroup's name cannot be changed.

Parameter Syntax

$result = $client->updateWorkGroup([
    'ConfigurationUpdates' => [
        'BytesScannedCutoffPerQuery' => <integer>,
        'EnforceWorkGroupConfiguration' => true || false,
        'PublishCloudWatchMetricsEnabled' => true || false,
        'RemoveBytesScannedCutoffPerQuery' => true || false,
        'ResultConfigurationUpdates' => [
            'EncryptionConfiguration' => [
                'EncryptionOption' => 'SSE_S3|SSE_KMS|CSE_KMS', // REQUIRED
                'KmsKey' => '<string>',
            ],
            'OutputLocation' => '<string>',
            'RemoveEncryptionConfiguration' => true || false,
            'RemoveOutputLocation' => true || false,
        ],
    ],
    'Description' => '<string>',
    'State' => 'ENABLED|DISABLED',
    'WorkGroup' => '<string>', // REQUIRED
]);

Parameter Details

Members

ConfigurationUpdates

Type: WorkGroupConfigurationUpdates structure

The workgroup configuration that will be updated for the given workgroup.

Description

Type: string

The workgroup description.

State

Type: string

The workgroup state that will be updated for the given workgroup.

WorkGroup

Required: Yes
Type: string

The specified workgroup that will be updated.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

InternalServerException:
Indicates a platform issue, which may be due to a transient condition or outage.
InvalidRequestException:
Indicates that something is wrong with the input to the request. For example, a required parameter may be missing or out of range.

Shapes

ColumnInfo

Description

Information about the columns in a query execution result.

Members

CaseSensitive

Type: boolean

Indicates whether values in the column are case-sensitive.

CatalogName

Type: string

The catalog to which the query results belong.

Label

Type: string

A column label.

Name

Required: Yes
Type: string

The name of the column.

Nullable

Type: string

Indicates the column's nullable status.

Precision

Type: int

For DECIMAL data types, specifies the total number of digits, up to 38. For performance reasons, we recommend up to 18 digits.

Scale

Type: int

For DECIMAL data types, specifies the total number of digits in the fractional part of the value. Defaults to 0.

SchemaName

Type: string

The schema name (database name) to which the query results belong.

TableName

Type: string

The table name for the query results.

Type

Required: Yes
Type: string

The data type of the column.

Datum

Description

A piece of data (a field in the table).

Members

VarCharValue

Type: string

The value of the datum.

EncryptionConfiguration

Description

If query results are encrypted in Amazon S3, indicates the encryption option used (for example, SSE-KMS or CSE-KMS) and key information.

Members

EncryptionOption

Required: Yes
Type: string

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.

KmsKey

Type: string

For SSE-KMS and CSE-KMS, this is the KMS key ARN or ID.

InternalServerException

Description

Indicates a platform issue, which may be due to a transient condition or outage.

Members

Message

Type: string

InvalidRequestException

Description

Indicates that something is wrong with the input to the request. For example, a required parameter may be missing or out of range.

Members

AthenaErrorCode

Type: string

The error code returned when the query execution failed to process, or when the processing request for the named query failed.

Message

Type: string

NamedQuery

Description

A query, where QueryString is the list of SQL query statements that comprise the query.

Members

Database

Required: Yes
Type: string

The database to which the query belongs.

Description

Type: string

The query description.

Name

Required: Yes
Type: string

The query name.

NamedQueryId

Type: string

The unique identifier of the query.

QueryString

Required: Yes
Type: string

The SQL query statements that comprise the query.

WorkGroup

Type: string

The name of the workgroup that contains the named query.

QueryExecution

Description

Information about a single instance of a query execution.

Members

Query

Type: string

The SQL query statements which the query execution ran.

QueryExecutionContext

Type: QueryExecutionContext structure

The database in which the query execution occurred.

QueryExecutionId

Type: string

The unique identifier for each query execution.

ResultConfiguration

Type: ResultConfiguration structure

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.

StatementType

Type: string

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>.

Statistics

Type: QueryExecutionStatistics structure

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.

Status

Type: QueryExecutionStatus structure

The completion date, current state, submission time, and state change reason (if applicable) for the query execution.

WorkGroup

Type: string

The name of the workgroup in which the query ran.

QueryExecutionContext

Description

The database in which the query execution occurs.

Members

Database

Type: string

The name of the database.

QueryExecutionStatistics

Description

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.

Members

DataScannedInBytes

Type: long (int|float)

The number of bytes in the data that was queried.

EngineExecutionTimeInMillis

Type: long (int|float)

The number of milliseconds that the query took to execute.

QueryExecutionStatus

Description

The completion date, current state, submission time, and state change reason (if applicable) for the query execution.

Members

CompletionDateTime

Type: timestamp (string|DateTime or anything parsable by strtotime)

The date and time that the query completed.

State

Type: string

The state of query execution. QUEUED state is listed but is not used by Athena and is reserved for future use. RUNNING indicates that the query has been submitted to the service, and Athena will execute the query as soon as resources are available. 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.

StateChangeReason

Type: string

Further detail about the status of the query.

SubmissionDateTime

Type: timestamp (string|DateTime or anything parsable by strtotime)

The date and time that the query was submitted.

ResourceNotFoundException

Description

A resource, such as a workgroup, was not found.

Members

Message

Type: string

ResourceName

Type: string

ResultConfiguration

Description

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 location for the query results and the encryption configuration that are specified for the workgroup.

Members

EncryptionConfiguration

Type: EncryptionConfiguration structure

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 and Workgroup Settings Override Client-Side Settings.

OutputLocation

Type: string

The location in Amazon S3 where your query results are stored, such as s3://path/to/query/bucket/. For more information, see Queries and Query Result Files. 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.

ResultConfigurationUpdates

Description

The information about the updates in the query results, such as output location and encryption configuration for the query results.

Members

EncryptionConfiguration

Type: EncryptionConfiguration structure

The encryption configuration for the query results.

OutputLocation

Type: string

RemoveEncryptionConfiguration

Type: boolean

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.

RemoveOutputLocation

Type: boolean

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.

ResultSet

Description

The metadata and rows that comprise a query result set. The metadata describes the column structure and data types.

Members

ResultSetMetadata

Type: ResultSetMetadata structure

The metadata that describes the column structure and data types of a table of query results.

Rows

Type: Array of Row structures

The rows in the table.

ResultSetMetadata

Description

The metadata that describes the column structure and data types of a table of query results.

Members

ColumnInfo

Type: Array of ColumnInfo structures

Information about the columns returned in a query result metadata.

Row

Description

The rows that comprise a query result table.

Members

Data

Type: Array of Datum structures

The data that populates a row in a query result table.

Tag

Description

A tag that you can add to a resource. A tag is a label that you assign to an AWS Athena resource (a workgroup). Each tag consists of a key and an optional value, both of which you define. Tags enable you to categorize workgroups in Athena, for example, by purpose, owner, or environment. Use a consistent set of tag keys to make it easier to search and filter workgroups in your account. The maximum tag key length is 128 Unicode characters in UTF-8. The maximum tag value length is 256 Unicode characters in UTF-8. You 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.

Members

Key

Type: string

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.

Value

Type: string

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.

TooManyRequestsException

Description

Indicates that the request was throttled.

Members

Message

Type: string

Reason

Type: string

The reason for the query throttling, for example, when it exceeds the concurrent query limit.

UnprocessedNamedQueryId

Description

Information about a named query ID that could not be processed.

Members

ErrorCode

Type: string

The error code returned when the processing request for the named query failed, if applicable.

ErrorMessage

Type: string

The error message returned when the processing request for the named query failed, if applicable.

NamedQueryId

Type: string

The unique identifier of the named query.

UnprocessedQueryExecutionId

Description

Describes a query execution that failed to process.

Members

ErrorCode

Type: string

The error code returned when the query execution failed to process, if applicable.

ErrorMessage

Type: string

The error message returned when the query execution failed to process, if applicable.

QueryExecutionId

Type: string

The unique identifier of the query execution.

WorkGroup

Description

A workgroup, which contains a name, description, creation time, state, and other configuration, listed under WorkGroup$Configuration. 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.

Members

Configuration

Type: WorkGroupConfiguration structure

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 limit for the amount of data scanned per query, if it is specified. The workgroup settings override is specified in EnforceWorkGroupConfiguration (true/false) in the WorkGroupConfiguration. See WorkGroupConfiguration$EnforceWorkGroupConfiguration.

CreationTime

Type: timestamp (string|DateTime or anything parsable by strtotime)

The date and time the workgroup was created.

Description

Type: string

The workgroup description.

Name

Required: Yes
Type: string

The workgroup name.

State

Type: string

The state of the workgroup: ENABLED or DISABLED.

WorkGroupConfiguration

Description

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 limit for the amount of data scanned per query, if it is specified. The workgroup settings override is specified in EnforceWorkGroupConfiguration (true/false) in the WorkGroupConfiguration. See WorkGroupConfiguration$EnforceWorkGroupConfiguration.

Members

BytesScannedCutoffPerQuery

Type: long (int|float)

The upper data usage limit (cutoff) for the amount of bytes a single query in a workgroup is allowed to scan.

EnforceWorkGroupConfiguration

Type: boolean

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.

PublishCloudWatchMetricsEnabled

Type: boolean

Indicates that the Amazon CloudWatch metrics are enabled for the workgroup.

ResultConfiguration

Type: ResultConfiguration structure

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.

WorkGroupConfigurationUpdates

Description

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.

Members

BytesScannedCutoffPerQuery

Type: long (int|float)

The upper limit (cutoff) for the amount of bytes a single query in a workgroup is allowed to scan.

EnforceWorkGroupConfiguration

Type: boolean

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.

PublishCloudWatchMetricsEnabled

Type: boolean

Indicates whether this workgroup enables publishing metrics to Amazon CloudWatch.

RemoveBytesScannedCutoffPerQuery

Type: boolean

Indicates that the data usage control limit per query is removed. WorkGroupConfiguration$BytesScannedCutoffPerQuery

ResultConfigurationUpdates

Type: ResultConfigurationUpdates structure

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.

WorkGroupSummary

Description

The summary information for the workgroup, which includes its name, state, description, and the date and time it was created.

Members

CreationTime

Type: timestamp (string|DateTime or anything parsable by strtotime)

The workgroup creation date and time.

Description

Type: string

The workgroup description.

Name

Type: string

The name of the workgroup.

State

Type: string

The state of the workgroup.

Namespaces

Classes

Interfaces

Traits

Exceptions

Functions

Amazon Athena 2017-05-18

Operation Summary

Paginators

Operations

BatchGetNamedQuery

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors

BatchGetQueryExecution

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors

CreateNamedQuery

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors

CreateWorkGroup

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Errors

DeleteNamedQuery

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Errors

DeleteWorkGroup

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Errors

GetNamedQuery

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors

GetQueryExecution

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors

GetQueryResults

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors

GetWorkGroup