feat: fix location requirement and add vended credential and table metadata support (#291)

Author: jackye1995

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

@@ -10,7 +10,8 @@
 |**id** | **List<String>** |  |  [optional] |
 |**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 false (default), only `location` is required in the response. When true, the response includes additional metadata such as `version`, `schema`, and `stats` which require reading the dataset.  |  [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] |
+|**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

@@ -10,11 +10,12 @@
 |**table** | **String** | Table name. Only populated when `load_detailed_metadata` is true.  |  [optional] |
 |**namespace** | **List<String>** | The namespace identifier as a list of parts. Only populated when `load_detailed_metadata` is true.  |  [optional] |
 |**version** | **Long** | Table version number. Only populated when `load_detailed_metadata` is true.  |  [optional] |
-|**location** | **String** | Table storage location (e.g., S3/GCS path). This is the only required field and is always returned.  |  |
+|**location** | **String** | Table storage location (e.g., S3/GCS path).  |  [optional] |
 |**tableUri** | **String** | Table URI. Unlike location, this field must be a complete and valid URI. Only returned when `with_table_uri` is true.  |  [optional] |
 |**schema** | [**JsonArrowSchema**](JsonArrowSchema.md) | Table schema in JSON Arrow format. Only populated when `load_detailed_metadata` is true.  |  [optional] |
-|**storageOptions** | **Map<String, String>** | 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.  |  [optional] |
+|**storageOptions** | **Map<String, String>** | 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.  |  [optional] |
 |**stats** | [**TableBasicStats**](TableBasicStats.md) | Table statistics. Only populated when `load_detailed_metadata` is true.  |  [optional] |
+|**metadata** | **Map<String, String>** | Optional table metadata as key-value pairs.  |  [optional] |
 
 
 

docs/src/rest.yaml

@@ -2150,16 +2150,20 @@ components:
         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`
+            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
+        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
-          default: false
 
     DescribeTableResponse:
       type: object
-      required:
-        - location
       properties:
         table:
           type: string
@@ -2184,7 +2188,6 @@ components:
           type: string
           description: |
             Table storage location (e.g., S3/GCS path).
-            This is the only required field and is always returned.
         table_uri:
           type: string
           description: |
@@ -2201,6 +2204,9 @@ components:
             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:
@@ -2209,6 +2215,12 @@ components:
           description: |
             Table statistics.
             Only populated when `load_detailed_metadata` is true.
+        metadata:
+          type: object
+          description: |
+            Optional table metadata as key-value pairs.
+          additionalProperties:
+            type: string
 
     TableBasicStats:
       type: object

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

@@ -2886,7 +2886,8 @@ components:
         - id
         version: 0
         with_table_uri: false
-        load_detailed_metadata: false
+        load_detailed_metadata: true
+        vend_credentials: true
       properties:
         id:
           items:
@@ -2906,12 +2907,18 @@ components:
             Default is false.
           type: boolean
         load_detailed_metadata:
-          default: false
           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`
+            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
+        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
     DescribeTableResponse:
       example:
@@ -2939,6 +2946,8 @@ components:
               - null
               - null
               type: type
+        metadata:
+          key: metadata
         table_uri: table_uri
         stats:
           num_deleted_rows: 0
@@ -2974,7 +2983,6 @@ components:
         location:
           description: |
             Table storage location (e.g., S3/GCS path).
-            This is the only required field and is always returned.
           type: string
         table_uri:
           description: |
@@ -2990,10 +2998,16 @@ components:
             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.
         stats:
           $ref: '#/components/schemas/TableBasicStats'
-      required:
-      - location
+        metadata:
+          additionalProperties:
+            type: string
+          description: |
+            Optional table metadata as key-value pairs.
     TableBasicStats:
       example:
         num_deleted_rows: 0

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

@@ -10,7 +10,8 @@
 |**id** | **List<String>** |  |  [optional] |
 |**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 false (default), only `location` is required in the response. When true, the response includes additional metadata such as `version`, `schema`, and `stats` which require reading the dataset.  |  [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] |
+|**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

@@ -10,11 +10,12 @@
 |**table** | **String** | Table name. Only populated when `load_detailed_metadata` is true.  |  [optional] |
 |**namespace** | **List<String>** | The namespace identifier as a list of parts. Only populated when `load_detailed_metadata` is true.  |  [optional] |
 |**version** | **Long** | Table version number. Only populated when `load_detailed_metadata` is true.  |  [optional] |
-|**location** | **String** | Table storage location (e.g., S3/GCS path). This is the only required field and is always returned.  |  |
+|**location** | **String** | Table storage location (e.g., S3/GCS path).  |  [optional] |
 |**tableUri** | **String** | Table URI. Unlike location, this field must be a complete and valid URI. Only returned when `with_table_uri` is true.  |  [optional] |
 |**schema** | [**JsonArrowSchema**](JsonArrowSchema.md) | Table schema in JSON Arrow format. Only populated when `load_detailed_metadata` is true.  |  [optional] |
-|**storageOptions** | **Map<String, String>** | 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.  |  [optional] |
+|**storageOptions** | **Map<String, String>** | 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.  |  [optional] |
 |**stats** | [**TableBasicStats**](TableBasicStats.md) | Table statistics. Only populated when `load_detailed_metadata` is true.  |  [optional] |
+|**metadata** | **Map<String, String>** | Optional table metadata as key-value pairs.  |  [optional] |
 
 
 

java/lance-namespace-apache-client/src/main/java/org/lance/namespace/model/DescribeTableRequest.java

@@ -29,7 +29,8 @@
   DescribeTableRequest.JSON_PROPERTY_ID,
   DescribeTableRequest.JSON_PROPERTY_VERSION,
   DescribeTableRequest.JSON_PROPERTY_WITH_TABLE_URI,
-  DescribeTableRequest.JSON_PROPERTY_LOAD_DETAILED_METADATA
+  DescribeTableRequest.JSON_PROPERTY_LOAD_DETAILED_METADATA,
+  DescribeTableRequest.JSON_PROPERTY_VEND_CREDENTIALS
 })
 @javax.annotation.Generated(
     value = "org.openapitools.codegen.languages.JavaClientCodegen",
@@ -45,7 +46,10 @@ public class DescribeTableRequest {
   @javax.annotation.Nullable private Boolean withTableUri = false;
 
   public static final String JSON_PROPERTY_LOAD_DETAILED_METADATA = "load_detailed_metadata";
-  @javax.annotation.Nullable private Boolean loadDetailedMetadata = false;
+  @javax.annotation.Nullable private Boolean loadDetailedMetadata;
+
+  public static final String JSON_PROPERTY_VEND_CREDENTIALS = "vend_credentials";
+  @javax.annotation.Nullable private Boolean vendCredentials;
 
   public DescribeTableRequest() {}
 
@@ -138,10 +142,10 @@ public DescribeTableRequest loadDetailedMetadata(
   }
 
   /**
-   * 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` which require
-   * reading the dataset.
+   * 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.
    *
    * @return loadDetailedMetadata
    */
@@ -158,6 +162,32 @@ public void setLoadDetailedMetadata(@javax.annotation.Nullable Boolean loadDetai
     this.loadDetailedMetadata = loadDetailedMetadata;
   }
 
+  public DescribeTableRequest vendCredentials(@javax.annotation.Nullable Boolean vendCredentials) {
+
+    this.vendCredentials = vendCredentials;
+    return this;
+  }
+
+  /**
+   * 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.
+   *
+   * @return vendCredentials
+   */
+  @javax.annotation.Nullable
+  @JsonProperty(JSON_PROPERTY_VEND_CREDENTIALS)
+  @JsonInclude(value = JsonInclude.Include.USE_DEFAULTS)
+  public Boolean getVendCredentials() {
+    return vendCredentials;
+  }
+
+  @JsonProperty(JSON_PROPERTY_VEND_CREDENTIALS)
+  @JsonInclude(value = JsonInclude.Include.USE_DEFAULTS)
+  public void setVendCredentials(@javax.annotation.Nullable Boolean vendCredentials) {
+    this.vendCredentials = vendCredentials;
+  }
+
   @Override
   public boolean equals(Object o) {
     if (this == o) {
@@ -170,12 +200,13 @@ public boolean equals(Object o) {
     return Objects.equals(this.id, describeTableRequest.id)
         && Objects.equals(this.version, describeTableRequest.version)
         && Objects.equals(this.withTableUri, describeTableRequest.withTableUri)
-        && Objects.equals(this.loadDetailedMetadata, describeTableRequest.loadDetailedMetadata);
+        && Objects.equals(this.loadDetailedMetadata, describeTableRequest.loadDetailedMetadata)
+        && Objects.equals(this.vendCredentials, describeTableRequest.vendCredentials);
   }
 
   @Override
   public int hashCode() {
-    return Objects.hash(id, version, withTableUri, loadDetailedMetadata);
+    return Objects.hash(id, version, withTableUri, loadDetailedMetadata, vendCredentials);
   }
 
   @Override
@@ -188,6 +219,7 @@ public String toString() {
     sb.append("    loadDetailedMetadata: ")
         .append(toIndentedString(loadDetailedMetadata))
         .append("\n");
+    sb.append("    vendCredentials: ").append(toIndentedString(vendCredentials)).append("\n");
     sb.append("}");
     return sb.toString();
   }
@@ -302,6 +334,22 @@ public String toUrlQueryString(String prefix) {
       }
     }
 
+    // add `vend_credentials` to the URL query string
+    if (getVendCredentials() != null) {
+      try {
+        joiner.add(
+            String.format(
+                "%svend_credentials%s=%s",
+                prefix,
+                suffix,
+                URLEncoder.encode(String.valueOf(getVendCredentials()), "UTF-8")
+                    .replaceAll("\\+", "%20")));
+      } catch (UnsupportedEncodingException e) {
+        // Should never happen, UTF-8 is always supported
+        throw new RuntimeException(e);
+      }
+    }
+
     return joiner.toString();
   }
 }