Amazon Athena Athena Session API

openapi: 3.2.0
info:
  title: Amazon Athena Session API
  version: '2017-05-18'
  description: Generated from AWS's published Smithy model for Amazon Athena. 3 operation(s).
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/contact-us/
  license:
    name: Apache 2.0
    identifier: Apache-2.0
    url: https://github.com/aws/api-models-aws/blob/main/LICENSE
servers:
- url: https://athena.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
tags:
- name: Session
paths:
  /#GetSession:
    post:
      operationId: GetSession
      summary: Get Session
      description: Gets the full details of a previously created session, including the session status and configuration.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/GetSessionResponse'
        '500':
          description: InternalServerException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '400':
          description: InvalidRequestException; ResourceNotFoundException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InvalidRequestException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - AmazonAthena.GetSession
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/GetSessionRequest'
      tags:
      - Session
  /#ListSessions:
    post:
      operationId: ListSessions
      summary: List Sessions
      description: 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.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ListSessionsResponse'
        '500':
          description: InternalServerException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '400':
          description: InvalidRequestException; ResourceNotFoundException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InvalidRequestException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - AmazonAthena.ListSessions
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/ListSessionsRequest'
      tags:
      - Session
  /#StartSession:
    post:
      operationId: StartSession
      summary: Start Session
      description: Creates a session for running calculations within a workgroup. The session is ready when it reaches an IDLE state.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/StartSessionResponse'
        '500':
          description: InternalServerException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '400':
          description: InvalidRequestException; ResourceNotFoundException; SessionAlreadyExistsException; TooManyRequestsException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InvalidRequestException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - AmazonAthena.StartSession
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/StartSessionRequest'
      tags:
      - Session
