Describe information of a table

Describe the detailed information for table id.

REST NAMESPACE ONLY REST namespace passes with_table_uri and load_detailed_metadata as query parameters instead of in the request body.

POST /v1/table/{id}/describe

Error

A valid request URL is required to generate request examples

200

{
  "table": "<string>",
  "namespace": [
    "<string>"
  ],
  "version": 1,
  "location": "<string>",
  "table_uri": "<string>",
  "schema": {
    "fields": [
      {
        "name": "<string>",
        "nullable": true,
        "type": {
          "type": "<string>",
          "fields": "<array>",
          "length": 1
        },
        "metadata": {}
      }
    ],
    "metadata": {}
  },
  "storage_options": {},
  "stats": {
    "num_deleted_rows": 1,
    "num_fragments": 1
  },
  "metadata": {}
}

Authorizations

OAuth2BearerAuthApiKeyAuth

Authorization · string · header · required

The access token received from the authorization server in the OAuth 2.0 flow.

Path Parameters

id · string · required

string identifier of an object in a namespace, following the Lance Namespace spec. When the value is equal to the delimiter, it represents the root namespace. For example, v1/namespace/$/list performs a ListNamespace on the root namespace.

Query Parameters

delimiter · string

An optional delimiter of the string identifier, following the Lance Namespace spec. When not specified, the $ delimiter must be used.

with_table_uri · boolean · default: false

Whether to include the table URI in the response

load_detailed_metadata · boolean · default: false

Whether to load detailed metadata that requires opening the dataset. When false (default), only location is required in the response. When true, the response includes additional metadata such as version, schema, and stats.

Body

application/json

identity · object

Identity information of a request.

Show child attributes

context · object

Arbitrary context for a request as key-value pairs. How to use the context is custom to the specific implementation.

REST NAMESPACE ONLY Context entries are passed via HTTP headers using the naming convention x-lance-ctx-<key>: <value>. For example, a context entry {"trace_id": "abc123"} would be sent as the header x-lance-ctx-trace_id: abc123.

Show child attributes

id · string[]

version · integer<int64>

Version of the table to describe. If not specified, server should resolve it to the latest version.

Required range: x >= 0

with_table_uri · boolean · default: false

Whether to include the table URI in the response. Default is false.

load_detailed_metadata · boolean

Whether to load detailed metadata that requires opening the dataset. When true, the response must include all detailed metadata such as version, schema, and stats which require reading the dataset. When not set, the implementation can decide whether to return detailed metadata and which parts of detailed metadata to return.

vend_credentials · boolean

Whether to include vended credentials in the response storage_options. When true, the implementation should provide vended credentials for accessing storage. When not set, the implementation can decide whether to return vended credentials.

Response

200

application/json

Table properties result when loading a table

table · string

Table name. Only populated when load_detailed_metadata is true.

namespace · string[]

The namespace identifier as a list of parts. Only populated when load_detailed_metadata is true.

version · integer<int64>

Table version number. Only populated when load_detailed_metadata is true.

Required range: x >= 0

location · string

Table storage location (e.g., S3/GCS path).

table_uri · string

Table URI. Unlike location, this field must be a complete and valid URI. Only returned when with_table_uri is true.

schema · object

Table schema in JSON Arrow format. Only populated when load_detailed_metadata is true.

Show child attributes

storage_options · object

Configuration options to be used to access storage. The available options depend on the type of storage in use. These will be passed directly to Lance to initialize storage access. When vend_credentials is true, this field may include vended credentials. If the vended credentials are temporary, the expires_at_millis key should be included to indicate the millisecond timestamp when the credentials expire.

Show child attributes

stats · object

Table statistics. Only populated when load_detailed_metadata is true.

Show child attributes

metadata · object

Optional table metadata as key-value pairs.

Show child attributes