2022/11/30 - Amazon Athena - 23 new 3 updated api methods
Changes This release includes support for using Apache Spark in Amazon Athena.
Gets the full details of a previously created session, including the session status and configuration.
See also: AWS API Documentation
Request Syntax
client.get_session(
SessionId='string'
)
string
[REQUIRED]
The session ID.
dict
Response Syntax
{
'SessionId': 'string',
'Description': 'string',
'WorkGroup': 'string',
'EngineVersion': 'string',
'EngineConfiguration': {
'CoordinatorDpuSize': 123,
'MaxConcurrentDpus': 123,
'DefaultExecutorDpuSize': 123,
'AdditionalConfigs': {
'string': 'string'
}
},
'NotebookVersion': 'string',
'SessionConfiguration': {
'ExecutionRole': 'string',
'WorkingDirectory': 'string',
'IdleTimeoutSeconds': 123,
'EncryptionConfiguration': {
'EncryptionOption': 'SSE_S3'|'SSE_KMS'|'CSE_KMS',
'KmsKey': 'string'
}
},
'Status': {
'StartDateTime': datetime(2015, 1, 1),
'LastModifiedDateTime': datetime(2015, 1, 1),
'EndDateTime': datetime(2015, 1, 1),
'IdleSinceDateTime': datetime(2015, 1, 1),
'State': 'CREATING'|'CREATED'|'IDLE'|'BUSY'|'TERMINATING'|'TERMINATED'|'DEGRADED'|'FAILED',
'StateChangeReason': 'string'
},
'Statistics': {
'DpuExecutionInMillis': 123
}
}
Response Structure
(dict) --
SessionId (string) --
The session ID.
Description (string) --
The session description.
WorkGroup (string) --
The workgroup to which the session belongs.
EngineVersion (string) --
The engine version used by the session (for example, PySpark engine version 3 ). You can get a list of engine versions by calling ListEngineVersions .
EngineConfiguration (dict) --
Contains engine configuration information like DPU usage.
CoordinatorDpuSize (integer) --
The number of DPUs to use for the coordinator. A coordinator is a special executor that orchestrates processing work and manages other executors in a notebook session.
MaxConcurrentDpus (integer) --
The maximum number of DPUs that can run concurrently.
DefaultExecutorDpuSize (integer) --
The default number of DPUs to use for executors. An executor is the smallest unit of compute that a notebook session can request from Athena.
AdditionalConfigs (dict) --
Contains additional notebook engine MAP<string, string> parameter mappings in the form of key-value pairs. To specify an Amazon S3 URI that the Jupyter server will download and serve, specify a value for the StartSessionRequest$NotebookVersion field, and then add a key named NotebookFileURI to AdditionalConfigs that has value of the Amazon S3 URI.
(string) --
(string) --
NotebookVersion (string) --
The notebook version.
SessionConfiguration (dict) --
Contains the workgroup configuration information used by the session.
ExecutionRole (string) --
The ARN of the execution role used for the session.
WorkingDirectory (string) --
The Amazon S3 location that stores information for the notebook.
IdleTimeoutSeconds (integer) --
The idle timeout in seconds for the session.
EncryptionConfiguration (dict) --
If query results are encrypted in Amazon S3, indicates the encryption option used (for example, SSE_KMS or CSE_KMS ) and key information.
EncryptionOption (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 (string) --
For SSE_KMS and CSE_KMS , this is the KMS key ARN or ID.
Status (dict) --
Contains information about the status of the session.
StartDateTime (datetime) --
The date and time that the session started.
LastModifiedDateTime (datetime) --
The most recent date and time that the session was modified.
EndDateTime (datetime) --
The date and time that the session ended.
IdleSinceDateTime (datetime) --
The date and time starting at which the session became idle. Can be empty if the session is not currently idle.
State (string) --
The state of the session. A description of each state follows.
CREATING - The session is being started, including acquiring resources.
CREATED - The session has been started.
IDLE - The session is able to accept a calculation.
BUSY - The session is processing another task and is unable to accept a calculation.
TERMINATING - The session is in the process of shutting down.
TERMINATED - The session and its resources are no longer running.
DEGRADED - The session has no healthy coordinators.
FAILED - Due to a failure, the session and its resources are no longer running.
StateChangeReason (string) --
The reason for the session state change (for example, canceled because the session was terminated).
Statistics (dict) --
Contains the DPU execution time.
DpuExecutionInMillis (integer) --
The data processing unit execution time for a session in milliseconds.
Requests the cancellation of a calculation. A StopCalculationExecution call on a calculation that is already in a terminal state (for example, STOPPED , FAILED , or COMPLETED ) succeeds but has no effect.
Note
Cancelling a calculation is done on a best effort basis. If a calculation cannot be cancelled, you can be charged for its completion. If you are concerned about being charged for a calculation that cannot be cancelled, consider terminating the session in which the calculation is running.
See also: AWS API Documentation
Request Syntax
client.stop_calculation_execution(
CalculationExecutionId='string'
)
string
[REQUIRED]
The calculation execution UUID.
dict
Response Syntax
{
'State': 'CREATING'|'CREATED'|'QUEUED'|'RUNNING'|'CANCELING'|'CANCELED'|'COMPLETED'|'FAILED'
}
Response Structure
(dict) --
State (string) --
CREATING - The calculation is in the process of being created.
CREATED - The calculation has been created and is ready to run.
QUEUED - The calculation has been queued for processing.
RUNNING - The calculation is running.
CANCELING - A request to cancel the calculation has been received and the system is working to stop it.
CANCELED - The calculation is no longer running as the result of a cancel request.
COMPLETED - The calculation has completed without error.
FAILED - The calculation failed and is no longer running.
Updates the metadata for a notebook.
See also: AWS API Documentation
Request Syntax
client.update_notebook_metadata(
NotebookId='string',
ClientRequestToken='string',
Name='string'
)
string
[REQUIRED]
The ID of the notebook to update the metadata for.
string
A unique case-sensitive string used to ensure the request to create the notebook is idempotent (executes only once).
Warning
This token is listed as not required because Amazon Web Services SDKs (for example the Amazon Web Services SDK for Java) auto-generate the token for you. If you are not using the Amazon Web Services SDK or the Amazon Web Services CLI, you must provide this token or the action will fail.
string
[REQUIRED]
The name to update the notebook to.
dict
Response Syntax
{}
Response Structure
(dict) --
Creates an empty ipynb file in the specified Apache Spark enabled workgroup. Throws an error if a file in the workgroup with the same name already exists.
See also: AWS API Documentation
Request Syntax
client.create_notebook(
WorkGroup='string',
Name='string',
ClientRequestToken='string'
)
string
[REQUIRED]
The name of the Spark enabled workgroup in which the notebook will be created.
string
[REQUIRED]
The name of the ipynb file to be created in the Spark workgroup, without the .ipynb extension.
string
A unique case-sensitive string used to ensure the request to create the notebook is idempotent (executes only once).
Warning
This token is listed as not required because Amazon Web Services SDKs (for example the Amazon Web Services SDK for Java) auto-generate the token for you. If you are not using the Amazon Web Services SDK or the Amazon Web Services CLI, you must provide this token or the action will fail.
dict
Response Syntax
{
'NotebookId': 'string'
}
Response Structure
(dict) --
NotebookId (string) --
A unique identifier for the notebook.
Gets the status of a current calculation.
See also: AWS API Documentation
Request Syntax
client.get_calculation_execution_status(
CalculationExecutionId='string'
)
string
[REQUIRED]
The calculation execution UUID.
dict
Response Syntax
{
'Status': {
'SubmissionDateTime': datetime(2015, 1, 1),
'CompletionDateTime': datetime(2015, 1, 1),
'State': 'CREATING'|'CREATED'|'QUEUED'|'RUNNING'|'CANCELING'|'CANCELED'|'COMPLETED'|'FAILED',
'StateChangeReason': 'string'
},
'Statistics': {
'DpuExecutionInMillis': 123,
'Progress': 'string'
}
}
Response Structure
(dict) --
Status (dict) --
Contains information about the calculation execution status.
SubmissionDateTime (datetime) --
The date and time the calculation was submitted for processing.
CompletionDateTime (datetime) --
The date and time the calculation completed processing.
State (string) --
The state of the calculation execution. A description of each state follows.
CREATING - The calculation is in the process of being created.
CREATED - The calculation has been created and is ready to run.
QUEUED - The calculation has been queued for processing.
RUNNING - The calculation is running.
CANCELING - A request to cancel the calculation has been received and the system is working to stop it.
CANCELED - The calculation is no longer running as the result of a cancel request.
COMPLETED - The calculation has completed without error.
FAILED - The calculation failed and is no longer running.
StateChangeReason (string) --
The reason for the calculation state change (for example, the calculation was canceled because the session was terminated).
Statistics (dict) --
Contains information about the DPU execution time and progress.
DpuExecutionInMillis (integer) --
The data processing unit execution time in milliseconds for the calculation.
Progress (string) --
The progress of the calculation.
Exports the specified notebook and its metadata.
See also: AWS API Documentation
Request Syntax
client.export_notebook(
NotebookId='string'
)
string
[REQUIRED]
The ID of the notebook to export.
dict
Response Syntax
{
'NotebookMetadata': {
'NotebookId': 'string',
'Name': 'string',
'WorkGroup': 'string',
'CreationTime': datetime(2015, 1, 1),
'Type': 'IPYNB',
'LastModifiedTime': datetime(2015, 1, 1)
},
'Payload': 'string'
}
Response Structure
(dict) --
NotebookMetadata (dict) --
The notebook metadata, including notebook ID, notebook name, and workgroup name.
NotebookId (string) --
The notebook ID.
Name (string) --
The name of the notebook.
WorkGroup (string) --
The name of the Spark enabled workgroup to which the notebook belongs.
CreationTime (datetime) --
The time when the notebook was created.
Type (string) --
The type of notebook. Currently, the only valid type is IPYNB .
LastModifiedTime (datetime) --
The time when the notebook was last modified.
Payload (string) --
The content of the exported notebook.
Retrieves notebook metadata for the specified notebook ID.
See also: AWS API Documentation
Request Syntax
client.get_notebook_metadata(
NotebookId='string'
)
string
[REQUIRED]
The ID of the notebook whose metadata is to be retrieved.
dict
Response Syntax
{
'NotebookMetadata': {
'NotebookId': 'string',
'Name': 'string',
'WorkGroup': 'string',
'CreationTime': datetime(2015, 1, 1),
'Type': 'IPYNB',
'LastModifiedTime': datetime(2015, 1, 1)
}
}
Response Structure
(dict) --
NotebookMetadata (dict) --
The metadata that is returned for the specified notebook ID.
NotebookId (string) --
The notebook ID.
Name (string) --
The name of the notebook.
WorkGroup (string) --
The name of the Spark enabled workgroup to which the notebook belongs.
CreationTime (datetime) --
The time when the notebook was created.
Type (string) --
The type of notebook. Currently, the only valid type is IPYNB .
LastModifiedTime (datetime) --
The time when the notebook was last modified.
Imports a single ipynb file to a Spark enabled workgroup. The maximum file size that can be imported is 10 megabytes. If an ipynb file with the same name already exists in the workgroup, throws an error.
See also: AWS API Documentation
Request Syntax
client.import_notebook(
WorkGroup='string',
Name='string',
Payload='string',
Type='IPYNB',
ClientRequestToken='string'
)
string
[REQUIRED]
The name of the Spark enabled workgroup to import the notebook to.
string
[REQUIRED]
The name of the notebook to import.
string
[REQUIRED]
The notebook content to be imported.
string
[REQUIRED]
The notebook content type. Currently, the only valid type is IPYNB .
string
A unique case-sensitive string used to ensure the request to import the notebook is idempotent (executes only once).
Warning
This token is listed as not required because Amazon Web Services SDKs (for example the Amazon Web Services SDK for Java) auto-generate the token for you. If you are not using the Amazon Web Services SDK or the Amazon Web Services CLI, you must provide this token or the action will fail.
dict
Response Syntax
{
'NotebookId': 'string'
}
Response Structure
(dict) --
NotebookId (string) --
The ID of the notebook to import.
Displays the notebook files for the specified workgroup in paginated format.
See also: AWS API Documentation
Request Syntax
client.list_notebook_metadata(
Filters={
'Name': 'string'
},
NextToken='string',
MaxResults=123,
WorkGroup='string'
)
dict
Search filter string.
Name (string) --
The name of the notebook to search for.
string
A token generated by the Athena service that specifies where to continue pagination if a previous request was truncated.
integer
Specifies the maximum number of results to return.
string
[REQUIRED]
The name of the Spark enabled workgroup to retrieve notebook metadata for.
dict
Response Syntax
{
'NextToken': 'string',
'NotebookMetadataList': [
{
'NotebookId': 'string',
'Name': 'string',
'WorkGroup': 'string',
'CreationTime': datetime(2015, 1, 1),
'Type': 'IPYNB',
'LastModifiedTime': datetime(2015, 1, 1)
},
]
}
Response Structure
(dict) --
NextToken (string) --
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.
NotebookMetadataList (list) --
The list of notebook metadata for the specified workgroup.
(dict) --
Contains metadata for notebook, including the notebook name, ID, workgroup, and time created.
NotebookId (string) --
The notebook ID.
Name (string) --
The name of the notebook.
WorkGroup (string) --
The name of the Spark enabled workgroup to which the notebook belongs.
CreationTime (datetime) --
The time when the notebook was created.
Type (string) --
The type of notebook. Currently, the only valid type is IPYNB .
LastModifiedTime (datetime) --
The time when the notebook was last modified.
Lists, in descending order, the sessions that have been created in a notebook that are in an active state like CREATING , CREATED , IDLE or BUSY . Newer sessions are listed first; older sessions are listed later.
See also: AWS API Documentation
Request Syntax
client.list_notebook_sessions(
NotebookId='string',
MaxResults=123,
NextToken='string'
)
string
[REQUIRED]
The ID of the notebook to list sessions for.
integer
The maximum number of notebook sessions to return.
string
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.
dict
Response Syntax
{
'NotebookSessionsList': [
{
'SessionId': 'string',
'CreationTime': datetime(2015, 1, 1)
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
NotebookSessionsList (list) --
A list of the sessions belonging to the notebook.
(dict) --
Contains the notebook session ID and notebook session creation time.
SessionId (string) --
The notebook session ID.
CreationTime (datetime) --
The time when the notebook session was created.
NextToken (string) --
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.
Updates the contents of a Spark notebook.
See also: AWS API Documentation
Request Syntax
client.update_notebook(
NotebookId='string',
Payload='string',
Type='IPYNB',
SessionId='string',
ClientRequestToken='string'
)
string
[REQUIRED]
The ID of the notebook to update.
string
The updated content for the notebook.
string
The notebook content type. Currently, the only valid type is IPYNB .
string
The ID of the session in which the notebook will be updated.
string
A unique case-sensitive string used to ensure the request to create the notebook is idempotent (executes only once).
Warning
This token is listed as not required because Amazon Web Services SDKs (for example the Amazon Web Services SDK for Java) auto-generate the token for you. If you are not using the Amazon Web Services SDK or the Amazon Web Services CLI, you must provide this token or the action will fail.
dict
Response Syntax
{}
Response Structure
(dict) --
Returns the supported DPU sizes for the supported application runtimes (for example, Jupyter 1.0 ).
See also: AWS API Documentation
Request Syntax
client.list_application_dpu_sizes(
MaxResults=123,
NextToken='string'
)
integer
Specifies the maximum number of results to return.
string
A token generated by the Athena service that specifies where to continue pagination if a previous request was truncated.
dict
Response Syntax
{
'ApplicationDPUSizes': [
{
'ApplicationRuntimeId': 'string',
'SupportedDPUSizes': [
123,
]
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
ApplicationDPUSizes (list) --
A list of the supported DPU sizes that the application runtime supports.
(dict) --
Contains the application runtime IDs and their supported DPU sizes.
ApplicationRuntimeId (string) --
The name of the supported application runtime (for example, Jupyter 1.0 ).
SupportedDPUSizes (list) --
A list of the supported DPU sizes that the application runtime supports.
(integer) --
NextToken (string) --
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.
Creates a session for running calculations within a workgroup. The session is ready when it reaches an IDLE state.
See also: AWS API Documentation
Request Syntax
client.start_session(
Description='string',
WorkGroup='string',
EngineConfiguration={
'CoordinatorDpuSize': 123,
'MaxConcurrentDpus': 123,
'DefaultExecutorDpuSize': 123,
'AdditionalConfigs': {
'string': 'string'
}
},
NotebookVersion='string',
SessionIdleTimeoutInMinutes=123,
ClientRequestToken='string'
)
string
The session description.
string
[REQUIRED]
The workgroup to which the session belongs.
dict
[REQUIRED]
Contains engine data processing unit (DPU) configuration settings and parameter mappings.
CoordinatorDpuSize (integer) --
The number of DPUs to use for the coordinator. A coordinator is a special executor that orchestrates processing work and manages other executors in a notebook session.
MaxConcurrentDpus (integer) -- [REQUIRED]
The maximum number of DPUs that can run concurrently.
DefaultExecutorDpuSize (integer) --
The default number of DPUs to use for executors. An executor is the smallest unit of compute that a notebook session can request from Athena.
AdditionalConfigs (dict) --
Contains additional notebook engine MAP<string, string> parameter mappings in the form of key-value pairs. To specify an Amazon S3 URI that the Jupyter server will download and serve, specify a value for the StartSessionRequest$NotebookVersion field, and then add a key named NotebookFileURI to AdditionalConfigs that has value of the Amazon S3 URI.
(string) --
(string) --
string
The notebook version. This value is required only when requesting that a notebook server be started for the session. The only valid notebook version is Jupyter1.0 .
integer
The idle timeout in minutes for the session.
string
A unique case-sensitive string used to ensure the request to create the session is idempotent (executes only once). If another StartSessionRequest is received, the same response is returned and another session is not created. If a parameter has changed, an error is returned.
Warning
This token is listed as not required because Amazon Web Services SDKs (for example the Amazon Web Services SDK for Java) auto-generate the token for users. If you are not using the Amazon Web Services SDK or the Amazon Web Services CLI, you must provide this token or the action will fail.
dict
Response Syntax
{
'SessionId': 'string',
'State': 'CREATING'|'CREATED'|'IDLE'|'BUSY'|'TERMINATING'|'TERMINATED'|'DEGRADED'|'FAILED'
}
Response Structure
(dict) --
SessionId (string) --
The session ID.
State (string) --
The state of the session. A description of each state follows.
CREATING - The session is being started, including acquiring resources.
CREATED - The session has been started.
IDLE - The session is able to accept a calculation.
BUSY - The session is processing another task and is unable to accept a calculation.
TERMINATING - The session is in the process of shutting down.
TERMINATED - The session and its resources are no longer running.
DEGRADED - The session has no healthy coordinators.
FAILED - Due to a failure, the session and its resources are no longer running.
Deletes the specified notebook.
See also: AWS API Documentation
Request Syntax
client.delete_notebook(
NotebookId='string'
)
string
[REQUIRED]
The ID of the notebook to delete.
dict
Response Syntax
{}
Response Structure
(dict) --
Retrieves a pre-signed URL to a copy of the code that was executed for the calculation.
See also: AWS API Documentation
Request Syntax
client.get_calculation_execution_code(
CalculationExecutionId='string'
)
string
[REQUIRED]
The calculation execution UUID.
dict
Response Syntax
{
'CodeBlock': 'string'
}
Response Structure
(dict) --
CodeBlock (string) --
A pre-signed URL to the code that executed the calculation.
Gets the current status of a session.
See also: AWS API Documentation
Request Syntax
client.get_session_status(
SessionId='string'
)
string
[REQUIRED]
The session ID.
dict
Response Syntax
{
'SessionId': 'string',
'Status': {
'StartDateTime': datetime(2015, 1, 1),
'LastModifiedDateTime': datetime(2015, 1, 1),
'EndDateTime': datetime(2015, 1, 1),
'IdleSinceDateTime': datetime(2015, 1, 1),
'State': 'CREATING'|'CREATED'|'IDLE'|'BUSY'|'TERMINATING'|'TERMINATED'|'DEGRADED'|'FAILED',
'StateChangeReason': 'string'
}
}
Response Structure
(dict) --
SessionId (string) --
The session ID.
Status (dict) --
Contains information about the status of the session.
StartDateTime (datetime) --
The date and time that the session started.
LastModifiedDateTime (datetime) --
The most recent date and time that the session was modified.
EndDateTime (datetime) --
The date and time that the session ended.
IdleSinceDateTime (datetime) --
The date and time starting at which the session became idle. Can be empty if the session is not currently idle.
State (string) --
The state of the session. A description of each state follows.
CREATING - The session is being started, including acquiring resources.
CREATED - The session has been started.
IDLE - The session is able to accept a calculation.
BUSY - The session is processing another task and is unable to accept a calculation.
TERMINATING - The session is in the process of shutting down.
TERMINATED - The session and its resources are no longer running.
DEGRADED - The session has no healthy coordinators.
FAILED - Due to a failure, the session and its resources are no longer running.
StateChangeReason (string) --
The reason for the session state change (for example, canceled because the session was terminated).
Describes a previously submitted calculation execution.
See also: AWS API Documentation
Request Syntax
client.get_calculation_execution(
CalculationExecutionId='string'
)
string
[REQUIRED]
The calculation execution UUID.
dict
Response Syntax
{
'CalculationExecutionId': 'string',
'SessionId': 'string',
'Description': 'string',
'WorkingDirectory': 'string',
'Status': {
'SubmissionDateTime': datetime(2015, 1, 1),
'CompletionDateTime': datetime(2015, 1, 1),
'State': 'CREATING'|'CREATED'|'QUEUED'|'RUNNING'|'CANCELING'|'CANCELED'|'COMPLETED'|'FAILED',
'StateChangeReason': 'string'
},
'Statistics': {
'DpuExecutionInMillis': 123,
'Progress': 'string'
},
'Result': {
'StdOutS3Uri': 'string',
'StdErrorS3Uri': 'string',
'ResultS3Uri': 'string',
'ResultType': 'string'
}
}
Response Structure
(dict) --
CalculationExecutionId (string) --
The calculation execution UUID.
SessionId (string) --
The session ID that the calculation ran in.
Description (string) --
The description of the calculation execution.
WorkingDirectory (string) --
The Amazon S3 location in which calculation results are stored.
Status (dict) --
Contains information about the status of the calculation.
SubmissionDateTime (datetime) --
The date and time the calculation was submitted for processing.
CompletionDateTime (datetime) --
The date and time the calculation completed processing.
State (string) --
The state of the calculation execution. A description of each state follows.
CREATING - The calculation is in the process of being created.
CREATED - The calculation has been created and is ready to run.
QUEUED - The calculation has been queued for processing.
RUNNING - The calculation is running.
CANCELING - A request to cancel the calculation has been received and the system is working to stop it.
CANCELED - The calculation is no longer running as the result of a cancel request.
COMPLETED - The calculation has completed without error.
FAILED - The calculation failed and is no longer running.
StateChangeReason (string) --
The reason for the calculation state change (for example, the calculation was canceled because the session was terminated).
Statistics (dict) --
Contains information about the data processing unit (DPU) execution time and progress. This field is populated only when statistics are available.
DpuExecutionInMillis (integer) --
The data processing unit execution time in milliseconds for the calculation.
Progress (string) --
The progress of the calculation.
Result (dict) --
Contains result information. This field is populated only if the calculation is completed.
StdOutS3Uri (string) --
The Amazon S3 location of the stdout file for the calculation.
StdErrorS3Uri (string) --
The Amazon S3 location of the stderr error messages file for the calculation.
ResultS3Uri (string) --
The Amazon S3 location of the folder for the calculation results.
ResultType (string) --
The data format of the calculation result.
Lists, in descending order, the executors that have been submitted to a session. Newer executors are listed first; older executors are listed later. The result can be optionally filtered by state.
See also: AWS API Documentation
Request Syntax
client.list_executors(
SessionId='string',
ExecutorStateFilter='CREATING'|'CREATED'|'REGISTERED'|'TERMINATING'|'TERMINATED'|'FAILED',
MaxResults=123,
NextToken='string'
)
string
[REQUIRED]
The session ID.
string
A filter for a specific executor state. A description of each state follows.
CREATING - The executor is being started, including acquiring resources.
CREATED - The executor has been started.
REGISTERED - The executor has been registered.
TERMINATING - The executor is in the process of shutting down.
TERMINATED - The executor is no longer running.
FAILED - Due to a failure, the executor is no longer running.
integer
The maximum number of executors to return.
string
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.
dict
Response Syntax
{
'SessionId': 'string',
'NextToken': 'string',
'ExecutorsSummary': [
{
'ExecutorId': 'string',
'ExecutorType': 'COORDINATOR'|'GATEWAY'|'WORKER',
'StartDateTime': 123,
'TerminationDateTime': 123,
'ExecutorState': 'CREATING'|'CREATED'|'REGISTERED'|'TERMINATING'|'TERMINATED'|'FAILED',
'ExecutorSize': 123
},
]
}
Response Structure
(dict) --
SessionId (string) --
The session ID.
NextToken (string) --
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.
ExecutorsSummary (list) --
Contains summary information about the executor.
(dict) --
Contains summary information about an executor.
ExecutorId (string) --
The UUID of the executor.
ExecutorType (string) --
The type of executor used for the application (COORDINATOR , GATEWAY , or WORKER ).
StartDateTime (integer) --
The date and time that the executor started.
TerminationDateTime (integer) --
The date and time that the executor was terminated.
ExecutorState (string) --
The processing state of the executor. A description of each state follows.
CREATING - The executor is being started, including acquiring resources.
CREATED - The executor has been started.
REGISTERED - The executor has been registered.
TERMINATING - The executor is in the process of shutting down.
TERMINATED - The executor is no longer running.
FAILED - Due to a failure, the executor is no longer running.
ExecutorSize (integer) --
The smallest unit of compute that a session can request from Athena. Size is measured in data processing unit (DPU) values, a relative measure of processing power.
Terminates an active session. A TerminateSession call on a session that is already inactive (for example, in a FAILED , TERMINATED or TERMINATING state) succeeds but has no effect. Calculations running in the session when TerminateSession is called are forcefully stopped, but may display as FAILED instead of STOPPED .
See also: AWS API Documentation
Request Syntax
client.terminate_session(
SessionId='string'
)
string
[REQUIRED]
The session ID.
dict
Response Syntax
{
'State': 'CREATING'|'CREATED'|'IDLE'|'BUSY'|'TERMINATING'|'TERMINATED'|'DEGRADED'|'FAILED'
}
Response Structure
(dict) --
State (string) --
The state of the session. A description of each state follows.
CREATING - The session is being started, including acquiring resources.
CREATED - The session has been started.
IDLE - The session is able to accept a calculation.
BUSY - The session is processing another task and is unable to accept a calculation.
TERMINATING - The session is in the process of shutting down.
TERMINATED - The session and its resources are no longer running.
DEGRADED - The session has no healthy coordinators.
FAILED - Due to a failure, the session and its resources are no longer running.
Lists the sessions in a workgroup that are in an active state like CREATING , CREATED , IDLE , or BUSY . Newer sessions are listed first; older sessions are listed later.
See also: AWS API Documentation
Request Syntax
client.list_sessions(
WorkGroup='string',
StateFilter='CREATING'|'CREATED'|'IDLE'|'BUSY'|'TERMINATING'|'TERMINATED'|'DEGRADED'|'FAILED',
MaxResults=123,
NextToken='string'
)
string
[REQUIRED]
The workgroup to which the session belongs.
string
A filter for a specific session state. A description of each state follows.
CREATING - The session is being started, including acquiring resources.
CREATED - The session has been started.
IDLE - The session is able to accept a calculation.
BUSY - The session is processing another task and is unable to accept a calculation.
TERMINATING - The session is in the process of shutting down.
TERMINATED - The session and its resources are no longer running.
DEGRADED - The session has no healthy coordinators.
FAILED - Due to a failure, the session and its resources are no longer running.
integer
The maximum number of sessions to return.
string
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.
dict
Response Syntax
{
'NextToken': 'string',
'Sessions': [
{
'SessionId': 'string',
'Description': 'string',
'EngineVersion': {
'SelectedEngineVersion': 'string',
'EffectiveEngineVersion': 'string'
},
'NotebookVersion': 'string',
'Status': {
'StartDateTime': datetime(2015, 1, 1),
'LastModifiedDateTime': datetime(2015, 1, 1),
'EndDateTime': datetime(2015, 1, 1),
'IdleSinceDateTime': datetime(2015, 1, 1),
'State': 'CREATING'|'CREATED'|'IDLE'|'BUSY'|'TERMINATING'|'TERMINATED'|'DEGRADED'|'FAILED',
'StateChangeReason': 'string'
}
},
]
}
Response Structure
(dict) --
NextToken (string) --
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.
Sessions (list) --
A list of sessions.
(dict) --
Contains summary information about a notebook session.
SessionId (string) --
The session ID.
Description (string) --
The session description.
EngineVersion (dict) --
The engine version used by the session (for example, PySpark engine version 3 ).
SelectedEngineVersion (string) --
The engine version requested by the user. Possible values are determined by the output of ListEngineVersions , including Auto. The default is Auto.
EffectiveEngineVersion (string) --
Read only. The engine version on which the query runs. If the user requests a valid engine version other than Auto, the effective engine version is the same as the engine version that the user requested. If the user requests Auto, the effective engine version is chosen by Athena. When a request to update the engine version is made by a CreateWorkGroup or UpdateWorkGroup operation, the EffectiveEngineVersion field is ignored.
NotebookVersion (string) --
The notebook version.
Status (dict) --
Contains information about the session status.
StartDateTime (datetime) --
The date and time that the session started.
LastModifiedDateTime (datetime) --
The most recent date and time that the session was modified.
EndDateTime (datetime) --
The date and time that the session ended.
IdleSinceDateTime (datetime) --
The date and time starting at which the session became idle. Can be empty if the session is not currently idle.
State (string) --
The state of the session. A description of each state follows.
CREATING - The session is being started, including acquiring resources.
CREATED - The session has been started.
IDLE - The session is able to accept a calculation.
BUSY - The session is processing another task and is unable to accept a calculation.
TERMINATING - The session is in the process of shutting down.
TERMINATED - The session and its resources are no longer running.
DEGRADED - The session has no healthy coordinators.
FAILED - Due to a failure, the session and its resources are no longer running.
StateChangeReason (string) --
The reason for the session state change (for example, canceled because the session was terminated).
Lists the calculations that have been submitted to a session in descending order. Newer calculations are listed first; older calculations are listed later.
See also: AWS API Documentation
Request Syntax
client.list_calculation_executions(
SessionId='string',
StateFilter='CREATING'|'CREATED'|'QUEUED'|'RUNNING'|'CANCELING'|'CANCELED'|'COMPLETED'|'FAILED',
MaxResults=123,
NextToken='string'
)
string
[REQUIRED]
The session ID.
string
A filter for a specific calculation execution state. A description of each state follows.
CREATING - The calculation is in the process of being created.
CREATED - The calculation has been created and is ready to run.
QUEUED - The calculation has been queued for processing.
RUNNING - The calculation is running.
CANCELING - A request to cancel the calculation has been received and the system is working to stop it.
CANCELED - The calculation is no longer running as the result of a cancel request.
COMPLETED - The calculation has completed without error.
FAILED - The calculation failed and is no longer running.
integer
The maximum number of calculation executions to return.
string
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.
dict
Response Syntax
{
'NextToken': 'string',
'Calculations': [
{
'CalculationExecutionId': 'string',
'Description': 'string',
'Status': {
'SubmissionDateTime': datetime(2015, 1, 1),
'CompletionDateTime': datetime(2015, 1, 1),
'State': 'CREATING'|'CREATED'|'QUEUED'|'RUNNING'|'CANCELING'|'CANCELED'|'COMPLETED'|'FAILED',
'StateChangeReason': 'string'
}
},
]
}
Response Structure
(dict) --
NextToken (string) --
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.
Calculations (list) --
A list of CalculationSummary objects.
(dict) --
Summary information for a notebook calculation.
CalculationExecutionId (string) --
The calculation execution UUID.
Description (string) --
A description of the calculation.
Status (dict) --
Contains information about the status of the calculation.
SubmissionDateTime (datetime) --
The date and time the calculation was submitted for processing.
CompletionDateTime (datetime) --
The date and time the calculation completed processing.
State (string) --
The state of the calculation execution. A description of each state follows.
CREATING - The calculation is in the process of being created.
CREATED - The calculation has been created and is ready to run.
QUEUED - The calculation has been queued for processing.
RUNNING - The calculation is running.
CANCELING - A request to cancel the calculation has been received and the system is working to stop it.
CANCELED - The calculation is no longer running as the result of a cancel request.
COMPLETED - The calculation has completed without error.
FAILED - The calculation failed and is no longer running.
StateChangeReason (string) --
The reason for the calculation state change (for example, the calculation was canceled because the session was terminated).
Submits calculations for execution within a session. You can supply the code to run as an inline code block within the request or as an Amazon S3 URL.
See also: AWS API Documentation
Request Syntax
client.start_calculation_execution(
SessionId='string',
Description='string',
CalculationConfiguration={
'CodeBlock': 'string'
},
CodeBlock='string',
ClientRequestToken='string'
)
string
[REQUIRED]
The session ID.
string
A description of the calculation.
dict
Contains configuration information for the calculation.
CodeBlock (string) --
A string that contains the code for the calculation.
string
A string that contains the code of the calculation.
string
A unique case-sensitive string used to ensure the request to create the calculation is idempotent (executes only once). If another StartCalculationExecutionRequest is received, the same response is returned and another calculation is not created. If a parameter has changed, an error is returned.
Warning
This token is listed as not required because Amazon Web Services SDKs (for example the Amazon Web Services SDK for Java) auto-generate the token for users. If you are not using the Amazon Web Services SDK or the Amazon Web Services CLI, you must provide this token or the action will fail.
dict
Response Syntax
{
'CalculationExecutionId': 'string',
'State': 'CREATING'|'CREATED'|'QUEUED'|'RUNNING'|'CANCELING'|'CANCELED'|'COMPLETED'|'FAILED'
}
Response Structure
(dict) --
CalculationExecutionId (string) --
The calculation execution UUID.
State (string) --
CREATING - The calculation is in the process of being created.
CREATED - The calculation has been created and is ready to run.
QUEUED - The calculation has been queued for processing.
RUNNING - The calculation is running.
CANCELING - A request to cancel the calculation has been received and the system is working to stop it.
CANCELED - The calculation is no longer running as the result of a cancel request.
COMPLETED - The calculation has completed without error.
FAILED - The calculation failed and is no longer running.
Gets an authentication token and the URL at which the notebook can be accessed. During programmatic access, CreatePresignedNotebookUrl must be called every 10 minutes to refresh the authentication token.
See also: AWS API Documentation
Request Syntax
client.create_presigned_notebook_url(
SessionId='string'
)
string
[REQUIRED]
The session ID.
dict
Response Syntax
{
'NotebookUrl': 'string',
'AuthToken': 'string',
'AuthTokenExpirationTime': 123
}
Response Structure
(dict) --
NotebookUrl (string) --
The URL of the notebook. The URL includes the authentication token and notebook file name and points directly to the opened notebook.
AuthToken (string) --
The authentication token for the notebook.
AuthTokenExpirationTime (integer) --
The UTC epoch time when the authentication token expires.
{'Configuration': {'AdditionalConfiguration': 'string',
'CustomerContentEncryptionConfiguration': {'KmsKey': 'string'},
'ExecutionRole': 'string'}}
Creates a workgroup with the specified name. Only one of Configurations or Configuration can be specified; Configurations for a workgroup with multi engine support (for example, an Apache Spark enabled workgroup) or Configuration for an Athena SQL workgroup.
See also: AWS API Documentation
Request Syntax
client.create_work_group(
Name='string',
Configuration={
'ResultConfiguration': {
'OutputLocation': 'string',
'EncryptionConfiguration': {
'EncryptionOption': 'SSE_S3'|'SSE_KMS'|'CSE_KMS',
'KmsKey': 'string'
},
'ExpectedBucketOwner': 'string',
'AclConfiguration': {
'S3AclOption': 'BUCKET_OWNER_FULL_CONTROL'
}
},
'EnforceWorkGroupConfiguration': True|False,
'PublishCloudWatchMetricsEnabled': True|False,
'BytesScannedCutoffPerQuery': 123,
'RequesterPaysEnabled': True|False,
'EngineVersion': {
'SelectedEngineVersion': 'string',
'EffectiveEngineVersion': 'string'
},
'AdditionalConfiguration': 'string',
'ExecutionRole': 'string',
'CustomerContentEncryptionConfiguration': {
'KmsKey': 'string'
}
},
Description='string',
Tags=[
{
'Key': 'string',
'Value': 'string'
},
]
)
string
[REQUIRED]
The workgroup name.
dict
Contains configuration information for creating an Athena SQL 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 .
ResultConfiguration (dict) --
The configuration for the workgroup, which includes the location in Amazon S3 where query results are stored and the encryption option, if any, used for query results. To run the query, you must specify the query results location using one of the ways: either in the workgroup using this setting, or for individual queries (client-side), using ResultConfiguration$OutputLocation . If none of them is set, Athena issues an error that no output location is provided. For more information, see Query Results .
OutputLocation (string) --
The location in Amazon S3 where your query results are stored, such as s3://path/to/query/bucket/ . To run the query, you must specify the query results location using one of the ways: either for individual queries using either this setting (client-side), or in the workgroup, using WorkGroupConfiguration . If none of them is set, Athena issues an error that no output location is provided. For more information, see Query Results . If workgroup settings override client-side settings, then the query uses the settings specified for the workgroup. See WorkGroupConfiguration$EnforceWorkGroupConfiguration .
EncryptionConfiguration (dict) --
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 .
EncryptionOption (string) -- [REQUIRED]
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 (string) --
For SSE_KMS and CSE_KMS , this is the KMS key ARN or ID.
ExpectedBucketOwner (string) --
The Amazon Web Services account ID that you expect to be the owner of the Amazon S3 bucket specified by ResultConfiguration$OutputLocation . If set, Athena uses the value for ExpectedBucketOwner when it makes Amazon S3 calls to your specified output location. If the ExpectedBucketOwner Amazon Web Services account ID does not match the actual owner of the Amazon S3 bucket, the call fails with a permissions error.
This is a client-side setting. If workgroup settings override client-side settings, then the query uses the ExpectedBucketOwner setting that is specified for the workgroup, and also uses the location for storing query results specified in the workgroup. See WorkGroupConfiguration$EnforceWorkGroupConfiguration and Workgroup Settings Override Client-Side Settings .
AclConfiguration (dict) --
Indicates that an Amazon S3 canned ACL should be set to control ownership of stored query results. Currently the only supported canned ACL is BUCKET_OWNER_FULL_CONTROL . This is a client-side setting. If workgroup settings override client-side settings, then the query uses the ACL configuration that is specified for the workgroup, and also uses the location for storing query results specified in the workgroup. For more information, see WorkGroupConfiguration$EnforceWorkGroupConfiguration and Workgroup Settings Override Client-Side Settings .
S3AclOption (string) -- [REQUIRED]
The Amazon S3 canned ACL that Athena should specify when storing query results. Currently the only supported canned ACL is BUCKET_OWNER_FULL_CONTROL . If a query runs in a workgroup and the workgroup overrides client-side settings, then the Amazon S3 canned ACL specified in the workgroup's settings is used for all queries that run in the workgroup. For more information about Amazon S3 canned ACLs, see Canned ACL in the Amazon S3 User Guide .
EnforceWorkGroupConfiguration (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 (boolean) --
Indicates that the Amazon CloudWatch metrics are enabled for the workgroup.
BytesScannedCutoffPerQuery (integer) --
The upper data usage limit (cutoff) for the amount of bytes a single query in a workgroup is allowed to scan.
RequesterPaysEnabled (boolean) --
If set to true , allows members assigned to a workgroup to reference Amazon S3 Requester Pays buckets in queries. If set to false , workgroup members cannot query data from Requester Pays buckets, and queries that retrieve data from Requester Pays buckets cause an error. The default is false . For more information about Requester Pays buckets, see Requester Pays Buckets in the Amazon Simple Storage Service Developer Guide .
EngineVersion (dict) --
The engine version that all queries running on the workgroup use. Queries on the AmazonAthenaPreviewFunctionality workgroup run on the preview engine regardless of this setting.
SelectedEngineVersion (string) --
The engine version requested by the user. Possible values are determined by the output of ListEngineVersions , including Auto. The default is Auto.
EffectiveEngineVersion (string) --
Read only. The engine version on which the query runs. If the user requests a valid engine version other than Auto, the effective engine version is the same as the engine version that the user requested. If the user requests Auto, the effective engine version is chosen by Athena. When a request to update the engine version is made by a CreateWorkGroup or UpdateWorkGroup operation, the EffectiveEngineVersion field is ignored.
AdditionalConfiguration (string) --
Specifies a user defined JSON string that is passed to the notebook engine.
ExecutionRole (string) --
Role used in a notebook session for accessing the user's resources.
CustomerContentEncryptionConfiguration (dict) --
Specifies the KMS key that is used to encrypt the user's data stores in Athena.
KmsKey (string) -- [REQUIRED]
The KMS key that is used to encrypt the user's data stores in Athena.
string
The workgroup description.
list
A list of comma separated tags to add to the workgroup that is created.
(dict) --
A label that you assign to a resource. In Athena, a resource can be a workgroup or data catalog. Each tag consists of a key and an optional value, both of which you define. For example, you can use tags to categorize Athena workgroups or data catalogs by purpose, owner, or environment. Use a consistent set of tag keys to make it easier to search and filter workgroups or data catalogs in your account. For best practices, see Tagging Best Practices . Tag keys can be from 1 to 128 UTF-8 Unicode characters, and tag values can be from 0 to 256 UTF-8 Unicode characters. Tags can use letters and numbers representable in UTF-8, and the following characters: + - = . _ : / @. Tag keys and values are case-sensitive. Tag keys must be unique per resource. If you specify more than one tag, separate them by commas.
Key (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 (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.
dict
Response Syntax
{}
Response Structure
(dict) --
{'WorkGroup': {'Configuration': {'AdditionalConfiguration': 'string',
'CustomerContentEncryptionConfiguration': {'KmsKey': 'string'},
'ExecutionRole': 'string'}}}
Returns information about the workgroup with the specified name.
See also: AWS API Documentation
Request Syntax
client.get_work_group(
WorkGroup='string'
)
string
[REQUIRED]
The name of the workgroup.
dict
Response Syntax
{
'WorkGroup': {
'Name': 'string',
'State': 'ENABLED'|'DISABLED',
'Configuration': {
'ResultConfiguration': {
'OutputLocation': 'string',
'EncryptionConfiguration': {
'EncryptionOption': 'SSE_S3'|'SSE_KMS'|'CSE_KMS',
'KmsKey': 'string'
},
'ExpectedBucketOwner': 'string',
'AclConfiguration': {
'S3AclOption': 'BUCKET_OWNER_FULL_CONTROL'
}
},
'EnforceWorkGroupConfiguration': True|False,
'PublishCloudWatchMetricsEnabled': True|False,
'BytesScannedCutoffPerQuery': 123,
'RequesterPaysEnabled': True|False,
'EngineVersion': {
'SelectedEngineVersion': 'string',
'EffectiveEngineVersion': 'string'
},
'AdditionalConfiguration': 'string',
'ExecutionRole': 'string',
'CustomerContentEncryptionConfiguration': {
'KmsKey': 'string'
}
},
'Description': 'string',
'CreationTime': datetime(2015, 1, 1)
}
}
Response Structure
(dict) --
WorkGroup (dict) --
Information about the workgroup.
Name (string) --
The workgroup name.
State (string) --
The state of the workgroup: ENABLED or DISABLED.
Configuration (dict) --
The configuration of the workgroup, which includes the location in Amazon S3 where query results are stored, the encryption configuration, if any, used for query results; whether the Amazon CloudWatch Metrics are enabled for the workgroup; whether workgroup settings override client-side settings; and the data usage limits for the amount of data scanned per query or per workgroup. The workgroup settings override is specified in EnforceWorkGroupConfiguration (true/false) in the WorkGroupConfiguration . See WorkGroupConfiguration$EnforceWorkGroupConfiguration .
ResultConfiguration (dict) --
The configuration for the workgroup, which includes the location in Amazon S3 where query results are stored and the encryption option, if any, used for query results. To run the query, you must specify the query results location using one of the ways: either in the workgroup using this setting, or for individual queries (client-side), using ResultConfiguration$OutputLocation . If none of them is set, Athena issues an error that no output location is provided. For more information, see Query Results .
OutputLocation (string) --
The location in Amazon S3 where your query results are stored, such as s3://path/to/query/bucket/ . To run the query, you must specify the query results location using one of the ways: either for individual queries using either this setting (client-side), or in the workgroup, using WorkGroupConfiguration . If none of them is set, Athena issues an error that no output location is provided. For more information, see Query Results . If workgroup settings override client-side settings, then the query uses the settings specified for the workgroup. See WorkGroupConfiguration$EnforceWorkGroupConfiguration .
EncryptionConfiguration (dict) --
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 .
EncryptionOption (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 (string) --
For SSE_KMS and CSE_KMS , this is the KMS key ARN or ID.
ExpectedBucketOwner (string) --
The Amazon Web Services account ID that you expect to be the owner of the Amazon S3 bucket specified by ResultConfiguration$OutputLocation . If set, Athena uses the value for ExpectedBucketOwner when it makes Amazon S3 calls to your specified output location. If the ExpectedBucketOwner Amazon Web Services account ID does not match the actual owner of the Amazon S3 bucket, the call fails with a permissions error.
This is a client-side setting. If workgroup settings override client-side settings, then the query uses the ExpectedBucketOwner setting that is specified for the workgroup, and also uses the location for storing query results specified in the workgroup. See WorkGroupConfiguration$EnforceWorkGroupConfiguration and Workgroup Settings Override Client-Side Settings .
AclConfiguration (dict) --
Indicates that an Amazon S3 canned ACL should be set to control ownership of stored query results. Currently the only supported canned ACL is BUCKET_OWNER_FULL_CONTROL . This is a client-side setting. If workgroup settings override client-side settings, then the query uses the ACL configuration that is specified for the workgroup, and also uses the location for storing query results specified in the workgroup. For more information, see WorkGroupConfiguration$EnforceWorkGroupConfiguration and Workgroup Settings Override Client-Side Settings .
S3AclOption (string) --
The Amazon S3 canned ACL that Athena should specify when storing query results. Currently the only supported canned ACL is BUCKET_OWNER_FULL_CONTROL . If a query runs in a workgroup and the workgroup overrides client-side settings, then the Amazon S3 canned ACL specified in the workgroup's settings is used for all queries that run in the workgroup. For more information about Amazon S3 canned ACLs, see Canned ACL in the Amazon S3 User Guide .
EnforceWorkGroupConfiguration (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 (boolean) --
Indicates that the Amazon CloudWatch metrics are enabled for the workgroup.
BytesScannedCutoffPerQuery (integer) --
The upper data usage limit (cutoff) for the amount of bytes a single query in a workgroup is allowed to scan.
RequesterPaysEnabled (boolean) --
If set to true , allows members assigned to a workgroup to reference Amazon S3 Requester Pays buckets in queries. If set to false , workgroup members cannot query data from Requester Pays buckets, and queries that retrieve data from Requester Pays buckets cause an error. The default is false . For more information about Requester Pays buckets, see Requester Pays Buckets in the Amazon Simple Storage Service Developer Guide .
EngineVersion (dict) --
The engine version that all queries running on the workgroup use. Queries on the AmazonAthenaPreviewFunctionality workgroup run on the preview engine regardless of this setting.
SelectedEngineVersion (string) --
The engine version requested by the user. Possible values are determined by the output of ListEngineVersions , including Auto. The default is Auto.
EffectiveEngineVersion (string) --
Read only. The engine version on which the query runs. If the user requests a valid engine version other than Auto, the effective engine version is the same as the engine version that the user requested. If the user requests Auto, the effective engine version is chosen by Athena. When a request to update the engine version is made by a CreateWorkGroup or UpdateWorkGroup operation, the EffectiveEngineVersion field is ignored.
AdditionalConfiguration (string) --
Specifies a user defined JSON string that is passed to the notebook engine.
ExecutionRole (string) --
Role used in a notebook session for accessing the user's resources.
CustomerContentEncryptionConfiguration (dict) --
Specifies the KMS key that is used to encrypt the user's data stores in Athena.
KmsKey (string) --
The KMS key that is used to encrypt the user's data stores in Athena.
Description (string) --
The workgroup description.
CreationTime (datetime) --
The date and time the workgroup was created.
{'ConfigurationUpdates': {'AdditionalConfiguration': 'string',
'CustomerContentEncryptionConfiguration': {'KmsKey': 'string'},
'ExecutionRole': 'string',
'RemoveCustomerContentEncryptionConfiguration': 'boolean'}}
Updates the workgroup with the specified name. The workgroup's name cannot be changed. Only one of ConfigurationsUpdates or ConfigurationUpdates can be specified; ConfigurationsUpdates for a workgroup with multi engine support (for example, an Apache Spark enabled workgroup) or ConfigurationUpdates for an Athena SQL workgroup.
See also: AWS API Documentation
Request Syntax
client.update_work_group(
WorkGroup='string',
Description='string',
ConfigurationUpdates={
'EnforceWorkGroupConfiguration': True|False,
'ResultConfigurationUpdates': {
'OutputLocation': 'string',
'RemoveOutputLocation': True|False,
'EncryptionConfiguration': {
'EncryptionOption': 'SSE_S3'|'SSE_KMS'|'CSE_KMS',
'KmsKey': 'string'
},
'RemoveEncryptionConfiguration': True|False,
'ExpectedBucketOwner': 'string',
'RemoveExpectedBucketOwner': True|False,
'AclConfiguration': {
'S3AclOption': 'BUCKET_OWNER_FULL_CONTROL'
},
'RemoveAclConfiguration': True|False
},
'PublishCloudWatchMetricsEnabled': True|False,
'BytesScannedCutoffPerQuery': 123,
'RemoveBytesScannedCutoffPerQuery': True|False,
'RequesterPaysEnabled': True|False,
'EngineVersion': {
'SelectedEngineVersion': 'string',
'EffectiveEngineVersion': 'string'
},
'RemoveCustomerContentEncryptionConfiguration': True|False,
'AdditionalConfiguration': 'string',
'ExecutionRole': 'string',
'CustomerContentEncryptionConfiguration': {
'KmsKey': 'string'
}
},
State='ENABLED'|'DISABLED'
)
string
[REQUIRED]
The specified workgroup that will be updated.
string
The workgroup description.
dict
Contains configuration updates for an Athena SQL workgroup.
EnforceWorkGroupConfiguration (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 .
ResultConfigurationUpdates (dict) --
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.
OutputLocation (string) --
The location in Amazon S3 where your query results are stored, such as s3://path/to/query/bucket/ . For more information, see Query Results If workgroup settings override client-side settings, then the query uses the location for the query results and the encryption configuration that are specified for the workgroup. The "workgroup settings override" is specified in EnforceWorkGroupConfiguration (true/false) in the WorkGroupConfiguration . See WorkGroupConfiguration$EnforceWorkGroupConfiguration .
RemoveOutputLocation (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 .
EncryptionConfiguration (dict) --
The encryption configuration for the query results.
EncryptionOption (string) -- [REQUIRED]
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 (string) --
For SSE_KMS and CSE_KMS , this is the KMS key ARN or ID.
RemoveEncryptionConfiguration (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 .
ExpectedBucketOwner (string) --
The Amazon Web Services account ID that you expect to be the owner of the Amazon S3 bucket specified by ResultConfiguration$OutputLocation . If set, Athena uses the value for ExpectedBucketOwner when it makes Amazon S3 calls to your specified output location. If the ExpectedBucketOwner Amazon Web Services account ID does not match the actual owner of the Amazon S3 bucket, the call fails with a permissions error.
If workgroup settings override client-side settings, then the query uses the ExpectedBucketOwner setting that is specified for the workgroup, and also uses the location for storing query results specified in the workgroup. See WorkGroupConfiguration$EnforceWorkGroupConfiguration and Workgroup Settings Override Client-Side Settings .
RemoveExpectedBucketOwner (boolean) --
If set to "true", removes the Amazon Web Services account ID previously specified for ResultConfiguration$ExpectedBucketOwner . If set to "false" or not set, and a value is present in the ExpectedBucketOwner in ResultConfigurationUpdates (the client-side setting), the ExpectedBucketOwner in the workgroup's ResultConfiguration is updated with the new value. For more information, see Workgroup Settings Override Client-Side Settings .
AclConfiguration (dict) --
The ACL configuration for the query results.
S3AclOption (string) -- [REQUIRED]
The Amazon S3 canned ACL that Athena should specify when storing query results. Currently the only supported canned ACL is BUCKET_OWNER_FULL_CONTROL . If a query runs in a workgroup and the workgroup overrides client-side settings, then the Amazon S3 canned ACL specified in the workgroup's settings is used for all queries that run in the workgroup. For more information about Amazon S3 canned ACLs, see Canned ACL in the Amazon S3 User Guide .
RemoveAclConfiguration (boolean) --
If set to true , indicates that the previously-specified ACL configuration for queries in this workgroup should be ignored and set to null. If set to false or not set, and a value is present in the AclConfiguration of ResultConfigurationUpdates , the AclConfiguration in the workgroup's ResultConfiguration is updated with the new value. For more information, see Workgroup Settings Override Client-Side Settings .
PublishCloudWatchMetricsEnabled (boolean) --
Indicates whether this workgroup enables publishing metrics to Amazon CloudWatch.
BytesScannedCutoffPerQuery (integer) --
The upper limit (cutoff) for the amount of bytes a single query in a workgroup is allowed to scan.
RemoveBytesScannedCutoffPerQuery (boolean) --
Indicates that the data usage control limit per query is removed. WorkGroupConfiguration$BytesScannedCutoffPerQuery
RequesterPaysEnabled (boolean) --
If set to true , allows members assigned to a workgroup to specify Amazon S3 Requester Pays buckets in queries. If set to false , workgroup members cannot query data from Requester Pays buckets, and queries that retrieve data from Requester Pays buckets cause an error. The default is false . For more information about Requester Pays buckets, see Requester Pays Buckets in the Amazon Simple Storage Service Developer Guide .
EngineVersion (dict) --
The engine version requested when a workgroup is updated. After the update, all queries on the workgroup run on the requested engine version. If no value was previously set, the default is Auto. Queries on the AmazonAthenaPreviewFunctionality workgroup run on the preview engine regardless of this setting.
SelectedEngineVersion (string) --
The engine version requested by the user. Possible values are determined by the output of ListEngineVersions , including Auto. The default is Auto.
EffectiveEngineVersion (string) --
Read only. The engine version on which the query runs. If the user requests a valid engine version other than Auto, the effective engine version is the same as the engine version that the user requested. If the user requests Auto, the effective engine version is chosen by Athena. When a request to update the engine version is made by a CreateWorkGroup or UpdateWorkGroup operation, the EffectiveEngineVersion field is ignored.
RemoveCustomerContentEncryptionConfiguration (boolean) --
Removes content encryption configuration for a workgroup.
AdditionalConfiguration (string) --
Contains a user defined string in JSON format for a Spark-enabled workgroup.
ExecutionRole (string) --
Contains the ARN of the execution role for the workgroup
CustomerContentEncryptionConfiguration (dict) --
Specifies the KMS key that is used to encrypt the user's data stores in Athena.
KmsKey (string) -- [REQUIRED]
The KMS key that is used to encrypt the user's data stores in Athena.
string
The workgroup state that will be updated for the given workgroup.
dict
Response Syntax
{}
Response Structure
(dict) --