1. REST API for Oracle AI Data Catalog
  2. Tasks
  3. Catalog API

Commit updates to a table

post

{scheme}://{host}/{basePath}/v1/{prefix}/namespaces/{namespace}/tables/{table}

Commit updates to a table. Commits have two parts, requirements and updates. Requirements are assertions that will be validated before attempting to make and commit changes. For example, `assert-ref-snapshot-id` will check that a named ref's snapshot ID has a certain value. Server implementations are required to fail with a 400 status code if any unknown updates or requirements are received. Updates are changes to make to table metadata. For example, after asserting that the current main ref is at the expected snapshot, a commit may add a new child snapshot and set the ref to the new snapshot id. Create table transactions that are started by createTable with `stage-create` set to true are committed using this route. Transactions should include all changes to the table, including table initialization, like AddSchemaUpdate and SetCurrentSchemaUpdate. The `assert-create` requirement is used to ensure that the table was not created concurrently.

Request

Path Parameters
  • A namespace identifier as a single string. Multipart namespace parts must be separated by the namespace separator as indicated via the /config override `namespace-separator`, which defaults to the unit separator `0x1F` byte (url encoded `%1F`). To be compatible with older clients, servers must use both the advertised separator and `0x1F` as valid separators when decoding namespaces. The `namespace-separator` should be provided in a url encoded form.
    Examples

  • An optional prefix in the path
  • A table name
    Example:
    sales
Header Parameters
  • Optional client-provided idempotency key for safe request retries. When present, the server ensures no additional effects for requests that carry the same Idempotency-Key. If a prior request with this key has been finalized, the server returns an equivalent final response without re-running the operation. The response body may reflect a newer state of the catalog than existed at the time of the commit. Finalization rules: - Finalize & replay: 200, 201, 204, and deterministic terminal 4xx (including 409 such as AlreadyExists, NamespaceNotEmpty, etc.) - Do not finalize (not stored/replayed): 5xx Key Requirements: - Key format: UUIDv7 in string form (RFC 9562). - The idempotency key must be globally unique (no reuse across different operations). - Catalogs SHOULD NOT expire keys before the end of the advertised token lifetime. - If Idempotency-Key is used, clients MUST reuse the same key when retrying the same logical operation and MUST generate a new key for a different operation.
Supported Media Types
Request Body - application/json ()
Root Schema : schema
Type: object
Show Source
Nested Schema : TableIdentifier
Type: object
Show Source
Nested Schema : requirements
Type: array
Show Source
  • Discriminator: type
    Discriminator: { "propertyName":"type", "mapping":{ "assert-create":"#/components/schemas/AssertCreate", "assert-table-uuid":"#/components/schemas/AssertTableUUID", "assert-ref-snapshot-id":"#/components/schemas/AssertRefSnapshotId", "assert-last-assigned-field-id":"#/components/schemas/AssertLastAssignedFieldId", "assert-current-schema-id":"#/components/schemas/AssertCurrentSchemaId", "assert-last-assigned-partition-id":"#/components/schemas/AssertLastAssignedPartitionId", "assert-default-spec-id":"#/components/schemas/AssertDefaultSpecId", "assert-default-sort-order-id":"#/components/schemas/AssertDefaultSortOrderId" } }
Nested Schema : updates
Type: array
Show Source
Nested Schema : Namespace
Type: array
Reference to one or more levels of a namespace
Show Source
Example:
[
    "accounting",
    "tax"
]
Nested Schema : Discriminator: type
Type: object
Discriminator: type

Discriminator Values

Show Source
Back to Top

Response

Supported Media Types

200 Response

Response used when a table is successfully updated. The table metadata JSON is returned in the metadata field. The corresponding file location of table metadata must be returned in the metadata-location field. Clients can check whether metadata has changed by comparing metadata locations.
Headers
  • Identifies a unique version of the table metadata. Implementations that support ETags should produce unique tags for responses that return different metadata content but represent the same version of table metadata. For example, the `snapshots` query parameter may result in different metadata representations depending on whether `refs` or `all` is provided, therefore should have distinct ETags.
