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=

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

prefix

string

required

An optional prefix in the path

namespace

string

required

A namespace identifier as a single string. Multipart namespace parts should be separated by the unit separator (0x1F) byte.

table

string

required

A table name

Query Params

snapshots

string

enum

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:

Headers

X-Iceberg-Access-Delegation

string

enum

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.

Allowed:

If-None-Match

string

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 or LoadTableResponse.

Responses

304

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

200Table metadata result when loading a table

400Indicates 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.

401Unauthorized. 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.

403Forbidden. Authenticated user does not have the necessary permissions.

404Not Found - NoSuchTableException, table to load does not exist

419This 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.

503The 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.

5XXA server-side problem that might not be addressable from the client side. Used for server 5xx errors without more specific documentation in individual routes.