Unity Catalog Delta Commits API

openapi: 3.2.0
info:
  title: Unity Catalog Delta Commits API
  version: '0.1'
  description: '"Delta commits" is a Delta tables feature that allows Delta tables to designate a coordinator to coordinate commits. This is Unity Catalog''s API to allow Unity Catalog be the commit coordinator for managed tables. (See https://github.com/delta-io/delta/blob/master/protocol_rfcs/catalog-managed.md for more details)'
servers:
- url: http://localhost:8080/api/2.1/unity-catalog
  description: Localhost reference server
tags:
- name: DeltaCommits
  description: '"Delta commits" is a Delta tables feature that allows Delta tables to designate a coordinator to coordinate commits. This is Unity Catalog''s API to allow Unity Catalog be the commit coordinator for managed tables. (See https://github.com/delta-io/delta/blob/master/protocol_rfcs/catalog-managed.md for more details)'
paths:
  /delta/preview/commits:
    get:
      operationId: getCommits
      tags:
      - DeltaCommits
      summary: List unbackfilled Delta table commits.
      description: 'List all the unbackfilled Delta commits that are currently being tracked by the UC coordinator.

        If no commits are being tracked in the specific version range (from start_version to an optional end_version),

        it will return an empty list.

        WARNING: This API is experimental and may change in future versions.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeltaGetCommits'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeltaGetCommitsResponse'
        '400':
          description: 'Bad request or Invalid Argument. Example: table_uri in the request doesn''t match the existing table_uri for the table.

            '
        '401':
          description: Unauthorized. Authentication credentials are missing or incorrect.
        '403':
          description: Forbidden. The user does not have the necessary permissions to perform this action.
        '404':
          description: Not Found. The specified table does not exist.
        '500':
          description: Internal Server Error. An unexpected error occurred on the server.
    post:
      tags:
      - DeltaCommits
      summary: Commit changes to a specified Delta table.
      operationId: commit
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeltaCommit'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeltaCommitResponse'
        '400':
          description: "Bad request or Invalid Argument. Example: Commit version is not expected (e.g., latest_table_version +1) \nor Latest backfilled version exceeds the last commit version or table_uri in the request doesn't match the \nexisting table_uri for the table.\n"
        '401':
          description: Unauthorized. Authentication credentials are missing or incorrect.
        '403':
          description: Forbidden. The user does not have the necessary permissions to perform this action.
        '404':
          description: Not Found. The specified table does not exist.
        '409':
          description: Conflict. Indicates that a different commit with the same version already exists.
        '429':
          description: The maximum number of unbackfilled commits per table has been reached. Please backfill some commits before retrying.
        '500':
          description: Internal Server Error. An unexpected error occurred on the server.
        '501':
          description: Not Implemented. The requested functionality is not supported.