Body ()
Root Schema : CommitTableResponse
Type: object
Show Source
Nested Schema : TableMetadata
Type: object
Show Source
Nested Schema : encryption-keys
Type: array
Show Source
Nested Schema : MetadataLog
Type: array
Show Source
Nested Schema : partition-specs
Type: array
Show Source
Nested Schema : partition-statistics
Type: array
Show Source
Nested Schema : properties
Type: object
Additional Properties Allowed
Show Source
Nested Schema : SnapshotReferences
Type: object
Additional Properties Allowed
Show Source
Nested Schema : schemas
Type: array
Show Source
Nested Schema : SnapshotLog
Type: array
Show Source
Nested Schema : snapshots
Type: array
Show Source
Nested Schema : sort-orders
Type: array
Show Source
Nested Schema : statistics
Type: array
Show Source
Nested Schema : EncryptedKey
Type: object
Show Source
Nested Schema : properties
Type: object
Additional Properties Allowed
Show Source
Nested Schema : items
Type: object
Show Source
Nested Schema : PartitionSpec
Type: object
Show Source
Nested Schema : fields
Type: array
Show Source
Nested Schema : PartitionField
Type: object
Show Source
Nested Schema : PartitionStatisticsFile
Type: object
Show Source
Nested Schema : SnapshotReference
Type: object
Show Source
Nested Schema : Schema
Match All
Show Source
Nested Schema : StructType
Type: object
Show Source
Nested Schema : Schema-allOf[1]
Type: object
Show Source
Nested Schema : fields
Type: array
Show Source
Nested Schema : StructField
Type: object
Show Source
Nested Schema : PrimitiveTypeValue
Match One Schema
Show Source
  • Title: BooleanTypeValue
    Example: true
  • Title: IntegerTypeValue
    Example: 42
  • Title: LongTypeValue
    Example: 9223372036854776000
  • Title: FloatTypeValue
    Example: 3.14
  • Title: DoubleTypeValue
    Example: 123.456
  • Title: DecimalTypeValue
    Decimal type values are serialized as strings. Decimals with a positive scale serialize as numeric plain text, while decimals with a negative scale use scientific notation and the exponent will be equal to the negated scale. For instance, a decimal with a positive scale is '123.4500', with zero scale is '2', and with a negative scale is '2E+20'
    Example: 123.45
  • Title: StringTypeValue
    Example: hello
  • Title: UUIDTypeValue
    Minimum Length: 36
    Maximum Length: 36
    Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
    UUID type values are serialized as a 36-character lowercase string in standard UUID format as specified by RFC-4122
    Example: eb26bdb1-a1d8-4aa6-990e-da940875492c
  • Title: DateTypeValue
    Date type values follow the 'YYYY-MM-DD' ISO-8601 standard date format
    Example: 2007-12-03
  • Title: TimeTypeValue
    Time type values follow the 'HH:MM:SS.ssssss' ISO-8601 format with microsecond precision
    Example: 22:31:08.123456
  • Title: TimestampTypeValue
    Timestamp type values follow the 'YYYY-MM-DDTHH:MM:SS.ssssss' ISO-8601 format with microsecond precision
    Example: 2007-12-03T10:15:30.123456
  • Title: TimestampTzTypeValue
    TimestampTz type values follow the 'YYYY-MM-DDTHH:MM:SS.ssssss+00:00' ISO-8601 format with microsecond precision, and a timezone offset (+00:00 for UTC)
    Example: 2007-12-03T10:15:30.123456+00:00
  • Title: TimestampNanoTypeValue
    Timestamp_ns type values follow the 'YYYY-MM-DDTHH:MM:SS.sssssssss' ISO-8601 format with nanosecond precision
    Example: 2007-12-03T10:15:30.123456789
  • Title: TimestampTzNanoTypeValue
    Timestamp_ns type values follow the 'YYYY-MM-DDTHH:MM:SS.sssssssss+00:00' ISO-8601 format with nanosecond precision, and a timezone offset (+00:00 for UTC)
    Example: 2007-12-03T10:15:30.123456789+00:00
  • Title: FixedTypeValue
    Fixed length type values are stored and serialized as an uppercase hexadecimal string preserving the fixed length
    Example: 78797A
  • Title: BinaryTypeValue
    Binary type values are stored and serialized as an uppercase hexadecimal string
    Example: 78797A
Nested Schema : Type
Match One Schema
Show Source
Nested Schema : StructType
Type: object
Title: StructType
Show Source
Nested Schema : ListType
Type: object
Title: ListType
Show Source
Nested Schema : MapType
Type: object
Title: MapType
Show Source
Nested Schema : fields
Type: array
Show Source
Nested Schema : identifier-field-ids
Type: array
Show Source
Nested Schema : items
Type: object
Show Source
Nested Schema : Snapshot
Type: object
Show Source
Nested Schema : summary
Type: object
Additional Properties Allowed
Show Source Show Source
Nested Schema : SortOrder
Type: object
Show Source
Nested Schema : fields
Type: array
Show Source
Nested Schema : SortField
Type: object
Show Source
Nested Schema : StatisticsFile
Type: object
Show Source
Nested Schema : blob-metadata
Type: array
Show Source
Nested Schema : BlobMetadata
Type: object
Show Source
Nested Schema : fields
Type: array
Show Source
Nested Schema : properties
Type: object
Additional Properties Allowed
Show Source

400 Response

Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure, such as invalid json. Usually serves application/json content, although in some cases simple text/plain content might be returned by the server's middleware.
Body ()
Root Schema : IcebergErrorResponse
Type: object
JSON wrapper for all error responses (non-2xx)
Show Source
Example:
{
    "error":{
        "message":"The server does not support this operation",
        "type":"UnsupportedOperationException",
        "code":406
    }
}
Nested Schema : ErrorModel
Type: object
JSON error payload returned in a response with further details on the error
Show Source
Nested Schema : stack
Type: array
Show Source

401 Response

