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

Load a table from the catalog

get

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

Load a table from the catalog. The response contains both configuration and table metadata. The configuration, if non-empty is used as additional configuration for the table that overrides catalog configuration. For example, this configuration may change the FileIO implementation to be used for the table. The response also contains the table's full metadata, matching the table metadata JSON file. The catalog configuration may contain credentials that should be used for subsequent requests for the table. The configuration key "token" is used to pass an access token to be used as a bearer token for table requests. Otherwise, a token may be passed using a RFC 8693 token type as a configuration key. For example, "urn:ietf:params:oauth:token-type:jwt=".

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
Query Parameters
  • A comma-separated list of fully qualified view names (namespace and view name) representing the view reference chain when an entity (table or view) is loaded via a view. The list should be ordered with the outermost view first, followed by any intermediate views it references, down to the view that directly references the entity. For a simple case where a view directly references the entity, the list contains a single view identifier. For nested views (a view referencing another view which references the entity), the list contains multiple view identifiers representing the complete dependency chain. The view identifier is a composite string of the format {namespace}{separator}{viewName}. The namespace-separator (defined in /config) acts as the delimiter. When parsing, the last occurrence of this separator identifies the boundary between the namespace and the view name. Multipart namespaces must follow the encoding rules of the parent parameter in the list namespaces endpoint. Multiple view identifiers are separated by commas. Servers should split the parameter value on comma characters to parse individual view identifiers. If view names contain commas, they must be url-encoded as %2C. Example with multiple views (where prod%1Fanalytics is a nested namespace which has a quarterly_view which references to monthly_view which then references the entity being loaded) - prod%1Fanalytics%1Fquarterly_view,prod%1Fanalytics%1Fmonthly_view
  • The snapshots to return in the body of the metadata. Setting the value to `all` would return the full set of snapshots currently valid for the table. Setting the value to `refs` would load all snapshots referenced by branches or tags. Default if no param is provided is `all`.
    Allowed Values: [ "all", "refs" ]
Header Parameters
  • An optional header that allows the server to return 304 (Not Modified) if the metadata is current. The content is the value of the ETag received in a CreateTableResponse, LoadTableResponse or CommitTableResponse.
  • 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

There's no request body for this operation.

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

304 Response

Not Modified - Based on the content of the 'If-None-Match' header the table metadata has not changed since.

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

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