Sign in
Table
Metadata

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

Path parameters

idstring 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

delimiterstring

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

with_table_uriboolean

Whether to include the table URI in the response

load_detailed_metadataboolean

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.

Request body

idstring[]
versioninteger

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

with_table_uriboolean

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

load_detailed_metadataboolean

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_credentialsboolean

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.

Example request

{
  "id": [
    "id",
    "id"
  ],
  "version": 0,
  "with_table_uri": false,
  "load_detailed_metadata": true,
  "vend_credentials": true
}

Response

Table properties result when loading a table

tablestring

Table name. Only populated when load_detailed_metadata is true.

namespacestring[]

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

versioninteger

Table version number. Only populated when load_detailed_metadata is true.

locationstring

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

table_uristring

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

{"stackTrail":"components:schemas:DescribeTableResponse:properties:storage_options","oasType":"schema","type":"unknown","description":"Configuration options to be used to access storage. The available\noptions depend on the type of storage in use. These will be\npassed directly to Lance to initialize storage access.\nWhen `vend_credentials` is true, this field may include vended credentials.\nIf the vended credentials are temporary, the `expires_at_millis` key should be\nincluded to indicate the millisecond timestamp when the credentials expire.\n"}
{"stackTrail":"components:schemas:DescribeTableResponse:properties:metadata","oasType":"schema","type":"unknown","description":"Optional table metadata as key-value pairs.\n"}

Example response

{
  "schema": {
    "metadata": {
      "key": "metadata"
    },
    "fields": [
      {
        "metadata": {
          "key": "metadata"
        },
        "nullable": true,
        "name": "name",
        "type": {
          "length": 0,
          "fields": [
            null,
            null
          ],
          "type": "type"
        }
      },
      {
        "metadata": {
          "key": "metadata"
        },
        "nullable": true,
        "name": "name",
        "type": {
          "length": 0,
          "fields": [
            null,
            null
          ],
          "type": "type"
        }
      }
    ]
  },
  "metadata": {
    "key": "metadata"
  },
  "table_uri": "table_uri",
  "stats": {
    "num_deleted_rows": 0,
    "num_fragments": 0
  },
  "namespace": [
    "namespace",
    "namespace"
  ],
  "location": "location",
  "version": 0,
  "table": "table",
  "storage_options": {
    "key": "storage_options"
  }
}

Changes