Load a table from the catalog

GET 
/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=<JWT-token>".

Request

Path Parameters

prefix stringrequired

The catalog name in Gravitino, as returned in defaults.prefix by GET /v1/config

namespace stringrequired

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:

singlepart_namespace

Example: accounting

multipart_namespace

Example: accounting%1Ftax

table stringrequired
A table name
Example: sales

Query Parameters

snapshots string

Possible values: [all, refs]

The snapshots to return in the body of the metadata via the snapshots field. 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.

referenced-by string

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

Header Parameters

X-Iceberg-Access-Delegation string
Possible values: [vended-credentials, remote-signing]
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 and remote-signing are documented in the LoadTableResult schema section of this spec document.
Example: vended-credentials,remote-signing
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, LoadTableResponse or CommitTableResponse.

Responses

200

Table metadata result when loading a table

Response Headers

• etag

  string

  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.

application/json

Schema

Schema

metadata-location stringnullable

May be null if the table is staged as part of a transaction

metadata

object

required

format-version integerrequired

Possible values: >= 1 and <= 3

table-uuid stringrequired

location string

last-updated-ms int64

next-row-id int64

A long higher than all assigned row IDs; the next snapshot's first-row-id.

properties

object

property name* string

schemas object[]

current-schema-id integer

last-column-id integer

partition-specs

object[]

Array [

spec-id integer

fields

object[]

required

Array [

field-id integer

source-id integerrequired

name stringrequired

transform Transform (string)required

]

]

default-spec-id integer

last-partition-id integer

sort-orders

object[]

Array [

order-id integerrequired

fields

object[]

required

Array [

source-id integerrequired

transform Transform (string)required

direction SortDirection (string)required

Possible values: [asc, desc]

null-order NullOrder (string)required

Possible values: [nulls-first, nulls-last]

]

]

default-sort-order-id integer

encryption-keys

object[]

Array [

key-id stringrequired

encrypted-key-metadata byterequired

encrypted-by-id string

properties

object

property name* string

]

snapshots

object[]

Array [

snapshot-id int64required

parent-snapshot-id int64

sequence-number int64

timestamp-ms int64required

manifest-list stringrequired

Location of the snapshot's manifest list file

first-row-id int64

The first _row_id assigned to the first row in the first data file in the first manifest

added-rows int64

The upper bound of the number of rows with assigned row IDs

summary

object

required

operation stringrequired

Possible values: [append, replace, overwrite, delete]

property name* string

schema-id integer

]

refs

object

property name*

SnapshotReference

type stringrequired

Possible values: [tag, branch]

snapshot-id int64required

max-ref-age-ms int64

max-snapshot-age-ms int64

min-snapshots-to-keep integer

current-snapshot-id int64

last-sequence-number int64

snapshot-log

object[]

Array [

snapshot-id int64required

timestamp-ms int64required

]

metadata-log

object[]

Array [

metadata-file stringrequired

timestamp-ms int64required

]

statistics

object[]

Array [

snapshot-id int64required

statistics-path stringrequired

file-size-in-bytes int64required

file-footer-size-in-bytes int64required

blob-metadata

object[]

required

Array [

type stringrequired

snapshot-id int64required

sequence-number int64required

fields integer[]required

properties

object

property name* string

]

]

partition-statistics

object[]

Array [

snapshot-id int64required

statistics-path stringrequired

file-size-in-bytes int64required

]

config

object

property name* string

storage-credentials

object[]

Array [

prefix stringrequired

Indicates a storage location prefix where the credential is relevant. Clients should choose the most specific prefix (by selecting the longest prefix) if several credentials of the same type are available.

config

object

required

property name* string

]

Example (from schema)

{
  "metadata-location": "string",
  "metadata": {
    "format-version": 0,
    "table-uuid": "string",
    "location": "string",
    "last-updated-ms": 0,
    "next-row-id": 0,
    "properties": {},
    "schemas": [
      {
        "type": "string",
        "fields": [
          {
            "id": 0,
            "name": "string",
            "type": [
              "long",
              "string",
              "fixed[16]",
              "decimal(10,2)"
            ],
            "required": true,
            "doc": "string",
            "initial-default": true,
            "write-default": true
          }
        ],
        "schema-id": 0,
        "identifier-field-ids": [
          0
        ]
      }
    ],
    "current-schema-id": 0,
    "last-column-id": 0,
    "partition-specs": [
      {
        "spec-id": 0,
        "fields": [
          {
            "field-id": 0,
            "source-id": 0,
            "name": "string",
            "transform": [
              "identity",
              "year",
              "month",
              "day",
              "hour",
              "bucket[256]",
              "truncate[16]"
            ]
          }
        ]
      }
    ],
    "default-spec-id": 0,
    "last-partition-id": 0,
    "sort-orders": [
      {
        "order-id": 0,
        "fields": [
          {
            "source-id": 0,
            "transform": [
              "identity",
              "year",
              "month",
              "day",
              "hour",
              "bucket[256]",
              "truncate[16]"
            ],
            "direction": "asc",
            "null-order": "nulls-first"
          }
        ]
      }
    ],
    "default-sort-order-id": 0,
    "encryption-keys": [
      {
        "key-id": "string",
        "encrypted-key-metadata": "string",
        "encrypted-by-id": "string",
        "properties": {}
      }
    ],
    "snapshots": [
      {
        "snapshot-id": 0,
        "parent-snapshot-id": 0,
        "sequence-number": 0,
        "timestamp-ms": 0,
        "manifest-list": "string",
        "first-row-id": 0,
        "added-rows": 0,
        "summary": {
          "operation": "append"
        },
        "schema-id": 0
      }
    ],
    "refs": {},
    "current-snapshot-id": 0,
    "last-sequence-number": 0,
    "snapshot-log": [
      {
        "snapshot-id": 0,
        "timestamp-ms": 0
      }
    ],
    "metadata-log": [
      {
        "metadata-file": "string",
        "timestamp-ms": 0
      }
    ],
    "statistics": [
      {
        "snapshot-id": 0,
        "statistics-path": "string",
        "file-size-in-bytes": 0,
        "file-footer-size-in-bytes": 0,
        "blob-metadata": [
          {
            "type": "string",
            "snapshot-id": 0,
            "sequence-number": 0,
            "fields": [
              0
            ],
            "properties": {}
          }
        ]
      }
    ],
    "partition-statistics": [
      {
        "snapshot-id": 0,
        "statistics-path": "string",
        "file-size-in-bytes": 0
      }
    ]
  },
  "config": {},
  "storage-credentials": [
    {
      "prefix": "string",
      "config": {}
    }
  ]
}