components:
  schemas:
    DeltaUniformIceberg:
      type: object
      description: "Iceberg conversion metadata tracking the Delta-to-Iceberg conversion state.\nIt contains the metadata location pointer, converted Delta version, timestamp, and \noptional base converted Delta version of the corresponding conversion.\n"
      properties:
        metadata_location:
          type: string
          format: uri
          description: 'The latest Iceberg metadata location.

            Example: s3://abc/def/metadata/v1.json

            '
        converted_delta_version:
          type: integer
          format: int64
          description: 'The Delta version that was converted to Iceberg to produce the Iceberg metadata location.

            It should match the Delta version in the commit info.

            Example: 1044

            '
        converted_delta_timestamp:
          type: string
          description: 'The timestamp that Delta finished conversion to produce the Iceberg metadata location.

            The string must represent a valid instant in UTC with ISO 8601 format.

            Example: 2025-01-04T03:13:11.423Z

            '
        base_converted_delta_version:
          type: integer
          format: int64
          description: 'Optional Delta version used to incrementally convert Delta changes to Iceberg changes to

            produce the latest Iceberg metadata at the metadata_location.

            Example: 1042

            '
      required:
      - metadata_location
      - converted_delta_version
      - converted_delta_timestamp
    ColumnInfos:
      type: object
      description: The schema of the table.
      properties:
        columns:
          type: array
          items:
            $ref: '#/components/schemas/ColumnInfo'
          maxItems: 32768
          description: The array of column descriptions.
    DeltaCommit:
      type: object
      description: Request body for committing changes to a specified Delta table. At least one of commit_info and latest_backfilled_version must be present.
      properties:
        table_id:
          type: string
          description: The ID of the table to commit to. This ID uniquely identifies a table.
        table_uri:
          type: string
          description: "The URI of the storage location of the table. If the table_id exists but the table_uri is \ndifferent from the one previously registered (e.g., if the client moved the table), the request will fail.\nExample: s3://bucket-name/tables/some-table-id\n"
        commit_info:
          $ref: '#/components/schemas/DeltaCommitInfo'
        latest_backfilled_version:
          type: integer
          format: int64
          description: "The highest version of the commits that have been backfilled for this table; meaning UC no longer \nneeds to keep track of commits of versions <= this version.\n"
        metadata:
          $ref: '#/components/schemas/DeltaMetadata'
        uniform:
          $ref: '#/components/schemas/DeltaUniform'
          description: "Optional UniForm metadata to be committed alongside this Delta commit. Whether this field is\nstrictly required by a UC API compatible implementation is left up to the implementation.\nIt is set by UniForm conversion processes after converting a Delta commit. When set, \nUC will atomically update the table's format-specific metadata (e.g. DeltaUniformIceberg),\nkeeping the conversion state synchronized with the Delta version.\nUniform enables Delta tables to be read by other table formats (e.g., Iceberg) without data conversion.\nIndependent of the `metadata` field, both can be provided together or separately.\n"
      required:
      - table_id
      - table_uri
    DeltaCommitInfo:
      type: object
      description: Represents a Delta commit version.
      properties:
        version:
          type: integer
          format: int64
          description: The version of this commit.
        timestamp:
          type: integer
          format: int64
          description: The timestamp for when the commit was made. This is the in-commit timestamp as produced by the Delta client writing to the table.
        file_name:
          type: string
          description: The filename of the UUID-based commit file.
        file_size:
          type: integer
          format: int64
          description: The size of the commit file in bytes.
        file_modification_timestamp:
          type: integer
          format: int64
          description: The modification time of the commit file. This is the mod time of the file as written to the file system.
      required:
      - version
      - timestamp
      - file_name
      - file_size
      - file_modification_timestamp
    DeltaCommitMetadataProperties:
      description: The properties of the Delta table. Updated by UC if set.
      type: object
      properties:
        properties:
          $ref: '#/components/schemas/SecurablePropertiesMap'
    DeltaUniform:
      type: object
      description: 'Uniform metadata that can be atomically committed alongside a Delta commit.

        Uniform enables Delta tables to be read by other table formats (e.g. Iceberg)

        without data conversion. When this message is provided in a Commit request,

        UC will atomically update the table''s format-specific metadata during the commit.

        '
      properties:
        iceberg:
          $ref: '#/components/schemas/DeltaUniformIceberg'
          description: Metadata for Delta UniForm Iceberg conversion.
      required:
      - iceberg
    ColumnInfo:
      type: object
      properties:
        name:
          description: Name of Column.
          type: string
        type_text:
          description: Full data type specification as SQL/catalogString text.
          type: string
        type_json:
          description: Full data type specification, JSON-serialized.
          type: string
        type_name:
          $ref: '#/components/schemas/ColumnTypeName'
        type_precision:
          description: Digits of precision; required for DecimalTypes.
          type: integer
          format: int32
        type_scale:
          description: Digits to right of decimal; Required for DecimalTypes.
          type: integer
          format: int32
        type_interval_type:
          description: Format of IntervalType.
          type: string
        position:
          description: Ordinal position of column (starting at position 0).
          type: integer
          format: int32
        comment:
          description: User-provided free-form text description.
          type: string
        nullable:
          description: Whether field may be Null.
          type: boolean
          default: 'true'
        partition_index:
          description: Partition index for column.
          type: integer
          format: int32
    DeltaCommitResponse:
      type: object
      description: The response for the Delta commit action
    DeltaMetadata:
      description: Represents a Delta metadata action (see https://github.com/delta-io/delta/blob/master/PROTOCOL.md#change-metadata for more information).
      properties:
        description:
          type: string
          description: The table comment.
        schema:
          $ref: '#/components/schemas/ColumnInfos'
        properties:
          $ref: '#/components/schemas/DeltaCommitMetadataProperties'
    ColumnTypeName:
      description: Name of type (INT, STRUCT, MAP, etc.).
      type: string
      enum:
      - BOOLEAN
      - BYTE
      - SHORT
      - INT
      - LONG
      - FLOAT
      - DOUBLE
      - DATE
      - TIMESTAMP
      - TIMESTAMP_NTZ
      - STRING
      - BINARY
      - DECIMAL
      - INTERVAL
      - ARRAY
      - STRUCT
      - MAP
      - VARIANT
      - CHAR
      - 'NULL'
      - USER_DEFINED_TYPE
      - TABLE_TYPE
    DeltaGetCommitsResponse:
      type: object
      properties:
        commits:
          type: array
          description: The list of unbackfilled Delta table commits. Can be in arbitrary order.
          items:
            $ref: '#/components/schemas/DeltaCommitInfo'
        latest_table_version:
          type: integer
          format: int64
          description: 'Represents the latest version of the table tracked by UC. For a newly created managed table

            with no commits, this returns 0. Use this field to manage pagination —

            if the returned commits don''t cover the range up to latest_table_version or end_version (whichever is smaller),

            it indicates that more unbackfilled commits may be available.

            '
      required:
      - commits
      - latest_table_version
    DeltaGetCommits:
      type: object
      properties:
        table_id:
          type: string
          description: The ID of the table to get the commits for. This ID uniquely identifies a table.
        table_uri:
          type: string
          description: "The URI of the storage location of the table. If the table_id exists but the table_uri is \ndifferent from the one previously registered (e.g., if the client moved the table), the request will fail.\nExample: s3://bucket-name/tables/some-table-id\n"
        start_version:
          type: integer
          format: int64
          description: 'The start version from which to retrieve commits (inclusive). This along with the

            optional end_version specifies the range of commit versions that this request wants.

            '
        end_version:
          type: integer
          format: int64
          description: 'The end version upto which to retrieve commits (inclusive).

            If not set, the latest version will be used as the end version. This does not affect the

            latest_table_version in the response.

            If num of commits that meet this criteria is larger than a limit set by server config,

            the response will be limited to the first X commits. Call can send request again with a

            larger start_version according to the response to get the remaining commits.

            '
      required:
      - table_id
      - table_uri
      - start_version
    SecurablePropertiesMap:
      description: A map of key-value properties attached to the securable.
      type: object
      additionalProperties:
        type: string