Unauthorized. The REST Catalog SHOULD respond with the 401 UnauthorizedResponse when the access token provided is expired, revoked, malformed, or invalid for other reasons. The client MAY request a new access token and retry the request.
Body ()
Root Schema : IcebergErrorResponse
Type: object
JSON wrapper for all error responses (non-2xx)
Show Source
Example:
{
    "error":{
        "message":"The server does not support this operation",
        "type":"UnsupportedOperationException",
        "code":406
    }
}
Nested Schema : ErrorModel
Type: object
JSON error payload returned in a response with further details on the error
Show Source
Nested Schema : stack
Type: array
Show Source

403 Response

Forbidden. Authenticated user does not have the necessary permissions.
Body ()
Root Schema : IcebergErrorResponse
Type: object
JSON wrapper for all error responses (non-2xx)
Show Source
Example:
{
    "error":{
        "message":"The server does not support this operation",
        "type":"UnsupportedOperationException",
        "code":406
    }
}
Nested Schema : ErrorModel
Type: object
JSON error payload returned in a response with further details on the error
Show Source
Nested Schema : stack
Type: array
Show Source

404 Response

Not Found - NoSuchTableException, table to load does not exist
Body ()
Root Schema : IcebergErrorResponse
Type: object
JSON wrapper for all error responses (non-2xx)
Show Source
Example:
{
    "error":{
        "message":"The server does not support this operation",
        "type":"UnsupportedOperationException",
        "code":406
    }
}
Nested Schema : ErrorModel
Type: object
JSON error payload returned in a response with further details on the error
Show Source
Nested Schema : stack
Type: array
Show Source
Examples

409 Response

Conflict - CommitFailedException, one or more requirements failed. The client may retry.
Body ()
Root Schema : IcebergErrorResponse
Type: object
JSON wrapper for all error responses (non-2xx)
Show Source
Example:
{
    "error":{
        "message":"The server does not support this operation",
        "type":"UnsupportedOperationException",
        "code":406
    }
}
Nested Schema : ErrorModel
Type: object
JSON error payload returned in a response with further details on the error
Show Source
Nested Schema : stack
Type: array
Show Source

419 Response

This is an optional status response type that the REST Catalog can issue when the token has expired. The client MAY request a new access token and retry the request. 401 UnauthorizedResponse SHOULD be preferred over this response type on token expiry.
Body ()
Root Schema : IcebergErrorResponse
Type: object
JSON wrapper for all error responses (non-2xx)
Show Source
Example:
{
    "error":{
        "message":"The server does not support this operation",
        "type":"UnsupportedOperationException",
        "code":406
    }
}
Nested Schema : ErrorModel
Type: object
JSON error payload returned in a response with further details on the error
Show Source
Nested Schema : stack
Type: array
Show Source

500 Response

An unknown server-side problem occurred; the commit state is unknown.
Body ()
Root Schema : IcebergErrorResponse
Type: object
JSON wrapper for all error responses (non-2xx)
Show Source
Example:
{
    "error":{
        "message":"The server does not support this operation",
        "type":"UnsupportedOperationException",
        "code":406
    }
}
Nested Schema : ErrorModel
Type: object
JSON error payload returned in a response with further details on the error
Show Source
Nested Schema : stack
Type: array
Show Source

502 Response

A gateway or proxy received an invalid response from the upstream server; the commit state is unknown.
Body ()
Root Schema : IcebergErrorResponse
Type: object
JSON wrapper for all error responses (non-2xx)
Show Source
Example:
{
    "error":{
        "message":"The server does not support this operation",
        "type":"UnsupportedOperationException",
        "code":406
    }
}
Nested Schema : ErrorModel
Type: object
JSON error payload returned in a response with further details on the error
Show Source
Nested Schema : stack
Type: array
Show Source

503 Response

The service is not ready to handle the request, request could have been partially processed. The service may additionally send a Retry-After header to indicate when to retry, a non idempotent request should only be retried by the client when the Retry-After header is present.
Body ()
Root Schema : IcebergErrorResponse
Type: object
JSON wrapper for all error responses (non-2xx)
Show Source
Example:
{
    "error":{
        "message":"The server does not support this operation",
        "type":"UnsupportedOperationException",
        "code":406
    }
}
Nested Schema : ErrorModel
Type: object
JSON error payload returned in a response with further details on the error
Show Source
Nested Schema : stack
Type: array
Show Source

504 Response

A server-side gateway timeout occurred; the commit state is unknown.
Body ()
Root Schema : IcebergErrorResponse
Type: object
JSON wrapper for all error responses (non-2xx)
Show Source
Example:
{
    "error":{
        "message":"The server does not support this operation",
        "type":"UnsupportedOperationException",
        "code":406
    }
}
Nested Schema : ErrorModel
Type: object
JSON error payload returned in a response with further details on the error
Show Source
Nested Schema : stack
Type: array
Show Source

5XX Response

A server-side problem that might not be addressable on the client.
Body ()
Root Schema : IcebergErrorResponse
Type: object
JSON wrapper for all error responses (non-2xx)
Show Source
Example:
{
    "error":{
        "message":"The server does not support this operation",
        "type":"UnsupportedOperationException",
        "code":406
    }
}
Nested Schema : ErrorModel
Type: object
JSON error payload returned in a response with further details on the error
Show Source
Nested Schema : stack
Type: array
Show Source
Back to Top