> ## Documentation Index > Fetch the complete documentation index at: https://docs.lancedb.com/llms.txt > Use this file to discover all available pages before exploring further. # Describe information of a table > 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. ## OpenAPI ````yaml /api-reference/rest/openapi.yml post /v1/table/{id}/describe openapi: 3.1.1 info: title: Lance Namespace Specification license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html version: 1.0.0 description: > This OpenAPI specification is a part of the Lance namespace specification. It contains 2 parts: The `components/schemas`, `components/responses`, `components/examples`, `tags` sections define the request and response shape for each operation in a Lance Namespace across all implementations. See https://lance.org/format/namespace/operations for more details. The `servers`, `security`, `paths`, `components/parameters` sections are for the Lance REST Namespace implementation, which defines a complete REST server that can work with Lance datasets. See https://lance.org/format/namespace/rest for more details. servers: - url: '{scheme}://{host}:{port}/{basePath}' description: Generic server URL with all parts configurable variables: scheme: default: http host: default: localhost port: default: '2333' basePath: default: '' - url: '{scheme}://{host}/{basePath}' description: Server URL when the port can be inferred from the scheme variables: scheme: default: http host: default: localhost basePath: default: '' security: - OAuth2: [] - BearerAuth: [] - ApiKeyAuth: [] tags: - name: Namespace description: | Operations that are related to a namespace - name: Table description: | Operations that are related to a table - name: Index description: | Operations that are related to an index - name: Tag description: | Operations that are related to tags - name: Transaction description: | Operations that are related to a transaction - name: Metadata description: > Operations that only interact with object metadata and should be computationally lightweight - name: Data description: > Operations that interact with object data and might be computationally intensive paths: /v1/table/{id}/describe: parameters: - $ref: '#/components/parameters/id' - $ref: '#/components/parameters/delimiter' - $ref: '#/components/parameters/with_table_uri' - $ref: '#/components/parameters/load_detailed_metadata' - $ref: '#/components/parameters/check_declared' post: tags: - Table - Metadata summary: Describe information of a table description: > 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. operationId: DescribeTable requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DescribeTableRequest' responses: '200': $ref: '#/components/responses/DescribeTableResponse' '400': $ref: '#/components/responses/BadRequestErrorResponse' '401': $ref: '#/components/responses/UnauthorizedErrorResponse' '403': $ref: '#/components/responses/ForbiddenErrorResponse' '404': $ref: '#/components/responses/NotFoundErrorResponse' '503': $ref: '#/components/responses/ServiceUnavailableErrorResponse' 5XX: $ref: '#/components/responses/ServerErrorResponse' components: parameters: id: name: id description: > `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. in: path required: true schema: type: string delimiter: name: delimiter description: > An optional delimiter of the `string identifier`, following the Lance Namespace spec. When not specified, the `$` delimiter must be used. in: query required: false schema: type: string with_table_uri: name: with_table_uri description: Whether to include the table URI in the response in: query required: false schema: type: boolean default: false load_detailed_metadata: name: load_detailed_metadata description: > 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`. in: query required: false schema: type: boolean default: false check_declared: name: check_declared description: | Whether to check if the table exists only as a namespace declaration without storage data. When false (default), the response should return null for `is_only_declared` unless another option such as `load_detailed_metadata` requires the check. in: query required: false schema: type: boolean default: false schemas: DescribeTableRequest: type: object properties: identity: $ref: '#/components/schemas/Identity' context: $ref: '#/components/schemas/Context' id: type: array items: type: string version: description: | Version of the table to describe. If not specified, server should resolve it to the latest version. type: integer format: int64 minimum: 0 with_table_uri: description: | Whether to include the table URI in the response. Default is false. type: boolean default: false load_detailed_metadata: description: > 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. type: boolean check_declared: description: > 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. type: boolean default: false vend_credentials: description: > 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. type: boolean Identity: type: object description: | Identity information of a request. properties: api_key: type: string description: | API key for authentication. REST NAMESPACE ONLY This is passed via the `x-api-key` header. auth_token: type: string description: | Bearer token for authentication. REST NAMESPACE ONLY This is passed via the `Authorization` header with the Bearer scheme (e.g., `Bearer `). Context: type: object description: > 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-: `. For example, a context entry `{"trace_id": "abc123"}` would be sent as the header `x-lance-ctx-trace_id: abc123`. additionalProperties: type: string DescribeTableResponse: type: object properties: table: type: string description: | Table name. Only populated when `load_detailed_metadata` is true. namespace: type: array items: type: string description: | The namespace identifier as a list of parts. Only populated when `load_detailed_metadata` is true. version: type: integer format: int64 minimum: 0 description: | Table version number. Only populated when `load_detailed_metadata` is true. location: type: string description: | Table storage location (e.g., S3/GCS path). table_uri: type: string description: > Table URI. Unlike location, this field must be a complete and valid URI. Only returned when `with_table_uri` is true. schema: $ref: '#/components/schemas/JsonArrowSchema' description: | Table schema in JSON Arrow format. Only populated when `load_detailed_metadata` is true. storage_options: type: object description: > 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. additionalProperties: type: string stats: $ref: '#/components/schemas/TableBasicStats' nullable: true description: | Table statistics. Only populated when `load_detailed_metadata` is true. metadata: type: object description: > Optional table metadata as key-value pairs. This records the information of the table and requires loading the table. It is only populated when `load_detailed_metadata` is true. additionalProperties: type: string properties: type: object description: >- Properties stored on the table, if supported by the server. This records the information managed by the namespace. If the server does not support table properties, it should return null for this field. If table properties are supported, but none are set, it should return an empty object. additionalProperties: type: string example: owner: Ralph created_at: '1452120468' default: {} nullable: true managed_versioning: type: boolean description: > 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: type: boolean nullable: true description: > 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. ErrorResponse: type: object description: Common JSON error response model required: - code properties: error: type: string description: A brief, human-readable message about the error. example: Table 'users' not found in namespace 'production' code: type: integer minimum: 0 description: | Lance Namespace error code identifying the error type. Error codes: 0 - Unsupported: Operation not supported by this backend 1 - NamespaceNotFound: The specified namespace does not exist 2 - NamespaceAlreadyExists: A namespace with this name already exists 3 - NamespaceNotEmpty: Namespace contains tables or child namespaces 4 - TableNotFound: The specified table does not exist 5 - TableAlreadyExists: A table with this name already exists 6 - TableIndexNotFound: The specified table index does not exist 7 - TableIndexAlreadyExists: A table index with this name already exists 8 - TableTagNotFound: The specified table tag does not exist 9 - TableTagAlreadyExists: A table tag with this name already exists 10 - TransactionNotFound: The specified transaction does not exist 11 - TableVersionNotFound: The specified table version does not exist 12 - TableColumnNotFound: The specified table column does not exist 13 - InvalidInput: Malformed request or invalid parameters 14 - ConcurrentModification: Optimistic concurrency conflict 15 - PermissionDenied: User lacks permission for this operation 16 - Unauthenticated: Authentication credentials are missing or invalid 17 - ServiceUnavailable: Service is temporarily unavailable 18 - Internal: Unexpected server/implementation error 19 - InvalidTableState: Table is in an invalid state for the operation 20 - TableSchemaValidationError: Table schema validation failed example: 4 detail: type: string description: > An optional human-readable explanation of the error. This can be used to record additional information such as stack trace. example: The table may have been dropped or renamed instance: type: string description: > A string that identifies the specific occurrence of the error. This can be a URI, a request or response ID, or anything that the implementation can recognize to trace specific occurrence of the error. example: /v1/table/production$users/describe JsonArrowSchema: type: object description: | JSON representation of a Apache Arrow schema. required: - fields properties: fields: type: array items: $ref: '#/components/schemas/JsonArrowField' metadata: type: object additionalProperties: type: string propertyNames: type: string TableBasicStats: type: object required: - num_deleted_rows - num_fragments properties: num_deleted_rows: type: integer minimum: 0 description: Number of deleted rows in the table num_fragments: type: integer minimum: 0 description: Number of fragments in the table JsonArrowField: type: object description: | JSON representation of an Apache Arrow field. required: - name - type - nullable properties: metadata: type: object additionalProperties: type: string propertyNames: type: string name: type: string nullable: type: boolean type: $ref: '#/components/schemas/JsonArrowDataType' JsonArrowDataType: type: object description: JSON representation of an Apache Arrow DataType required: - type properties: fields: type: array items: $ref: '#/components/schemas/JsonArrowField' description: Fields for complex types like Struct, Union, etc. length: type: integer format: int64 description: Length for fixed-size types minimum: 0 type: type: string description: The data type name responses: DescribeTableResponse: description: Table properties result when loading a table content: application/json: schema: $ref: '#/components/schemas/DescribeTableResponse' BadRequestErrorResponse: description: >- 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. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: type: /errors/bad-request title: Malformed request status: 400 detail: '' instance: /v1/namespaces UnauthorizedErrorResponse: description: >- Unauthorized. The request lacks valid authentication credentials for the operation. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: type: /errors/unauthorized-request title: No valid authentication credentials for the operation status: 401 detail: '' instance: /v1/namespaces ForbiddenErrorResponse: description: Forbidden. Authenticated user does not have the necessary permissions. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: type: /errors/forbidden-request title: Not authorized to make this request status: 403 detail: '' instance: /v1/namespaces NotFoundErrorResponse: description: A server-side problem that means can not find the specified resource. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: type: /errors/not-found-error title: Not found Error status: 404 detail: '' instance: /v1/namespaces/{ns} ServiceUnavailableErrorResponse: description: >- 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. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: type: /errors/service-unavailable title: Slow down status: 503 detail: '' instance: /v1/namespaces ServerErrorResponse: description: >- 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. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: type: /errors/server-error title: Internal Server Error status: 500 detail: '' instance: /v1/namespaces securitySchemes: OAuth2: type: oauth2 flows: clientCredentials: tokenUrl: /oauth/token scopes: {} BearerAuth: type: http scheme: bearer ApiKeyAuth: type: apiKey in: header name: x-api-key ````