components:
  schemas:
    SessionConfiguration:
      type: object
      properties:
        ExecutionRole:
          type: string
          description: The ARN of the execution role used to access user resources for Spark sessions and Identity Center enabled workgroups. This property applies only to Spark enabled workgroups and Identity Center enabled workgroups.
        WorkingDirectory:
          type: string
          description: The Amazon S3 location that stores information for the notebook.
        IdleTimeoutSeconds:
          type: integer
          description: The idle timeout in seconds for the session.
        SessionIdleTimeoutInMinutes:
          type: integer
          description: The idle timeout in seconds for the session.
        EncryptionConfiguration:
          $ref: '#/components/schemas/EncryptionConfiguration'
    Tag:
      type: object
      properties:
        Key:
          type: string
          description: 'A tag key. The tag key length is from 1 to 128 Unicode characters in UTF-8. You can use letters and numbers representable in UTF-8, and the following characters: + - = . _ : / @. Tag keys are case-sensitive and must be unique per resource.'
        Value:
          type: string
          description: '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.'
    SessionStatistics:
      type: object
      properties:
        DpuExecutionInMillis:
          type: integer
          description: The data processing unit execution time for a session in milliseconds.
    Classification:
      type: object
      properties:
        Name:
          type: string
          description: The name of the configuration classification.
        Properties:
          type: object
          additionalProperties:
            type: string
          description: A set of properties specified within a configuration classification.
    EngineVersion:
      type: object
      properties:
        SelectedEngineVersion:
          type: string
          description: The engine version requested by the user. Possible values are determined by the output of ListEngineVersions, including AUTO. The default is AUTO.
        EffectiveEngineVersion:
          type: string
          description: 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.
    SessionSummary:
      type: object
      properties:
        SessionId:
          type: string
          description: The session ID.
        Description:
          type: string
          description: The session description.
        EngineVersion:
          $ref: '#/components/schemas/EngineVersion'
        NotebookVersion:
          type: string
          description: The notebook version.
        Status:
          $ref: '#/components/schemas/SessionStatus'
    EncryptionConfiguration:
      type: object
      properties:
        EncryptionOption:
          type: string
          enum:
          - SSE_S3
          - SSE_KMS
          - CSE_KMS
          description: Indicates whether Amazon S3 server-side encryption with Amazon S3-managed keys (SSE_S3), server-side encryption with KMS-managed keys (SSE_KMS), or client-side encryption with KMS-managed keys (CSE_KMS) is used. If a query runs in a workgroup and the workgroup overrides client-side settings, then the workgroup's setting for encryption is used. It specifies whether query results must be encrypted, for all queries that run in this workgroup.
        KmsKey:
          type: string
          description: For SSE_KMS and CSE_KMS, this is the KMS key ARN or ID.
      required:
      - EncryptionOption
    ListSessionsRequest:
      type: object
      properties:
        WorkGroup:
          type: string
          description: The workgroup to which the session belongs.
        StateFilter:
          type: string
          enum:
          - CREATING
          - CREATED
          - IDLE
          - BUSY
          - TERMINATING
          - TERMINATED
          - DEGRADED
          - FAILED
          description: 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.
        MaxResults:
          type: integer
          description: The maximum number of sessions to return.
        NextToken:
          type: string
          description: 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.
      required:
      - WorkGroup
    MonitoringConfiguration:
      type: object
      properties:
        CloudWatchLoggingConfiguration:
          $ref: '#/components/schemas/CloudWatchLoggingConfiguration'
        ManagedLoggingConfiguration:
          $ref: '#/components/schemas/ManagedLoggingConfiguration'
        S3LoggingConfiguration:
          $ref: '#/components/schemas/S3LoggingConfiguration'
    GetSessionRequest:
      type: object
      properties:
        SessionId:
          type: string
          description: The session ID.
      required:
      - SessionId
    ManagedLoggingConfiguration:
      type: object
      properties:
        Enabled:
          type: boolean
          description: Enables mamanged log persistence.
        KmsKey:
          type: string
          description: The KMS key ARN to encrypt the logs stored in managed log persistence.
      required:
      - Enabled
    EngineConfiguration:
      type: object
      properties:
        CoordinatorDpuSize:
          type: integer
          description: 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. The default is 1.
        MaxConcurrentDpus:
          type: integer
          description: The maximum number of DPUs that can run concurrently.
        DefaultExecutorDpuSize:
          type: integer
          description: 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. The default is 1.
        AdditionalConfigs:
          type: object
          additionalProperties:
            type: string
          description: Contains additional notebook engine MAP parameter mappings in the form of key-value pairs. To specify an Athena notebook that the Jupyter server will download and serve, specify a value for the StartSessionRequest$NotebookVersion field, and then add a key named NotebookId to AdditionalConfigs that has the value of the Athena notebook ID.
        SparkProperties:
          type: object
          additionalProperties:
            type: string
          description: Specifies custom jar files and Spark properties for use cases like cluster encryption, table formats, and general Spark tuning.
        Classifications:
          type: array
          items:
            $ref: '#/components/schemas/Classification'
          description: The configuration classifications that can be specified for the engine.
    CloudWatchLoggingConfiguration:
      type: object
      properties:
        Enabled:
          type: boolean
          description: Enables CloudWatch logging.
        LogGroup:
          type: string
          description: The name of the log group in Amazon CloudWatch Logs where you want to publish your logs.
        LogStreamNamePrefix:
          type: string
          description: Prefix for the CloudWatch log stream name.
        LogTypes:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: The types of logs that you want to publish to CloudWatch.
      required:
      - Enabled
    S3LoggingConfiguration:
      type: object
      properties:
        Enabled:
          type: boolean
          description: Enables S3 log delivery.
        KmsKey:
          type: string
          description: The KMS key ARN to encrypt the logs published to the given Amazon S3 destination.
        LogLocation:
          type: string
          description: The Amazon S3 destination URI for log publishing.
      required:
      - Enabled
    StartSessionResponse:
      type: object
      properties:
        SessionId:
          type: string
          description: The session ID.
        State:
          type: string
          enum:
          - CREATING
          - CREATED
          - IDLE
          - BUSY
          - TERMINATING
          - TERMINATED
          - DEGRADED
          - FAILED
          description: 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.
    StartSessionRequest:
      type: object
      properties:
        Description:
          type: string
          description: The session description.
        WorkGroup:
          type: string
          description: The workgroup to which the session belongs.
        EngineConfiguration:
          $ref: '#/components/schemas/EngineConfiguration'
        ExecutionRole:
          type: string
          description: The ARN of the execution role used to access user resources for Spark sessions and Identity Center enabled workgroups. This property applies only to Spark enabled workgroups and Identity Center enabled workgroups.
        MonitoringConfiguration:
          $ref: '#/components/schemas/MonitoringConfiguration'
        NotebookVersion:
          type: string
          description: The notebook version. This value is supplied automatically for notebook sessions in the Athena console and is not required for programmatic session access. The only valid notebook version is Athena notebook version 1. If you specify a value for NotebookVersion, you must also specify a value for NotebookId. See EngineConfiguration$AdditionalConfigs.
        SessionIdleTimeoutInMinutes:
          type: integer
          description: The idle timeout in minutes for the session.
        ClientRequestToken:
          type: string
          description: 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. 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.
        Tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
          description: A list of comma separated tags to add to the session that is created.
        CopyWorkGroupTags:
          type: boolean
          description: Copies the tags from the Workgroup to the Session when.
      required:
      - WorkGroup
      - EngineConfiguration
    GetSessionResponse:
      type: object
      properties:
        SessionId:
          type: string
          description: The session ID.
        Description:
          type: string
          description: The session description.
        WorkGroup:
          type: string
          description: The workgroup to which the session belongs.
        EngineVersion:
          type: string
          description: 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:
          $ref: '#/components/schemas/EngineConfiguration'
        NotebookVersion:
          type: string
          description: The notebook version.
        MonitoringConfiguration:
          $ref: '#/components/schemas/MonitoringConfiguration'
        SessionConfiguration:
          $ref: '#/components/schemas/SessionConfiguration'
        Status:
          $ref: '#/components/schemas/SessionStatus'
        Statistics:
          $ref: '#/components/schemas/SessionStatistics'
    InvalidRequestException:
      type: object
      properties:
        AthenaErrorCode:
          type: string
        Message:
          type: string
    InternalServerException:
      type: object
      properties:
        Message:
          type: string
    SessionStatus:
      type: object
      properties:
        StartDateTime:
          type: string
          format: date-time
          description: The date and time that the session started.
        LastModifiedDateTime:
          type: string
          format: date-time
          description: The most recent date and time that the session was modified.
        EndDateTime:
          type: string
          format: date-time
          description: The date and time that the session ended.
        IdleSinceDateTime:
          type: string
          format: date-time
          description: The date and time starting at which the session became idle. Can be empty if the session is not currently idle.
        State:
          type: string
          enum:
          - CREATING
          - CREATED
          - IDLE
          - BUSY
          - TERMINATING
          - TERMINATED
          - DEGRADED
          - FAILED
          description: 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:
          type: string
          description: The reason for the session state change (for example, canceled because the session was terminated).
    ListSessionsResponse:
      type: object
      properties:
        NextToken:
          type: string
          description: 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:
          type: array
          items:
            $ref: '#/components/schemas/SessionSummary'
          description: A list of sessions.
  securitySchemes:
    sigv4:
      type: apiKey
      in: header
      name: Authorization
      description: AWS Signature Version 4. The Authorization header carries an AWS4-HMAC-SHA256 signature over the canonical request, with X-Amz-Date (and X-Amz-Security-Token for temporary credentials). Not a bearer token.
      x-aws-sigv4:
        signingName: athena
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/582e55931c45b944739742a2c1620b6026dd2d13/models/athena/service/2017-05-18/athena-2017-05-18.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)