spec/polaris-catalog-apis/generic-tables-api.yaml

#
# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements.  See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership.  The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License.  You may obtain a copy of the License at
#
#   http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied.  See the License for the
# specific language governing permissions and limitations
# under the License.
#

---
paths:
  /polaris/v1/{prefix}/namespaces/{namespace}/generic-tables:
    parameters:
      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/namespace'

    get:
      tags:
        - Generic Table API
      summary: List all generic tables identifiers underneath a given namespace
      description: Return all generic table identifiers under this namespace
      operationId: listGenericTables
      parameters:
        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
      responses:
        200:
          $ref: '#/components/responses/ListGenericTablesResponse'
        400:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
        403:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
        404:
          description: Not Found - The namespace specified does not exist
          content:
            application/json:
              schema:
                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
              examples:
                NamespaceNotFound:
                  $ref: '../iceberg-rest-catalog-open-api.yaml#/components/examples/NoSuchNamespaceError'
        503:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
        5XX:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'

    post:
      tags:
        - Generic Table API
      summary: Create a generic table under the given namespace
      description:
        Create a generic table under the given namespace, and return the created table information as a response.
      operationId: createGenericTable
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGenericTableRequest'
      responses:
        200:
          $ref: '#/components/responses/CreateGenericTableResponse'
        400:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
        403:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
        404:
          description: Not Found - The namespace specified does not exist
          content:
            application/json:
              schema:
                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
              examples:
                NamespaceNotFound:
                  $ref: '../iceberg-rest-catalog-open-api.yaml#/components/examples/NoSuchNamespaceError'
        409:
          description: Conflict - The table already exists under the given namespace
          content:
            application/json:
              schema:
                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
              examples:
                TableAlreadyExists:
                  $ref: '../iceberg-rest-catalog-open-api.yaml#/components/examples/TableAlreadyExistsError'
        503:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
        5XX:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'

  /polaris/v1/{prefix}/namespaces/{namespace}/generic-tables/{generic-table}:
    parameters:
      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/namespace'
      - $ref: '#/components/parameters/generic-table'

    get:
      tags:
        - Generic Table API
      summary: Load a generic table under the given namespace from the catalog
      operationId: loadGenericTable
      description:
        Load a generic table from the catalog under the given namespace.
      
        The response contains all table information passed during create.

      responses:
        200:
          $ref: '#/components/responses/LoadGenericTableResponse'
        400:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
        403:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
        404:
          description:
            Not Found - NoSuchTableError, generic table to load does not exist
          content:
            application/json:
              schema:
                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
              examples:
                TableToLoadDoesNotExist:
                  $ref: '../iceberg-rest-catalog-open-api.yaml#/components/examples/NoSuchTableError'
        503:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
        5XX:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'

    delete:
      tags:
        - Generic Table API
      summary: Drop a generic table under the given namespace from the catalog
      operationId: dropGenericTable
      description: Remove a table under the given namespace from the catalog
      responses:
        204:
          description: Success, no content
        400:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
        403:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
        404:
          description:
            Not Found - NoSuchTableError, Generic table to drop does not exist
          content:
            application/json:
              schema:
                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
              examples:
                TableToDeleteDoesNotExist:
                  $ref: '../iceberg-rest-catalog-open-api.yaml#/components/examples/NoSuchTableError'
        503:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
        5XX:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'

components:
  parameters:
    generic-table:
      name: generic-table
      in: path
      description: A generic table name
      required: true
      schema:
        type: string
      example: "sales"

  schemas:
    CreateGenericTableRequest:
      type: object
      required:
        - name
        - format
      properties:
        name:
          type: string
        format:
          type: string
        base-location:
          type: string
        doc:
          type: string
        properties:
          type: object
          additionalProperties:
            type: string

    GenericTable:
      type: object
      description: >
        Generic Table information.
        
        - `name` (REQUIRED): name for the generic table
        
        - `format` (REQUIRED): format for the generic table, i.e. "delta", "csv"
        
        - `base-location` (OPTIONAL): table base location in URI format. For example: s3://<my-bucket>/path/to/table.
          - The table base location is a location that includes all files for the table.
          - A table with multiple disjoint locations (i.e. containing files that are outside the configured base location) is not compliant with the current generic table support in Polaris.
          - If no location is provided, clients or users are responsible for managing the location.
        
        - `properties` (OPTIONAL): properties for the generic table passed on creation
        
        - `doc` (OPTIONAL): comment or description for the generic table
      required:
        - name
        - format
      properties:
        name:
          type: string
        format:
          type: string
        base-location:
          type: string
        doc:
          type: string
        properties:
          type: object
          additionalProperties:
            type: string

    LoadGenericTableResponse:
      description: Result used when a table is successfully loaded.
      type: object
      required:
        - table
      properties:
        table:
          $ref: '#/components/schemas/GenericTable'

    ListGenericTablesResponse:
      type: object
      properties:
        next-page-token:
          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/PageToken'
        identifiers:
          type: array
          uniqueItems: true
          items:
            $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/TableIdentifier'

  responses:

    LoadGenericTableResponse:
      description: Table result if successfully load a generic table.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LoadGenericTableResponse'


    CreateGenericTableResponse:
      description: Table result if successfully created a generic table.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LoadGenericTableResponse'


    ListGenericTablesResponse:
      description: List of generic table identifiers.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ListGenericTablesResponse'