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.
DeleteNamedQuery ( array $params = [] )
Deletes a named query.
GetNamedQuery ( array $params = [] )
Returns information about a single query.
GetQueryExecution ( array $params = [] )
Returns information about a single execution of a query.
GetQueryResults ( array $params = [] )
Returns the results of a single query execution specified by QueryExecutionId.
ListNamedQueries ( array $params = [] )
Provides a list of all available query IDs.
ListQueryExecutions ( array $params = [] )
Provides a list of all available query execution IDs.
StartQueryExecution ( array $params = [] )
Runs (executes) the SQL query statements contained in the Query string.
StopQueryExecution ( array $params = [] )
Stops a query execution.

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

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. Use ListNamedQueries to get the list of named query IDs. If information could not be retrieved for a submitted query ID, information about the query ID submitted is listed under UnprocessedNamedQueryId. Named queries are different from executed queries. Use BatchGetQueryExecution to get details about each unique query execution, and ListQueryExecutions to get a list of query execution IDs.

Parameter Syntax

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

Parameter Details

Members

NamedQueryIds

Type: Array of strings

An array of query IDs.

Result Syntax

[
    'NamedQueries' => [
        [
            'Database' => '<string>',
            'Description' => '<string>',
            'Name' => '<string>',
            'NamedQueryId' => '<string>',
            'QueryString' => '<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. To get a list of query execution IDs, use ListQueryExecutions. Query executions are different from named (saved) queries. Use BatchGetNamedQuery to get details about named queries.

Parameter Syntax

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

Parameter Details

Members

QueryExecutionIds

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>',
            ],
            'Statistics' => [
                'DataScannedInBytes' => <integer>,
                'EngineExecutionTimeInMillis' => <integer>,
            ],
            'Status' => [
                'CompletionDateTime' => <DateTime>,
                'State' => 'QUEUED|RUNNING|SUCCEEDED|FAILED|CANCELLED',
                'StateChangeReason' => '<string>',
                'SubmissionDateTime' => <DateTime>,
            ],
        ],
        // ...
    ],
    '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.

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
]);

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

Type: string

The database to which the query belongs.

Description

Type: string

A brief explanation of the query.

Name

Type: string

The plain language name for the query.

QueryString

Type: string

The text of the query itself. In other words, all query statements.

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.

DeleteNamedQuery

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

Deletes a named query.

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

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.

GetNamedQuery

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

Returns information about a single query.

Parameter Syntax

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

Parameter Details

Members

NamedQueryId

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>',
    ],
]

Result Details

Members

NamedQuery

Required: Yes
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. 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

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>',
        ],
        'Statistics' => [
            'DataScannedInBytes' => <integer>,
            'EngineExecutionTimeInMillis' => <integer>,
        ],
        'Status' => [
            'CompletionDateTime' => <DateTime>,
            'State' => 'QUEUED|RUNNING|SUCCEEDED|FAILED|CANCELLED',
            'StateChangeReason' => '<string>',
            'SubmissionDateTime' => <DateTime>,
        ],
    ],
]

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

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>',
                    ],
                    // ...
                ],
            ],
            // ...
        ],
    ],
]

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.

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 all available query IDs.

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>',
]);

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.

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 all available query execution IDs.

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>',
]);

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.

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.

StartQueryExecution

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

Runs (executes) the SQL query statements contained in the Query string.

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' => [ // REQUIRED
        'EncryptionConfiguration' => [
            'EncryptionOption' => 'SSE_S3|SSE_KMS|CSE_KMS', // REQUIRED
            'KmsKey' => '<string>',
        ],
        'OutputLocation' => '<string>', // REQUIRED
    ],
]);

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

Type: string

The SQL query statements to be executed.

ResultConfiguration

Required: Yes
Type: ResultConfiguration structure

Specifies information about where and how to save the results of the query execution.

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.

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

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.

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

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

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 Amazon S3 encryption option used.

Members

EncryptionOption

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.

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

Message

Type: string

NamedQuery

Description

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

Members

Database

Type: string

The database to which the query belongs.

Description

Type: string

A brief description of the query.

Name

Type: string

The plain-language name of the query.

NamedQueryId

Type: string

The unique identifier of the query.

QueryString

Type: string

The SQL query statements that comprise the 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

Required: Yes
Type: ResultConfiguration structure

The location in Amazon S3 where query results were stored and the encryption option, if any, used for query results.

Statistics

Type: QueryExecutionStatistics structure

The amount of data scanned during the query execution and the amount of time that it took to execute.

Status

Type: QueryExecutionStatus structure

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

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.

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. SUBMITTED indicates that the query is queued for execution. RUNNING indicates that the query is scanning data and returning results. SUCCEEDED indicates that the query completed without error. FAILED indicates that the query experienced an error and did not complete processing. CANCELLED indicates that 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.

ResultConfiguration

Description

The location in Amazon S3 where query results are stored and the encryption option, if any, used for query results.

Members

EncryptionConfiguration

Required: Yes
Type: EncryptionConfiguration structure

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

OutputLocation

Type: string

The location in S3 where query results are stored.

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 in a query execution result.

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.

TooManyRequestsException

Description

Indicates that the request was throttled.

Members

Message

Type: string

Reason

Type: string

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.

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

DeleteNamedQuery

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

ListNamedQueries

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members

Errors

ListQueryExecutions

Parameter Syntax

Parameter Details

Members

Result Syntax

Result Details

Members