本页尚未翻译

本页内容仍为英文原文，源自官方文档 api-reference/rest/table/describe-information-of-a-table。中文翻译正在分批进行中。

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

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: http://localhost:2333
    description: Default local server
  - 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
        tag:
          description: >
            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`.
          type: string
        branch:
          type: string
          description: |
            Branch to target. When not specified, the main branch is used.
        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 <token>`).
    Context:
      type: object
      description: >
        Arbitrary context as key-value pairs.

        How to use the context is custom to the specific implementation.


        On a request, it carries caller-provided context to the implementation.

        On a response, it carries implementation-provided context back to the
        caller.


        REST NAMESPACE ONLY

        Context entries are mapped to and from HTTP headers using the `header.`
        prefix:

        - On a request, any entry whose key starts with `header.` is sent as an
        HTTP
          request header with the prefix stripped. For example, the entry
          `{"header.Authorization": "Bearer abc"}` is sent as the request header
          `Authorization: Bearer abc`.
        - On a response, every HTTP response header is returned as an entry
        whose key is the
          header name prefixed with `header.`. For example, the response header
          `x-request-id: abc123` is returned as the entry `{"header.x-request-id": "abc123"}`.
      additionalProperties:
        type: string
    DescribeTableResponse:
      type: object
      properties:
        context:
          $ref: '#/components/schemas/Context'
        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:
        context:
          $ref: '#/components/schemas/Context'
        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 field 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
              21 - Throttling: Request rate limit exceeded
              22 - TableBranchNotFound: The specified table branch does not exist
              23 - TableBranchAlreadyExists: A table branch with this name already exists
          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