304

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

400

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.

application/json

Schema

Schema

error

object

required

JSON error payload returned in a response with further details on the error

message stringrequired

Human-readable error message

type stringrequired

Internal type definition of the error

code integerrequired

Possible values: >= 400 and <= 600

HTTP response code

stack string[]

Example (from schema)

{
  "error": {
    "message": "The server does not support this operation",
    "type": "UnsupportedOperationException",
    "code": 406
  }
}

Example

{
  "error": {
    "message": "Malformed request",
    "type": "BadRequestException",
    "code": 400
  }
}

401

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.

application/json

Schema

Schema

error

object

required

JSON error payload returned in a response with further details on the error

message stringrequired

Human-readable error message

type stringrequired

Internal type definition of the error

code integerrequired

Possible values: >= 400 and <= 600

HTTP response code

stack string[]

Example (from schema)

{
  "error": {
    "message": "The server does not support this operation",
    "type": "UnsupportedOperationException",
    "code": 406
  }
}

Example

{
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 401
  }
}

403

Forbidden. Authenticated user does not have the necessary permissions.

application/json

Schema

Schema

error

object

required

JSON error payload returned in a response with further details on the error

message stringrequired

Human-readable error message

type stringrequired

Internal type definition of the error

code integerrequired

Possible values: >= 400 and <= 600

HTTP response code

stack string[]

Example (from schema)

{
  "error": {
    "message": "The server does not support this operation",
    "type": "UnsupportedOperationException",
    "code": 406
  }
}

Example

{
  "error": {
    "message": "Not authorized to make this request",
    "type": "NotAuthorizedException",
    "code": 403
  }
}

404

Not Found - NoSuchTableException, table to load does not exist

application/json

Schema

Schema

error

object

required

JSON error payload returned in a response with further details on the error

message stringrequired

Human-readable error message

type stringrequired

Internal type definition of the error

code integerrequired

Possible values: >= 400 and <= 600

HTTP response code

stack string[]

Example (from schema)

{
  "error": {
    "message": "The server does not support this operation",
    "type": "UnsupportedOperationException",
    "code": 406
  }
}

TableToLoadDoesNotExist

The requested table does not exist

{
  "error": {
    "message": "The given table does not exist",
    "type": "NoSuchTableException",
    "code": 404
  }
}

419

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.

application/json

Schema

Schema

error

object

required

JSON error payload returned in a response with further details on the error

message stringrequired

Human-readable error message

type stringrequired

Internal type definition of the error

code integerrequired

Possible values: >= 400 and <= 600

HTTP response code

stack string[]

Example (from schema)

{
  "error": {
    "message": "The server does not support this operation",
    "type": "UnsupportedOperationException",
    "code": 406
  }
}

Example

{
  "error": {
    "message": "Credentials have timed out",
    "type": "AuthenticationTimeoutException",
    "code": 419
  }
}

503

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.

application/json

Schema

Schema

error

object

required

JSON error payload returned in a response with further details on the error

message stringrequired

Human-readable error message

type stringrequired

Internal type definition of the error

code integerrequired

Possible values: >= 400 and <= 600

HTTP response code

stack string[]

Example (from schema)

{
  "error": {
    "message": "The server does not support this operation",
    "type": "UnsupportedOperationException",
    "code": 406
  }
}

Example

{
  "error": {
    "message": "Slow down",
    "type": "SlowDownException",
    "code": 503
  }
}

5XX

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.

application/json

Schema

Schema

error

object

required

JSON error payload returned in a response with further details on the error

message stringrequired

Human-readable error message

type stringrequired

Internal type definition of the error

code integerrequired

Possible values: >= 400 and <= 600

HTTP response code

stack string[]

Example (from schema)

{
  "error": {
    "message": "The server does not support this operation",
    "type": "UnsupportedOperationException",
    "code": 406
  }
}

Example

{
  "error": {
    "message": "Internal Server Error",
    "type": "InternalServerError",
    "code": 500
  }
}

Loading...