feat: add check_declared in describe table request (#334)

Checking declared implies additional calls, the caller should have the
option to choose to not check it if the information is not important.

Author: jackye1995

docs/src/client/operations/index.md

@@ -119,10 +119,10 @@ The following restrictions apply to the recommended basic operations to minimize
 This means the namespace must be empty (no tables or child namespaces) before it can be dropped.
 The `Cascade` behavior mode, which recursively drops all contents, is not required for basic implementations.
 
-**DescribeTable:** Only `load_detailed_metadata=false` (the default) is required.
+**DescribeTable:** Only `load_detailed_metadata=false` and `check_declared=false` (the defaults) are required.
 This means the implementation only needs to return the table `location` without opening the dataset.
 Returning detailed metadata such as `version`, `schema`, and `stats` (which require opening the dataset)
-is not required for basic implementations.
+or checking whether the table exists only as a namespace declaration is not required for basic implementations.
 
 ### Why Not `CreateTable` and `DropTable`?
 

docs/src/client/operations/models/DescribeTableRequest.md

@@ -13,6 +13,7 @@
 |**version** | **Long** | Version of the table to describe. If not specified, server should resolve it to the latest version.  |  [optional] |
 |**withTableUri** | **Boolean** | Whether to include the table URI in the response. Default is false.  |  [optional] |
 |**loadDetailedMetadata** | **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.  |  [optional] |
+|**checkDeclared** | **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.  |  [optional] |
 |**vendCredentials** | **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.  |  [optional] |
 
 

docs/src/client/operations/models/DescribeTableResponse.md

@@ -18,7 +18,7 @@
 |**metadata** | **Map<String, String>** | 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.  |  [optional] |
 |**properties** | **Map<String, String>** | 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. |  [optional] |
 |**managedVersioning** | **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.  |  [optional] |
-|**isOnlyDeclared** | **Boolean** | 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. Operations like describe_table with load_detailed_metadata=true may fail for such tables. When false or not set, the table has storage components (data and metadata files).  |  [optional] |
+|**isOnlyDeclared** | **Boolean** | 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.  |  [optional] |
 
 
 

docs/src/rest.yaml

@@ -392,6 +392,7 @@ paths:
       - $ref: "#/components/parameters/delimiter"
       - $ref: "#/components/parameters/with_table_uri"
       - $ref: "#/components/parameters/load_detailed_metadata"
+      - $ref: "#/components/parameters/check_declared"
     post:
       tags:
         - Table
@@ -402,7 +403,7 @@ paths:
         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.
+        REST namespace passes `with_table_uri`, `load_detailed_metadata`, and `check_declared` as query parameters instead of in the request body.
       requestBody:
         required: true
         content:
@@ -2069,6 +2070,18 @@ components:
       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:
     ErrorResponse:
@@ -2459,6 +2472,16 @@ components:
             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`.
@@ -2547,13 +2570,18 @@ components:
             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.
-            Operations like describe_table with load_detailed_metadata=true may fail
-            for such tables. When false or not set, the table has storage components
-            (data and metadata files).
+            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.
 
     TableBasicStats:
       type: object

docs/src/rest/catalog-spec.md

@@ -133,12 +133,14 @@ Uses GET without a request body. Pagination parameters are passed as query param
 
 **Route:** `POST /v1/table/{id}/describe`
 
-The `with_table_uri` field is passed as a query parameter instead of in the request body.
-
-| Request Field    | REST Form        | Location        |
-|------------------|------------------|-----------------|
-| `id`             | `{id}`           | Path parameter  |
-| `with_table_uri` | `with_table_uri` | Query parameter |
+The `with_table_uri`, `load_detailed_metadata`, and `check_declared` fields are passed as query parameters instead of in the request body.
+
+| Request Field            | REST Form                | Location        |
+|--------------------------|--------------------------|-----------------|
+| `id`                     | `{id}`                   | Path parameter  |
+| `with_table_uri`         | `with_table_uri`         | Query parameter |
+| `load_detailed_metadata` | `load_detailed_metadata` | Query parameter |
+| `check_declared`         | `check_declared`         | Query parameter |
 
 ### CreateTable
 

java/lance-namespace-apache-client/api/openapi.yaml

@@ -411,18 +411,20 @@ paths:
     - $ref: '#/components/parameters/delimiter'
     - $ref: '#/components/parameters/with_table_uri'
     - $ref: '#/components/parameters/load_detailed_metadata'
+    - $ref: '#/components/parameters/check_declared'
     post:
       description: |
         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.
+        REST namespace passes `with_table_uri`, `load_detailed_metadata`, and `check_declared` as query parameters instead of in the request body.
       operationId: DescribeTable
       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'
       requestBody:
         content:
           application/json:
@@ -2472,6 +2474,20 @@ components:
         default: false
         type: boolean
       style: form
+    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.
+      explode: true
+      in: query
+      name: check_declared
+      required: false
+      schema:
+        default: false
+        type: boolean
+      style: form
   responses:
     ListNamespacesResponse:
       content:
@@ -3401,6 +3417,7 @@ components:
           auth_token: auth_token
         context:
           key: context
+        check_declared: false
         id:
         - id
         - id
@@ -3447,6 +3464,16 @@ components:
             When not set, the implementation can decide whether to return detailed metadata
             and which parts of detailed metadata to return.
           type: boolean
+        check_declared:
+          default: false
+          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
         vend_credentials:
           description: |
             Whether to include vended credentials in the response `storage_options`.
@@ -3572,10 +3599,15 @@ components:
             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.
-            Operations like describe_table with load_detailed_metadata=true may fail
-            for such tables. When false or not set, the table has storage components
-            (data and metadata files).
+            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.
           type: boolean
+          nullable: true
     TableBasicStats:
       example:
         num_deleted_rows: 0

java/lance-namespace-apache-client/docs/DescribeTableRequest.md

@@ -13,6 +13,7 @@
 |**version** | **Long** | Version of the table to describe. If not specified, server should resolve it to the latest version.  |  [optional] |
 |**withTableUri** | **Boolean** | Whether to include the table URI in the response. Default is false.  |  [optional] |
 |**loadDetailedMetadata** | **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.  |  [optional] |
+|**checkDeclared** | **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.  |  [optional] |
 |**vendCredentials** | **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.  |  [optional] |
 
 

java/lance-namespace-apache-client/docs/DescribeTableResponse.md

@@ -18,7 +18,7 @@
 |**metadata** | **Map<String, String>** | 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.  |  [optional] |
 |**properties** | **Map<String, String>** | 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. |  [optional] |
 |**managedVersioning** | **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.  |  [optional] |
-|**isOnlyDeclared** | **Boolean** | 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. Operations like describe_table with load_detailed_metadata=true may fail for such tables. When false or not set, the table has storage components (data and metadata files).  |  [optional] |
+|**isOnlyDeclared** | **Boolean** | 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.  |  [optional] |
 
 
 

java/lance-namespace-apache-client/docs/MetadataApi.md

@@ -1414,11 +1414,11 @@ public class Example {
 
 ## describeTable
 
-> DescribeTableResponse describeTable(id, describeTableRequest, delimiter, withTableUri, loadDetailedMetadata)
+> DescribeTableResponse describeTable(id, describeTableRequest, delimiter, withTableUri, loadDetailedMetadata, checkDeclared)
 
 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. 
+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. 
 
 ### Example
 
@@ -1456,8 +1456,9 @@ public class Example {
         String delimiter = "delimiter_example"; // String | An optional delimiter of the `string identifier`, following the Lance Namespace spec. When not specified, the `$` delimiter must be used. 
         Boolean withTableUri = false; // Boolean | Whether to include the table URI in the response
         Boolean loadDetailedMetadata = false; // Boolean | 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`. 
+        Boolean checkDeclared = false; // Boolean | 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. 
         try {
-            DescribeTableResponse result = apiInstance.describeTable(id, describeTableRequest, delimiter, withTableUri, loadDetailedMetadata);
+            DescribeTableResponse result = apiInstance.describeTable(id, describeTableRequest, delimiter, withTableUri, loadDetailedMetadata, checkDeclared);
             System.out.println(result);
         } catch (ApiException e) {
             System.err.println("Exception when calling MetadataApi#describeTable");
@@ -1480,6 +1481,7 @@ public class Example {
 | **delimiter** | **String**| An optional delimiter of the `string identifier`, following the Lance Namespace spec. When not specified, the `$` delimiter must be used.  | [optional] |
 | **withTableUri** | **Boolean**| Whether to include the table URI in the response | [optional] [default to false] |
 | **loadDetailedMetadata** | **Boolean**| 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`.  | [optional] [default to false] |
+| **checkDeclared** | **Boolean**| 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.  | [optional] [default to false] |
 
 ### Return type