openapi: 3.0.1
info:
  title: ByteHouse Public API
  description: >-
    The public ByteHouse API is organized around REST. Our API has predictable
    resource-oriented URLs, accepts JSON-encoded request bodies, returns
    JSON-encoded responses, and uses standard HTTP response codes,
    authentication, and verbs.
  version: 1.0.0
  x-logo:
    url: "./docs/static/bytehouse.png"
    backgroundColor: "#FFFFFF"
    altText: "Bytehouse"
servers:
  # Replace by environment variable to support each environment. Ignore linter.
  - url: https://bytemart-cn-shanghai.bytehouse.volcbiz.com
# path summary used for TOP API action and name
# valid: [0-9a-zA-Z-_] and length 3-30
# path description: NOVOLCANO used to ignore conversion for path
paths:
  /v1/metadata-subscription:
    summary: Pub-Metadata
    post:
      summary: Make metadata subscription
      parameters:
        - $ref: '#/components/parameters/subscribeAccountIDHeader'
        - $ref: '#/components/parameters/userIDHeader'
        - $ref: '#/components/parameters/bytehouseTokenHeader'
      responses:
        200:
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponseWithoutError'
          description: Make metadata subscription successfully
        403:
          description: Authentication Failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/AuthenticationErrorResponse'
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
      tags:
        - Metadata

  /v1/metadata-unsubscription:
    summary: Unsub-Metadata
    post:
      summary: Make metadata unsubscription
      parameters:
        - $ref: '#/components/parameters/subscribeAccountIDHeader'
        - $ref: '#/components/parameters/userIDHeader'
        - $ref: '#/components/parameters/bytehouseTokenHeader'
      responses:
        200:
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponseWithoutError'
          description: Make metadata unsubscription successfully
        403:
          description: Authentication Failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/AuthenticationErrorResponse'
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
      tags:
        - Metadata


  /v1/databases:
    summary: Pub-Database
    get:
      summary: List databases
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
        - $ref: '#/components/parameters/filterQuery'
        - $ref: '#/components/parameters/listOffset'
        - $ref: '#/components/parameters/listLimit'
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ListDatabasesResponse'
                  - $ref: '#/components/schemas/BaseOffsetListResponse'

        403:
          description: Authentication Failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/AuthenticationErrorResponse'

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
      tags:
        - Databases
    post:
      summary: Create a database
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDatabaseRequest'
      responses:
        201:
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/CreateDatabasesResponse'
          headers:
            Location:
              description: Newly created database URI
              schema:
                example: /databases/some_name
                type: string
          description: Created Database successfully

        403:
          description: Authentication Failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/AuthenticationErrorResponse'

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
      tags:
        - Databases

  /v1/databases/{db_name}:
    summary: Pub-DatabaseDetail
    delete:
      summary: Delete a database
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
        - $ref: '#/components/parameters/databaseNamePath'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponseWithoutMessage'

        403:
          description: Authentication Failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/AuthenticationErrorResponse'

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
      tags:
        - Databases
    get:
      summary: Retrieve a database
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
        - $ref: '#/components/parameters/databaseNamePath'
      responses:
        200:
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/GetDatabaseResponse'
          description: Success

        403:
          description: Authentication Failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/AuthenticationErrorResponse'
        404:
          description: Database not found

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
      tags:
        - Databases

  # Alter Database API is NOT ready yet

  #    put:
  #      summary: Alter database description
  #      parameters:
  #        - $ref: '#/components/parameters/activeRoleHeader'
  #        - $ref: '#/components/parameters/databaseNamePath'
  #      requestBody:
  #        content:
  #          application/json:
  #            schema:
  #              $ref: '#/components/schemas/AlterDatabaseRequest'
  #      responses:
  #        200:
  #          content:
  #            application/json:
  #              schema:
  #                allOf:
  #                  - $ref: '#/components/schemas/BaseResponseWithoutMessage'
  #          description: Success
  #      tags:
  #        - Databases

  /v1/databases/{db_name}/tables:
    summary: Pub-DatabaseTables
    get:
      summary: List tables for a specified database
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
        - $ref: '#/components/parameters/databaseNamePath'
        - $ref: '#/components/parameters/filterQuery'
        - $ref: '#/components/parameters/listOffset'
        - $ref: '#/components/parameters/listLimit'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ListTablesResponse'
                  - $ref: '#/components/schemas/BaseOffsetListResponse'

        403:
          description: Authentication Failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/AuthenticationErrorResponse'

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
      tags:
        - Databases
    post:
      summary: Create a table for a specified database
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
        - $ref: '#/components/parameters/databaseNamePath'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTableRequest'
      responses:
        201:
          description: Created table successfully
          headers:
            Location:
              description: Newly created table URI
              schema:
                example: /databases/some_db/tables/some_table
                type: string
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/CreateTableResponse'

        403:
          description: Authentication Failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/AuthenticationErrorResponse'

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
      tags:
        - Databases

  /v1/databases/{db_name}/tables-views:
    summary: Pub-DatabaseTablesViews
    get:
      summary: List tables, views for a specified database
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
        - $ref: '#/components/parameters/databaseNamePath'
        - $ref: '#/components/parameters/filterQuery'
        - $ref: '#/components/parameters/listOffset'
        - $ref: '#/components/parameters/listLimit'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ListTablesViewsResponse'
                  - $ref: '#/components/schemas/BaseOffsetListResponse'

        403:
          description: Authentication Failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/AuthenticationErrorResponse'

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
      tags:
        - Databases

  /v1/databases/{db_name}/materialized-mysql-sync-status:
    summary: Pub-MySQLDatabaseSyncStatus
    get:
      summary: Get sync status for a materialized mysql database and all its underlying tables
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
        - $ref: '#/components/parameters/databaseNamePath'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/GetMaterializedMySQLDatabaseSyncStatusResponse'

        403:
          description: Authentication Failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/AuthenticationErrorResponse'

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
      tags:
        - Databases

  /v1/databases/{db_name}/tables/{table_name}:
    summary: Pub-DatabaseTablesDetail
    delete:
      summary: Delete a table
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
        - $ref: '#/components/parameters/databaseNamePath'
        - $ref: '#/components/parameters/tableNamePath'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponseWithoutMessage'

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
      tags:
        - Databases
    put:
      summary: Update a table
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
        - $ref: '#/components/parameters/databaseNamePath'
        - $ref: '#/components/parameters/tableNamePath'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlterTableRequest'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponseWithoutMessage'

        403:
          description: Authentication Failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/AuthenticationErrorResponse'

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
      tags:
        - Databases
    get:
      summary: Retrieve a table
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
        - $ref: '#/components/parameters/databaseNamePath'
        - $ref: '#/components/parameters/tableNamePath'
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/GetTableDetailsResponse'

        403:
          description: Authentication Failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/AuthenticationErrorResponse'

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
      tags:
        - Databases

  /v1/databases/{db_name}/tables/{table_name}/partitions:
    summary: Pub-DatabaseTablePartitions
    get:
      summary: Retrieve the partitions for a specified table
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
        - $ref: '#/components/parameters/listLimit'
        - $ref: '#/components/parameters/listOffset'
        - $ref: '#/components/parameters/filterQuery'
        - $ref: '#/components/parameters/databaseNamePath'
        - $ref: '#/components/parameters/tableNamePath'
      responses:
        200:
          content:
            application/json:
              schema:
                allOf:
                  - properties:
                      data:
                        $ref: '#/components/schemas/ListPartitionStatsResponse'
                    type: object
                  - $ref: '#/components/schemas/BaseOffsetListResponse'
          description: Success
        400:
          description: Bad request

        403:
          description: Authentication Failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/AuthenticationErrorResponse'
        404:
          description: Database or table not found

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
      tags:
        - Databases
    delete:
      summary: Delete partitions for a specified table
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
        - $ref: '#/components/parameters/databaseNamePath'
        - $ref: '#/components/parameters/tableNamePath'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartitionNames'
      responses:
        200:
          content:
            application/json:
              schema:
                example: {"data": "Success"}
          description: Success
      tags:
        - Databases

  # TODO: enable once verified end to end
  #  /v1/databases/{db_name}/tables/{table_name}/column-partitions:
  #    summary: TableColumnPartitions
  #    get:
  #      summary: Retrieve the partitions for a specified table
  #      parameters:
  #        - $ref: '#/components/parameters/activeRoleHeader'
  #        - $ref: '#/components/parameters/columnQuery'
  #        - $ref: '#/components/parameters/partitionQuery'
  #        - $ref: '#/components/parameters/databaseNamePath'
  #        - $ref: '#/components/parameters/tableNamePath'
  #      responses:
  #        200:
  #          description: Success
  #          content:
  #            application/json:
  #              schema:
  #                $ref: '#/components/schemas/ListColumnPartitionResponse'
  #        400:
  #          description: Bad Request
  #          content:
  #            application/json:
  #              schema:
  #                $ref: '#/components/schemas/BadRequestErrorResponse'
  #        403:
  #          description: Authentication Failed
  #          content:
  #            application/json:
  #              schema:
  #                $ref: '#/components/schemas/AuthenticationErrorResponse'
  #        404:
  #          description: Database or table not found
  #          content:
  #            application/json:
  #              schema:
  #                $ref: '#/components/schemas/ResourceNotFoundErrorResponse'
  #        500:
  #          description: Internal server error
  #          content:
  #            application/json:
  #              schema:
  #                $ref: '#/components/schemas/BaseErrorResponse'
  #      tags:
  #        - Databases

  /v1/databases/{db_name}/tables/{table_name}/min-max-partitions:
    summary: Pub-DatabaseTableLSPartName
    get:
      summary: >-
        Retrieves the min and max partition names in alphabet-numerical order for a specified table
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
        - $ref: '#/components/parameters/databaseNamePath'
        - $ref: '#/components/parameters/tableNamePath'
      responses:
        200:
          content:
            application/json:
              schema:
                allOf:
                  - properties:
                      data:
                        $ref: '#/components/schemas/GetMinMaxPartitionResponse'
                    type: object
          description: Success
        400:
          description: Bad request

        403:
          description: Authentication Failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/AuthenticationErrorResponse'
        404:
          description: Database or table not found

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
      tags:
        - Databases

  /v1/databases/{db_name}/materialized-views:
    summary: Pub-DatabaseMaterializedView
    get:
      summary: List materialized views for a specified database
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
        - $ref: '#/components/parameters/databaseNamePath'
        - $ref: '#/components/parameters/filterQuery'
        - $ref: '#/components/parameters/listOffset'
        - $ref: '#/components/parameters/listLimit'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ListMaterializedViewsResponse'
                  - $ref: '#/components/schemas/BaseOffsetListResponse'

        403:
          description: Authentication Failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/AuthenticationErrorResponse'

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
      tags:
        - Databases

  /v1/databases/{db_name}/materialized-views/{mv_name}:
    summary: Pub-DatabaseMvDetail
    get:
      summary: Retrieve a materialized view
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
        - $ref: '#/components/parameters/databaseNamePath'
        - $ref: '#/components/parameters/mvNamePath'
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/GetMaterializedViewDetailsResponse'

        403:
          description: Authentication Failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/AuthenticationErrorResponse'

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
      tags:
        - Databases

  /v1/databases/{db_name}/dictionaries/{dict_name}:
    summary: Pub-DatabaseDictionaryDetail
    delete:
      summary: Delete a dictionary
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
        - $ref: '#/components/parameters/databaseNamePath'
        - $ref: '#/components/parameters/dictionaryNamePath'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponseWithoutMessage'

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
      tags:
        - Databases

  /v1/cluster-status/{db_name}/{table_name}:
    summary: Pub-GetClusterStatusOfTable
    parameters:
      - $ref: '#/components/parameters/databaseNamePath'
      - $ref: '#/components/parameters/tableNamePath'
    get:
      summary: Retrieve cluster status of a particular table to provision its bucketing progress
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/GetClusterStatusOfTableResponse'
                  - $ref: '#/components/schemas/BaseResponse'
        403:
          description: Authentication Failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/AuthenticationErrorResponse'

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
      tags:
        - Cluster Status


  #  Query History API is NOT ready yet

  #  /v1/sql/queries:
  #    summary: Pub-Queries (Not Ready)
  #    get:
  #      summary: List query history records or List running query records
  #      parameters:
  #        - $ref: '#/components/parameters/activeRoleHeader'
  #        - $ref: '#/components/parameters/listCursor'
  #        - $ref: '#/components/parameters/listLimit'
  #        - $ref: '#/components/parameters/runningQuery'
  #      responses:
  #        200:
  #          content:
  #            application/json:
  #              schema:
  #                allOf:
  #                  - properties:
  #                      data:
  #                        $ref: '#/components/schemas/ListCombinedQueryResponse'
  #                    type: object
  #                  - $ref: '#/components/schemas/BaseListResponse'
  #          description: Success
  #        500:
  #          description: Internal Server Error
  #      tags:
  #        - Queries

  #  Query History API is NOT ready yet

  #  /v1/sql/queries/{id}/history:
  #    summary: Pub-QueryDetail (Not Ready)
  #    get:
  #      summary: Get a query history record given query id
  #      parameters:
  #        - $ref: '#/components/parameters/resourceIDPath'
  #        - $ref: '#/components/parameters/activeRoleHeader'
  #      responses:
  #        200:
  #          content:
  #            application/json:
  #              schema:
  #                allOf:
  #                  - properties:
  #                      data:
  #                        $ref: '#/components/schemas/QueryRecord'
  #                    type: object
  #                  - $ref: '#/components/schemas/BaseResponseWithoutMessage'
  #          description: Success
  #        404:
  #          description: Resource not found
  #        500:
  #          description: Internal server error
  #      tags:
  #        - Queries

  #  Query Profile API is NOT ready yet

  #  /v1/sql/queries/{id}/profile:
  #    summary: Pub-QueryProfile
  #    get:
  #      operationId: getQueryProfile
  #      parameters:
  #        - $ref: '#/components/parameters/resourceIDPath'
  #        - $ref: '#/components/parameters/activeRoleHeader'
  #      responses:
  #        200:
  #          content:
  #            application/json:
  #              schema:
  #                allOf:
  #                  - properties:
  #                      data:
  #                        $ref: '#/components/schemas/QueryProfile'
  #                    type: object
  #                  - $ref: '#/components/schemas/BaseResponseWithoutMessage'
  #          description: Success
  #        404:
  #          description: Resource not found
  #        500:
  #          description: Internal server error
  #      summary: Get a query profile record given query id
  #      tags:
  #        - Queries
  /:
    summary: Clickhouse-HTTPQuery
    servers:
      # Replace by environment variable to support each environment. Ignore linter.
      - url: https://<ClickhouseHTTP>:8123
    get:
      summary: >-
        Clickhouse HTTP Interface with a different hostname
      tags:
        - Queries-V2
      parameters:
        - $ref: '#/components/parameters/clickhouseUserHeader'
        - $ref: '#/components/parameters/clickhousePasswordHeader'
        - $ref: '#/components/parameters/virtualWarehouseQuery'
        - $ref: '#/components/parameters/queryParams'
        - $ref: '#/components/parameters/userParams'
        - $ref: '#/components/parameters/passwordParams'
      responses:
        200:
          content:
            text/plain:
              schema:
                type: string
                example: "responses follow https://clickhouse.com/docs/en/interfaces/http and changes depending on format"
          description: response

    post:
      summary: >-
        Clickhouse HTTP Interface with a different hostname
      tags:
        - Queries-V2
      parameters:
        - $ref: '#/components/parameters/clickhouseUserHeader'
        - $ref: '#/components/parameters/clickhousePasswordHeader'
        - $ref: '#/components/parameters/virtualWarehouseQuery'
        - $ref: '#/components/parameters/queryParams'
        - $ref: '#/components/parameters/userParams'
        - $ref: '#/components/parameters/passwordParams'
      responses:
        200:
          content:
            text/plain:
              schema:
                type: string
                example: "responses follow https://clickhouse.com/docs/en/interfaces/http and changes depending on format"
          description: response
        403:
          description: Authentication Failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/AuthenticationErrorResponse'

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'

  /v2/sql/sync:
    summary: Pub-QueriesSyncV2
    servers:
      # Replace by environment variable to support each environment. Ignore linter.
      - url: https://<ClickhouseHTTP>:8123
    post:
      summary: >-
        Submit a synchronous query with a different hostname limited to first 1000 rows.
      tags:
        - Queries-V2
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitAsyncQueryRequest'
      responses:
        200:
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SQLQueryResponse'
          description: response
        403:
          description: Authentication Failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/AuthenticationErrorResponse'

  /v2/sql/async:
    summary: Pub-QueriesAsyncV2
    servers:
      # Replace by environment variable to support each environment. Ignore linter.
      - url: https://<ClickhouseHTTP>:8123
    post:
      summary: >-
        Submit a asynchronous query with a different hostname
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitAsyncQueryRequest'
      tags:
        - Queries-V2
      responses:
        200:
          content:
            application/json:
              schema:
                allOf:
                  - properties:
                      data:
                        $ref: '#/components/schemas/SubmitLongRunningQueryResponseV2'
                    type: object
          description: success

  /v2/sql/async/{id}/status:
    summary: Pub-AsyncQueryStatusV2
    servers:
      # Replace by environment variable to support each environment. Ignore linter.
      - url: https://<ClickhouseHTTP>:8123
    get:
      summary: Retrieve the status for a specified asynchronous query
      tags:
        - Queries-V2
      parameters:
        - $ref: '#/components/parameters/resourceIDPath'
        - $ref: '#/components/parameters/activeRoleHeader'
      responses:
        200:
          content:
            application/json:
              schema:
                allOf:
                  - properties:
                      data:
                        $ref: '#/components/schemas/CheckLongRunningQueryStatusResponse'
                    type: object
          description: Success

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'


  /v2/sql/async/{id}/results:
    summary: Pub-AsyncQueryResultV2
    servers:
      # Replace by environment variable to support each environment. Ignore linter.
      - url: https://<ClickhouseHTTP>:8123
    get:
      summary: Retrieve the results for a specified asynchronous query
      tags:
        - Queries-V2
      parameters:
        - $ref: '#/components/parameters/resourceIDPath'
        - $ref: '#/components/parameters/activeRoleHeader'
      responses:
        200:
          content:
            application/json:
              schema:
                allOf:
                  - properties:
                      data:
                        $ref: '#/components/schemas/SQLQueryResponse'
                    type: object
          description: Success

        403:
          description: Authentication Failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/AuthenticationErrorResponse'

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'

  /v1/sql/sync:
    summary: Pub-QueriesSync
    post:
      summary: Submit a synchronous query
      deprecated: true
      parameters:
        - $ref: '#/components/parameters/querySessionHeader'
        - $ref: '#/components/parameters/activeRoleHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitSyncQueryRequest'
      responses:
        200:
          content:
            application/json:
              schema:
                allOf:
                  - properties:
                      data:
                        $ref: '#/components/schemas/SubmitQueryResponse'
                    type: object
          description: success
          headers:
            X-QuerySession-ID:
              $ref: '#/components/headers/querySessionHeader'

        403:
          description: Authentication Failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/AuthenticationErrorResponse'

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
      tags:
        - Queries

    delete:
      summary: Abort a synchronous query
      deprecated: true
      parameters:
        - $ref: '#/components/parameters/querySessionHeader'
        - $ref: '#/components/parameters/activeRoleHeader'
      responses:
        200:
          content:
            application/json:
              schema:
                allOf:
                  - properties:
                      data:
                        $ref: '#/components/schemas/KillQueryResponse'
                    type: object
          description: Success

        403:
          description: Authentication Failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/AuthenticationErrorResponse'

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
      tags:
        - Queries

  /v1/sql/sync/{id}:
    summary: Pub-SyncQueryDetail
    delete:
      deprecated: true
      summary: Kill a sync query
      parameters:
        - $ref: '#/components/parameters/resourceIDPath'
        - $ref: '#/components/parameters/activeRoleHeader'
      responses:
        200:
          content:
            application/json:
              schema:
                allOf:
                  - properties:
                      data:
                        $ref: '#/components/schemas/KillQueryResponse'
                    type: object
          description: Success

        403:
          description: Authentication Failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/AuthenticationErrorResponse'

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
      tags:
        - Queries

  /v1/sql/async:
    summary: Pub-AsyncQuery
    #    get:
    #      summary: get recent queries
    #      parameters:
    #        - $ref: '#/components/parameters/activeRoleHeader'
    #        - $ref: '#/components/parameters/listOffset'
    #        - $ref: '#/components/parameters/listLimit'
    #      responses:
    #        200:
    #          content:
    #            application/json:
    #              schema:
    #                allOf:
    #                  - properties:
    #                      data:
    #                        $ref: '#/components/schemas/GetRecentQueriesRecord'
    #                    type: object
    #                  - $ref: '#/components/schemas/BaseOffsetListResponse'
    #          description: Success
    #
    #        500:
    #          description: Internal server error
    #          content:
    #            application/json:
    #              schema:
    #                allOf:
    #                  - $ref: '#/components/schemas/BaseErrorResponse'
    #      tags:
    #        - Queries
    post:
      summary: Submit an asynchronous query
      deprecated: true
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitAsyncQueryRequest'
      responses:
        200:
          content:
            application/json:
              schema:
                allOf:
                  - properties:
                      data:
                        $ref: '#/components/schemas/SubmitLongRunningQueryResponse'
                    type: object
          description: Success

        403:
          description: Authentication Failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/AuthenticationErrorResponse'

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
      tags:
        - Queries

  /v1/sql/async/{id}:
    summary: Pub-AsyncQueryDetail
    delete:
      deprecated: true
      summary: Kill a query
      parameters:
        - $ref: '#/components/parameters/resourceIDPath'
        - $ref: '#/components/parameters/activeRoleHeader'
      responses:
        200:
          content:
            application/json:
              schema:
                allOf:
                  - properties:
                      data:
                        $ref: '#/components/schemas/KillQueryResponse'
                    type: object
          description: Success

        403:
          description: Authentication Failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/AuthenticationErrorResponse'

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
      tags:
        - Queries

  /v1/sql/async/{id}/status:
    summary: Pub-AsyncQueryStatus
    get:
      summary: Retrieve the status for a specified asynchronous query
      deprecated: true
      parameters:
        - $ref: '#/components/parameters/resourceIDPath'
        - $ref: '#/components/parameters/activeRoleHeader'
      responses:
        200:
          content:
            application/json:
              schema:
                allOf:
                  - properties:
                      data:
                        $ref: '#/components/schemas/CheckLongRunningQueryStatusResponse'
                    type: object
          description: Success

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
      tags:
        - Queries

  /v1/sql/async/{id}/results:
    summary: Pub-AsyncQueryResult
    get:
      summary: Retrieve the results for a specified asynchronous query
      deprecated: true
      parameters:
        - $ref: '#/components/parameters/resourceIDPath'
        - $ref: '#/components/parameters/activeRoleHeader'
        - $ref: '#/components/parameters/maxRowsReturnQuery'
      responses:
        200:
          content:
            application/json:
              schema:
                allOf:
                  - properties:
                      data:
                        $ref: '#/components/schemas/SubmitQueryResponse'
                    type: object
          description: Success

        403:
          description: Authentication Failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/AuthenticationErrorResponse'

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
      tags:
        - Queries

  /v1/sql/validate:
    summary: Pub-SqValidate
    post:
      summary: check tables, views and materialized views queried for query
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryRequest'
      responses:
        200:
          content:
            application/json:
              schema:
                allOf:
                  - properties:
                      data:
                        $ref: '#/components/schemas/CheckTablesForQueryResponse'
                    type: object
          description: Success

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
      tags:
        - Queries

  /v1/sql/dialects:
    summary: Pub-DialectTypes
    get:
      summary: Retrieve dialects available for a user
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
      responses:
        200:
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/GetDialectTypesResponse'
          description: Success

        403:
          description: Authentication Failed
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/AuthenticationErrorResponse'

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
      tags:
        - Queries

  /v1/documentation/functions/list:
    summary: ListDocumentationFunction
    post:
      tags:
        - Documentation
      summary: List all sql functions available to Bytehouse
      description: List all sql functions available to Bytehouse
      parameters:
        - $ref: "#/components/parameters/activeRoleHeader"
      responses:
        '200':
          description: Success.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/ListDocumentationFunctionResponse'
        '400':
          description: Request parameters are incorrect.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'
        '403':
          description: Operator does not have privilege to perform the operation.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'


  ##########################################
  #           IAM API Definitions          #
  ##########################################

  # API Keys

  /v1/iam/api-key:
    summary: Pub-APIKey
    post:
      summary: Create API key
      description: |-
        Create a new API key for current user. The number of API key is limited to 2 per user.
        Use API key in header Authorization: Bearer <api-key> for authentication.
      tags:
        - Authentication
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateAPIKeyRequest"
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateAPIKeyResponse"
          description: Success
        '400':
          description: Request parameters are incorrect.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'
    get:
      summary: List user API keys
      description: Listing all of the current user's API key(s).
      tags:
        - Authentication
      responses:
        200:
          description: Response containing the list of user's API keys.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListAPIKeysResponse"

  /v1/iam/api-key/{api_key_id}:
    summary: Pub-APIKeyDetail
    parameters:
      - $ref: '#/components/parameters/apiKeyIDParam'
    delete:
      summary: Delete API key
      description: Delete self-owned API key.
      tags:
        - Authentication
      responses:
        '200':
          description: Success.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseResponseWithoutError'
        '403':
          description: Operator does not have privilege to perform the operation.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'
        '404':
          description: Resource not found.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'

  /v1/iam/api-key/{api_key_id}/status:
    summary: Pub-APIKeyStatus
    parameters:
      - $ref: '#/components/parameters/apiKeyIDParam'
    put:
      summary: Enable or disable API Key
      description: Update the status of the API key.
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
      tags:
        - Authentication
      requestBody:
        content:
          application/json:
            schema:
              description: Request body to update API key status.
              properties:
                status:
                  $ref: '#/components/schemas/ApiKeyStatus'
              type: object
      responses:
        '200':
          description: Success.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseResponseWithoutError'
        '403':
          description: Operator does not have privilege to perform the operation.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'
        '404':
          description: Resource not found.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'

  /v1/iam/api-key/{api_key_id}/expiry:
    summary: Pub-APIKeyExpiry
    parameters:
      - $ref: '#/components/parameters/apiKeyIDParam'
    put:
      summary: Extend API key expiry time
      description: Extends the expiry date of an API key, this is a no-op when given a non-expiring API key.
      tags:
        - Authentication
      requestBody:
        content:
          application/json:
            schema:
              description: Request body.
              properties:
                addExpiryInDays:
                  type: integer
                  description: Number of days to add on to the expiry.
                  example: 90
      responses:
        '200':
          description: Success.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseResponseWithoutError'
        '403':
          description: Operator does not have privilege to perform the operation.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'
        '404':
          description: Resource not found.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'

  # Privileges

  /v1/privileges/list-actions:
    summary: IAMListActions
    post:
      operationId: IAMListActions
      tags:
        - Authorization
      summary: List resource actions
      description: List the available action enums on given resources. Only the resource type matters.
      requestBody:
        content:
          application/json; charset=utf-8:
            schema:
              $ref: '#/components/schemas/IAMListActionsRequest'
        required: true
      responses:
        '200':
          description: Response containing list of privileges.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/IAMListActionsResponse'
        '400':
          description: Request parameters are incorrect.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'
  /v1/privileges/check:
    summary: IAMCheckPrivileges
    post:
      tags:
        - Authorization
      summary: Check privileges
      description: Check if operator is authorized to perform actions
      parameters:
        - $ref: "#/components/parameters/activeRoleHeader"
      requestBody:
        content:
          application/json; charset=utf-8:
            schema:
              $ref: '#/components/schemas/CheckPrivilegesRequest'
        required: true
      responses:
        '200':
          description: Request successful.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/CheckPrivilegesResponse'
        '400':
          description: Request parameters or authorization info is incorrect.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'
  /v1/privileges/grant:
    summary: IAMGrantPrivilege
    post:
      tags:
        - Authorization
      summary: Grant privileges
      description: Grant privileges over a resource to a principal. The operator must have grant capabilities.
      parameters:
        - $ref: "#/components/parameters/activeRoleHeader"
      requestBody:
        content:
          application/json; charset=utf-8:
            schema:
              $ref: '#/components/schemas/GrantPrivilegeRequest'
        required: true
      responses:
        '200':
          description: Success.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseResponseWithoutError'
        '400':
          description: Request parameters are incorrect.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'
        '403':
          description: Operator does not have privilege to perform the operation.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'
  /v1/privileges/revoke:
    summary: IAMRevokePrivilege
    post:
      tags:
        - Authorization
      summary: Revoke privileges
      description: Revoke privileges over a resource from a principal.
      parameters:
        - $ref: "#/components/parameters/activeRoleHeader"
      requestBody:
        content:
          application/json; charset=utf-8:
            schema:
              $ref: '#/components/schemas/RevokePrivilegeRequest'
        required: true
      responses:
        '200':
          description: Success.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseResponseWithoutError'
        '400':
          description: Request parameters are incorrect.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'
        '403':
          description: Operator does not have privilege to perform the operation.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'
  /v1/privileges/list:
    summary: IAMListPrivileges
    post:
      tags:
        - Authorization
      summary: List principal privileges
      description: List privileges granted to a principal.
      parameters:
        - $ref: "#/components/parameters/activeRoleHeader"
      requestBody:
        content:
          application/json; charset=utf-8:
            schema:
              $ref: '#/components/schemas/ListPrivilegesRequest'
        required: true
      responses:
        '200':
          description: Response containing list of privileges.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/ListPrivilegesResponse'
        '400':
          description: Request parameters are incorrect.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'
  /v1/privileges/list-principals:
    summary: IAMListPrincipals
    post:
      tags:
        - Authorization
      summary: List privileges grouped by (principal,resource)
      description: List privileges grouped by (principal,resource).
      parameters:
        - $ref: "#/components/parameters/activeRoleHeader"
      requestBody:
        content:
          application/json; charset=utf-8:
            schema:
              $ref: '#/components/schemas/ListPrincipalsRequest'
        required: true
      responses:
        '200':
          description: Response containing list of privileges.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/ListPricipalsResponse'
        '400':
          description: Request parameters are incorrect.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'
  /v1/privileges/list-privileges-principals:
    summary: IAMListPrivilegesPrincipals
    post:
      tags:
        - Authorization
      summary: List privileges grouped by (resource,principal)
      description: List privileges grouped by (resource,principal).
      parameters:
        - $ref: "#/components/parameters/activeRoleHeader"
      requestBody:
        content:
          application/json; charset=utf-8:
            schema:
              $ref: '#/components/schemas/ListPrivilegesPrincipalsRequest'
        required: true
      responses:
        '200':
          description: Response containing list of privileges.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/ListPrivilegesPrincipalsResponse'
        '400':
          description: Request parameters are incorrect.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'

  # Roles

  /v1/roles:
    summary: IAMListRoles
    get:
      tags:
        - Roles and Assignments
      summary: List all roles
      description: List all role names.
      parameters:
        - $ref: "#/components/parameters/activeRoleHeader"
      responses:
        '200':
          description: Success.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/ListRolesResponse'
        '400':
          description: Request parameters are incorrect.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'
        '403':
          description: Operator does not have privilege to perform the operation.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'

  /v1/roles/create:
    summary: IAMCreateRole
    post:
      tags:
        - Roles and Assignments
      summary: Create role
      description: Creates a new role, this will be a no-op operation if given a role that already exists.
      parameters:
        - $ref: "#/components/parameters/activeRoleHeader"
      requestBody:
        content:
          application/json; charset=utf-8:
            schema:
              $ref: '#/components/schemas/CreateRoleRequest'
        required: true
      responses:
        '200':
          description: Success.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseResponseWithoutError'
        '400':
          description: Request parameters are incorrect.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'
        '403':
          description: Operator does not have privilege to perform the operation.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'

  /v1/roles/delete:
    summary: IAMDeleteRole
    post:
      tags:
        - Roles and Assignments
      summary: Delete role
      description: Deletes an existing role.
      parameters:
        - $ref: "#/components/parameters/activeRoleHeader"
      requestBody:
        content:
          application/json; charset=utf-8:
            schema:
              $ref: '#/components/schemas/DeleteRoleRequest'
        required: true
      responses:
        '200':
          description: Success.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseResponseWithoutError'
        '400':
          description: Request parameters are incorrect.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'
        '403':
          description: Operator does not have privilege to perform the operation.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'
        '404':
          description: Resource not found.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'
  /v1/roles/get:
    summary: IAMGetRole
    post:
      tags:
        - Roles and Assignments
      summary: Get a role
      description: Get a role information.
      parameters:
        - $ref: "#/components/parameters/activeRoleHeader"
      requestBody:
        content:
          application/json; charset=utf-8:
            schema:
              $ref: '#/components/schemas/GetRoleRequest'
        required: true
      responses:
        '200':
          description: Success.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/GetRoleResponse'
        '400':
          description: Request parameters are incorrect.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'
        '403':
          description: Operator does not have privilege to perform the operation.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'
        '404':
          description: Resource not found.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'

  /v1/roles/assign:
    summary: IAMAssignRoleToUser
    post:
      tags:
        - Roles and Assignments
      summary: Assign role
      description: Assign a role to a user.
      parameters:
        - $ref: "#/components/parameters/activeRoleHeader"
      requestBody:
        content:
          application/json; charset=utf-8:
            schema:
              $ref: '#/components/schemas/AssignRoleToUserRequest'
        required: true
      responses:
        '200':
          description: Success.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseResponseWithoutError'
        '400':
          description: Request parameters are incorrect.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'
        '403':
          description: Operator does not have privilege to perform the operation.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'
        '404':
          description: Resource not found.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'

  /v1/roles/unassign:
    summary: IAMUnassignRoleFromUser
    post:
      tags:
        - Roles and Assignments
      summary: Unassign role
      description: Unassign a role from a user.
      parameters:
        - $ref: "#/components/parameters/activeRoleHeader"
      requestBody:
        content:
          application/json; charset=utf-8:
            schema:
              $ref: '#/components/schemas/UnassignRoleFromUserRequest'
        required: true
      responses:
        '200':
          description: Success.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseResponseWithoutError'
        '400':
          description: Request parameters are incorrect.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'
        '403':
          description: Operator does not have privilege to perform the operation.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'
        '404':
          description: Resource not found.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/BaseErrorResponse'

  /v1/roles/list-assignments:
    summary: IAMListRoleAssignments
    post:
      tags:
        - Roles and Assignments
      summary: List role assignments
      description: List existing role assignments.
      parameters:
        - $ref: "#/components/parameters/activeRoleHeader"
      requestBody:
        content:
          application/json; charset=utf-8:
            schema:
              $ref: '#/components/schemas/ListRoleAssignmentsRequest'
        required: true
      responses:
        '200':
          description: Success.
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/ListRoleAssignmentsResponse'

  ##########################################
  #       End of IAM API Definitions       #
  ##########################################

  /v1/usage-billing/storages:
    summary: Pub-UsageStorage
    get:
      summary: Retrieve the storage utilisation for a specified timeframe
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
        - $ref: '#/components/parameters/startTimeQuery'
        - $ref: '#/components/parameters/endTimeQuery'
        - $ref: '#/components/parameters/dbNameQuery'
      responses:
        200:
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
                  - $ref: '#/components/schemas/GetUsageBillingStorageResponse'
          description: Success

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
      tags:
        - Usage

  /v1/usage-billing/virtual-warehouses:
    summary: Pub-UsageVirtualWarehouse
    get:
      summary: Retrieve the virtual warehouse utilisation for a specified timeframe
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
        - $ref: '#/components/parameters/startTimeQuery'
        - $ref: '#/components/parameters/endTimeQuery'
        - $ref: '#/components/parameters/vwNameQuery'
      responses:
        200:
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
                  - $ref: '#/components/schemas/GetUsageBillingVWCreditResponse'
          description: Success

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
      tags:
        - Usage

  # /v1/audits:
  #   summary: Pub-AuditLog
  #   get:
  #     parameters:
  #       - $ref: '#/components/parameters/activeRoleHeader'
  #       - $ref: '#/components/parameters/filterQuery'
  #       - $ref: '#/components/parameters/cursorQuery'
  #       - $ref: '#/components/parameters/sortQuery'
  #       - $ref: '#/components/parameters/listLimit'
  #     responses:
  #       200:
  #         content:
  #           application/json:
  #             schema:
  #               allOf:
  #                 - $ref: '#/components/schemas/BaseListResponse'
  #                 - $ref: '#/components/schemas/GetAuditResponse'
  #         description: Success
  #       500:
  #         description: Internal server error
  #     summary: Get audit log
  #     tags:
  #       - Audit

  /v1/query-statistics/{id}:
    summary: QueryStatisticsDetail
    get:
      summary: Retrieve a query statistic
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
        - $ref: '#/components/parameters/resourceIDPath'
      tags:
        - Statistics
      responses:
        200:
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
                  - properties:
                      data:
                        $ref: '#/components/schemas/QueryStatistics'
                    type: object
          description: Success
        404:
          description: Resource not found
        500:
          description: Internal server error

  /v1/connections:
    summary: Pub-Connections
    post:
      summary: Create a connection
      operationId: create-connection
      tags:
        - Data Loading
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConnectionRequest'
      responses:
        201:
          description: Created connection successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
                  - $ref: '#/components/schemas/CreateConnectionResponse'
        400:
          description: Bad request, request body is invalid to construct a connection
        403:
          description: Forbidden, user/role doesn't have permission to create connection
        422:
          description: Illegal state, num of connections has reached quota

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
    get:
      summary: List connections
      operationId: list-connections
      tags:
        - Data Loading
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
        - $ref: '#/components/parameters/listCursor'
        - $ref: '#/components/parameters/listLimit'
      responses:
        200:
          description: List connections successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseListResponse'
                  - $ref: '#/components/schemas/ListConnectionsResponse'

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'

  /v1/connections/{id}:
    summary: Pub-ConnectionsDetail
    parameters:
      - $ref: '#/components/parameters/activeRoleHeader'
      - $ref: '#/components/parameters/integerIdPath'
    put:
      summary: Update a connection
      operationId: update-connection
      tags:
        - Data Loading
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateConnectionRequest'
      responses:
        200:
          description: Updated connection successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
        400:
          description: Bad request, connection id should be an integer or request body is invalid to construct a connection
        403:
          description: Forbidden, user/role doesn't have permission to update this connection
        404:
          description: Not found, the connection with specified id doesn't exist
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
    delete:
      summary: Delete a connection
      operationId: delete-connection
      tags:
        - Data Loading
      responses:
        200:
          description: Deleted connection successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
        400:
          description: Bad request, connection id should be an integer
        403:
          description: Forbidden, user/role doesn't have permission to delete this connection

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'

  /v1/connections/{id}/masked:
    summary: Pub-ConnectionDetailMasked
    get:
      summary: Get masked connection
      operationId: get-masked-connection
      tags:
        - Data Loading
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
        - $ref: '#/components/parameters/integerIdPath'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
                  - $ref: '#/components/schemas/GetMaskedConnectionResponse'
        403:
          description: Forbidden, user/role doesn't have permission to view this connection
        404:
          description: Not found, the connection with specified id doesn't exist

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'

  /v1/import-jobs:
    summary: Pub-ImportJobs
    post:
      summary: Create an import job
      operationId: create-import-jobs
      tags:
        - Data Loading
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateImportJobRequest'
      responses:
        201:
          description: Created import job successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
                  - $ref: '#/components/schemas/CreateImportJobResponse'
        400:
          description: Bad request, request body is invalid to construct a job
        403:
          description: Forbidden, user/role doesn't have permission to create job
        422:
          description: Illegal state, num of jobs has reached quota

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
    get:
      summary: List import jobs
      operationId: list-import-jobs
      tags:
        - Data Loading
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
        - $ref: '#/components/parameters/listCursor'
        - $ref: '#/components/parameters/listLimit'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseListResponse'
                  - $ref: '#/components/schemas/ListImportJobsResponse'

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'

  /v1/import-jobs/{id}:
    summary: Pub-ImportJobDetail
    parameters:
      - $ref: '#/components/parameters/activeRoleHeader'
      - $ref: '#/components/parameters/integerIdPath'
    get:
      summary: Get an import job
      operationId: get-import-jobs
      tags:
        - Data Loading
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
                  - $ref: '#/components/schemas/GetImportJobResponse'
        400:
          description: Bad request, job id should be an integer
        403:
          description: Forbidden, user/role doesn't have permission to view this job
        404:
          description: Not found, the job with specified id doesn't exist

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
    put:
      summary: Update an import job
      operationId: update-import-jobs
      tags:
        - Data Loading
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateImportJobRequest'
      responses:
        200:
          description: Updated import job successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
        400:
          description: Bad request, job id should be an integer or request body is invalid to construct a job
        403:
          description: Forbidden, user/role doesn't have permission to update this job
        404:
          description: Not found, the job with specified id doesn't exist

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
    delete:
      summary: Delete an import job
      operationId: delete-import-jobs
      tags:
        - Data Loading
      responses:
        200:
          description: Deleted import job successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
        400:
          description: Bad request, job id should be an integer
        403:
          description: Forbidden, user/role doesn't have permission to delete this job

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'

  /v1/import-jobs/{id}/rename:
    summary: Pub-RenameImportJob
    parameters:
      - $ref: '#/components/parameters/activeRoleHeader'
      - $ref: '#/components/parameters/integerIdPath'
    post:
      summary: Rename an import job
      operationId: rename-import-jobs
      tags:
        - Data Loading
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RenameImportJobRequest'
      responses:
        200:
          description: Renamed import job successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
        400:
          description: Bad request, job id should be an integer or request body is invalid to construct a job
        403:
          description: Forbidden, user/role doesn't have permission to rename this job
        404:
          description: Not found, the job with specified id doesn't exist

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'

  /v1/import-jobs/{id}/update-description:
    summary: Pub-UpdateImportJobDescription
    parameters:
      - $ref: '#/components/parameters/activeRoleHeader'
      - $ref: '#/components/parameters/integerIdPath'
    post:
      summary: Update an import job description
      operationId: update-import-jobs-description
      tags:
        - Data Loading
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateImportJobDescriptionRequest'
      responses:
        200:
          description: Update import job description successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
        400:
          description: Bad request, job id should be an integer or request body is invalid to construct a job
        403:
          description: Forbidden, user/role doesn't have permission to update this job description
        404:
          description: Not found, the job with specified id doesn't exist

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'

  /v1/import-jobs/{id}/start-args:
    summary: Pub-ImportJobStartArgs
    get:
      summary: Get the starting arguments for a specified import job
      operationId: get-import-jobs-start-args
      tags:
        - Data Loading
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
        - $ref: '#/components/parameters/integerIdPath'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
                  - $ref: '#/components/schemas/GetImportJobStartArgsResponse'
        400:
          description: Bad Request, job id should be an integer
        403:
          description: Forbidden, user/role doesn't have permission to view this job
        404:
          description: Not found, the job with specified id doesn't exist

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'

  /v1/import-jobs/{id}/start:
    summary: Pub-ImportJobStart
    post:
      summary: Start a specified import job
      operationId: start-import-job
      tags:
        - Data Loading
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
        - $ref: '#/components/parameters/integerIdPath'
      requestBody:
        description: Starting Argument of the file
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartImportJobRequest'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
                  - $ref: '#/components/schemas/StartImportJobResponse'
        400:
          description: Bad Request, job id should be an integer or the start arguments specified in request body is invalid
        403:
          description: Forbidden, user/role doesn't have permission to start this job
        404:
          description: Not found, the job with specified id doesn't exist
        422:
          description: Illegal state, cannot start an active job

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'

  /v1/import-jobs/{id}/stop:
    summary: Pub-ImportJobStop
    post:
      summary: Stop a specified import job
      operationId: stop-import-job
      tags:
        - Data Loading
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
        - $ref: '#/components/parameters/integerIdPath'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
        400:
          description: Bad Request, job id should be an integer
        403:
          description: Forbidden, user/role doesn't have permission to stop this job
        404:
          description: Not found, the job with specified id doesn't exist

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'

  /v1/import-jobs/{id}/executions:
    summary: Pub-ImportJobExecutions
    get:
      summary: List executions for a specified import job
      operationId: list-import-job-executions
      tags:
        - Data Loading
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
        - $ref: '#/components/parameters/integerIdPath'
        - $ref: '#/components/parameters/listCursor'
        - $ref: '#/components/parameters/listLimit'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseListResponse'
                  - $ref: '#/components/schemas/ListImportJobExecutionsResponse'
        400:
          description: Bad Request, job id should be an integer
        403:
          description: Forbidden, user/role doesn't have permission to view this job
        404:
          description: Not found, the job with specified id doesn't exist

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'

  /v1/import-executions:
    summary: Pub-ImportExecutions
    get:
      summary: List executions
      operationId: list-import-executions
      tags:
        - Data Loading
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
        - $ref: '#/components/parameters/listCursor'
        - $ref: '#/components/parameters/listLimit'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseListResponse'
                  - $ref: '#/components/schemas/ListImportExecutionsResponse'

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'

  /v1/import-executions/{id}:
    summary: Pub-ImportExecutionDetail
    get:
      summary: Get execution details
      operationId: get-import-execution
      tags:
        - Data Loading
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
        - $ref: '#/components/parameters/uuidPath'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
                  - $ref: '#/components/schemas/GetImportExecutionResponse'
        403:
          description: Forbidden, user/role doesn't have permission to view this job
        404:
          description: Not found, the execution with specified id doesn't exist

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'

  /v1/import-executions/{id}/logs:
    summary: Pub-ImportExecutionLogs
    get:
      summary: Get Execution Logs, currently public api does not support logs from kafka
      operationId: get-import-execution-logs
      tags:
        - Data Loading
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
        - $ref: '#/components/parameters/uuidPath'
        - $ref: '#/components/parameters/listLimit'
      responses:
        200:
          description: Success
          content:
            text/plain:
              schema:
                allOf:
                  - $ref: '#/components/schemas/GetImportExecutionLogsResponse'
        403:
          description: Forbidden, user/role doesn't have permission to view this job
        404:
          description: Not found, the execution with specified id doesn't exist

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'

  /v1/import-executions/{id}/kafka-consuming-status:
    summary: Pub-KafkaExecConsumingStatus
    get:
      summary: Get historical consuming status for a specified Kafka execution
      description: >
        Get historical consuming status of a Kafka execution including current
        offset, lag and consumption speed.

        The response will be an array of consuming status of time windows in the
        period from now back trace to now - 'period' (from query parameter).

        The time window length is specified by the 'granularity' query
        parameter.
      operationId: get-import-execution-kafka-consuming-status
      tags:
        - Data Loading
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
        - $ref: '#/components/parameters/resourceIDPath'
        - in: query
          name: partition
          description: 'Kafka topic partition used to query kafka consuming status.'
          required: true
          schema:
            type: integer
          example: 0
        - in: query
          name: period
          description: |-
            Time period to request for kafka historical consuming status and the value should be
            a valid duration string according to https://pkg.go.dev/time#ParseDuration.
          required: true
          schema:
            type: string
          example: '1h'
        - in: query
          name: granularity
          description: |-
            Time granularity to request for kafka historical consuming status and the value should be
            a valid duration string according to https://pkg.go.dev/time#ParseDuration.
          schema:
            type: string
          required: true
          example: '2m'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'
                  - $ref: '#/components/schemas/GetKafkaConsumingStatusResponse'
        400:
          description: Bad Request, invalid request parameters were given
        403:
          description: Forbidden, user/role doesn't have permission to view this job
        404:
          description: Not found, the execution with specified id doesn't exist

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'

  /v1/virtual-warehouse/compute:
    summary: Pub-VWCompute
    description: use "VW" short for Virtual Warehouse
    get:
      summary: List virtual warehouses
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
        - $ref: '#/components/parameters/vwListLimit'
        - $ref: '#/components/parameters/listOffset'
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ListVirtualWarehouseResponse'
                  - $ref: '#/components/schemas/BaseOffsetListResponse'

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
      tags:
        - Virtual Warehouse
    post:
      summary: Create a virtual warehouse
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVirtualWarehouseRequest'
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/CreateVirtualWarehouseResponse'
                  - $ref: '#/components/schemas/BaseResponse'

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
      tags:
        - Virtual Warehouse
  /v1/virtual-warehouse/compute/{name}:
    summary: Pub-VWComputeDetail
    get:
      summary: Get a virtual warehouse
      description: Getting the virtual warehouse details by name
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
        - $ref: '#/components/parameters/vwNamePath'
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                description: Virtual Warehouse detail response
                allOf:
                  - $ref: '#/components/schemas/VirtualWarehouse'
                  - $ref: '#/components/schemas/BaseResponse'

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                description: Virtual Warehouse detail error response
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
      tags:
        - Virtual Warehouse
    patch:
      summary: Update a virtual warehouse
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
        - $ref: '#/components/parameters/vwNamePath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateVirtualWarehouseRequest'
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
      tags:
        - Virtual Warehouse
    delete:
      summary: Delete a virtual warehouse
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
        - $ref: '#/components/parameters/vwNamePath'
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseResponse'

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
      tags:
        - Virtual Warehouse
  /v1/virtual-warehouse/config:
    summary: Pub-VWConfig
    get:
      summary: List virtual warehouse configurations
      parameters:
        - $ref: '#/components/parameters/activeRoleHeader'
        - $ref: '#/components/parameters/vwListLimit'
        - $ref: '#/components/parameters/listOffset'
      responses:
        200:
          description: success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ListVirtualWarehouseConfigResponse'
                  - $ref: '#/components/schemas/BaseOffsetListResponse'

        500:
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseErrorResponse'
      tags:
        - Virtual Warehouse
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  parameters:
    subscribeAccountIDHeader:
      in: header
      name: X-Account-ID
      description: accountID for subscribing
      required: true
      schema:
        type: string
      example: '2100042608'
    userIDHeader:
      in: header
      name: X-User-ID
      description: user ID
      required: true
      schema:
        type: string
      example: '2100042608'
    accountIDHeader:
      in: header
      name: X-Account-ID
      description: Account ID
      schema:
        type: string
      example: "3218581405375043103"
    bytehouseTokenHeader:
      in: header
      name: X-Bytehouse-Token
      description: bytehouse token
      required: true
      schema:
        type: string
      example: 'eyJhbGciOiJSUzI1Ni'
    activeRoleHeader:
      in: header
      name: X-User-ActiveRole
      description: User Active Role
      required: false
      schema:
        type: string
      example: 'AccountAdmin'
    clickhouseUserHeader:
      in: header
      name: X-ClickHouse-User
      required: true
      schema:
        type: string
      example: 'Bytehouse'
    clickhousePasswordHeader:
      in: header
      name: X-ClickHouse-Key
      required: true
      schema:
        type: string
      example: 'your-api-key'
    querySessionHeader:
      name: X-QuerySession-ID
      in: header
      description: Query/Worksheet session ID
      schema:
        type: string
    databaseNamePath:
      in: path
      name: db_name
      required: true
      schema:
        type: string
    tableNamePath:
      in: path
      name: table_name
      required: true
      schema:
        type: string
    dictionaryNamePath:
      in: path
      name: dict_name
      required: true
      schema:
        type: string
    mvNamePath:
      in: path
      name: mv_name
      required: true
      schema:
        type: string
    integerIdPath:
      in: path
      name: id
      required: true
      schema:
        type: integer
    uuidPath:
      in: path
      name: id
      required: true
      schema:
        type: string
        format: uuid

    columnQuery:
      in: query
      name: column
      schema:
        type: string
      example: employee_id

    partitionQuery:
      in: query
      name: partition
      schema:
        type: string
      example: (12-12-01)

    runningQuery:
      in: query
      name: running
      schema:
        type: boolean
      example: true
    maxRowsReturnQuery:
      in: query
      description: maximum rows return in the result(0 means return all rows)
      name: maxRowsReturn
      schema:
        type: integer
      example: 2
    filterQuery:
      in: query
      name: filter
      schema:
        type: string
    cursorQuery:
      in: query
      name: cursor
      schema:
        type: string
    sortQuery:
      in: query
      name: sort
      schema:
        type: string
    resourceIDPath:
      in: path
      name: id
      required: true
      schema:
        type: string
      example: 'b36fa16e-a0ce-4274-a744-621357180928'
    listCursor:
      in: query
      name: cursor
      schema:
        type: string
      example: 'eyJ2YWx1ZSI6bnVsbCwic29ydF92YWx1ZSI6bnVsbH0='
    listLimit:
      in: query
      name: limit
      schema:
        type: integer
      example: 100
    listOffset:
      in: query
      name: offset
      description: skip specified number of elements, offset shuold be >= 0
      schema:
        type: integer
      example: 200
    listFilter:
      in: query
      name: filter
      schema:
        type: string
      example: '{jobID:"5"}'
    listSort:
      in: query
      name: sort
      schema:
        type: string
      example: '-createdAt'
    startTimeQuery:
      in: query
      name: startTime
      schema:
        type: string
      required: true
      example: "2021-11-23T09:23:55.840932013Z"
      description: stats start time
    endTimeQuery:
      in: query
      name: endTime
      schema:
        type: string
      required: true
      example: "2021-11-24T09:23:55.840932013Z"
      description: stats end time
    dbNameQuery:
      in: query
      name: dbName
      schema:
        type: string
      required: false
      example: "dbName"
      description: db name
    vwNameQuery:
      in: query
      name: vwName
      schema:
        type: string
      required: false
      example: "vwName"
      description: vw name
    vwNamePath:
      in: path
      name: name
      schema:
        type: string
      required: true
      example: "seg1_vw2"
      description: vw name
    vwListLimit:
      in: query
      name: limit
      description: |-
        limitation of the response row count.
        - limit value should >= 0;
        - default value is 10, if no "limit" parameter passed, 10 will be set by default;
        - max value is 100, if 120 passed, which exceed 100, will be corrected to 100.
      schema:
        type: integer
      example: 100
    virtualWarehouseQuery:
      in: query
      name: virtual_warehouse
      schema:
        type: string
      description: virtual warehouse to be used for the query
      required: false
    queryParams:
      in: query
      name: query
      schema:
        type: string
      description: query to be ran
      required: false
    userParams:
      in: query
      name: user
      schema:
        type: string
      description: bytehouse
      example: "bytehouse"
      required: false
    passwordParams:
      in: query
      name: password
      schema:
        type: string
      description: api-key
      required: false

    ##########################################
    #       Start of IAM API Parameters      #
    ##########################################

    apiKeyIDParam:
      name: api_key_id
      in: path
      description: ID of User's API Key
      schema:
        type: integer
        description: ID of User's API Key
      required: true
      example: 1

  ##########################################
  #        End of IAM API Parameters       #
  ##########################################

  schemas:
    BaseResponse:
      type: object
      description: Base response schema.
      properties:
        message:
          type: string
          description: Request status.
          example: "Success"
        error:
          type: object
          description: Error details.
          nullable: true
          properties:
            message:
              type: string
              description: Error message.
              example: 'omitempty if no error, otherwise, it will be error message'
    BaseResponseWithoutError:
      type: object
      description: Success response body.
      properties:
        message:
          description: Success message.
          type: string
          example: "Success"
    BaseResponseWithoutMessage:
      type: object
    BaseListResponse:
      type: object
      properties:
        message:
          type: string
          example: "Success"
        meta:
          type: object
          nullable: true
          properties:
            nextCursor:
              type: string
              example: nextCursor
              nullable: true
            prevCursor:
              type: string
              example: prevCursor
              nullable: true
            offset:
              type: number
              example: 4
              nullable: true
            total:
              type: number
              example: 5
              nullable: true
        error:
          type: object
          nullable: true
          properties:
            message:
              type: string
              example: 'null if no error, otherwise, it will be error message'
    BaseOffsetListResponse:
      type: object
      properties:
        meta:
          type: object
          nullable: true
          properties:
            offset:
              type: number
              example: 4
              nullable: true
            total:
              type: number
              example: 5
              nullable: true

    BaseErrorResponse:
      type: object
      description: Base error structure.
      properties:
        error:
          type: object
          description: Error details.
          nullable: true
          properties:
            message:
              type: string
              description: Error message.
              example: 'something went wrong, please refer to document or find help from tech support'
          required:
            - message
      required:
        - error

    AuthenticationErrorResponse:
      type: object
      properties:
        error:
          type: object
          nullable: true
          properties:
            message:
              type: string
              example: 'user 12345 does not have permission to resource with identifier 0c3c217b-5a00-4e44-9538-328dac95625b'
          required:
            - message
      required:
        - error

    BadRequestErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              example: 'some query parameter/header is missing'
          required:
            - message
      required:
        - error

    ResourceNotFoundErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              example: 'some the request resource is not found'
          required:
            - message
      required:
        - error

    Database:
      type: object
      properties:
        name:
          type: string
          example: 'db_name'
        type:
          type: string
          example: 'DATABASE'
        uuid:
          type: string
          example: '0c3c217b-5a00-4e44-9538-328dac95625b'
        createdBy:
          oneOf:
            - $ref: "#/components/schemas/UserWithType"
            - $ref: "#/components/schemas/UserWithName"
        createdAt:
          $ref: "#/components/schemas/DateTime"
      required:
        - name
        - uuid
        - type
        - createdBy
        - createdAt

    ListDatabasesResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Database"

    CreateDatabasesResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            uuid:
              type: string
              example: 'f9cac8f6-7bf0-4c37-bba1-5066356410a2'
          required:
            - uuid
    CreateTableResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            uuid:
              type: string
              example: 'f9cac8f6-7bf0-4c37-bba1-5066356410a2'
          required:
            - uuid

    AlterTableRequest:
      type: object
      properties:
        addColumns:
          type: array
          items:
            $ref: "#/components/schemas/Column"
          example:
            - name: ColumnID
              type: String
              nullable: false
              defaultValue: "defaultValue"
              comment: "updated_column_comment"
            - name: ColumnDate
              type: Date
              nullable: false
              defaultValue: "2019-01-01"
        dropColumns:
          type: array
          items:
            type: string
          example: [ "dropColumn1", "dropColumn2" ]
        modifyColumns:
          type: array
          items:
            $ref: "#/components/schemas/Column"
          example:
            - name: ColumnExisting
              type: String
              defaultValue: "defaultValue"
              comment: "you can update data type (including Nullable), default value and comment when modifying columns"
            - name: ColumnExisting2
              type: Date
              nullable: false
              defaultValue: "2019-01-01"
        renameColumns:
          type: array
          items:
            type: object
            properties:
              fromName:
                type: string
                example: "old_column_name"
              toName:
                type: string
                example: "new_column_name"
        ttl:
          description: Table TTL (time to live) for rows - set a new interval for the table TTL
          type: object
          properties:
            column:
              description: The column for table TTL (must be Date/DateTime) - the row expires the moment the value of the column + interval is reached
              type: string
              example: order_date
            value:
              description: The value of the table TTL interval (e.g. for an interval of 3 months, value is 3 and unit is MONTH)
              type: integer
              example: 3
            unit:
              description: The unit of the table TTL interval (e.g. for an interval of 3 months, value is 3 and unit is MONTH)
              type: string
              example: MONTH
            granularity:
              description: the granularity used for PARTITION KEY
              example: hour
          required:
            - column
            - value
            - unit
        isRemoveTTL:
          type: boolean
          example: false

    Column:
      type: object
      properties:
        name:
          type: string
        nullable:
          type: boolean
        type:
          description: CNCH column data-type only, lettercase matter
          type: string
        defaultValue:
          description: expression for default value
          type: string
        comment:
          description: comment for column
          type: string
        isDefaultValueRawExpression:
          description: true if default value does not need to be quoted, typically functions
          type: boolean
      required:
        - name
        - type
    CreateDatabaseRequest:
      type: object
      properties:
        name:
          type: string
          example: "db_name"
        description:
          type: string
          example: "testing database, please don't delete"
      required:
        - name

    ListTablesResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              uuid:
                type: string
                example: 'sample_table_uuid'
              name:
                type: string
                example: 'performance'
              description:
                type: string
                example: 'sample description'
              tableType:
                type: string
                example: 'TABLE'
              createdBy:
                oneOf:
                  - $ref: "#/components/schemas/UserWithType"
                  - $ref: "#/components/schemas/UserWithName"
              createdAt:
                $ref: '#/components/schemas/DateTime'
              lastModifiedAt:
                $ref: '#/components/schemas/DateTime'
            required:
              - name
              - createdBy
              - createdAt
              - noOfColumns
              - noOfRows
              - lastModifiedAt

    ListMaterializedViewsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              uuid:
                type: string
                example: 'sample_mv_uuid'
              name:
                type: string
                example: 'performance'
              description:
                type: string
                example: 'sample description'
              tableType:
                type: string
                example: 'MATERIALIZED-VIEW'
              baseDatabase:
                type: string
                example: "base"
              baseTable:
                type: string
                example: "table"
              targetDatabase:
                type: string
                example: "target"
              targetTable:
                type: string
                example: "table"
              ratio:
                type: number
                example: 124.1
              hitTimes:
                type: integer
                example: 100
              createdBy:
                oneOf:
                  - $ref: "#/components/schemas/UserWithType"
                  - $ref: "#/components/schemas/UserWithName"
              createdAt:
                $ref: '#/components/schemas/DateTime'
              lastModifiedAt:
                $ref: '#/components/schemas/DateTime'
            required:
              - name
              - createdBy
              - createdAt
              - noOfColumns
              - noOfRows
              - lastModifiedAt
              - baseDatabase
              - baseTable
              - targetDatabase
              - targetTable
              - ratio
              - hitTimes


    GetMaterializedViewDetailsResponse:
      type: object
      properties:
        data:
          allOf:
            - $ref: '#/components/schemas/MaterializedViewDetailsHeader'
            - $ref: '#/components/schemas/TableEngine'
            - type: object
              properties:
                tableType:
                  type: string
                  example: "TABLE"
                columns:
                  type: array
                  items:
                    allOf:
                      - $ref: "#/components/schemas/ColumnWithStats"
                      - type: object
                        properties:
                          queryFrequency:
                            description: Visiting frequency for this column, only available in GET API
                            type: integer
                          queryCount:
                            type: integer
                            description: query count of latest 7 days
                          fullColumnExpression:
                            type: string
                            description: the full column type before parsing
                            example: String, Nullable(String)
                          encoding_expression:
                            type: string
                            description: if the column is BitEngineEncode, the value will be BitEngineEncode, else, the value will be omitted
                  example:
                    - uuid: "f965ac8f6-7bf0-4c37-bba1-5066353410a4"
                      name: ColumnID
                      type: String
                      nullable: false
                      defaultValue: "defaultValue"
                      queryFrequency: 1000
                      queryCount: 243242
                      comment: "hello comment"
                      lastQueryTime: "2020-11-23T09:23:55.840932013Z"
                      fullColumnExpression: String
                    - uuid: "f965ac8f6-7bf0-4c37-bba1-5066353410a5"
                      name: ColumnDate
                      type: Date
                      nullable: false
                      defaultValue: "2019-01-01"
                      queryFrequency: 898
                      queryCount: 24324
                      lastQueryTime: null
                      fullColumnExpression: Date
                    - uuid: "f965ac8f6-7bf0-4c37-bba1-5066353410a6"
                      name: ColumnHello
                      type: Int
                      nullable: true
                      queryFrequency: 500
                      queryCount: 2432
                      lastQueryTime: "2020-11-23T09:23:55.840932013Z"
                      fullColumnExpression: Nullable(Int)
                    - uuid: "f965ac8f6-7bf0-4c37-bba1-5066353410a7"
                      name: ColumnNotNull
                      type: String
                      nullable: false
                      queryFrequency: 100
                      queryCount: 243
                      lastQueryTime: "2020-11-23T09:23:55.840932013Z"
                      fullColumnExpression: String
                    - uuid: "f965ac8f6-7bf0-4c37-bba1-5066353410a4"
                      name: ColumnBitEngine
                      type: BitMap64
                      nullable: false
                      queryFrequency: 100
                      queryCount: 243
                      lastQueryTime: "2020-11-23T09:23:55.840932013Z"
                      fullColumnExpression: Nullable(BitMap64)
                      encoding_expression: BitEngineEncode
              required:
                - columns

    ListTablesViewsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              uuid:
                type: string
                example: 'sample_table_uuid'
              name:
                type: string
                example: 'performance'
              tableType:
                type: string
                example: 'TABLE'
              description:
                type: string
                example: 'sample description'
              createdBy:
                oneOf:
                  - $ref: "#/components/schemas/UserWithType"
                  - $ref: "#/components/schemas/UserWithName"
              createdAt:
                $ref: '#/components/schemas/DateTime'
              lastModifiedAt:
                $ref: '#/components/schemas/DateTime'
            required:
              - name
              - createdBy
              - createdAt
              - noOfColumns
              - noOfRows
              - lastModifiedAt

    GetMaterializedMySQLDatabaseSyncStatusResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            dbSyncStatus:
              type: string
              example: "Running"
            tableSyncStatus:
              type: array
              items:
                type: object
                properties:
                  tableName:
                    type: string
                    example: "materialized_mysql_table_1"
                  status:
                    type: string
                    example: "Running"
            lastException:
              type: string
              example: "ConnectionFailed"

    DateTime:
      type: string
      format: date-time
      example: "2020-11-23T09:23:55.840932013Z"
      nullable: true

    UserWithType:
      type: object
      properties:
        id:
          type: integer
          example: 4780622283186922000
        type:
          type: string
          example: 'VOLCANO_MAIN_ACCOUNT'
      required:
        - id
        - type

    UserWithName:
      type: object
      properties:
        name:
          type: string
          example: 'bytehouse_qa'
      required:
        - name

    ListTablesRequest:
      type: object
      properties:
        keyword:
          type: string
          example: 'table_name'

    CreateTableRequest:
      type: object
      description: Request body to create table.
      properties:
        name:
          description: Name of the table.
          type: string
          example: table_name
        description:
          description: Description of the table.
          type: string
          example: Hello Table
        columns:
          description: List of columns of the table.
          type: array
          items:
            $ref: '#/components/schemas/Column'
          example:
            - name: ColumnID
              type: String
              nullable: false
              defaultValue: "defaultValue"
              comment: "hello comment"
            - name: ColumnDate
              type: Date
              nullable: false
              defaultValue: "2019-01-01"
            - name: ColumnHello
              type: int
            - name: ColumnNotNull
              type: String
              nullable: false
            - name: EventTime
              type: DateTime
              defaultValue: "now()"
              isDefaultValueRawExpression: true
        orderByKeys:
          description: Name of the column whose values will be used to order the table's data. A key has to be one of the columns.
          type: array
          items:
            description: Order of the ordering columns.
            type: string
          example: [ "ColumnID", "ColumnDate" ]
        samplingKey:
          description: SAMPLE BY expression. A key has to be one of the columns.
          type: string
          example: ColumnID
        partitionKeys:
          description: Keys to partition the table. A key has to be one of the columns.
          type: array
          items:
            description: Individual partition key definition.
            type: object
            properties:
              column:
                description: Column used to partition the table.
                type: string
              granularity:
                description: Granularity of the partition.
                type: string
                nullable: true
              expression:
                description: PARTITION BY expression.
                type: string
            required:
              - column
          example:
            - column: ColumnDate
              granularity: day
              expression: toStartOfDay(`ColumnDate`)
            - column: ColumnNotNull
              granularity: null
              expression: ColumnNotNull
        primaryKeys:
          description: Primary keys of the table used as the main identifier of the rows. A key has to be one of the columns.
          type: array
          items:
            description: Individual primary key definition.
            type: string
          example: [ "ColumnID", "ColumnDate" ]
        ttl:
          description: Table rows time-to-live (TTL) configuration.
          allOf:
            - $ref: '#/components/schemas/TTLSchema'
        uniqueKey:
          description: Key used to guarantee uniqueness in the table. A key has to be one of the columns.
          allOf:
            - $ref: '#/components/schemas/TableUniqueKey'
        clusterKey:
          description: Bucket key. Modifiable after creation. A key has to be one of the columns.
          allOf:
            - $ref: '#/components/schemas/TableClusterKeyWithExpression'
        settings:
          description: Settings used for a table
          allOf:
            - $ref: '#/components/schemas/Settings'
      required:
        - name
        - columns
        - orderByKeys

    TableEngine:
      type: object
      properties:
        name:
          type: string
          example: table_name
        description:
          type: string
          example: Hello Table
        orderByKeys:
          type: array
          items:
            type: string
          example: [ "ColumnID", "ColumnDate" ]
        samplingKey:
          description: SAMPLE BY expression
          type: string
          example: ColumnID
        partitionKeys:
          type: array
          items:
            type: object
            properties:
              column:
                type: string
              granularity:
                type: string
                nullable: true
              expression:
                type: string
            required:
              - column
          example:
            - column: ColumnDate
              granularity: day
              expression: toStartOfDay(`ColumnDate`)
            - column: ColumnNotNull
              granularity: null
              expression: ColumnNotNull
        primaryKeys:
          type: array
          items:
            type: string
          example: [ "ColumnID", "ColumnDate" ]
        ttl:
          allOf:
            - $ref: '#/components/schemas/TTLSchema'
        uniqueKey:
          allOf:
            - $ref: '#/components/schemas/TableUniqueKey'

        clusterKey:
          allOf:
            - $ref: '#/components/schemas/TableClusterKeyWithExpression'

      required:
        - name
        - orderByKeys

    TableClusterKeyWithExpression:
      description: Work as bucket key
      type: object
      properties:
        columns:
          type: array
          items:
            type: string
          example: [ "ColumnID", "ColumnDate" ]
        numOfBuckets:
          type: integer
          example: 20
        expression:
          type: string
          example: (`ColumnID`, `ColumnDate`)
      required:
        - columns
        - numOfBuckets

    Settings:
      description: Settings appended to a query
      type: object
      additionalProperties:
        oneOf:
          - type: string
          - type: number
      example:
        storage_dialect_type: "MYSQL"
        partition_level_unique_keys: 0

    TableUniqueKey:
      description: Column/s used to guarantee uniqueness of data. Currently up to 10 columns can be used.
        Supported data types are [U]Int8/16/32/64, Boolean, Date, DateTime, String.
        Nullable columns cannot be used as unique keys.
        Uniqueness can be in the partition level or table level. It is partition level by default. Unique keys cannot be altered once table is created.
      type: object
      properties:
        columns:
          type: array
          items:
            type: string
          example: [ "ColumnID", "ColumnDate" ]
        isUniqueTable:
          type: boolean
        expression:
          type: string
          example: (`ColumnID`, `ColumnDate`)
      required:
        - columns
    TTLSchema:
      description: Table TTL (time to live) for rows
      type: object
      properties:
        column:
          description: The column for table TTL (must be Date/DateTime) - the row expires the moment the value of the column + interval is reached
          type: string
          example: order_date
        value:
          description: The value of the table TTL interval (e.g. for an interval of 3 months, value is 3 and unit is MONTH)
          type: integer
          example: 3
        unit:
          description: The unit of the table TTL interval (e.g. for an interval of 3 months, value is 3 and unit is MONTH)
          type: string
          example: MONTH
        granularity:
          description: the granularity used for PARTITION KEY
          example: hour
        expression:
          description: the expression of ttl SQL
          type: string
          example: "`toStartOfHour`(`order_date`) + INTERVAL 3 MONTH"
      required:
        - column
        - Value
        - unit

    MaterializedViewDetailsHeader:
      type: object
      properties:
        uuid:
          type: string
          example: "a637ce52-07ca-4e80-b05a-458c42ab2f72"
        baseDatabase:
          type: string
          example: "base"
        baseTable:
          type: string
          example: "table"
        targetDatabase:
          type: string
          example: "target"
        targetTable:
          type: string
          example: "table"
        ratio:
          type: number
          example: 124.1
        hitTimes:
          type: integer
          example: 100
        createdBy:
          oneOf:
            - $ref: "#/components/schemas/UserWithType"
            - $ref: "#/components/schemas/UserWithName"
        createdAt:
          $ref: '#/components/schemas/DateTime'
        lastModifiedAt:
          $ref: '#/components/schemas/DateTime'
      required:
        - uuid
        - createdBy
        - createdAt
        - baseDatabase
        - baseTable
        - targetDatabase
        - targetTable
        - ratio
        - hitTimes

    TableDetailsHeader:
      type: object
      properties:
        uuid:
          type: string
          example: a637ce52-07ca-4e80-b05a-458c42ab2f72
        sizeInBytes:
          type: integer
          format: int64
          example: 13011000000000
        noOfRows:
          type: integer
          format: int64
          example: 34567890
        createdBy:
          oneOf:
            - $ref: "#/components/schemas/UserWithType"
            - $ref: "#/components/schemas/UserWithName"
        createdAt:
          $ref: '#/components/schemas/DateTime'
        lastModifiedAt:
          $ref: '#/components/schemas/DateTime'
      required:
        - uuid
        - sizeInBytes
        - noOfRows
        - createdBy
        - createdAt

    ColumnWithStats:
      type: object
      properties:
        uuid:
          description: the column uuid
          type: string
        name:
          type: string
        nullable:
          type: boolean
        type:
          description: CNCH column data-type only, lettercase matter
          type: string
        defaultValue:
          description: expression for default value
          type: string
        comment:
          description: comment for column
          type: string
        lastQueryTime:
          $ref: '#/components/schemas/DateTime'

    GetClusterStatusOfTableResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            status:
              type: array
              items:
                type: integer
                example: 1

    GetTableDetailsResponse:
      type: object
      properties:
        data:
          allOf:
            - $ref: '#/components/schemas/TableDetailsHeader'
            - $ref: '#/components/schemas/TableEngine'
            - type: object
              properties:
                tableType:
                  type: string
                  example: "TABLE"
                columns:
                  type: array
                  items:
                    allOf:
                      - $ref: "#/components/schemas/ColumnWithStats"
                      - type: object
                        properties:
                          queryFrequency:
                            description: Visiting frequency for this column, only available in GET API
                            type: integer
                          queryCount:
                            type: integer
                            description: query count of latest 7 days
                          fullColumnExpression:
                            type: string
                            description: the full column type before parsing
                            example: String, Nullable(String)
                          encoding_expression:
                            type: string
                            description: if the column is BitEngineEncode, the value will be BitEngineEncode, else, the value will be omitted
                  example:
                    - uuid: "f965ac8f6-7bf0-4c37-bba1-5066353410a4"
                      name: ColumnID
                      type: String
                      nullable: false
                      defaultValue: "defaultValue"
                      queryFrequency: 1000
                      queryCount: 243242
                      comment: "hello comment"
                      lastQueryTime: "2020-11-23T09:23:55.840932013Z"
                      fullColumnExpression: String
                    - uuid: "f965ac8f6-7bf0-4c37-bba1-5066353410a5"
                      name: ColumnDate
                      type: Date
                      nullable: false
                      defaultValue: "2019-01-01"
                      queryFrequency: 898
                      queryCount: 24324
                      lastQueryTime: null
                      fullColumnExpression: Date
                    - uuid: "f965ac8f6-7bf0-4c37-bba1-5066353410a6"
                      name: ColumnHello
                      type: Int
                      nullable: true
                      queryFrequency: 500
                      queryCount: 2432
                      lastQueryTime: "2020-11-23T09:23:55.840932013Z"
                      fullColumnExpression: Nullable(Int)
                    - uuid: "f965ac8f6-7bf0-4c37-bba1-5066353410a7"
                      name: ColumnNotNull
                      type: String
                      nullable: false
                      queryFrequency: 100
                      queryCount: 243
                      lastQueryTime: "2020-11-23T09:23:55.840932013Z"
                      fullColumnExpression: String
                    - uuid: "f965ac8f6-7bf0-4c37-bba1-5066353410a4"
                      name: ColumnBitEngine
                      type: BitMap64
                      nullable: false
                      queryFrequency: 100
                      queryCount: 243
                      lastQueryTime: "2020-11-23T09:23:55.840932013Z"
                      fullColumnExpression: Nullable(BitMap64)
                      encoding_expression: BitEngineEncode
              required:
                - columns

    ListPartitionStatsResponse:
      type: array
      items:
        type: object
        properties:
          partitionName:
            type: string
            example: "partition 1"
          sizeInBytes:
            type: integer
            example: 300
          rowCount:
            type: integer
            example: 3000
          lastModifiedAt:
            $ref: '#/components/schemas/DateTime'
        required:
          - partitionName
          - sizeInBytes
          - rowCount
          - lastModifiedAt

    ColumnPartition:
      type: object
      properties:
        database:
          type: string
          example: "db1"
        table:
          type: string
          example: "tab1"
        column:
          type: string
          example: "col1"
        partition:
          type: string
          example: "part1"
          nullable: true
        sizeInBytes:
          type: integer
          example: 300
    ListColumnPartitionResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ColumnPartition'

    ListPartitionStatsResponseWithTotalCount:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ListPartitionStatsResponse'
        totalCount:
          type: integer
          example: 1000

    ListQueryResponseWithTotalCount:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ListQueryResponse'
        totalCount:
          type: integer
          example: 1000
        cursor:
          type: string
          example: "2021-12-15T09:41:20.011579Z"

    GetMinMaxPartitionResponse:
      type: object
      properties:
        maxPartitionName:
          type: string
          example: "`2022-07-31`"
        minPartitionName:
          type: string
          example: "`2022-07-01`"
      required:
        - maxPartitionName
        - minPartitionName

    GetQueryResultResponse:
      type: array
      items:
        type: array
        items:
          type: string
      example:
        - [ "123456", "Linus Torvald", "Principal Developer, Linux Kernel", "March 21 1990" ]
        - [ "123456", "Rob Pike", "Google Cloud Leading Director", "Jan 23 1996" ]

    ListQueryResultMetadataResponse:
      type: array
      items:
        $ref: '#/components/schemas/QueryResultMetadata'

    QueryResultMetadata:
      type: object
      properties:
        sessionID:
          type: string
          example: "08c2cf17-b4e4-43b7-a93f-6012e5d63ff8"
        queryID:
          type: string
          example: "08c2cf17-b4e4-43b7-a93f-6012e5d63ff8"
        sqlStatement:
          type: string
          example: "SELECT *\nFROM `test_db`.`test_table`\nLIMIT 1000"
        executionType:
          type: string
          enum: [ QUERY, COMMAND ]
        status:
          type: string
          enum: [ SUCCESS, FAIL, RUNNING ]
          example: SUCCESS
        startTime:
          $ref: '#/components/schemas/DateTime'
        endTime:
          $ref: '#/components/schemas/DateTime'
        durationInMs:
          type: integer
          example: 3050
        vwResumeDurationInMs:
          type: integer
          example: 3000
        errorMessage:
          type: string
          example: "Code 100 DB Exception: Unknown Table `fakeDB.fakeTable`"
        rowsNum:
          type: integer
          example: 100
        columns:
          type: array
          items:
            $ref: "#/components/schemas/Column"
          example:
            - name: ColumnID
              type: String
              nullable: false
              defaultValue: "defaultValue"
            - name: ColumnDate
              type: Date
              nullable: false
              defaultValue: "2019-01-01"

    ListRunningQueriesResponse:
      type: array
      items:
        $ref: '#/components/schemas/RunningQueryRecord'

    RunningQueryRecord:
      type: object
      properties:
        queryID:
          type: string
          example: 'query-id-one-two-three'
        accountID:
          type: integer
          example: 123
        userID:
          type: integer
          example: 123
        startTime:
          type: string
          example: '2021-01-18T14:54:21.932+08:00'
        sqlText:
          type: string
          example: 'SELECT * FROM test_db.test_table'
        activeRole:
          type: string
          example: admin
        warehouseID:
          type: string
          example: 'Compute_Warehouse_XL'
        sqlType:
          type: string
          example: 'SELECT'
        sqlMode:
          type: string
          example: 'Clickhouse SQL'

    CombinedQueryRecord:
      type: object
      properties:
        queryID:
          type: string
          example: 'query-id-one-two-three'
        accountID:
          type: integer
          example: 1234567890
        virtualWarehouse:
          type: string
          example: 'Compute_Warehouse_XL'
        user:
          oneOf:
            - $ref: "#/components/schemas/UserWithType"
            - $ref: "#/components/schemas/UserWithName"
        sqlText:
          type: string
          example: 'SELECT * FROM test_db.test_table'
        startTime:
          type: string
          example: '2021-01-18T14:54:21.932+08:00'
        endTime:
          type: string
          example: '2021-01-18T14:54:22.132+08:00 or null if running'
        state:
          type: string
          example: 'success or running'
        durationInMs:
          type: integer
          nullable: true
          example: 200
        vwAutoResumeDurationInMs:
          type: integer
          nullable: true
          example: 190
        sqlMode:
          type: string
          enum: [ ClickHouse SQL, ANSI SQL, N.A. ]
          example: "ANSI SQL"
        database:
          type: string
          example: 'db-1 or null if running'
        sqlType:
          type: string
          example: 'SELECT'
        activeRole:
          type: string
          example: admin

    ListCombinedQueryResponse:
      type: array
      items:
        $ref: '#/components/schemas/CombinedQueryRecord'

    SubmitQueryResponse:
      type: array
      items:
        allOf:
          - $ref: '#/components/schemas/QueryResultMetadata'
          - type: object
            properties:
              rows:
                $ref: '#/components/schemas/GetQueryResultResponse'
    SubmitQueryResponseV2:
      type: array
      items:
        allOf:
          - $ref: '#/components/schemas/QueryResultMetadata'
          - type: object
            properties:
              rows:
                $ref: '#/components/schemas/GetQueryResultResponse'

    SubmitSyncQueryRequest:
      type: object
      properties:
        query:
          type: string
          example: "USE TUTORIAL_DB; SELECT * FROM TUTORIAL_DB.Customer;"
        mode:
          type: string
          enum: [ ansi_sql, clickhouse_sql ]
        vwID:
          type: string
          example: "vw-compute-wh-test-8839992783"
        queryID:
          type: string
          example: "optional-1234567891011121314151617181920s211a22231"
        asyncModeSwitchAfterInSec:
          type: integer
          example: 0
        maxRowsReturn:
          type: integer
          example: 2
          description: maximum number of rows return in the result (0 means return all rows)
        insertWithData:
          type: boolean
          example: false
          description: sends all the data in a single pass for insert queries
      required:
        - query
        - mode

    SubmitAsyncQueryRequest:
      type: object
      properties:
        query:
          type: string
          example: "USE TUTORIAL_DB; SELECT * FROM TUTORIAL_DB.Customer;"
        mode:
          type: string
          enum: [ ansi_sql, clickhouse_sql ]
        vwID:
          type: string
          example: "vw-compute-wh-test-8839992783"
        queryID:
          type: string
          example: "optional-1234567891011121314151617181920s211a22231"
      required:
        - query
        - mode

    QueryRequest:
      type: object
      properties:
        query:
          type: string
          example: "USE TUTORIAL_DB; SELECT * FROM TUTORIAL_DB.Customer;"
        userInfo:
          $ref: '#/components/schemas/UserInfo'

    UserInfo:
      type: object
      properties:
        accountID:
          type: number
          example: 112233
        userID:
          type: number
          example: 112233
        activeRole:
          type: string
          example: "AccountAdmin"

    QueryRecord:
      type: object
      properties:
        queryID:
          type: string
          example: 'query-id-one-two-three'
        virtualWarehouse:
          type: string
          example: 'Compute_Warehouse_XL'
        user:
          oneOf:
            - $ref: "#/components/schemas/UserWithType"
            - $ref: "#/components/schemas/UserWithName"
        sqlText:
          type: string
          example: 'SELECT * FROM test_db.test_table'
        startTime:
          type: string
          example: '2021-01-18T14:54:21.932+08:00'
        endTime:
          type: string
          example: '2021-01-18T14:54:22.132+08:00'
        state:
          type: string
          example: 'success'
        durationInMs:
          type: integer
          example: 200
        vwAutoResumeDurationInMs:
          type: integer
          example: 190
        sqlMode:
          type: string
          enum: [ ClickHouse SQL, ANSI SQL, N.A. ]
          example: "ANSI SQL"
        database:
          type: string
          example: db-1
        activeRole:
          type: string
          example: admin

    SubmitLongRunningQueryResponse:
      type: array
      items:
        type: object
        properties:
          status:
            type: string
            example: 'running'
          queryID:
            type: string
            example: 'query-id-one-two-three'
          Exception:
            type: string
            example: "Code 100 DB Exception: Unknown Table `fakeDB.fakeTable`"

    SubmitLongRunningQueryResponseV2:
      type: array
      items:
        type: object
        properties:
          status:
            type: string
            example: 'running'
          queryID:
            type: string
            example: 'query-id-one-two-three'
          errorMessage:
            type: string
            example: "Code 100 DB Exception: Unknown Table `fakeDB.fakeTable`"

    GetRecentQueriesRecord:
      type: array
      items:
        type: object
      example: [ { 'queryID': 1, 'status': 'finished', 'sqlStatement': 'SELECT 1' }, { 'queryID': 2, 'status': 'running', 'sqlStatement': 'SELECT *' } ]

    CheckTablesForQueryResponse:
      type: object
      properties:
        valid:
          type: boolean
          example: true
        message:
          type: string
          example: "access denied, user has not access to table1 "
        tables:
          type: array
          items:
            type: string
            example: "a"
          example: [ "databaseName.table1","databaseName.table2" ]

    GetDialectTypesResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: string
          example: ['clickhouse','ansi', 'mysql']


    CheckLongRunningQueryStatusResponse:
      type: object
      properties:
        state:
          type: string
          example: "running"
        errorMessage:
          type: string
          example: "internal error"
        sqlStatement:
          type: string
          example: 'SELECT 1'
        startTime:
          $ref: '#/components/schemas/DateTime'
        endTime:
          $ref: '#/components/schemas/DateTime'

    KillQueryResponse:
      type: object
      properties:
        killed:
          type: boolean
          example: true

    QueryProfile:
      type: object
      properties:
        readBytes:
          type: integer
          example: 132412
        writeBytes:
          type: integer
          example: 90989
        resultRows:
          type: integer
          example: 100
        totalCPUTime:
          type: integer
          example: 9049
        totalIOTime:
          type: integer
          example: 77587
        peakMemory:
          type: integer
          example: 7890370
        operatorLevel:
          $ref: '#/components/schemas/QueryProfileOperatorLevel'

    QueryProfileOperatorLevel:
      type: object
      properties:
        stream:
          type: string
          example: Union
        bytesProcessed:
          type: integer
          example: 89
        rowsProcessed:
          type: integer
          example: 980
        cpuTime:
          type: integer
          example: 34
        ioTime:
          type: integer
          example: 34
        elapsedTime:
          type: integer
          example: 897
        bytesThroughput:
          type: integer
          example: 9089
        children:
          type: array
          items:
            $ref: "#/components/schemas/QueryProfileOperatorLevel"
          example: [ ]

    GetDatabaseResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            uuid:
              type: string
              example: 'sample_db_uuid'
            name:
              type: string
              example: my_db_name
            description:
              type: string
              example: DB description entered by user with limit length.
            noOfTables:
              type: integer
              example: 12
            sizeInBytes:
              type: integer
              example: 212600881152
            createdBy:
              oneOf:
                - $ref: "#/components/schemas/UserWithType"
                - $ref: "#/components/schemas/UserWithName"
            createdAt:
              $ref: '#/components/schemas/DateTime'
            lastModifiedBy:
              oneOf:
                - $ref: "#/components/schemas/UserWithType"
                - $ref: "#/components/schemas/UserWithName"
            lastModifiedAt:
              $ref: '#/components/schemas/DateTime'
            databaseType:
              type: string
              example: 'DATABASE'
          required:
            - name
            - description
            - noOfTables
            - sizeInBytes
            - createdBy
            - createdAt
            - lastModifiedBy
            - lastModifiedAt

    AlterPartition:
      type: object
      properties:
        action:
          type: string
          enum: [ ATTACH, REPLACE, DROP, DETACH ]
          example: ATTACH
        partition:
          type: string
          example: partitionA
        fromDB:
          type: string
          example: db1
        fromTable:
          type: string
          example: table1
      required:
        - action
        - partition

    AlterDatabaseRequest:
      type: object
      properties:
        description:
          type: string
          example: new description

    ListQueryResponse:
      type: array
      items:
        $ref: '#/components/schemas/QueryRecord'

    ListDocumentationFunctionResponse:
      type: object
      properties:
        data:
          type: array
          description: List of SQL functions.
          items:
            type: object
            description: Function info.
            properties:
              name:
                type: string
                example: "any"
              type:
                type: string
                example: "aggregate"
              description:
                type: string
                example: "Selects the first encountered value."
              example:
                type: string
                example: "SELECT any(number) FROM numbers(10);"
              class:
                type: string
                example: ""

    ProfilerRecord:
      type: object
      properties:
        queryID:
          type: string
          example: 'b36fa16e-a0ce-4274-a744-621357180928'
        query:
          type: string
          example: 'SELECT 1\nLIMIT 0, 100000\nSETTINGS enable_distributed_stages = 1'
        state:
          type: string
          example: 'QUERY_FINISHED'
        sqlType:
          type: string
          example: 'SELECT'
        database:
          type: string
          example: 'my_db'
        table:
          type: string
          example: 'my_tab'
        complexQuery:
          type: integer
          example: 1
        serverID:
          type: string
          example: 'cnch-default-server-1'
        timestamp:
          type: string
          example: '2022-03-31T11:17:41Z'
        elapsedTime:
          type: integer
          example: 1
        initTime:
          type: integer
          example: 2
        catalogTime:
          type: integer
          example: 1
        cpuTime:
          type: integer
          example: 1
        peakMemoryBytes:
          type: integer
          example: 8320
        readRows:
          type: integer
          example: 1
        readBytes:
          type: integer
          example: 1
        readCachedBytes:
          type: integer
          example: 1
        readDuration:
          type: integer
          example: 1
        writeRows:
          type: integer
          example: 1
        writeBytes:
          type: integer
          example: 1
        writeDuration:
          type: integer
          example: 1
        resultRows:
          type: integer
          example: 1
        profileType:
          type: string
          example: 'QUERY_FINISHED'
        operatorTree:
          type: object
          properties:
            operatorMetrics:
              $ref: '#/components/schemas/QueryProfileOperatorLevelV2'

    ProfilerSegment:
      type: object
      properties:
        queryID:
          type: string
          example: 'b36fa16e-a0ce-4274-a744-621357180928'
        query:
          type: string
          example: 'SELECT count() FROM __exchange__1()  SETTINGS enable_distributed_stages = 1'
        segmentID:
          type: integer
          example: 1
        exchangeMode:
          type: string
          example: 'GATHER'
        parallelSize:
          type: integer
          example: 2
        sources:
          type: string
          example: '2'
        rfType:
          type: string
          example: 'none'
        rfDependencySegmentID:
          type: integer
          example: 0
        rfCondition:
          type: string
          example: ''

    ComplexQuerySummary:
      type: object
      properties:
        queryID:
          type: string
          example: '6166fdff-d548-4205-8417-25a7b4cbccd2'
        latency:
          type: integer
          example: 284
        totalCPUTime:
          type: integer
          example: 0
        initTime:
          type: integer
          example: 225
        rowsScanned:
          type: integer
          example: 80
        bytesScanned:
          type: integer
          example: 1600
        bytesSent:
          type: integer
          example: 429
        cacheScannedRatio:
          type: number
          example: 0
        bytesWritten:
          type: integer
          example: 0
        partitionsTotal:
          type: integer
          example: 0

    QueryStatistics:
      type: object
      properties:
        elapsed:
          type: number
          example: 1.0
        rows_read:
          type: integer
          example: 100
        bytes_read:
          type: integer
          example: 100
        total_cpu_seconds:
          type: number
          example: 0.1
        io_wait_seconds:
          type: number
          example: 0.1

    CnchPlanSegmentLog:
      type: object
      properties:
        queryID:
          type: string
          example: 'b36fa16e-a0ce-4274-a744-621357180928'
        query:
          type: string
          example: 'SELECT count() FROM __exchange__1()  SETTINGS enable_distributed_stages = 1'
        segmentID:
          type: integer
          example: 1
        exchangeMode:
          type: string
          example: 'GATHER'
        parallelSize:
          type: integer
          example: 2
        sources:
          type: string
          example: '2'
        rfType:
          type: string
          example: 'none'
        rfDependencySegmentID:
          type: integer
          example: 0
        rfCondition:
          type: string
          example: ''
        eventDate:
          type: string
          example: '2022-01-26T00:00:00Z'
        eventTime:
          type: string
          example: '2022-01-26T03:53:22Z'
        user:
          type: string
          example: 'default'
        clientAddress:
          type: string
          example: '172.18.104.187:9510'
        state:
          type: integer
          example: 3
        startTime:
          type: string
          example: '2022.01.26 03:53:22.826.670'
        initTime:
          type: integer
          example: 0
        shuffleKey:
          type: string
          example: ''
        peakMemory:
          type: integer
          example: 4096
        readRows:
          type: integer
          example: 2
        writeRows:
          type: integer
          example: 8
        readDuration:
          type: integer
          example: 32
        writeDuration:
          type: integer
          example: 0
        readIOPS:
          type: number
          example: 0.12254714965820312
        writeIOPS:
          type: number
          example: 0
        executeDuration:
          type: number
          example: 32
        rfBuildMs:
          type: integer
          example: 0
        rfBuildBytes:
          type: integer
          example: 0
        rfExecuteMs:
          type: integer
          example: 0
        operatorProfile:
          type: object
          properties:
            operatorMetrics:
              $ref: '#/components/schemas/QueryProfileOperatorLevelV2'

    ComplexSegmentSummary:
      type: object
      properties:
        segment:
          $ref: '#/components/schemas/ProfilerSegment'
        exceptionSummary:
          type: string
          example: '\n'
        maxPeakMemory:
          type: string
          example: '4.00 KiB'
        scanLines:
          type: integer
          example: 0
        scanSize:
          type: string
          example: '0.00 B'
        totalInitTime:
          type: number
          example: 0
        totalReadRows:
          type: integer
          example: 2
        totalReadBytes:
          type: string
          example: '4.02 KiB'
        totalWriteRows:
          type: integer
          example: 8
        totalWriteBytes:
          type: string
          example: '8.00 B'
        maxExecutionDuration:
          type: number
          example: 0.032
        minExecutionDuration:
          type: number
          example: 0.032
        rfTotalBuildMs:
          type: number
          example: 0
        rfTotalBuildSize:
          type: string
          example: '0.00 B'
        rfTotalExecutionMs:
          type: number
          example: 0
        localQueueSizeAvg:
          type: integer
          example: 0
        remoteQueueSizeAvg:
          type: integer
          example: 0
        filterInSize:
          type: string
          example: '0.00 B'
        filterOutSize:
          type: string
          example: '0.00 B'
        filterRatio:
          type: string
        totalNetworkSendTime:
          type: number
        bufferFullCount:
          type: integer
        networkCrowdCount:
          type: integer
        totalNetworkSendSize:
          type: string
          example: '209.00 B'

    SegmentSummaryResp:
      type: object
      properties:
        segmentSummaries:
          type: array
          items:
            $ref: '#/components/schemas/ComplexSegmentSummary'
        totalExecutionDuration:
          type: number
          example: 0.5

    QueryProfileOperatorLevelV2:
      type: object
      properties:
        stream:
          type: string
          example: 'Union'
        number:
          type: integer
          example: 1
        bytes:
          type: integer
          example: 89
        rows:
          type: integer
          example: 980
        avgCpuTime:
          type: integer
          example: 34
        avgWallTime:
          type: integer
          example: 34
        maxCPUTime:
          type: integer
          example: 897
        maxWallTime:
          type: integer
          example: 9089
        rowsThroughput:
          type: integer
          example: 897
        bytesThroughput:
          type: integer
          example: 9089
        children:
          type: array
          items:
            $ref: '#/components/schemas/QueryProfileOperatorLevelV2'
          example: [ ]

    GetUsageBillingStorageResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            granularity:
              type: integer
              example: 3600
            series:
              type: array
              items:
                type: object
                properties:
                  date:
                    $ref: '#/components/schemas/DateTime'
                  totalSizeInBytes:
                    type: integer
                    example: 234
                  totalRows:
                    type: integer
                    example: 234
                  details:
                    type: array
                    items:
                      type: object
                      properties:
                        dbName:
                          type: string
                          example: "dbName1"
                        sizeInBytes:
                          type: integer
                          example: 2342
                        rows:
                          type: integer
                          example: 2342

    GetUsageBillingVWCreditResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            granularity:
              type: integer
              example: 3600
            series:
              type: array
              items:
                type: object
                properties:
                  date:
                    $ref: '#/components/schemas/DateTime'
                  totalCredits:
                    type: number
                    example: 234.1
                  details:
                    type: array
                    items:
                      type: object
                      properties:
                        vwName:
                          type: string
                          example: "vwName1"
                        credit:
                          type: number
                          example: 20.24

    GetAuditResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              timestamp:
                type: integer
                example: 1649222347081882857
              account_id:
                type: integer
                example: 2598667003573055500
              user_id:
                type: integer
                example: 4780622283186922000
              account_name:
                type: string
              username:
                type: string
              role_name:
                type: string
              operation:
                type: string
              total_duration_ms:
                type: integer
              exception:
                type: string
              dialect:
                type: string
              virtual_warehouse:
                type: string
              object:
                type: string
              object_id:
                type: string
              query_id:
                type: string
              source:
                type: string
              log_type:
                type: string
              is_finished:
                type: boolean
              updated_at:
                type: integer
                example: 1649222347081882857
    MetaQuery:
      type: object
      properties:
        name:
          type: string
        type:
          type: string
    StringEle:
      type: string
    IntegerEle:
      type: integer
    DataQuery:
      type: array
      items:
        type: array
        items:
          oneOf:
          - $ref: "#/components/schemas/StringEle"
          - $ref: "#/components/schemas/IntegerEle"
    StatisticsQuery:
      type: object
      properties:
        elapsed:
          type: number
          format: float
        rows_read:
          type: integer
        bytes_read:
          type: integer
    SQLQueryResponse:
      type: object
      properties:
        meta:
          type: array
          items:
            $ref: "#/components/schemas/MetaQuery"
        data:
          $ref: "#/components/schemas/DataQuery"
        rows:
          type: integer
        statistics:
          $ref: "#/components/schemas/StatisticsQuery"

    CreateConnectionRequest:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/ConnectionName'
        type:
          $ref: '#/components/schemas/ImportSourceType'
        data:
          oneOf:
            - $ref: '#/components/schemas/ConnectionDataS3'
            - $ref: '#/components/schemas/ConnectionDataTOS'
            - $ref: '#/components/schemas/ConnectionDataKafka'
            - $ref: '#/components/schemas/ConnectionDataMySql'
            - $ref: '#/components/schemas/ConnectionDataCFS'
            - $ref: '#/components/schemas/ConnectionDataLASFS'
      required: [ 'name', 'type', 'data' ]

    ConnectionName:
      type: string
      description: 'A descriptive name for your connection, 128 chars or less'
      example: 's3_sales_report'

    ConnectionDataS3:
      type: object
      properties:
        accessKey:
          type: string
          description: 'Access Key for S3 data source'
          example: 'AKIA1B2C3D4E5F6G7H8IJKLM'
        secretKey:
          type: string
          description: 'Secret Key for S3 data source'
          example: '94eUOh9w3yEFqJyGW2XdU8NHJO/yTI9RHen4e0iU'
      required: [ 'accessKey', 'secretKey' ]

    ConnectionMaskedDataS3:
      type: object
      properties:
        accessKey:
          type: string
          description: 'Masked Access Key for S3 data source, same length as original'
          example: '**********'
        secretKey:
          type: string
          description: 'Masked Secret Key for S3 data source, same length as original'
          example: '*************'
      required: [ 'accessKey', 'secretKey' ]

    ConnectionDataTOS:
      type: object
      properties:
        accessKey:
          type: string
          description: 'Access Key for TOS data source'
          example: 'AKIA1B2C3D4E5F6G7H8IJKLM'
        secretKey:
          type: string
          description: 'Secret Key for TOS data source'
          example: '94eUOh9w3yEFqJyGW2XdU8NHJO/yTI9RHen4e0iU'
      required: [ 'accessKey', 'secretKey' ]

    ConnectionMaskedDataTOS:
      type: object
      properties:
        accessKey:
          type: string
          description: 'Masked Access Key for TOS data source, same length as original'
          example: '**********'
        secretKey:
          type: string
          description: 'Masked Secret Key for TOS data source, same length as original'
          example: '*************'
      required: [ 'accessKey', 'secretKey' ]

    ConnectionDataKafka:
      type: object
      properties:
        brokers:
          type: string
          description: 'Kafka broker address'
          example: 'default-kafka.broker.bytehouse.com:9092'
        authMode:
          type: string
          description: 'Authenticate mode for Kafka broker'
          enum: [ NONE, PLAIN, SCRAM-SHA-256, SCRAM-SHA-512 ]
          example: SCRAM-SHA-512
        username:
          type: string
          example: 'username'
        password:
          type: string
          example: 'password'
        ssl:
          type: boolean
          description: 'Kafka TLS/SSL configuration, set it as true to enable SSL for authentication'
          example: true
      required: [ 'brokers', 'authMode' ]

    ConnectionMaskedDataKafka:
      type: object
      properties:
        brokers:
          type: string
          description: 'Kafka broker address'
          example: 'default-kafka.broker.bytehouse.com:9092'
        authMode:
          type: string
          description: 'Authenticate mode for Kafka broker'
          enum: [ NONE, PLAIN, SCRAM-SHA-256, SCRAM-SHA-512 ]
          example: SCRAM-SHA-512
        username:
          type: string
          description: 'Masked username for kafka broker, same length as original'
          example: '*****'
        password:
          type: string
          description: 'Masked password for kafka broker, same length as original'
          example: '*********'
        ssl:
          type: boolean
          description: 'Kafka TLS/SSL configuration, set it as true to enable SSL for authentication'
          example: true
      required: [ 'brokers', 'authMode' ]

    ConnectionDataMySql:
      type: object
      properties:
        host:
          type: string
          description: 'Mysql Host'
          example: 'host'
        port:
          type: string
          description: 'Mysql Port'
          example: '30036'
        username:
          type: string
          example: 'username'
        password:
          type: string
          example: 'password'
      required: [ 'host', 'port', 'username', 'password' ]

    ConnectionMaskedDataMySql:
      type: object
      properties:
        host:
          type: string
          description: 'Mysql Host'
          example: 'host'
        port:
          type: string
          description: 'Mysql Port'
          example: '30036'
        username:
          type: string
          description: 'Masked Mysql username, same length as original'
          example: '*****'
        password:
          type: string
          description: 'Masked Mysql password, same length as original'
          example: '****'
      required: [ 'host', 'port', 'username', 'password' ]

    ConnectionDataCFS:
      type: object
      properties:
        fileSystem:
          type: string
          description: 'File system of the Cloud File System service wants to connect'
          example: 'an-example.cfs-cn-beijing.ivolces.com'
        accessKey:
          type: string
          description: 'Access Key for file system'
          example: 'AKIA1B2C3D4E5F6G7H8IJKLM'
        secretKey:
          type: string
          description: 'Secret Key for file system'
          example: '94eUOh9w3yEFqJyGW2XdU8NHJO/yTI9RHen4e0iU'
      required: [ 'fileSystem', 'accessKey', 'secretKey' ]

    ConnectionMaskedDataCFS:
      type: object
      properties:
        fileSystem:
          type: string
          description: 'File system of the Cloud File System service wants to connect'
          example: 'an-example.cfs-cn-beijing.ivolces.com'
        accessKey:
          type: string
          description: 'Masked Access Key for file system, same length as original'
          example: '******************'
        secretKey:
          type: string
          description: 'Masked Secret Key for file system, same length as original'
          example: '*************************'
      required: [ 'fileSystem', 'accessKey', 'secretKey' ]

    ConnectionDataLASFS:
      type: object
      properties:
        endpoint:
          type: string
          description: 'Endpoint of the LAS File System service'
          example: '100.96.4.73:80'
        accessKey:
          type: string
          description: 'Access Key for the LAS File System'
          example: 'AKIA1B2C3D4E5F6G7H8IJKLM'
        secretKey:
          type: string
          description: 'Secret Key for the LAS File System'
          example: '94eUOh9w3yEFqJyGW2XdU8NHJO/yTI9RHen4e0iU'
      required: [ 'endpoint', 'accessKey', 'secretKey' ]

    ConnectionMaskedDataLASFS:
      type: object
      properties:
        endpoint:
          type: string
          description: 'Endpoint of the LAS File System service'
          example: '100.96.4.73:80'
        accessKey:
          type: string
          description: 'Masked Access Key for the LAS File System, same length as original'
          example: '**************'
        secretKey:
          type: string
          description: 'Masked Secret Key for the LAS File System, same length as original'
          example: '***************************'
      required: [ 'endpoint', 'accessKey', 'secretKey' ]

    CreateConnectionResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: integer
              description: 'Generated integer ID of newly created connection'
              example: 1

    ListConnectionsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
                description: 'ID of the connection'
                example: 12345
              name:
                $ref: '#/components/schemas/ConnectionName'
              type:
                $ref: '#/components/schemas/ImportSourceType'
              createdAt:
                type: string
                description: 'Time when the connection was created'
                example: '2022-05-10T12:43:56.722117+08:00'

    ImportSourceType:
      type: string
      enum: [ LOCAL, S3, TOS, HIVE, KAFKA, KINESIS, ALI_OSS, MINIO, CFS, LASFS, MYSQL, BYTEHOUSE ]
      example: TOS

    UpdateConnectionRequest:
      type: object
      properties:
        name:
          type: string
          description: 'Name of the connection'
          example: 's3_connection_updated'
        data:
          oneOf:
            - $ref: '#/components/schemas/ConnectionDataS3'
            - $ref: '#/components/schemas/ConnectionDataTOS'
            - $ref: '#/components/schemas/ConnectionDataKafka'
            - $ref: '#/components/schemas/ConnectionDataMySql'
            - $ref: '#/components/schemas/ConnectionDataCFS'
            - $ref: '#/components/schemas/ConnectionDataLASFS'
      required: [ 'name', 'data' ]

    CreateImportJobRequest:
      allOf:
        - $ref: '#/components/schemas/ImportJob'

    ImportJob:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/ImportJobName'
        description:
          type: string
          description: '[Optional] To describe the job in more details'
        connectionID:
          type: integer
          description: 'ID of the connection which provides credentials to read data from source, for ByteHouse import job, connectionID should be 0'
        configuration:
          $ref: '#/components/schemas/ImportJobConfiguration'
        sourceSchema:
          $ref: '#/components/schemas/ImportJobSourceSchema'
        schemaFile:
          type: string
          description: 'Base64 encoded string of protobuf schema file, required for KAFKA PROTOBUF'
        state:
          $ref: '#/components/schemas/ImportJobState'
      required: [ "name", "configuration", "sourceSchema", "state" ]

    ImportJobName:
      type: string
      description: 'A descriptive name, 128 chars or less'
      example: 's3-cell-towers-csv'

    ImportJobConfiguration:
      type: object
      properties:
        source:
          description: 'Provides essential details to locate the data from source'
          type: object
          properties:
            type:
              $ref: '#/components/schemas/ImportSourceType'
            properties:
              oneOf:
                - $ref: '#/components/schemas/ImportJobSourcePropertiesS3'
                - $ref: '#/components/schemas/ImportJobSourcePropertiesTOS'
                - $ref: '#/components/schemas/ImportJobSourcePropertiesKafka'
                - $ref: '#/components/schemas/ImportJobSourcePropertiesCFS'
                - $ref: '#/components/schemas/ImportJobSourcePropertiesLASFS'
                - $ref: '#/components/schemas/ImportJobSourcePropertiesByteHouse'
            parser:
              description: 'Instructs the parser to parses the data, such as CSV with comma or tab. Different format has different properties. This field can be omitted for ByteHouse data source'
              type: object
              properties:
                type:
                  $ref: '#/components/schemas/ImportJobParserType'
                properties:
                  oneOf:
                    - $ref: '#/components/schemas/ImportJobParserPropertiesCSV'
                    - $ref: '#/components/schemas/ImportJobParserPropertiesParquet'
                    - $ref: '#/components/schemas/ImportJobParserPropertiesJsonKafka'
                    - $ref: '#/components/schemas/ImportJobParserPropertiesProtobufKafka'
        sink:
          type: object
          properties:
            tableUUID:
              type: string
              format: uuid
              description: 'Sink (target) table UUID. Note that table name can be changed but its UUID is fixed'
            properties:
              type: object
              properties:
                loadingMode:
                  type: string
                  enum: [ FULL_REFRESH, OVERWRITE_PARTITION, APPEND, PARTIAL_COLUMNS ]
                  description: |
                    FULL_REFRESH would replace the entire table with the latest batch source.
                    OVERWRITE_PARTITION (previously known as INCREMENTAL) would append to the existing sink table with the new batches according to its partition.
                    ByteHouse would replace existing partitions instead of merging.
                    APPEND would simply append data to the existing sink table, without dropping any of the existing data.
                    PARTIAL_COLUMNS would load only specified columns into the sink table, as of Aug 2022, this loading mode
                    only support ByteHouse as data source.
        schema:
          type: object
          description: 'Defines schema mapping from source data to sink table'
          properties:
            strategy:
              type: string
              enum: [ NAME_CUSTOM_MAPPING ]
              description: 'As of now, only NAME_CUSTOM_MAPPING is supported. It requires explicit name mapping from source to sink column'
            columns:
              type: array
              items:
                type: object
                properties:
                  sourceColumnName:
                    type: string
                    example: 'unit price'
                  sinkColumnName:
                    type: string
                    example: 'unit_price'

    ImportJobSourcePropertiesS3:
      type: object
      properties:
        bucket:
          type: string
          example: 'bytehouse-data-express-test'
        region:
          type: string
          example: 'cn-north-1'
        fileNames:
          type: string
          example: 'cell_towers.json'
        pathPrefix:
          type: string
          example: 'shared/clickhouse/cell_towers/'

    ImportJobSourcePropertiesTOS:
      allOf:
        - $ref: '#/components/schemas/ImportJobSourcePropertiesS3'

    ImportJobSourcePropertiesKafka:
      type: object
      properties:
        topic:
          type: string
          example: transactions
        consumerGroup:
          type: string
          description: |-
            ByteHouse uses the existing consumer group or create a new one if the given consumer group does NOT exist.
            Please ensure that the user provided in connection has right to create the consumer group of the given name,
            e.g. consumer group with a given prefix in its name.
          example: bytehouse-dev-group-01
        numPartitions:
          type: integer
          example: 5
        maxPollIntervalMs:
          type: integer
          default: 3500
          description: The max time to poll from broker each iteration
        maxBlockSize:
          type: integer
          default: 65536
          description: The max size of block polled from Kafka once a time
        enableAsyncImport:
          type: boolean
          default: false
          description: |-
            Unique Key specific, whether to enable staging area for an unique table. Once enabled, the consuming speed
            should be faster, but will bring uncertain times of delay until data is fully visible or (queryable) to the client.
        defaultStartingOffset:
          type: string
          enum: [ CURRENT, EARLIEST, LATEST ]
      required: [ topic, consumerGroup, numPartitions ]

    ImportJobSourcePropertiesCFS:
      type: object
      properties:
        directoryPath:
          type: string
          example: 'shared/clickhouse/cell_towers/'
        fileNames:
          type: string
          example: 'cell_towers.json'

    ImportJobSourcePropertiesLASFS:
      allOf:
        - $ref: '#/components/schemas/ImportJobSourcePropertiesCFS'

    ImportJobSourcePropertiesByteHouse:
      type: object
      properties:
        sql:
          type: string
          example: "select date as date, id as id, name as name from a_db.a_table where date = '2021-01-01'"

    ImportJobParserType:
      type: string
      enum: [ CSV, JSON, AVRO, PARQUET, XLS, JSON_KAFKA, PROTOBUF_KAFKA ]
      example: CSV

    ImportJobParserPropertiesCSV:
      type: object
      properties:
        fieldSeparator:
          type: string
          default: ','
        encoding:
          type: string
          default: 'UTF-8'
        header:
          type: boolean
        quote:
          type: string
          default: '"'
          description: 'single quote or double quote'
      required: [ "header" ]

    ImportJobParserPropertiesParquet:
      type: object
      description: PARQUET format has no properties.

    ImportJobParserPropertiesJsonKafka:
      type: object
      description: JSON_KAFKA has no properties

    ImportJobParserPropertiesProtobufKafka:
      type: object
      properties:
        protobufMessageName:
          type: string
          description: Which message name from protobuf schema file to be used.
          example: Case
      required: [ protobufMessageName ]

    ImportJobSourceSchema:
      type: object
      description: 'Provides schema of the source data, optional for batch data sources'
      properties:
        properties:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: 'Source column/field name'
                example: radio
              type:
                type: string
                description: 'ByteHouse equivalent type of the source data type, refer: https://docs.bytehouse.cloud/en/docs/data-types'
                example: String
              example:
                type: string
                description: 'Example value of the column'
                example: "UMTS"
            required: [ "name", "type" ]

    ImportJobState:
      type: string
      enum: [ PUBLISHED, DRAFT ]
      description: 'DRAFT means the job is partially created.'

    CreateImportJobResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: integer
              description: 'Generated integer ID of newly created import job'

    ListImportJobsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
                description: 'ID of the job'
                example: 398
              name:
                type: string
                description: 'Name of the job'
                example: sample-s3-sales-70
              accountID:
                type: integer
                description: 'User AccountID'
                example: 8635733085987518394
              sourceType:
                $ref: '#/components/schemas/ImportSourceType'
              tableUUID:
                type: string
                description: 'Table UUID'
                example: feb4b7a6-fbc7-4164-abf5-a705499b02f9
              databaseName:
                type: string
                description: 'Name of the database'
                example: brian
              tableName:
                type: string
                description: 'Name of the table'
                example: sales
              createdAt:
                type: string
                description: 'Time the object is created'
                example: 2022-05-10T13:21:21+08:00
              createdBy:
                type: string
                description: 'UserID of user who created the job'
                example: '8628611004645993074'
              ingestedRecords:
                type: integer
                description: 'Number of records that have been imported'
                example: 0
              lastExecutionStatus:
                $ref: '#/components/schemas/ExecutionStatus'
              state:
                $ref: '#/components/schemas/ImportJobState'

    ExecutionStatus:
      type: string
      enum: [ QUEUING, PROVISIONING, RUNNING, RETRYING, STOPPED, FAILED, SUCCEEDED ]
      nullable: true
      example: RUNNING

    GetImportJobResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ImportJob'

    UpdateImportJobRequest:
      allOf:
        - $ref: '#/components/schemas/ImportJob'

    RenameImportJobRequest:
      type: object
      properties:
        name:
          type: string
          description: 'New name of import job'
          example: 'Job Updated Name'

    UpdateImportJobDescriptionRequest:
      type: object
      properties:
        description:
          type: string
          description: 'New description of import job'
          example: 'Job Updated Description'

    GetImportJobStartArgsResponse:
      type: object
      properties:
        data:
          oneOf:
            - $ref: '#/components/schemas/ImportJobStartArgsLocal'
            - $ref: '#/components/schemas/ImportJobStartArgsS3'
            - $ref: '#/components/schemas/ImportJobStartArgsKafka'
            - $ref: '#/components/schemas/ImportJobStartArgsCFS'
            - $ref: '#/components/schemas/ImportJobStartArgsLASFS'
            - $ref: '#/components/schemas/ImportJobStartArgsByteHouse'

    ImportJobStartArgsLocal:
      type: object
      properties:
        source.properties.fileStagingLocation:
          type: object
          properties:
            description:
              type: string
              description: 'Full path of uploaded file for the local ingestion job'
              example: 'Full path of uploaded file for the local ingestion job'
            type:
              type: string
              example: 'string'
            default:
              description: 'Default value'
              example: "employees.csv"
            required:
              type: boolean
              example: true

    ImportJobStartArgsS3:
      type: object
      properties:
        source.properties.fileNames:
          type: object
          properties:
            description:
              type: string
              example: "File names for the ingestion job"
              description: "File names for the ingestion job"
            type:
              type: string
              example: string
            default:
              type: string
              example: "part-00000-25631340-e09e-4fb7-a616-12c723a06de6-c000.avro"
            required:
              type: boolean
              example: true

    ImportJobStartArgsKafka:
      type: object
      properties:
        source.properties.defaultStartingOffset:
          type: object
          properties:
            description:
              type: string
              example: "defaultStartingOffset for all partitions, options are CURRENT, LATEST, EARLIEST."
              description: "defaultStartingOffset for all partitions, options are CURRENT, LATEST, EARLIEST."
            type:
              type: string
              example: string
            default:
              type: string
              example: CURRENT
            required:
              type: boolean
              example: false
        source.properties.offsets:
          type: object
          properties:
            description:
              type: string
              description: "Offsets to start consuming from, by default will continue from current offsets."
              example: "Offsets to start consuming from, by default will continue from current offsets."
            type:
              type: string
              example: string
            default:
              type: string
              example: "[]"
            required:
              type: boolean
              example: true

    ImportJobStartArgsCFS:
      allOf:
        - $ref: '#/components/schemas/ImportJobStartArgsS3'

    ImportJobStartArgsLASFS:
      allOf:
        - $ref: '#/components/schemas/ImportJobStartArgsS3'

    ImportJobStartArgsByteHouse:
      type: object
      properties:
        source.properties.sql:
          type: object
          properties:
            description:
              type: string
              example: 'SQL to run in ByteHouse, result will be data source'
              description: 'SQL to run in ByteHouse, result will be data source'
            type:
              type: string
              example: string
            default:
              type: string
              example: "select date as date, id as id, name as name from db_a.table_a where date = '2021-01-01'"
            required:
              type: boolean
              example: false
        virtualWarehouse:
          type: object
          properties:
            description:
              type: string
              example: 'ID of the virtualWarehouse that will be used to run the data loading queries'
              description: 'ID of the virtualWarehouse that will be used to run the data loading queries'
            type:
              type: string
              example: string
            default:
              type: string
              example: ''
            required:
              type: boolean
              example: true

    StartImportJobRequest:
      oneOf:
        - $ref: '#/components/schemas/StartImportJobS3Request'
        - $ref: '#/components/schemas/StartImportJobLocalRequest'
        - $ref: '#/components/schemas/StartImportJobKafkaRequest'
        - $ref: '#/components/schemas/StartImportJobCFSRequest'
        - $ref: '#/components/schemas/StartImportJobLASFSRequest'
        - $ref: '#/components/schemas/StartImportJobByteHouseRequest'

    StartImportJobS3Request:
      type: object
      properties:
        source.properties.fileNames:
          type: string
          example: "Forestry_Planting_Spaces.csv"

    StartImportJobLocalRequest:
      type: object
      properties:
        source.properties.fileStagingLocation:
          type: string
          example: "employees.csv"

    StartImportJobKafkaRequest:
      type: object
      properties:
        source.properties.defaultStartingOffset:
          type: string
          nullable: true
        source.properties.offsets:
          type: array
          items:
            type: object
            properties:
              partition:
                type: integer
                example: 1
              offset:
                type: integer
                example: -2

    StartImportJobCFSRequest:
      allOf:
        - $ref: '#/components/schemas/StartImportJobS3Request'

    StartImportJobLASFSRequest:
      allOf:
        - $ref: '#/components/schemas/StartImportJobS3Request'

    StartImportJobByteHouseRequest:
      type: object
      properties:
        virtualWarehouse:
          type: string
          example: "vw-1234567890-testvw"

    StartImportJobResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            executionID:
              $ref: '#/components/schemas/ExecutionID'

    ExecutionID:
      type: string
      format: uuid
      description: 'Globally unique ID of the execution'

    ListImportJobExecutionsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              id:
                $ref: '#/components/schemas/ExecutionID'
              jobID:
                type: integer
                description: Job ID
                example: 28834
              jobName:
                $ref: '#/components/schemas/ImportJobName'
              sourceType:
                $ref: '#/components/schemas/ImportSourceType'
              startedAt:
                type: string
                format: date-time
                example: '2022-05-12T03:28:22Z'
              durationInMs:
                type: integer
                example: 10760
              status:
                $ref: '#/components/schemas/ExecutionStatus'
              diagnostics:
                type: string
                example: ""
                nullable: true
              startedBy:
                type: integer
                description: UserID who started the executions
                example: 1360734397924064705
              numIngestedRecords:
                type: integer
                example: 0
              tableUUID:
                type: string
                description: UUID of the table
                example: 5f7ae696-651c-4252-b193-74a830c1f21a
              percentageCompletion:
                type: number
                example: 99.9
                nullable: true
              estimatedTimeLeftInMs:
                type: integer
                example: 0
                nullable: true

    ListImportExecutionsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              id:
                $ref: '#/components/schemas/ExecutionID'
              jobID:
                type: integer
                description: 'ID of the Job'
                example: 40449
              jobName:
                $ref: '#/components/schemas/ImportJobName'
              sourceType:
                $ref: '#/components/schemas/ImportSourceType'
              category:
                $ref: '#/components/schemas/ExecutionCategory'
              tableUUID:
                type: string
                description: 'Table UUID'
                example: feb4b7a6-fbc7-4164-abf5-a705499b02f9
              databaseName:
                type: string
                description: 'Name of the database'
                example: brian
              tableName:
                type: string
                description: 'Name of the table'
                example: sales
              startedAt:
                type: string
                description: 'Time the object is created'
                example: 2022-05-10T13:21:21+08:00
              startedBy:
                type: integer
                description: 'UserID of user who started the executions'
                example: 8628611004645993074
              durationInMs:
                type: integer
                description: 'Duration of the execution'
                example: 12420
              status:
                $ref: '#/components/schemas/ExecutionStatus'
              diagnostics:
                nullable: true
                type: string
              numIngestedRecords:
                type: integer
                description: 'Number of records that have been imported'
                example: 0
              numRejectedRecords:
                type: integer
                description: 'Number of records that have been rejected'
                example: 0
              percentageCompletion:
                type: number
                example: 99.9
                nullable: true
              estimatedTimeLeftInMs:
                type: integer
                example: 0
                nullable: true

    ExecutionCategory:
      type: string
      enum: [ BATCH, STREAMING ]
      example: BATCH

    GetMaskedConnectionResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: integer
              example: 48613
            name:
              type: string
              example: TOS china source
            type:
              $ref: '#/components/schemas/ImportSourceType'
            data:
              oneOf:
                - $ref: '#/components/schemas/ConnectionMaskedDataS3'
                - $ref: '#/components/schemas/ConnectionMaskedDataTOS'
                - $ref: '#/components/schemas/ConnectionMaskedDataKafka'
                - $ref: '#/components/schemas/ConnectionMaskedDataMySql'
                - $ref: '#/components/schemas/ConnectionMaskedDataCFS'
                - $ref: '#/components/schemas/ConnectionMaskedDataLASFS'
            accountID:
              type: integer
              example: 3093442639250928090
            userID:
              type: integer
              example: 1360734397924064705
            createdAt:
              type: string
              format: date-time
              example: 2022-04-27T04:36:11Z

    GetImportExecutionResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              $ref: '#/components/schemas/ExecutionID'
            jobID:
              type: integer
              example: 40395
            connectionID:
              type: integer
              example: 48613
            status:
              $ref: '#/components/schemas/ExecutionStatus'
            statusChangedAt:
              type: string
              format: date-time
              example: "2022-05-04T07:12:31Z"
            accountID:
              type: integer
              example: 3093442639250928090
            userID:
              type: integer
              example: 1360734397924064705
            createdAt:
              type: string
              format: date-time
              example: 2022-04-27T04:36:11Z
            startedAt:
              type: string
              format: date-time
              example: 2022-04-27T04:36:11Z
            finishedAt:
              type: string
              example: 0001-01-01T00:00:00Z
            durationInMs:
              type: integer
              example: 614179673
            sourceType:
              $ref: '#/components/schemas/ImportSourceType'
            configuration:
              $ref: '#/components/schemas/ImportJobConfiguration'
            sourceSchema:
              $ref: '#/components/schemas/ImportJobSourceSchema'
            schemaFile:
              type: string
              example: ""
              nullable: true
            diagnostics:
              type: string
              example: ""
              nullable: true
            numIngestedRecords:
              type: integer
              example: 0
            numRejectedRecords:
              type: integer
              example: 0
            percentageCompletion:
              type: number
              example: 99.9
              nullable: true
            estimatedTimeLeftInMs:
              type: integer
              example: 0
              nullable: true

    GetImportExecutionLogsResponse:
      type: string
      example: "2022-08-16 09:56:04,814 [mainn] INFO  org.apache.hadoop.mapreduce.util.ConfigUtil..."

    GetKafkaConsumingStatusResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              currentOffset:
                description: |-
                  Latest value of current offset of the consumer group on the given partition of the given topic
                  in the time window (of length granularity specified in query parameter).
                type: integer
                example: 12345
              lag:
                description: |-
                  Latest value of lag (difference between latest offset and current offset) of the consumer group
                  on the given partition of the given topic in the time window (of length granularity specified in query parameter).
                type: integer
                example: 2
              consumptionSpeed:
                description: |-
                  Average consumption speed of the time window (of length granularity specified in query parameter)
                  calculated by the number of records consumed per minute'.
                type: number
                example: 3.2
              time:
                description: |-
                  End datetime of the time window (of length granularity specified in query parameter)
                  where the kafka consuming status metrics is calculated.
                type: string
                example: '2022-05-12T11:15:00.000+08:00'
    Resource:
      type: object
      properties:
        cpu:
          description: |-
            float when 0<cpu<1; int when cpu >= 1
          type: string
          example: '2'
        memory:
          description: |-
            positive integer following with "Gi"
          type: string
          example: 10Gi
    VWResources:
      type: object
      properties:
        limits:
          description: |-
            maxmum resouces for vw
          $ref: "#/components/schemas/Resource"
        requests:
          description: |-
            basic resouces for vw
          $ref: "#/components/schemas/Resource"
    VWID:
      description: vwID, can be used in query
      type: string
      example: vw-123456789-vwname
    VWName:
      description: |-
        vw name.
        - string length should > 0 and < 32;
        - may contain digital, lower case letter or '_';
        - should start with lower case letter;
        - should end with digital or lower case letter.
      type: string
      example: depart1_name2
    VWDescription:
      type: string
      example: some description about this VW
      default: ""
    VWDescriptionNullable:
      type: string
      example: some description about this VW
      nullable: true
    VWConfigID:
      description: |-
        configID should > 0, you can get available resource settings by "list config" api.
      type: integer
      example: 123456
    VWConfigIDNullable:
      description: |-
        configID should > 0, you can get available resource settings by "list config" api.
      type: integer
      example: 123456
      nullable: true
    VWAutoSuspend:
      type: integer
      description: |-
        VW will auto suspend after x minutes of idleness.
        If set to 0(default), VW will never auto suspend.
        The value should be >= 0;
      example: 5
      default: 0
    VWAutoSuspendNullable:
      type: integer
      description: |-
        VW will auto suspend after x minutes of idleness.
        If set to 0(default), VW will never auto suspend.
        The value should be >= 0;
      example: 5
      nullable: true
    VWAutoResume:
      type: boolean
      description: |-
        If set to true, the VW will try auto resume when query arrives.
      example: true
      default: false
    VWAutoResumeNullable:
      type: boolean
      description: |-
        If set to true, the VW will try auto resume when query arrives.
      example: true
      nullable: true
    VWStatusParam:
      description: indicate target status of the vw. "up"-run/resume; "down"-suspend.
      type: string
      example: "up"
      default: "up"
    VWStatusParamNullable:
      description: indicate target status of the vw. "up"-run/resume; "down"-suspend.
      type: string
      example: "up"
      nullable: true
    VWStatusDisplay:
      description: |-
        show current status of the vw.
        - "up"-running;
        - "down"-suspending;
        - "pending"-warehouse is in the middle of starting up/shutting down workers;
        - "awaiting_resources"-no enough resources for creating/resuming the warehouse;
      type: string
      example: "up"
    VWReplicas:
      type: integer
      description: instance count for the VW
      example: 2
      default: 0
    VWPreview:
      type: boolean
      description: if dry run
      example: true
      default: false
    VirtualWarehouse:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/VWID'
        name:
          $ref: '#/components/schemas/VWName'
        description:
          $ref: '#/components/schemas/VWDescription'
        configID:
          $ref: '#/components/schemas/VWConfigID'
        status:
          $ref: '#/components/schemas/VWStatusDisplay'
        autoSuspend:
          $ref: '#/components/schemas/VWAutoSuspend'
        autoResume:
          $ref: '#/components/schemas/VWAutoResume'
        createdAt:
          $ref: '#/components/schemas/DateTime'
        lastModifiedAt:
          $ref: '#/components/schemas/DateTime'
    ListVirtualWarehouseResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/VirtualWarehouse"
    CreateVirtualWarehouseRequest:
      type: object
      properties:
        name:
          $ref: "#/components/schemas/VWName"
        status:
          $ref: "#/components/schemas/VWStatusParam"
        autoSuspend:
          $ref: "#/components/schemas/VWAutoSuspend"
        autoResume:
          $ref: "#/components/schemas/VWAutoResume"
        configID:
          $ref: "#/components/schemas/VWConfigID"
        description:
          $ref: '#/components/schemas/VWDescription'
      required: [ "name", "configID" ]
    UpdateVirtualWarehouseRequest:
      type: object
      description: all of the request fields are nullable, you can just change the specific fields.
      properties:
        description:
          $ref: "#/components/schemas/VWDescriptionNullable"
        configID:
          $ref: "#/components/schemas/VWConfigIDNullable"
        status:
          $ref: "#/components/schemas/VWStatusParamNullable"
        autoSuspend:
          $ref: "#/components/schemas/VWAutoSuspendNullable"
        autoResume:
          $ref: "#/components/schemas/VWAutoResumeNullable"
    ObjectUpdatePreview:
      type: object
      properties:
        currentConfig:
          type: string
        newConfig:
          type: string
    CreateVirtualWarehouseResponse:
      type: object
      properties:
        name:
          description: real name after "correction", like "vw-name" to "vw_name".
          type: string
        vwID:
          $ref: "#/components/schemas/VWID"
    VirtualWarehouseConfig:
      type: object
      properties:
        id:
          description: VWConfigID, can be used in create/update vw
          type: integer
          example: 10
        name:
          description: name of the config, easy to recognize
          type: string
          example: XS
        cpu:
          description: CPU size, float when 0<cpu<1, int when cpu >= 1
          type: string
          example: '0.6'
        memory:
          description: Memory size, string with positive integer following with Gi
          type: string
          example: 2Gi
        replica:
          $ref: '#/components/schemas/VWReplicas'
        isDefault:
          description: |-
            indicate whether the config is available for all tentants or specified tentants.
            - true - all tenants can get this config.
            - false - only specified tentants can get this config.
          type: boolean
          example: true
        createdAt:
          $ref: '#/components/schemas/DateTime'
    ListVirtualWarehouseConfigResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/VirtualWarehouseConfig"
    PartitionNames:
      type: object
      properties:
        partitionNames:
          type: array
          items:
            type: string
            example: "partition_name1"

    ##########################################
    #            IAM API Components          #
    ##########################################
    # API Keys

    CreateAPIKeyRequest:
      description: Request body to create API key.
      type: object
      properties:
        noExpiry:
          type: boolean
          description: Defines whether the API key has an expiry time or not. If set to true, `expiryInDays` will be ignored.
          example: false
        expiryInDays:
          type: integer
          description: Defines the expiry time (in days) of the created API key starting from time of creation.
          example: 90
        comment:
          type: string
          description: API key description / comment.

    CreateAPIKeyResponse:
      description: Create API key response body definition
      allOf:
        - type: object
          description: Response data
          properties:
            data:
              type: object
              description: API key object definition
              properties:
                id:
                  type: string
                  description: API key ID
                  example: "8914859996411850157"
                key:
                  type: string
                  description: API key (raw value)
                  example: "qUNomoCoqSokljuoRs5z"
                status:
                  $ref: '#/components/schemas/ApiKeyStatus'
                noExpiry:
                  type: boolean
                  description: flag indicating the API key having no expiry time (will not be present on expiring key)
                  example: false
                expiredAt:
                  description: API Key expiry time (will not be present on non-expiring key)
                  $ref: '#/components/schemas/DateTime'
                createdAt:
                  $ref: '#/components/schemas/DateTime'
                updatedAt:
                  $ref: '#/components/schemas/DateTime'
                comment:
                  type: string
                  description: API key description / comment.

    ListAPIKeysResponse:
      description: List API keys response
      allOf:
        - type: object
          description: Response data
          properties:
            data:
              type: array
              description: List of masked API key(s)
              items:
                type: object
                description: Masked API key details
                properties:
                  id:
                    type: string
                    description: API Key ID
                    example: "8914859996411850157"
                  maskedKey:
                    type: string
                    description: API Key (masked)
                    example: "qUNomoCoqS**********"
                  status:
                    $ref: '#/components/schemas/ApiKeyStatus'
                  expiredAt:
                    description: API Key expiry time (will not be present on non-expiring key)
                    $ref: '#/components/schemas/DateTime'
                  createdAt:
                    $ref: '#/components/schemas/DateTime'
                  updatedAt:
                    $ref: '#/components/schemas/DateTime'
                  noExpiry:
                    type: boolean
                    description: flag indicating the API key having no expiry time (will not be present on expiring key)
                    example: false
                  comment:
                    type: string
                    description: API key description / comment
                  accountID:
                    type: integer
                    description: Account ID

    ApiKeyStatus:
      type: string
      description: API key status
      enum: [ ENABLED, DISABLED ]
      example: "ENABLED"

    # Privileges

    BRNResource:
      type: string
      description: |-
        Resource in BRN format (brn:[accountID]:[region]:[resource]).
        Examples:
          - brn:123456789:cn-beijing:data/database:my_db/table:my_table
          - brn:123456789:cn-beijing:data/database:my_db/*
          - brn:123456789:cn-beijing:data/database:my_db
          - brn:123456789:cn-beijing:data/*
          - brn:123456789:cn-beijing:warehouse:my_vw
          - brn:123456789:cn-beijing:job:my_job
    Principal:
      type: object
      description: "Principal containing the principal type and ID"
      required:
        - type
        - id
      properties:
        type:
          type: string
          description: 'Principal type.'
          enum:
            - "USER"
            - "ROLE"
        id:
          type: string
          description: Principal ID (user ID or role name).
    ActionDisplay:
      type: object
      description: Privilege action details.
      properties:
        action:
          type: string
          description: Actions to be granted on the resource
          enum: ["CREATE", "SHOW", "ALTER", "DROP", "SELECT", "INSERT"]
          example: "SHOW"
        grant:
          type: boolean
          description: Allow the user or role to grant this privilege to another.
        mutable:
          type: boolean
          description: The privilege can be modified because it is granted on this exact scope, not from higher scope privileges.
    IAMListActionsRequest:
      type: object
      description: Request body to list resource actions.
      properties:
        resources:
          type: array
          description: List of resources to list the actions of. Only the type matters in this call.
          items:
            $ref: "#/components/schemas/BRNResource"
    IAMListActionsResponse:
      type: object
      description: Response body of successful list actions request.
      required:
        - data
      properties:
        data:
          type: object
          description: Response data.
          required: [ 'resource_actions' ]
          properties:
            resource_actions:
              type: array
              description: List of available valid actions for resource types.
              items:
                type: object
                description: Mapping between resources and their actions.
                properties:
                  resource:
                    $ref: "#/components/schemas/BRNResource"
                  actions:
                    type: array
                    description: List of privileges.
                    items:
                      type: string
                      description: Actions to be granted on the resource
                      example: "CREATE"
    CheckPrivilegesRequest:
      type: object
      description: Request structure to check privileges.
      properties:
        privileges:
          type: array
          description: List of action(s) on resource(s) to check.
          items:
            $ref: "#/components/schemas/PrivilegeCheck"
    CheckPrivilegesResponse:
      type: object
      description: response structure to check privileges.
      properties:
        allowed:
          type: array
          description: List of allowed action(s) on resource(s).
          items:
            $ref: "#/components/schemas/PrivilegeCheck"
        denied:
          type: array
          description: List of non-allowed action(s) on resource(s).
          items:
            $ref: "#/components/schemas/PrivilegeCheck"
    PrivilegeGrant:
      type: object
      description: Represents the actions to grant/revoke on/from a resource.
      properties:
        resource:
          $ref: "#/components/schemas/BRNResource"
        actions:
          type: array
          items:
            type: string
            description: Individual action to grant.
          description: Actions to grant/revoke on/from the resource.
        grant_option:
          type: boolean
          description: Set to `true` to check if the user can grant the privilege to others.
    PrivilegeCheck:
      type: object
      description: Represents the action to be checked on a resource.
      properties:
        resource:
          $ref: "#/components/schemas/BRNResource"
        action:
          $ref: "#/components/schemas/ResourceAction"
        grant_option:
          type: boolean
          description: Set to `true` to check if the user can grant the privilege to others.
    ResourceAction:
      description: Resource action, enums depend on the type of the resource. See "List resource actions".
      type: string
      enum: ["CREATE", "ALTER", "DROP", "SHOW", "SELECT", "INSERT", "OPTIMIZE", "TRUNCATE", "GET", "EXECUTE"]
    GrantPrivilegeRequest:
      type: object
      description: "Request body to grant privileges"
      required:
      - resource
      - principal
      - actions
      - grant
      properties:
        resource:
          $ref: "#/components/schemas/BRNResource"
        principal:
          $ref: "#/components/schemas/Principal"
        actions:
          type: array
          items:
            $ref: "#/components/schemas/ResourceAction"
          description: Actions to be granted on the resource. See "List resource actions".
        grant_option:
          type: boolean
          description: Allow the user or role to grant this privilege to another.
    RevokePrivilegeRequest:
      type: object
      description: "Request body to revoke privileges"
      required:
      - resource
      - principal
      - actions
      properties:
        resource:
          $ref: "#/components/schemas/BRNResource"
        principal:
          $ref: "#/components/schemas/Principal"
        actions:
          type: array
          items:
            $ref: "#/components/schemas/ResourceAction"
          description: Actions to be revoked on the resource. See "List resource actions".
    ListPrivilegesRequest:
      type: object
      description: Request body to list privileges.
      properties:
        principal:
          $ref: "#/components/schemas/Principal"
        resources:
          type: array
          description: List of resources to list the privileges of.
          items:
            type: string
            description: Resource in BRN format.
            example: "brn:123456789:cn-beijing:data/database:my_db/table:my_table"
    ListPrivilegesResponse:
      type: object
      description: Response body of successful list privileges request.
      required:
      - data
      properties:
        data:
          type: object
          description: Response data.
          properties:
            privileges:
              type: array
              description: List of privileges.
              items:
                type: object
                description: Privilege display info.
                properties:
                  resource:
                    $ref: "#/components/schemas/BRNResource"
                  actions:
                    type: array
                    description: Actions details
                    items:
                      $ref: '#/components/schemas/ActionDisplay'
    ListPrincipalsRequest:
      type: object
      description: Request body to list privileges.
      properties:
        resources:
          type: array
          description: List of resources to list the privileges of.
          items:
            type: string
            description: Resource in BRN format.
            example: "brn:123456789:cn-beijing:data/database:my_db/table:my_table"
    ListPricipalsResponse:
      type: object
      description: Response body of successful list principals request.
      required:
      - data
      properties:
        data:
          type: object
          description: Response data.
          properties:
            principals:
              type: array
              description: List of principals and their privileges.
              items:
                type: object
                description: Privilege display info.
                properties:
                  principal:
                    $ref: "#/components/schemas/Principal"
                  privileges:
                    type: array
                    description: principals' privileges
                    items:
                      type: object
                      description: principal's privileges
                      properties:
                        resource:
                          $ref: "#/components/schemas/BRNResource"
                        actions:
                          type: array
                          description: Actions details
                          items:
                            $ref: '#/components/schemas/ActionDisplay'
    ListPrivilegesPrincipalsRequest:
      type: object
      description: Request body to list privileges principals.
      properties:
        privileges:
          type: array
          description: List of resources to list the privileges of.
          items:
            $ref: "#/components/schemas/PrivilegeGrant"
    ListPrivilegesPrincipalsResponse:
      type: object
      description: Response body of successful list privileges principals request.
      required:
      - data
      properties:
        data:
          type: object
          description: Response data.
          properties:
            privileges:
              type: array
              description: List of privileges and their principals.
              items:
                type: object
                description: Privilege display info.
                properties:
                  resource:
                    $ref: "#/components/schemas/BRNResource"
                  principals:
                    type: array
                    description: Privilege's principals actions.
                    items:
                      type: object
                      description: Privilege's principal actions.
                      properties:
                        principal:
                          $ref: "#/components/schemas/Principal"
                        actions:
                          type: array
                          description: Actions details
                          items:
                            $ref: '#/components/schemas/ActionDisplay'

    # Roles

    CreateRoleRequest:
      type: object
      description: "Request body to create a new role"
      required:
      - name
      properties:
        name:
          type: string
          description: "Name of the role. This will be the main identifier of the role."
          example: "my_new_role"
        description:
          type: string
          description: "Description of the role"
    ListRolesResponse:
      description: "Response body of a successful role list"
      type: array
      items:
        type: string
        description: Role name (identifier)
        example: "my_new_role"

    GetRoleRequest:
      type: object
      description: "Request body to get the details of a role"
      required:
      - name
      properties:
        name:
          type: string
          description: "Name of the role"
          example: "my_new_role"
    GetRoleResponse:
      type: object
      description: "Response body of a successful role fetch"
      properties:
        name:
          type: string
          description: Role name (identifier)
          example: "my_new_role"
        description:
          type: string
          description: Description of the role, may be empty.
          example: "My new role"
        created_at:
          type: string
          description: Time of creation
          example: "2024-07-16T10:25:39.144Z"

    DeleteRoleRequest:
      type: object
      description: "Request body to delete a role"
      required:
      - name
      properties:
        name:
          type: string
          description: "Name of the role to delete"
          example: "my_new_role"

    AssignRoleToUserRequest:
      type: object
      description: "Request body to assign a role to a user"
      required:
      - role_name
      - user_id
      properties:
        role_name:
          type: string
          description: "Name of the role to assign"
          example: "my_new_role"
        user_id:
          type: integer
          description: "User ID to assign the role to"
          example: 123
    UnassignRoleFromUserRequest:
      type: object
      description: "Request body to unassign a role from a user"
      required:
      - role_name
      - user_id
      properties:
        role_name:
          type: string
          description: "Name of the role to unassign"
          example: "my_new_role"
        user_id:
          type: integer
          description: "User ID to unassign the role from"
          example: 123
    ListRoleAssignmentsRequest:
      type: object
      description: "Request body to list role assignments"
      properties:
        role_names:
          type: array
          description: "Optional role names filter"
          items:
            type: string
            description: "Role name"
          example: ["my_role", "my_new_role"]
        user_ids:
          type: array
          description: "Optional user IDs filter"
          items:
            type: integer
            description: "User ID"
          example: [123, 456]
    ListRoleAssignmentsResponse:
      type: object
      description: Response body of successful list role assignments request.
      required:
        - data
      properties:
        data:
          type: object
          description: Response data.
          required:
            - assignments
          properties:
            assignments:
              type: array
              description: List of role assignments.
              items:
                type: object
                description: Role assignment.
                properties:
                  role_name:
                    type: string
                    description: "Name of the assigned role"
                    example: "my_new_role"
                  user_id:
                    type: integer
                    description: "ID of the user that is assigned with the role"
                    example: 123

    ##########################################
    #        End of IAM API Components       #
    ##########################################

  headers:
    querySessionHeader:
      description: Query/Worksheet session ID
      schema:
        type: string

security:
  - BearerAuth: [ ]