fix: pass manifest naming scheme to create_table_versions (#307)

Author: jackye1995

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

@@ -16,6 +16,7 @@ Request to create a new table version entry. This supports `put_if_not_exists` s
 |**manifestSize** | **Long** | Size of the manifest file in bytes |  [optional] |
 |**eTag** | **String** | Optional ETag for the manifest file |  [optional] |
 |**metadata** | **Map<String, String>** | Optional metadata for the version |  [optional] |
+|**namingScheme** | **String** | The naming scheme used for manifest files in the `_versions/` directory.  Known values: - `V1`: `_versions/{version}.manifest` - Simple version-based naming - `V2`: `_versions/{inverted_version}.manifest` - Zero-padded, reversed version number   (uses `u64::MAX - version`) for O(1) lookup of latest version on object stores  V2 is preferred for new tables as it enables efficient latest-version discovery without needing to list all versions.  |  [optional] |
 
 
 

docs/src/rest.yaml

@@ -3931,6 +3931,8 @@ components:
           additionalProperties:
             type: string
           description: Optional metadata for the version
+        naming_scheme:
+          $ref: "#/components/schemas/ManifestNamingScheme"
 
     CreateTableVersionResponse:
       type: object
@@ -4066,6 +4068,20 @@ components:
             type: string
           description: Optional key-value pairs of metadata
 
+    ManifestNamingScheme:
+      type: string
+      description: |
+        The naming scheme used for manifest files in the `_versions/` directory.
+
+        Known values:
+        - `V1`: `_versions/{version}.manifest` - Simple version-based naming
+        - `V2`: `_versions/{inverted_version}.manifest` - Zero-padded, reversed version number
+          (uses `u64::MAX - version`) for O(1) lookup of latest version on object stores
+
+        V2 is preferred for new tables as it enables efficient latest-version discovery
+        without needing to list all versions.
+      example: V2
+
     ExplainTableQueryPlanRequest:
       type: object
       required:

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

@@ -5732,6 +5732,7 @@ components:
         This supports `put_if_not_exists` semantics,
         where the operation fails if the version already exists.
       example:
+        naming_scheme: V2
         metadata:
           key: metadata
         manifest_path: manifest_path
@@ -5785,6 +5786,19 @@ components:
           additionalProperties:
             type: string
           description: Optional metadata for the version
+        naming_scheme:
+          description: |
+            The naming scheme used for manifest files in the `_versions/` directory.
+
+            Known values:
+            - `V1`: `_versions/{version}.manifest` - Simple version-based naming
+            - `V2`: `_versions/{inverted_version}.manifest` - Zero-padded, reversed version number
+              (uses `u64::MAX - version`) for O(1) lookup of latest version on object stores
+
+            V2 is preferred for new tables as it enables efficient latest-version discovery
+            without needing to list all versions.
+          example: V2
+          type: string
       required:
       - manifest_path
       - version
@@ -5981,6 +5995,19 @@ components:
       required:
       - manifest_path
       - version
+    ManifestNamingScheme:
+      description: |
+        The naming scheme used for manifest files in the `_versions/` directory.
+
+        Known values:
+        - `V1`: `_versions/{version}.manifest` - Simple version-based naming
+        - `V2`: `_versions/{inverted_version}.manifest` - Zero-padded, reversed version number
+          (uses `u64::MAX - version`) for O(1) lookup of latest version on object stores
+
+        V2 is preferred for new tables as it enables efficient latest-version discovery
+        without needing to list all versions.
+      example: V2
+      type: string
     ExplainTableQueryPlanRequest:
       example:
         identity:

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

@@ -16,6 +16,7 @@ Request to create a new table version entry. This supports `put_if_not_exists` s
 |**manifestSize** | **Long** | Size of the manifest file in bytes |  [optional] |
 |**eTag** | **String** | Optional ETag for the manifest file |  [optional] |
 |**metadata** | **Map<String, String>** | Optional metadata for the version |  [optional] |
+|**namingScheme** | **String** | The naming scheme used for manifest files in the `_versions/` directory.  Known values: - `V1`: `_versions/{version}.manifest` - Simple version-based naming - `V2`: `_versions/{inverted_version}.manifest` - Zero-padded, reversed version number   (uses `u64::MAX - version`) for O(1) lookup of latest version on object stores  V2 is preferred for new tables as it enables efficient latest-version discovery without needing to list all versions.  |  [optional] |
 
 
 

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

@@ -38,7 +38,8 @@
   CreateTableVersionRequest.JSON_PROPERTY_MANIFEST_PATH,
   CreateTableVersionRequest.JSON_PROPERTY_MANIFEST_SIZE,
   CreateTableVersionRequest.JSON_PROPERTY_E_TAG,
-  CreateTableVersionRequest.JSON_PROPERTY_METADATA
+  CreateTableVersionRequest.JSON_PROPERTY_METADATA,
+  CreateTableVersionRequest.JSON_PROPERTY_NAMING_SCHEME
 })
 @javax.annotation.Generated(
     value = "org.openapitools.codegen.languages.JavaClientCodegen",
@@ -68,6 +69,9 @@ public class CreateTableVersionRequest {
   public static final String JSON_PROPERTY_METADATA = "metadata";
   @javax.annotation.Nullable private Map<String, String> metadata = new HashMap<>();
 
+  public static final String JSON_PROPERTY_NAMING_SCHEME = "naming_scheme";
+  @javax.annotation.Nullable private String namingScheme;
+
   public CreateTableVersionRequest() {}
 
   public CreateTableVersionRequest identity(@javax.annotation.Nullable Identity identity) {
@@ -291,6 +295,35 @@ public void setMetadata(@javax.annotation.Nullable Map<String, String> metadata)
     this.metadata = metadata;
   }
 
+  public CreateTableVersionRequest namingScheme(@javax.annotation.Nullable String namingScheme) {
+
+    this.namingScheme = namingScheme;
+    return this;
+  }
+
+  /**
+   * The naming scheme used for manifest files in the &#x60;_versions/&#x60; directory. Known
+   * values: - &#x60;V1&#x60;: &#x60;_versions/{version}.manifest&#x60; - Simple version-based
+   * naming - &#x60;V2&#x60;: &#x60;_versions/{inverted_version}.manifest&#x60; - Zero-padded,
+   * reversed version number (uses &#x60;u64::MAX - version&#x60;) for O(1) lookup of latest version
+   * on object stores V2 is preferred for new tables as it enables efficient latest-version
+   * discovery without needing to list all versions.
+   *
+   * @return namingScheme
+   */
+  @javax.annotation.Nullable
+  @JsonProperty(JSON_PROPERTY_NAMING_SCHEME)
+  @JsonInclude(value = JsonInclude.Include.USE_DEFAULTS)
+  public String getNamingScheme() {
+    return namingScheme;
+  }
+
+  @JsonProperty(JSON_PROPERTY_NAMING_SCHEME)
+  @JsonInclude(value = JsonInclude.Include.USE_DEFAULTS)
+  public void setNamingScheme(@javax.annotation.Nullable String namingScheme) {
+    this.namingScheme = namingScheme;
+  }
+
   @Override
   public boolean equals(Object o) {
     if (this == o) {
@@ -307,12 +340,14 @@ public boolean equals(Object o) {
         && Objects.equals(this.manifestPath, createTableVersionRequest.manifestPath)
         && Objects.equals(this.manifestSize, createTableVersionRequest.manifestSize)
         && Objects.equals(this.eTag, createTableVersionRequest.eTag)
-        && Objects.equals(this.metadata, createTableVersionRequest.metadata);
+        && Objects.equals(this.metadata, createTableVersionRequest.metadata)
+        && Objects.equals(this.namingScheme, createTableVersionRequest.namingScheme);
   }
 
   @Override
   public int hashCode() {
-    return Objects.hash(identity, context, id, version, manifestPath, manifestSize, eTag, metadata);
+    return Objects.hash(
+        identity, context, id, version, manifestPath, manifestSize, eTag, metadata, namingScheme);
   }
 
   @Override
@@ -327,6 +362,7 @@ public String toString() {
     sb.append("    manifestSize: ").append(toIndentedString(manifestSize)).append("\n");
     sb.append("    eTag: ").append(toIndentedString(eTag)).append("\n");
     sb.append("    metadata: ").append(toIndentedString(metadata)).append("\n");
+    sb.append("    namingScheme: ").append(toIndentedString(namingScheme)).append("\n");
     sb.append("}");
     return sb.toString();
   }
@@ -505,6 +541,22 @@ public String toUrlQueryString(String prefix) {
       }
     }
 
+    // add `naming_scheme` to the URL query string
+    if (getNamingScheme() != null) {
+      try {
+        joiner.add(
+            String.format(
+                "%snaming_scheme%s=%s",
+                prefix,
+                suffix,
+                URLEncoder.encode(String.valueOf(getNamingScheme()), "UTF-8")
+                    .replaceAll("\\+", "%20")));
+      } catch (UnsupportedEncodingException e) {
+        // Should never happen, UTF-8 is always supported
+        throw new RuntimeException(e);
+      }
+    }
+
     return joiner.toString();
   }
 }

java/lance-namespace-springboot-server/src/main/java/org/lance/namespace/server/springboot/model/CreateTableVersionRequest.java

@@ -55,6 +55,8 @@ public class CreateTableVersionRequest {
 
   @Valid private Map<String, String> metadata = new HashMap<>();
 
+  private String namingScheme;
+
   public CreateTableVersionRequest() {
     super();
   }
@@ -279,6 +281,35 @@ public void setMetadata(Map<String, String> metadata) {
     this.metadata = metadata;
   }
 
+  public CreateTableVersionRequest namingScheme(String namingScheme) {
+    this.namingScheme = namingScheme;
+    return this;
+  }
+
+  /**
+   * The naming scheme used for manifest files in the `_versions/` directory. Known values: - `V1`:
+   * `_versions/{version}.manifest` - Simple version-based naming - `V2`:
+   * `_versions/{inverted_version}.manifest` - Zero-padded, reversed version number (uses `u64::MAX
+   * - version`) for O(1) lookup of latest version on object stores V2 is preferred for new tables
+   * as it enables efficient latest-version discovery without needing to list all versions.
+   *
+   * @return namingScheme
+   */
+  @Schema(
+      name = "naming_scheme",
+      example = "V2",
+      description =
+          "The naming scheme used for manifest files in the `_versions/` directory.  Known values: - `V1`: `_versions/{version}.manifest` - Simple version-based naming - `V2`: `_versions/{inverted_version}.manifest` - Zero-padded, reversed version number   (uses `u64::MAX - version`) for O(1) lookup of latest version on object stores  V2 is preferred for new tables as it enables efficient latest-version discovery without needing to list all versions. ",
+      requiredMode = Schema.RequiredMode.NOT_REQUIRED)
+  @JsonProperty("naming_scheme")
+  public String getNamingScheme() {
+    return namingScheme;
+  }
+
+  public void setNamingScheme(String namingScheme) {
+    this.namingScheme = namingScheme;
+  }
+
   @Override
   public boolean equals(Object o) {
     if (this == o) {
@@ -295,12 +326,14 @@ public boolean equals(Object o) {
         && Objects.equals(this.manifestPath, createTableVersionRequest.manifestPath)
         && Objects.equals(this.manifestSize, createTableVersionRequest.manifestSize)
         && Objects.equals(this.eTag, createTableVersionRequest.eTag)
-        && Objects.equals(this.metadata, createTableVersionRequest.metadata);
+        && Objects.equals(this.metadata, createTableVersionRequest.metadata)
+        && Objects.equals(this.namingScheme, createTableVersionRequest.namingScheme);
   }
 
   @Override
   public int hashCode() {
-    return Objects.hash(identity, context, id, version, manifestPath, manifestSize, eTag, metadata);
+    return Objects.hash(
+        identity, context, id, version, manifestPath, manifestSize, eTag, metadata, namingScheme);
   }
 
   @Override
@@ -315,6 +348,7 @@ public String toString() {
     sb.append("    manifestSize: ").append(toIndentedString(manifestSize)).append("\n");
     sb.append("    eTag: ").append(toIndentedString(eTag)).append("\n");
     sb.append("    metadata: ").append(toIndentedString(metadata)).append("\n");
+    sb.append("    namingScheme: ").append(toIndentedString(namingScheme)).append("\n");
     sb.append("}");
     return sb.toString();
   }

python/lance_namespace_urllib3_client/docs/CreateTableVersionRequest.md

@@ -14,6 +14,7 @@ Name | Type | Description | Notes
 **manifest_size** | **int** | Size of the manifest file in bytes | [optional] 
 **e_tag** | **str** | Optional ETag for the manifest file | [optional] 
 **metadata** | **Dict[str, str]** | Optional metadata for the version | [optional] 
+**naming_scheme** | **str** | The naming scheme used for manifest files in the `_versions/` directory.  Known values: - `V1`: `_versions/{version}.manifest` - Simple version-based naming - `V2`: `_versions/{inverted_version}.manifest` - Zero-padded, reversed version number   (uses `u64::MAX - version`) for O(1) lookup of latest version on object stores  V2 is preferred for new tables as it enables efficient latest-version discovery without needing to list all versions.  | [optional] 
 
 ## Example
 

python/lance_namespace_urllib3_client/lance_namespace_urllib3_client/models/create_table_version_request.py

@@ -36,7 +36,8 @@ class CreateTableVersionRequest(BaseModel):
     manifest_size: Optional[Annotated[int, Field(strict=True, ge=0)]] = Field(default=None, description="Size of the manifest file in bytes")
     e_tag: Optional[StrictStr] = Field(default=None, description="Optional ETag for the manifest file")
     metadata: Optional[Dict[str, StrictStr]] = Field(default=None, description="Optional metadata for the version")
-    __properties: ClassVar[List[str]] = ["identity", "context", "id", "version", "manifest_path", "manifest_size", "e_tag", "metadata"]
+    naming_scheme: Optional[StrictStr] = Field(default=None, description="The naming scheme used for manifest files in the `_versions/` directory.  Known values: - `V1`: `_versions/{version}.manifest` - Simple version-based naming - `V2`: `_versions/{inverted_version}.manifest` - Zero-padded, reversed version number   (uses `u64::MAX - version`) for O(1) lookup of latest version on object stores  V2 is preferred for new tables as it enables efficient latest-version discovery without needing to list all versions. ")
+    __properties: ClassVar[List[str]] = ["identity", "context", "id", "version", "manifest_path", "manifest_size", "e_tag", "metadata", "naming_scheme"]
 
     model_config = ConfigDict(
         populate_by_name=True,
@@ -99,7 +100,8 @@ def from_dict(cls, obj: Optional[Dict[str, Any]]) -> Optional[Self]:
             "manifest_path": obj.get("manifest_path"),
             "manifest_size": obj.get("manifest_size"),
             "e_tag": obj.get("e_tag"),
-            "metadata": obj.get("metadata")
+            "metadata": obj.get("metadata"),
+            "naming_scheme": obj.get("naming_scheme")
         })
         return _obj
 

python/lance_namespace_urllib3_client/test/test_create_table_version_request.py

@@ -50,7 +50,8 @@ def make_instance(self, include_optional) -> CreateTableVersionRequest:
                 e_tag = '',
                 metadata = {
                     'key' : ''
-                    }
+                    },
+                naming_scheme = 'V2'
             )
         else:
             return CreateTableVersionRequest(

rust/lance-namespace-reqwest-client/docs/CreateTableVersionRequest.md

@@ -12,6 +12,7 @@ Name | Type | Description | Notes
 **manifest_size** | Option<**i64**> | Size of the manifest file in bytes | [optional]
 **e_tag** | Option<**String**> | Optional ETag for the manifest file | [optional]
 **metadata** | Option<**std::collections::HashMap<String, String>**> | Optional metadata for the version | [optional]
+**naming_scheme** | Option<**String**> | The naming scheme used for manifest files in the `_versions/` directory.  Known values: - `V1`: `_versions/{version}.manifest` - Simple version-based naming - `V2`: `_versions/{inverted_version}.manifest` - Zero-padded, reversed version number   (uses `u64::MAX - version`) for O(1) lookup of latest version on object stores  V2 is preferred for new tables as it enables efficient latest-version discovery without needing to list all versions.  | [optional]
 
 [[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)