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

Register a table in the given namespace using given metadata file location

post

{scheme}://{host}/{basePath}/v1/{prefix}/namespaces/{namespace}/register

Register a table using given metadata file location.

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
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.
  • Optional signal to the server that the client supports delegated access via a comma-separated list of access mechanisms. The server may choose to supply access via any or none of the requested mechanisms. Specific properties and handling for `vended-credentials` is documented in the `LoadTableResult` schema section of this spec document. The protocol and specification for `remote-signing` is documented in the `s3-signer-open-api.yaml` OpenApi spec in the `aws` module.
    Example:
    vended-credentials,remote-signing
Supported Media Types
Request Body - application/json ()
Root Schema : schema
Type: object
Show Source
Back to Top

Response

Supported Media Types

200 Response

Table metadata result when loading a table
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 : LoadTableResult
Type: object
Result used when a table is successfully loaded. The table metadata JSON is returned in the `metadata` field. The corresponding file location of table metadata should be returned in the `metadata-location` field, unless the metadata is not yet committed. For example, a create transaction may return metadata that is staged but not committed. Clients can check whether metadata has changed by comparing metadata locations after the table has been created. The `config` map returns table-specific configuration for the table's resources, including its HTTP client and FileIO. For example, config may contain a specific FileIO implementation class for the table depending on its underlying storage. The following configurations should be respected by clients: ## General Configurations - `token`: Authorization bearer token to use for table requests if OAuth2 security is enabled - `scan-planning-mode`: Communicates to clients the supported planning mode. Clients should use this value to fail fast if the supported scanning mode is not available on the client. Valid values: - `client`: Clients MUST use client-side scan planning - `server`: Clients MUST use server-side scan planning via the `planTableScan` endpoint ## AWS Configurations The following configurations should be respected when working with tables stored in AWS S3 - `client.region`: region to configure client for making requests to AWS - `s3.access-key-id`: id for credentials that provide access to the data in S3 - `s3.secret-access-key`: secret for credentials that provide access to data in S3 - `s3.session-token`: if present, this value should be used for as the session token - `s3.remote-signing-enabled`: if `true` remote signing should be performed as described in the `s3-signer-open-api.yaml` specification - `s3.cross-region-access-enabled`: if `true`, S3 Cross-Region bucket access is enabled ## Storage Credentials Credentials for ADLS / GCS / S3 / ... are provided through the `storage-credentials` field. Clients must first check whether the respective credentials exist in the `storage-credentials` field before checking the `config` for credentials.
Show Source
Nested Schema : config
Type: object
Additional Properties Allowed
Show Source
Nested Schema : TableMetadata
Type: object
Show Source
Nested Schema : storage-credentials
Type: array
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
Nested Schema : StorageCredential
Type: object
Show Source
Nested Schema : config
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 - The namespace specified 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 - The table already exists
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

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

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

5XX Response

A server-side problem that might not be addressable from the client side. Used for server 5xx errors without more specific documentation in individual routes.
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