---
title: "Describe information of a table"
method: POST
path: "/v1/table/{id}/describe"
tags: ["Table", "Metadata"]
---

# Describe information of a table

`POST /v1/table/{id}/describe`

Describe the detailed information for table `id`.

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

## Path parameters

- `id` string, required

## Query parameters

- `delimiter` string
- `with_table_uri` boolean
- `load_detailed_metadata` boolean
- `check_declared` boolean

## Request body

- DescribeTableRequest
  - `identity` Identity — Identity information of a request.
    - `api_key` string — API key for authentication. REST NAMESPACE ONLY This is passed via the `x-api-key` header.
    - `auth_token` string — Bearer token for authentication. REST NAMESPACE ONLY This is passed via the `Authorization` header with the Bearer scheme (e.g., `Bearer <token>`).
  - `context` unknown
  - `id` string[]
  - `version` integer — Version of the table to describe. If not specified, server should resolve it to the latest version.
  - `tag` string — Tag name to describe the table at. If specified, the server should resolve the tag to a version number and describe that version. Cannot be used together with `version` or `branch`.
  - `branch` string — Branch to target. When not specified, the main branch is used.
  - `with_table_uri` boolean — 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.
  - `check_declared` boolean — Whether to check if the table exists only as a namespace declaration without storage data. Default is false. When true, the response should populate `is_only_declared`. When false, the implementation should return null for `is_only_declared` unless another option such as `load_detailed_metadata` requires checking declared-only table state.
  - `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`

Table properties result when loading a table

- DescribeTableResponse
  - `context` unknown
  - `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 — Table version number. Only populated when `load_detailed_metadata` is true.
  - `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` JsonArrowSchema — JSON representation of a Apache Arrow schema.
    - `fields` JsonArrowField[], required
      - `metadata` unknown
      - `name` string, required
      - `nullable` boolean, required
      - `type` JsonArrowDataType, required — JSON representation of an Apache Arrow DataType
        - `fields` JsonArrowField[] — Fields for complex types like Struct, Union, etc.
        - `length` integer — Length for fixed-size types
        - `type` string, required — The data type name
    - `metadata` unknown
  - `storage_options` unknown
  - `stats` TableBasicStats
    - `num_deleted_rows` integer, required — Number of deleted rows in the table
    - `num_fragments` integer, required — Number of fragments in the table
  - `metadata` unknown
  - `properties` unknown
  - `managed_versioning` boolean — When true, the caller should use namespace table version operations (CreateTableVersion, BatchCreateTableVersions, DescribeTableVersion, ListTableVersions, BatchDeleteTableVersions) to manage table versions instead of relying on Lance's native version management.
  - `is_only_declared` boolean, nullable — When true, indicates that the table has been declared in the namespace but not yet created on storage. This means the table exists in the namespace but has no data files on the underlying storage. When false, the table has storage components (data and metadata files). When null, the implementation did not check whether the table is only declared. Clients should treat an omitted value as null. Implementations should populate this field when `check_declared` is true or another option such as `load_detailed_metadata` requires checking declared-only table state. Operations like describe_table with load_detailed_metadata=true may fail for declared-only tables.

## Other responses

- `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.
- `401` — Unauthorized. The request lacks valid authentication credentials for the operation.
- `403` — Forbidden. Authenticated user does not have the necessary permissions.
- `404` — A server-side problem that means can not find the specified resource.
- `503` — The service is not ready to handle the request. The client should wait and retry. The service may additionally send a Retry-After header to indicate when to retry.
- `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.

---

[API](https://skmtc.net/lance-format/apis/lance-namespace-specification.md) · [All operations](https://skmtc.net/lance-format/apis/lance-namespace-specification/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lance-format/lance-namespace-specification/versions/f09656f7f568/schema)