diff --git a/docs/src/client/operations/index.md b/docs/src/client/operations/index.md index f0b276d0..091b4166 100644 --- a/docs/src/client/operations/index.md +++ b/docs/src/client/operations/index.md @@ -87,7 +87,7 @@ See [REST Routes](../../rest/catalog-spec.md#rest-routes) for more details. ## Recommended Basic Operations -To have a functional basic namespace implementation, +To have a functional basic namespace implementation, the following metadata operations are recommended as a minimum: **Namespace Metadata Operations:** @@ -108,6 +108,19 @@ These operations provide the foundational metadata management capabilities neede without requiring data or index operation support. With the namespace able to provide basic information about the table, the Lance SDK can be used to fulfill the other operations. +### Restrictions for Basic Operations + +The following restrictions apply to the recommended basic operations to minimize implementation complexity: + +**DropNamespace:** Only the `Restrict` behavior mode is required. +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. +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. + ### Why Not `CreateTable` and `DropTable`? `CreateTable` and `DropTable` are common in most catalog systems, diff --git a/docs/src/client/operations/models/DescribeTableRequest.md b/docs/src/client/operations/models/DescribeTableRequest.md index 7789c645..29bd8cbf 100644 --- a/docs/src/client/operations/models/DescribeTableRequest.md +++ b/docs/src/client/operations/models/DescribeTableRequest.md @@ -10,6 +10,7 @@ |**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] | diff --git a/docs/src/client/operations/models/DescribeTableResponse.md b/docs/src/client/operations/models/DescribeTableResponse.md index e6244efe..5bfbc4bb 100644 --- a/docs/src/client/operations/models/DescribeTableResponse.md +++ b/docs/src/client/operations/models/DescribeTableResponse.md @@ -7,14 +7,14 @@ | Name | Type | Description | Notes | |------------ | ------------- | ------------- | -------------| -|**table** | **String** | Table name | [optional] | -|**namespace** | **List<String>** | The namespace identifier as a list of parts | [optional] | -|**version** | **Long** | | [optional] | -|**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 | [optional] | -|**schema** | [**JsonArrowSchema**](JsonArrowSchema.md) | | [optional] | +|**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. | | +|**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] | -|**stats** | [**TableBasicStats**](TableBasicStats.md) | Table statistics | [optional] | +|**stats** | [**TableBasicStats**](TableBasicStats.md) | Table statistics. Only populated when `load_detailed_metadata` is true. | [optional] | diff --git a/docs/src/integrations/template.md b/docs/src/integrations/template.md index 34f69425..629a48d9 100644 --- a/docs/src/integrations/template.md +++ b/docs/src/integrations/template.md @@ -56,17 +56,23 @@ For each of the 8 recommended basic operations, provide a detailed subsection. E The 8 basic operations are: **Namespace Operations:** + - CreateNamespace - ListNamespaces - DescribeNamespace -- DropNamespace +- DropNamespace (only `Restrict` behavior mode required) **Table Operations:** + - DeclareTable - ListTables -- DescribeTable +- DescribeTable (only `load_detailed_metadata=false` required) - DeregisterTable +**Note:** For basic implementations, DropNamespace only needs to support the `Restrict` behavior mode +(namespace must be empty before dropping). DescribeTable only needs to support `load_detailed_metadata=false` +(only return table `location` without opening the dataset). + --- ## Template Structure @@ -144,6 +150,8 @@ If {condition}, return error code `N` ({ErrorName}). {Same structure as above} +**Note:** Basic implementations only need to support `Restrict` behavior mode. + ### DeclareTable {Same structure as above} @@ -156,6 +164,8 @@ If {condition}, return error code `N` ({ErrorName}). {Same structure as above} +**Note:** Basic implementations only need to support `load_detailed_metadata=false` (only return table `location`). + ### DeregisterTable {Same structure as above} diff --git a/docs/src/rest.yaml b/docs/src/rest.yaml index 9f91707e..0e114f3d 100644 --- a/docs/src/rest.yaml +++ b/docs/src/rest.yaml @@ -388,6 +388,7 @@ paths: - $ref: '#/components/parameters/id' - $ref: '#/components/parameters/delimiter' - $ref: '#/components/parameters/with_table_uri' + - $ref: '#/components/parameters/load_detailed_metadata' post: tags: - Table @@ -398,7 +399,7 @@ paths: Describe the detailed information for table `id`. REST NAMESPACE ONLY - REST namespace passes `with_table_uri` as a query parameter instead of in the request body. + REST namespace passes `with_table_uri` and `load_detailed_metadata` as query parameters instead of in the request body. requestBody: required: true content: @@ -1835,6 +1836,17 @@ components: 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 schemas: ErrorResponse: @@ -2135,31 +2147,54 @@ components: Default is false. type: boolean default: false + 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` + which require reading the dataset. + type: boolean + default: false DescribeTableResponse: type: object + required: + - location properties: table: type: string - description: Table name + 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 + 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) + description: | + Table storage location (e.g., S3/GCS path). + This is the only required field and is always returned. table_uri: type: string description: | - Table URI. Unlike location, this field must be a complete and valid URI + 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: | @@ -2171,7 +2206,9 @@ components: stats: $ref: '#/components/schemas/TableBasicStats' nullable: true - description: Table statistics + description: | + Table statistics. + Only populated when `load_detailed_metadata` is true. TableBasicStats: type: object diff --git a/java/lance-namespace-apache-client/api/openapi.yaml b/java/lance-namespace-apache-client/api/openapi.yaml index 2a60d0f1..2a31d65c 100644 --- a/java/lance-namespace-apache-client/api/openapi.yaml +++ b/java/lance-namespace-apache-client/api/openapi.yaml @@ -399,17 +399,19 @@ paths: - $ref: '#/components/parameters/id' - $ref: '#/components/parameters/delimiter' - $ref: '#/components/parameters/with_table_uri' + - $ref: '#/components/parameters/load_detailed_metadata' post: description: | Describe the detailed information for table `id`. REST NAMESPACE ONLY - REST namespace passes `with_table_uri` as a query parameter instead of in the request body. + REST namespace passes `with_table_uri` and `load_detailed_metadata` 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' requestBody: content: application/json: @@ -2164,6 +2166,19 @@ components: default: false type: boolean style: form + 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`. + explode: true + in: query + name: load_detailed_metadata + required: false + schema: + default: false + type: boolean + style: form responses: ListNamespacesResponse: content: @@ -2871,6 +2886,7 @@ components: - id version: 0 with_table_uri: false + load_detailed_metadata: false properties: id: items: @@ -2889,6 +2905,14 @@ components: Whether to include the table URI in the response. 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` + which require reading the dataset. + type: boolean DescribeTableResponse: example: schema: @@ -2929,23 +2953,33 @@ components: key: storage_options properties: table: - description: Table name + description: | + Table name. + Only populated when `load_detailed_metadata` is true. type: string namespace: - description: The namespace identifier as a list of parts + description: | + The namespace identifier as a list of parts. + Only populated when `load_detailed_metadata` is true. items: type: string type: array version: + description: | + Table version number. + Only populated when `load_detailed_metadata` is true. format: int64 minimum: 0 type: integer location: - description: "Table storage location (e.g., S3/GCS path)" + description: | + Table storage location (e.g., S3/GCS path). + This is the only required field and is always returned. type: string table_uri: description: | - Table URI. Unlike location, this field must be a complete and valid URI + Table URI. Unlike location, this field must be a complete and valid URI. + Only returned when `with_table_uri` is true. type: string schema: $ref: '#/components/schemas/JsonArrowSchema' @@ -2958,6 +2992,8 @@ components: passed directly to Lance to initialize storage access. stats: $ref: '#/components/schemas/TableBasicStats' + required: + - location TableBasicStats: example: num_deleted_rows: 0 diff --git a/java/lance-namespace-apache-client/docs/DescribeTableRequest.md b/java/lance-namespace-apache-client/docs/DescribeTableRequest.md index 7789c645..29bd8cbf 100644 --- a/java/lance-namespace-apache-client/docs/DescribeTableRequest.md +++ b/java/lance-namespace-apache-client/docs/DescribeTableRequest.md @@ -10,6 +10,7 @@ |**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] | diff --git a/java/lance-namespace-apache-client/docs/DescribeTableResponse.md b/java/lance-namespace-apache-client/docs/DescribeTableResponse.md index e6244efe..5bfbc4bb 100644 --- a/java/lance-namespace-apache-client/docs/DescribeTableResponse.md +++ b/java/lance-namespace-apache-client/docs/DescribeTableResponse.md @@ -7,14 +7,14 @@ | Name | Type | Description | Notes | |------------ | ------------- | ------------- | -------------| -|**table** | **String** | Table name | [optional] | -|**namespace** | **List<String>** | The namespace identifier as a list of parts | [optional] | -|**version** | **Long** | | [optional] | -|**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 | [optional] | -|**schema** | [**JsonArrowSchema**](JsonArrowSchema.md) | | [optional] | +|**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. | | +|**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] | -|**stats** | [**TableBasicStats**](TableBasicStats.md) | Table statistics | [optional] | +|**stats** | [**TableBasicStats**](TableBasicStats.md) | Table statistics. Only populated when `load_detailed_metadata` is true. | [optional] | diff --git a/java/lance-namespace-apache-client/docs/MetadataApi.md b/java/lance-namespace-apache-client/docs/MetadataApi.md index 99dbcfdb..800e5955 100644 --- a/java/lance-namespace-apache-client/docs/MetadataApi.md +++ b/java/lance-namespace-apache-client/docs/MetadataApi.md @@ -1139,11 +1139,11 @@ public class Example { ## describeTable -> DescribeTableResponse describeTable(id, describeTableRequest, delimiter, withTableUri) +> DescribeTableResponse describeTable(id, describeTableRequest, delimiter, withTableUri, loadDetailedMetadata) Describe information of a table -Describe the detailed information for table `id`. REST NAMESPACE ONLY REST namespace passes `with_table_uri` as a query parameter instead of in the request body. +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. ### Example @@ -1180,8 +1180,9 @@ public class Example { DescribeTableRequest describeTableRequest = new DescribeTableRequest(); // DescribeTableRequest | 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`. try { - DescribeTableResponse result = apiInstance.describeTable(id, describeTableRequest, delimiter, withTableUri); + DescribeTableResponse result = apiInstance.describeTable(id, describeTableRequest, delimiter, withTableUri, loadDetailedMetadata); System.out.println(result); } catch (ApiException e) { System.err.println("Exception when calling MetadataApi#describeTable"); @@ -1203,6 +1204,7 @@ public class Example { | **describeTableRequest** | [**DescribeTableRequest**](DescribeTableRequest.md)| | | | **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] | ### Return type diff --git a/java/lance-namespace-apache-client/docs/TableApi.md b/java/lance-namespace-apache-client/docs/TableApi.md index fd773424..65844ae6 100644 --- a/java/lance-namespace-apache-client/docs/TableApi.md +++ b/java/lance-namespace-apache-client/docs/TableApi.md @@ -1324,11 +1324,11 @@ public class Example { ## describeTable -> DescribeTableResponse describeTable(id, describeTableRequest, delimiter, withTableUri) +> DescribeTableResponse describeTable(id, describeTableRequest, delimiter, withTableUri, loadDetailedMetadata) Describe information of a table -Describe the detailed information for table `id`. REST NAMESPACE ONLY REST namespace passes `with_table_uri` as a query parameter instead of in the request body. +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. ### Example @@ -1365,8 +1365,9 @@ public class Example { DescribeTableRequest describeTableRequest = new DescribeTableRequest(); // DescribeTableRequest | 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`. try { - DescribeTableResponse result = apiInstance.describeTable(id, describeTableRequest, delimiter, withTableUri); + DescribeTableResponse result = apiInstance.describeTable(id, describeTableRequest, delimiter, withTableUri, loadDetailedMetadata); System.out.println(result); } catch (ApiException e) { System.err.println("Exception when calling TableApi#describeTable"); @@ -1388,6 +1389,7 @@ public class Example { | **describeTableRequest** | [**DescribeTableRequest**](DescribeTableRequest.md)| | | | **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] | ### Return type diff --git a/java/lance-namespace-apache-client/src/main/java/org/lance/namespace/client/apache/api/MetadataApi.java b/java/lance-namespace-apache-client/src/main/java/org/lance/namespace/client/apache/api/MetadataApi.java index 059eb023..7b47a5d8 100644 --- a/java/lance-namespace-apache-client/src/main/java/org/lance/namespace/client/apache/api/MetadataApi.java +++ b/java/lance-namespace-apache-client/src/main/java/org/lance/namespace/client/apache/api/MetadataApi.java @@ -1344,8 +1344,8 @@ public DescribeNamespaceResponse describeNamespace( /** * Describe information of a table Describe the detailed information for table `id`. - * REST NAMESPACE ONLY REST namespace passes `with_table_uri` as a query parameter - * instead of in the request body. + * REST NAMESPACE ONLY REST namespace passes `with_table_uri` and + * `load_detailed_metadata` as query parameters instead of in the request body. * * @param id `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. @@ -1357,20 +1357,33 @@ public DescribeNamespaceResponse describeNamespace( * (optional) * @param withTableUri Whether to include the table URI in the response (optional, default to * false) + * @param 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`. (optional, default to false) * @return DescribeTableResponse * @throws ApiException if fails to make API call */ public DescribeTableResponse describeTable( - String id, DescribeTableRequest describeTableRequest, String delimiter, Boolean withTableUri) + String id, + DescribeTableRequest describeTableRequest, + String delimiter, + Boolean withTableUri, + Boolean loadDetailedMetadata) throws ApiException { return this.describeTable( - id, describeTableRequest, delimiter, withTableUri, Collections.emptyMap()); + id, + describeTableRequest, + delimiter, + withTableUri, + loadDetailedMetadata, + Collections.emptyMap()); } /** * Describe information of a table Describe the detailed information for table `id`. - * REST NAMESPACE ONLY REST namespace passes `with_table_uri` as a query parameter - * instead of in the request body. + * REST NAMESPACE ONLY REST namespace passes `with_table_uri` and + * `load_detailed_metadata` as query parameters instead of in the request body. * * @param id `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. @@ -1382,6 +1395,10 @@ public DescribeTableResponse describeTable( * (optional) * @param withTableUri Whether to include the table URI in the response (optional, default to * false) + * @param 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`. (optional, default to false) * @param additionalHeaders additionalHeaders for this call * @return DescribeTableResponse * @throws ApiException if fails to make API call @@ -1391,6 +1408,7 @@ public DescribeTableResponse describeTable( DescribeTableRequest describeTableRequest, String delimiter, Boolean withTableUri, + Boolean loadDetailedMetadata, Map additionalHeaders) throws ApiException { Object localVarPostBody = describeTableRequest; @@ -1422,6 +1440,8 @@ public DescribeTableResponse describeTable( localVarQueryParams.addAll(apiClient.parameterToPair("delimiter", delimiter)); localVarQueryParams.addAll(apiClient.parameterToPair("with_table_uri", withTableUri)); + localVarQueryParams.addAll( + apiClient.parameterToPair("load_detailed_metadata", loadDetailedMetadata)); localVarHeaderParams.putAll(additionalHeaders); diff --git a/java/lance-namespace-apache-client/src/main/java/org/lance/namespace/client/apache/api/TableApi.java b/java/lance-namespace-apache-client/src/main/java/org/lance/namespace/client/apache/api/TableApi.java index 88e53baa..24d0388c 100644 --- a/java/lance-namespace-apache-client/src/main/java/org/lance/namespace/client/apache/api/TableApi.java +++ b/java/lance-namespace-apache-client/src/main/java/org/lance/namespace/client/apache/api/TableApi.java @@ -1553,8 +1553,8 @@ public DeregisterTableResponse deregisterTable( /** * Describe information of a table Describe the detailed information for table `id`. - * REST NAMESPACE ONLY REST namespace passes `with_table_uri` as a query parameter - * instead of in the request body. + * REST NAMESPACE ONLY REST namespace passes `with_table_uri` and + * `load_detailed_metadata` as query parameters instead of in the request body. * * @param id `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. @@ -1566,20 +1566,33 @@ public DeregisterTableResponse deregisterTable( * (optional) * @param withTableUri Whether to include the table URI in the response (optional, default to * false) + * @param 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`. (optional, default to false) * @return DescribeTableResponse * @throws ApiException if fails to make API call */ public DescribeTableResponse describeTable( - String id, DescribeTableRequest describeTableRequest, String delimiter, Boolean withTableUri) + String id, + DescribeTableRequest describeTableRequest, + String delimiter, + Boolean withTableUri, + Boolean loadDetailedMetadata) throws ApiException { return this.describeTable( - id, describeTableRequest, delimiter, withTableUri, Collections.emptyMap()); + id, + describeTableRequest, + delimiter, + withTableUri, + loadDetailedMetadata, + Collections.emptyMap()); } /** * Describe information of a table Describe the detailed information for table `id`. - * REST NAMESPACE ONLY REST namespace passes `with_table_uri` as a query parameter - * instead of in the request body. + * REST NAMESPACE ONLY REST namespace passes `with_table_uri` and + * `load_detailed_metadata` as query parameters instead of in the request body. * * @param id `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. @@ -1591,6 +1604,10 @@ public DescribeTableResponse describeTable( * (optional) * @param withTableUri Whether to include the table URI in the response (optional, default to * false) + * @param 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`. (optional, default to false) * @param additionalHeaders additionalHeaders for this call * @return DescribeTableResponse * @throws ApiException if fails to make API call @@ -1600,6 +1617,7 @@ public DescribeTableResponse describeTable( DescribeTableRequest describeTableRequest, String delimiter, Boolean withTableUri, + Boolean loadDetailedMetadata, Map additionalHeaders) throws ApiException { Object localVarPostBody = describeTableRequest; @@ -1631,6 +1649,8 @@ public DescribeTableResponse describeTable( localVarQueryParams.addAll(apiClient.parameterToPair("delimiter", delimiter)); localVarQueryParams.addAll(apiClient.parameterToPair("with_table_uri", withTableUri)); + localVarQueryParams.addAll( + apiClient.parameterToPair("load_detailed_metadata", loadDetailedMetadata)); localVarHeaderParams.putAll(additionalHeaders); diff --git a/java/lance-namespace-apache-client/src/main/java/org/lance/namespace/model/DescribeTableRequest.java b/java/lance-namespace-apache-client/src/main/java/org/lance/namespace/model/DescribeTableRequest.java index 5eac634b..6225dc32 100644 --- a/java/lance-namespace-apache-client/src/main/java/org/lance/namespace/model/DescribeTableRequest.java +++ b/java/lance-namespace-apache-client/src/main/java/org/lance/namespace/model/DescribeTableRequest.java @@ -28,7 +28,8 @@ @JsonPropertyOrder({ DescribeTableRequest.JSON_PROPERTY_ID, DescribeTableRequest.JSON_PROPERTY_VERSION, - DescribeTableRequest.JSON_PROPERTY_WITH_TABLE_URI + DescribeTableRequest.JSON_PROPERTY_WITH_TABLE_URI, + DescribeTableRequest.JSON_PROPERTY_LOAD_DETAILED_METADATA }) @javax.annotation.Generated( value = "org.openapitools.codegen.languages.JavaClientCodegen", @@ -43,6 +44,9 @@ public class DescribeTableRequest { public static final String JSON_PROPERTY_WITH_TABLE_URI = "with_table_uri"; @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; + public DescribeTableRequest() {} public DescribeTableRequest id(@javax.annotation.Nullable List id) { @@ -126,6 +130,34 @@ public void setWithTableUri(@javax.annotation.Nullable Boolean withTableUri) { this.withTableUri = withTableUri; } + public DescribeTableRequest loadDetailedMetadata( + @javax.annotation.Nullable Boolean loadDetailedMetadata) { + + this.loadDetailedMetadata = loadDetailedMetadata; + return this; + } + + /** + * 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. + * + * @return loadDetailedMetadata + */ + @javax.annotation.Nullable + @JsonProperty(JSON_PROPERTY_LOAD_DETAILED_METADATA) + @JsonInclude(value = JsonInclude.Include.USE_DEFAULTS) + public Boolean getLoadDetailedMetadata() { + return loadDetailedMetadata; + } + + @JsonProperty(JSON_PROPERTY_LOAD_DETAILED_METADATA) + @JsonInclude(value = JsonInclude.Include.USE_DEFAULTS) + public void setLoadDetailedMetadata(@javax.annotation.Nullable Boolean loadDetailedMetadata) { + this.loadDetailedMetadata = loadDetailedMetadata; + } + @Override public boolean equals(Object o) { if (this == o) { @@ -137,12 +169,13 @@ public boolean equals(Object o) { DescribeTableRequest describeTableRequest = (DescribeTableRequest) o; return Objects.equals(this.id, describeTableRequest.id) && Objects.equals(this.version, describeTableRequest.version) - && Objects.equals(this.withTableUri, describeTableRequest.withTableUri); + && Objects.equals(this.withTableUri, describeTableRequest.withTableUri) + && Objects.equals(this.loadDetailedMetadata, describeTableRequest.loadDetailedMetadata); } @Override public int hashCode() { - return Objects.hash(id, version, withTableUri); + return Objects.hash(id, version, withTableUri, loadDetailedMetadata); } @Override @@ -152,6 +185,9 @@ public String toString() { sb.append(" id: ").append(toIndentedString(id)).append("\n"); sb.append(" version: ").append(toIndentedString(version)).append("\n"); sb.append(" withTableUri: ").append(toIndentedString(withTableUri)).append("\n"); + sb.append(" loadDetailedMetadata: ") + .append(toIndentedString(loadDetailedMetadata)) + .append("\n"); sb.append("}"); return sb.toString(); } @@ -250,6 +286,22 @@ public String toUrlQueryString(String prefix) { } } + // add `load_detailed_metadata` to the URL query string + if (getLoadDetailedMetadata() != null) { + try { + joiner.add( + String.format( + "%sload_detailed_metadata%s=%s", + prefix, + suffix, + URLEncoder.encode(String.valueOf(getLoadDetailedMetadata()), "UTF-8") + .replaceAll("\\+", "%20"))); + } catch (UnsupportedEncodingException e) { + // Should never happen, UTF-8 is always supported + throw new RuntimeException(e); + } + } + return joiner.toString(); } } diff --git a/java/lance-namespace-apache-client/src/main/java/org/lance/namespace/model/DescribeTableResponse.java b/java/lance-namespace-apache-client/src/main/java/org/lance/namespace/model/DescribeTableResponse.java index 16c17513..f950537b 100644 --- a/java/lance-namespace-apache-client/src/main/java/org/lance/namespace/model/DescribeTableResponse.java +++ b/java/lance-namespace-apache-client/src/main/java/org/lance/namespace/model/DescribeTableResponse.java @@ -51,7 +51,7 @@ public class DescribeTableResponse { @javax.annotation.Nullable private Long version; public static final String JSON_PROPERTY_LOCATION = "location"; - @javax.annotation.Nullable private String location; + @javax.annotation.Nonnull private String location; public static final String JSON_PROPERTY_TABLE_URI = "table_uri"; @javax.annotation.Nullable private String tableUri; @@ -74,7 +74,7 @@ public DescribeTableResponse table(@javax.annotation.Nullable String table) { } /** - * Table name + * Table name. Only populated when `load_detailed_metadata` is true. * * @return table */ @@ -106,7 +106,8 @@ public DescribeTableResponse addNamespaceItem(String namespaceItem) { } /** - * The namespace identifier as a list of parts + * The namespace identifier as a list of parts. Only populated when + * `load_detailed_metadata` is true. * * @return namespace */ @@ -130,7 +131,8 @@ public DescribeTableResponse version(@javax.annotation.Nullable Long version) { } /** - * Get version minimum: 0 + * Table version number. Only populated when `load_detailed_metadata` is true. minimum: + * 0 * * @return version */ @@ -147,27 +149,28 @@ public void setVersion(@javax.annotation.Nullable Long version) { this.version = version; } - public DescribeTableResponse location(@javax.annotation.Nullable String location) { + public DescribeTableResponse location(@javax.annotation.Nonnull String location) { this.location = location; return this; } /** - * Table storage location (e.g., S3/GCS path) + * Table storage location (e.g., S3/GCS path). This is the only required field and is always + * returned. * * @return location */ - @javax.annotation.Nullable + @javax.annotation.Nonnull @JsonProperty(JSON_PROPERTY_LOCATION) - @JsonInclude(value = JsonInclude.Include.USE_DEFAULTS) + @JsonInclude(value = JsonInclude.Include.ALWAYS) public String getLocation() { return location; } @JsonProperty(JSON_PROPERTY_LOCATION) - @JsonInclude(value = JsonInclude.Include.USE_DEFAULTS) - public void setLocation(@javax.annotation.Nullable String location) { + @JsonInclude(value = JsonInclude.Include.ALWAYS) + public void setLocation(@javax.annotation.Nonnull String location) { this.location = location; } @@ -178,7 +181,8 @@ public DescribeTableResponse tableUri(@javax.annotation.Nullable String tableUri } /** - * Table URI. Unlike location, this field must be a complete and valid URI + * Table URI. Unlike location, this field must be a complete and valid URI. Only returned when + * `with_table_uri` is true. * * @return tableUri */ @@ -202,7 +206,8 @@ public DescribeTableResponse schema(@javax.annotation.Nullable JsonArrowSchema s } /** - * Get schema + * Table schema in JSON Arrow format. Only populated when `load_detailed_metadata` is + * true. * * @return schema */ @@ -260,7 +265,7 @@ public DescribeTableResponse stats(@javax.annotation.Nullable TableBasicStats st } /** - * Table statistics + * Table statistics. Only populated when `load_detailed_metadata` is true. * * @return stats */ diff --git a/java/lance-namespace-springboot-server/src/main/java/org/lance/namespace/server/springboot/api/TableApi.java b/java/lance-namespace-springboot-server/src/main/java/org/lance/namespace/server/springboot/api/TableApi.java index 7a96e5c8..3e124669 100644 --- a/java/lance-namespace-springboot-server/src/main/java/org/lance/namespace/server/springboot/api/TableApi.java +++ b/java/lance-namespace-springboot-server/src/main/java/org/lance/namespace/server/springboot/api/TableApi.java @@ -2609,7 +2609,8 @@ default ResponseEntity deregisterTable( /** * POST /v1/table/{id}/describe : Describe information of a table Describe the detailed * information for table `id`. REST NAMESPACE ONLY REST namespace passes - * `with_table_uri` as a query parameter instead of in the request body. + * `with_table_uri` and `load_detailed_metadata` as query parameters instead + * of in the request body. * * @param id `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. @@ -2621,6 +2622,10 @@ default ResponseEntity deregisterTable( * (optional) * @param withTableUri Whether to include the table URI in the response (optional, default to * false) + * @param 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`. (optional, default to false) * @return Table properties result when loading a table (status code 200) or 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, @@ -2638,7 +2643,7 @@ default ResponseEntity deregisterTable( operationId = "describeTable", summary = "Describe information of a table", description = - "Describe the detailed information for table `id`. REST NAMESPACE ONLY REST namespace passes `with_table_uri` as a query parameter instead of in the request body. ", + "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. ", tags = {"Table", "Metadata"}, responses = { @ApiResponse( @@ -2739,7 +2744,15 @@ default ResponseEntity describeTable( in = ParameterIn.QUERY) @Valid @RequestParam(value = "with_table_uri", required = false, defaultValue = "false") - Optional withTableUri) { + Optional withTableUri, + @Parameter( + 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 = ParameterIn.QUERY) + @Valid + @RequestParam(value = "load_detailed_metadata", required = false, defaultValue = "false") + Optional loadDetailedMetadata) { getRequest() .ifPresent( request -> { diff --git a/java/lance-namespace-springboot-server/src/main/java/org/lance/namespace/server/springboot/model/DescribeTableRequest.java b/java/lance-namespace-springboot-server/src/main/java/org/lance/namespace/server/springboot/model/DescribeTableRequest.java index adafd94b..17147666 100644 --- a/java/lance-namespace-springboot-server/src/main/java/org/lance/namespace/server/springboot/model/DescribeTableRequest.java +++ b/java/lance-namespace-springboot-server/src/main/java/org/lance/namespace/server/springboot/model/DescribeTableRequest.java @@ -36,6 +36,8 @@ public class DescribeTableRequest { private Boolean withTableUri = false; + private Boolean loadDetailedMetadata = false; + public DescribeTableRequest id(List id) { this.id = id; return this; @@ -113,6 +115,32 @@ public void setWithTableUri(Boolean withTableUri) { this.withTableUri = withTableUri; } + public DescribeTableRequest loadDetailedMetadata(Boolean loadDetailedMetadata) { + this.loadDetailedMetadata = loadDetailedMetadata; + return this; + } + + /** + * 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. + * + * @return loadDetailedMetadata + */ + @Schema( + 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` which require reading the dataset. ", + requiredMode = Schema.RequiredMode.NOT_REQUIRED) + @JsonProperty("load_detailed_metadata") + public Boolean getLoadDetailedMetadata() { + return loadDetailedMetadata; + } + + public void setLoadDetailedMetadata(Boolean loadDetailedMetadata) { + this.loadDetailedMetadata = loadDetailedMetadata; + } + @Override public boolean equals(Object o) { if (this == o) { @@ -124,12 +152,13 @@ public boolean equals(Object o) { DescribeTableRequest describeTableRequest = (DescribeTableRequest) o; return Objects.equals(this.id, describeTableRequest.id) && Objects.equals(this.version, describeTableRequest.version) - && Objects.equals(this.withTableUri, describeTableRequest.withTableUri); + && Objects.equals(this.withTableUri, describeTableRequest.withTableUri) + && Objects.equals(this.loadDetailedMetadata, describeTableRequest.loadDetailedMetadata); } @Override public int hashCode() { - return Objects.hash(id, version, withTableUri); + return Objects.hash(id, version, withTableUri, loadDetailedMetadata); } @Override @@ -139,6 +168,9 @@ public String toString() { sb.append(" id: ").append(toIndentedString(id)).append("\n"); sb.append(" version: ").append(toIndentedString(version)).append("\n"); sb.append(" withTableUri: ").append(toIndentedString(withTableUri)).append("\n"); + sb.append(" loadDetailedMetadata: ") + .append(toIndentedString(loadDetailedMetadata)) + .append("\n"); sb.append("}"); return sb.toString(); } diff --git a/java/lance-namespace-springboot-server/src/main/java/org/lance/namespace/server/springboot/model/DescribeTableResponse.java b/java/lance-namespace-springboot-server/src/main/java/org/lance/namespace/server/springboot/model/DescribeTableResponse.java index dc619d2f..5609f519 100644 --- a/java/lance-namespace-springboot-server/src/main/java/org/lance/namespace/server/springboot/model/DescribeTableResponse.java +++ b/java/lance-namespace-springboot-server/src/main/java/org/lance/namespace/server/springboot/model/DescribeTableResponse.java @@ -48,19 +48,28 @@ public class DescribeTableResponse { private TableBasicStats stats; + public DescribeTableResponse() { + super(); + } + + /** Constructor with only required parameters */ + public DescribeTableResponse(String location) { + this.location = location; + } + public DescribeTableResponse table(String table) { this.table = table; return this; } /** - * Table name + * Table name. Only populated when `load_detailed_metadata` is true. * * @return table */ @Schema( name = "table", - description = "Table name", + description = "Table name. Only populated when `load_detailed_metadata` is true. ", requiredMode = Schema.RequiredMode.NOT_REQUIRED) @JsonProperty("table") public String getTable() { @@ -85,13 +94,15 @@ public DescribeTableResponse addNamespaceItem(String namespaceItem) { } /** - * The namespace identifier as a list of parts + * The namespace identifier as a list of parts. Only populated when `load_detailed_metadata` is + * true. * * @return namespace */ @Schema( name = "namespace", - description = "The namespace identifier as a list of parts", + description = + "The namespace identifier as a list of parts. Only populated when `load_detailed_metadata` is true. ", requiredMode = Schema.RequiredMode.NOT_REQUIRED) @JsonProperty("namespace") public List getNamespace() { @@ -108,12 +119,15 @@ public DescribeTableResponse version(Long version) { } /** - * Get version minimum: 0 + * Table version number. Only populated when `load_detailed_metadata` is true. minimum: 0 * * @return version */ @Min(0L) - @Schema(name = "version", requiredMode = Schema.RequiredMode.NOT_REQUIRED) + @Schema( + name = "version", + description = "Table version number. Only populated when `load_detailed_metadata` is true. ", + requiredMode = Schema.RequiredMode.NOT_REQUIRED) @JsonProperty("version") public Long getVersion() { return version; @@ -129,14 +143,17 @@ public DescribeTableResponse location(String location) { } /** - * Table storage location (e.g., S3/GCS path) + * Table storage location (e.g., S3/GCS path). This is the only required field and is always + * returned. * * @return location */ + @NotNull @Schema( name = "location", - description = "Table storage location (e.g., S3/GCS path)", - requiredMode = Schema.RequiredMode.NOT_REQUIRED) + description = + "Table storage location (e.g., S3/GCS path). This is the only required field and is always returned. ", + requiredMode = Schema.RequiredMode.REQUIRED) @JsonProperty("location") public String getLocation() { return location; @@ -152,13 +169,15 @@ public DescribeTableResponse tableUri(String tableUri) { } /** - * Table URI. Unlike location, this field must be a complete and valid URI + * Table URI. Unlike location, this field must be a complete and valid URI. Only returned when + * `with_table_uri` is true. * * @return tableUri */ @Schema( name = "table_uri", - description = "Table URI. Unlike location, this field must be a complete and valid URI ", + description = + "Table URI. Unlike location, this field must be a complete and valid URI. Only returned when `with_table_uri` is true. ", requiredMode = Schema.RequiredMode.NOT_REQUIRED) @JsonProperty("table_uri") public String getTableUri() { @@ -175,12 +194,16 @@ public DescribeTableResponse schema(JsonArrowSchema schema) { } /** - * Get schema + * Table schema in JSON Arrow format. Only populated when `load_detailed_metadata` is true. * * @return schema */ @Valid - @Schema(name = "schema", requiredMode = Schema.RequiredMode.NOT_REQUIRED) + @Schema( + name = "schema", + description = + "Table schema in JSON Arrow format. Only populated when `load_detailed_metadata` is true. ", + requiredMode = Schema.RequiredMode.NOT_REQUIRED) @JsonProperty("schema") public JsonArrowSchema getSchema() { return schema; @@ -229,14 +252,14 @@ public DescribeTableResponse stats(TableBasicStats stats) { } /** - * Table statistics + * Table statistics. Only populated when `load_detailed_metadata` is true. * * @return stats */ @Valid @Schema( name = "stats", - description = "Table statistics", + description = "Table statistics. Only populated when `load_detailed_metadata` is true. ", requiredMode = Schema.RequiredMode.NOT_REQUIRED) @JsonProperty("stats") public TableBasicStats getStats() { diff --git a/python/lance_namespace_urllib3_client/docs/DescribeTableRequest.md b/python/lance_namespace_urllib3_client/docs/DescribeTableRequest.md index 38227a97..2cc0946a 100644 --- a/python/lance_namespace_urllib3_client/docs/DescribeTableRequest.md +++ b/python/lance_namespace_urllib3_client/docs/DescribeTableRequest.md @@ -8,6 +8,7 @@ Name | Type | Description | Notes **id** | **List[str]** | | [optional] **version** | **int** | Version of the table to describe. If not specified, server should resolve it to the latest version. | [optional] **with_table_uri** | **bool** | Whether to include the table URI in the response. Default is false. | [optional] [default to False] +**load_detailed_metadata** | **bool** | 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] [default to False] ## Example diff --git a/python/lance_namespace_urllib3_client/docs/DescribeTableResponse.md b/python/lance_namespace_urllib3_client/docs/DescribeTableResponse.md index dd23ea0d..eb66598e 100644 --- a/python/lance_namespace_urllib3_client/docs/DescribeTableResponse.md +++ b/python/lance_namespace_urllib3_client/docs/DescribeTableResponse.md @@ -5,14 +5,14 @@ Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- -**table** | **str** | Table name | [optional] -**namespace** | **List[str]** | The namespace identifier as a list of parts | [optional] -**version** | **int** | | [optional] -**location** | **str** | Table storage location (e.g., S3/GCS path) | [optional] -**table_uri** | **str** | Table URI. Unlike location, this field must be a complete and valid URI | [optional] -**var_schema** | [**JsonArrowSchema**](JsonArrowSchema.md) | | [optional] +**table** | **str** | Table name. Only populated when `load_detailed_metadata` is true. | [optional] +**namespace** | **List[str]** | The namespace identifier as a list of parts. Only populated when `load_detailed_metadata` is true. | [optional] +**version** | **int** | Table version number. Only populated when `load_detailed_metadata` is true. | [optional] +**location** | **str** | Table storage location (e.g., S3/GCS path). This is the only required field and is always returned. | +**table_uri** | **str** | Table URI. Unlike location, this field must be a complete and valid URI. Only returned when `with_table_uri` is true. | [optional] +**var_schema** | [**JsonArrowSchema**](JsonArrowSchema.md) | Table schema in JSON Arrow format. Only populated when `load_detailed_metadata` is true. | [optional] **storage_options** | **Dict[str, str]** | 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] -**stats** | [**TableBasicStats**](TableBasicStats.md) | Table statistics | [optional] +**stats** | [**TableBasicStats**](TableBasicStats.md) | Table statistics. Only populated when `load_detailed_metadata` is true. | [optional] ## Example diff --git a/python/lance_namespace_urllib3_client/docs/MetadataApi.md b/python/lance_namespace_urllib3_client/docs/MetadataApi.md index e7f66a39..0789c421 100644 --- a/python/lance_namespace_urllib3_client/docs/MetadataApi.md +++ b/python/lance_namespace_urllib3_client/docs/MetadataApi.md @@ -1267,14 +1267,14 @@ Name | Type | Description | Notes [[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) # **describe_table** -> DescribeTableResponse describe_table(id, describe_table_request, delimiter=delimiter, with_table_uri=with_table_uri) +> DescribeTableResponse describe_table(id, describe_table_request, delimiter=delimiter, with_table_uri=with_table_uri, load_detailed_metadata=load_detailed_metadata) Describe information of a table Describe the detailed information for table `id`. REST NAMESPACE ONLY -REST namespace passes `with_table_uri` as a query parameter instead of in the request body. +REST namespace passes `with_table_uri` and `load_detailed_metadata` as query parameters instead of in the request body. ### Example @@ -1322,10 +1322,11 @@ with lance_namespace_urllib3_client.ApiClient(configuration) as api_client: describe_table_request = lance_namespace_urllib3_client.DescribeTableRequest() # DescribeTableRequest | delimiter = 'delimiter_example' # str | An optional delimiter of the `string identifier`, following the Lance Namespace spec. When not specified, the `$` delimiter must be used. (optional) with_table_uri = False # bool | Whether to include the table URI in the response (optional) (default to False) + load_detailed_metadata = False # bool | 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) try: # Describe information of a table - api_response = api_instance.describe_table(id, describe_table_request, delimiter=delimiter, with_table_uri=with_table_uri) + api_response = api_instance.describe_table(id, describe_table_request, delimiter=delimiter, with_table_uri=with_table_uri, load_detailed_metadata=load_detailed_metadata) print("The response of MetadataApi->describe_table:\n") pprint(api_response) except Exception as e: @@ -1343,6 +1344,7 @@ Name | Type | Description | Notes **describe_table_request** | [**DescribeTableRequest**](DescribeTableRequest.md)| | **delimiter** | **str**| An optional delimiter of the `string identifier`, following the Lance Namespace spec. When not specified, the `$` delimiter must be used. | [optional] **with_table_uri** | **bool**| Whether to include the table URI in the response | [optional] [default to False] + **load_detailed_metadata** | **bool**| 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] ### Return type diff --git a/python/lance_namespace_urllib3_client/docs/TableApi.md b/python/lance_namespace_urllib3_client/docs/TableApi.md index 59ebee21..782299a0 100644 --- a/python/lance_namespace_urllib3_client/docs/TableApi.md +++ b/python/lance_namespace_urllib3_client/docs/TableApi.md @@ -1480,14 +1480,14 @@ Name | Type | Description | Notes [[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md) # **describe_table** -> DescribeTableResponse describe_table(id, describe_table_request, delimiter=delimiter, with_table_uri=with_table_uri) +> DescribeTableResponse describe_table(id, describe_table_request, delimiter=delimiter, with_table_uri=with_table_uri, load_detailed_metadata=load_detailed_metadata) Describe information of a table Describe the detailed information for table `id`. REST NAMESPACE ONLY -REST namespace passes `with_table_uri` as a query parameter instead of in the request body. +REST namespace passes `with_table_uri` and `load_detailed_metadata` as query parameters instead of in the request body. ### Example @@ -1535,10 +1535,11 @@ with lance_namespace_urllib3_client.ApiClient(configuration) as api_client: describe_table_request = lance_namespace_urllib3_client.DescribeTableRequest() # DescribeTableRequest | delimiter = 'delimiter_example' # str | An optional delimiter of the `string identifier`, following the Lance Namespace spec. When not specified, the `$` delimiter must be used. (optional) with_table_uri = False # bool | Whether to include the table URI in the response (optional) (default to False) + load_detailed_metadata = False # bool | 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) try: # Describe information of a table - api_response = api_instance.describe_table(id, describe_table_request, delimiter=delimiter, with_table_uri=with_table_uri) + api_response = api_instance.describe_table(id, describe_table_request, delimiter=delimiter, with_table_uri=with_table_uri, load_detailed_metadata=load_detailed_metadata) print("The response of TableApi->describe_table:\n") pprint(api_response) except Exception as e: @@ -1556,6 +1557,7 @@ Name | Type | Description | Notes **describe_table_request** | [**DescribeTableRequest**](DescribeTableRequest.md)| | **delimiter** | **str**| An optional delimiter of the `string identifier`, following the Lance Namespace spec. When not specified, the `$` delimiter must be used. | [optional] **with_table_uri** | **bool**| Whether to include the table URI in the response | [optional] [default to False] + **load_detailed_metadata** | **bool**| 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] ### Return type diff --git a/python/lance_namespace_urllib3_client/lance_namespace_urllib3_client/api/metadata_api.py b/python/lance_namespace_urllib3_client/lance_namespace_urllib3_client/api/metadata_api.py index 33194cad..c976768c 100644 --- a/python/lance_namespace_urllib3_client/lance_namespace_urllib3_client/api/metadata_api.py +++ b/python/lance_namespace_urllib3_client/lance_namespace_urllib3_client/api/metadata_api.py @@ -4031,6 +4031,7 @@ def describe_table( describe_table_request: DescribeTableRequest, delimiter: Annotated[Optional[StrictStr], Field(description="An optional delimiter of the `string identifier`, following the Lance Namespace spec. When not specified, the `$` delimiter must be used. ")] = None, with_table_uri: Annotated[Optional[StrictBool], Field(description="Whether to include the table URI in the response")] = None, + load_detailed_metadata: Annotated[Optional[StrictBool], Field(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`. ")] = None, _request_timeout: Union[ None, Annotated[StrictFloat, Field(gt=0)], @@ -4046,7 +4047,7 @@ def describe_table( ) -> DescribeTableResponse: """Describe information of a table - Describe the detailed information for table `id`. REST NAMESPACE ONLY REST namespace passes `with_table_uri` as a query parameter instead of in the request body. + 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. :param id: `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. (required) :type id: str @@ -4056,6 +4057,8 @@ def describe_table( :type delimiter: str :param with_table_uri: Whether to include the table URI in the response :type with_table_uri: bool + :param load_detailed_metadata: 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`. + :type load_detailed_metadata: bool :param _request_timeout: timeout setting for this request. If one number provided, it will be total request timeout. It can also be a pair (tuple) of @@ -4083,6 +4086,7 @@ def describe_table( describe_table_request=describe_table_request, delimiter=delimiter, with_table_uri=with_table_uri, + load_detailed_metadata=load_detailed_metadata, _request_auth=_request_auth, _content_type=_content_type, _headers=_headers, @@ -4116,6 +4120,7 @@ def describe_table_with_http_info( describe_table_request: DescribeTableRequest, delimiter: Annotated[Optional[StrictStr], Field(description="An optional delimiter of the `string identifier`, following the Lance Namespace spec. When not specified, the `$` delimiter must be used. ")] = None, with_table_uri: Annotated[Optional[StrictBool], Field(description="Whether to include the table URI in the response")] = None, + load_detailed_metadata: Annotated[Optional[StrictBool], Field(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`. ")] = None, _request_timeout: Union[ None, Annotated[StrictFloat, Field(gt=0)], @@ -4131,7 +4136,7 @@ def describe_table_with_http_info( ) -> ApiResponse[DescribeTableResponse]: """Describe information of a table - Describe the detailed information for table `id`. REST NAMESPACE ONLY REST namespace passes `with_table_uri` as a query parameter instead of in the request body. + 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. :param id: `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. (required) :type id: str @@ -4141,6 +4146,8 @@ def describe_table_with_http_info( :type delimiter: str :param with_table_uri: Whether to include the table URI in the response :type with_table_uri: bool + :param load_detailed_metadata: 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`. + :type load_detailed_metadata: bool :param _request_timeout: timeout setting for this request. If one number provided, it will be total request timeout. It can also be a pair (tuple) of @@ -4168,6 +4175,7 @@ def describe_table_with_http_info( describe_table_request=describe_table_request, delimiter=delimiter, with_table_uri=with_table_uri, + load_detailed_metadata=load_detailed_metadata, _request_auth=_request_auth, _content_type=_content_type, _headers=_headers, @@ -4201,6 +4209,7 @@ def describe_table_without_preload_content( describe_table_request: DescribeTableRequest, delimiter: Annotated[Optional[StrictStr], Field(description="An optional delimiter of the `string identifier`, following the Lance Namespace spec. When not specified, the `$` delimiter must be used. ")] = None, with_table_uri: Annotated[Optional[StrictBool], Field(description="Whether to include the table URI in the response")] = None, + load_detailed_metadata: Annotated[Optional[StrictBool], Field(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`. ")] = None, _request_timeout: Union[ None, Annotated[StrictFloat, Field(gt=0)], @@ -4216,7 +4225,7 @@ def describe_table_without_preload_content( ) -> RESTResponseType: """Describe information of a table - Describe the detailed information for table `id`. REST NAMESPACE ONLY REST namespace passes `with_table_uri` as a query parameter instead of in the request body. + 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. :param id: `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. (required) :type id: str @@ -4226,6 +4235,8 @@ def describe_table_without_preload_content( :type delimiter: str :param with_table_uri: Whether to include the table URI in the response :type with_table_uri: bool + :param load_detailed_metadata: 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`. + :type load_detailed_metadata: bool :param _request_timeout: timeout setting for this request. If one number provided, it will be total request timeout. It can also be a pair (tuple) of @@ -4253,6 +4264,7 @@ def describe_table_without_preload_content( describe_table_request=describe_table_request, delimiter=delimiter, with_table_uri=with_table_uri, + load_detailed_metadata=load_detailed_metadata, _request_auth=_request_auth, _content_type=_content_type, _headers=_headers, @@ -4281,6 +4293,7 @@ def _describe_table_serialize( describe_table_request, delimiter, with_table_uri, + load_detailed_metadata, _request_auth, _content_type, _headers, @@ -4313,6 +4326,10 @@ def _describe_table_serialize( _query_params.append(('with_table_uri', with_table_uri)) + if load_detailed_metadata is not None: + + _query_params.append(('load_detailed_metadata', load_detailed_metadata)) + # process the header parameters # process the form parameters # process the body parameter diff --git a/python/lance_namespace_urllib3_client/lance_namespace_urllib3_client/api/table_api.py b/python/lance_namespace_urllib3_client/lance_namespace_urllib3_client/api/table_api.py index 62f4a5d5..68c2134c 100644 --- a/python/lance_namespace_urllib3_client/lance_namespace_urllib3_client/api/table_api.py +++ b/python/lance_namespace_urllib3_client/lance_namespace_urllib3_client/api/table_api.py @@ -4700,6 +4700,7 @@ def describe_table( describe_table_request: DescribeTableRequest, delimiter: Annotated[Optional[StrictStr], Field(description="An optional delimiter of the `string identifier`, following the Lance Namespace spec. When not specified, the `$` delimiter must be used. ")] = None, with_table_uri: Annotated[Optional[StrictBool], Field(description="Whether to include the table URI in the response")] = None, + load_detailed_metadata: Annotated[Optional[StrictBool], Field(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`. ")] = None, _request_timeout: Union[ None, Annotated[StrictFloat, Field(gt=0)], @@ -4715,7 +4716,7 @@ def describe_table( ) -> DescribeTableResponse: """Describe information of a table - Describe the detailed information for table `id`. REST NAMESPACE ONLY REST namespace passes `with_table_uri` as a query parameter instead of in the request body. + 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. :param id: `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. (required) :type id: str @@ -4725,6 +4726,8 @@ def describe_table( :type delimiter: str :param with_table_uri: Whether to include the table URI in the response :type with_table_uri: bool + :param load_detailed_metadata: 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`. + :type load_detailed_metadata: bool :param _request_timeout: timeout setting for this request. If one number provided, it will be total request timeout. It can also be a pair (tuple) of @@ -4752,6 +4755,7 @@ def describe_table( describe_table_request=describe_table_request, delimiter=delimiter, with_table_uri=with_table_uri, + load_detailed_metadata=load_detailed_metadata, _request_auth=_request_auth, _content_type=_content_type, _headers=_headers, @@ -4785,6 +4789,7 @@ def describe_table_with_http_info( describe_table_request: DescribeTableRequest, delimiter: Annotated[Optional[StrictStr], Field(description="An optional delimiter of the `string identifier`, following the Lance Namespace spec. When not specified, the `$` delimiter must be used. ")] = None, with_table_uri: Annotated[Optional[StrictBool], Field(description="Whether to include the table URI in the response")] = None, + load_detailed_metadata: Annotated[Optional[StrictBool], Field(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`. ")] = None, _request_timeout: Union[ None, Annotated[StrictFloat, Field(gt=0)], @@ -4800,7 +4805,7 @@ def describe_table_with_http_info( ) -> ApiResponse[DescribeTableResponse]: """Describe information of a table - Describe the detailed information for table `id`. REST NAMESPACE ONLY REST namespace passes `with_table_uri` as a query parameter instead of in the request body. + 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. :param id: `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. (required) :type id: str @@ -4810,6 +4815,8 @@ def describe_table_with_http_info( :type delimiter: str :param with_table_uri: Whether to include the table URI in the response :type with_table_uri: bool + :param load_detailed_metadata: 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`. + :type load_detailed_metadata: bool :param _request_timeout: timeout setting for this request. If one number provided, it will be total request timeout. It can also be a pair (tuple) of @@ -4837,6 +4844,7 @@ def describe_table_with_http_info( describe_table_request=describe_table_request, delimiter=delimiter, with_table_uri=with_table_uri, + load_detailed_metadata=load_detailed_metadata, _request_auth=_request_auth, _content_type=_content_type, _headers=_headers, @@ -4870,6 +4878,7 @@ def describe_table_without_preload_content( describe_table_request: DescribeTableRequest, delimiter: Annotated[Optional[StrictStr], Field(description="An optional delimiter of the `string identifier`, following the Lance Namespace spec. When not specified, the `$` delimiter must be used. ")] = None, with_table_uri: Annotated[Optional[StrictBool], Field(description="Whether to include the table URI in the response")] = None, + load_detailed_metadata: Annotated[Optional[StrictBool], Field(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`. ")] = None, _request_timeout: Union[ None, Annotated[StrictFloat, Field(gt=0)], @@ -4885,7 +4894,7 @@ def describe_table_without_preload_content( ) -> RESTResponseType: """Describe information of a table - Describe the detailed information for table `id`. REST NAMESPACE ONLY REST namespace passes `with_table_uri` as a query parameter instead of in the request body. + 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. :param id: `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. (required) :type id: str @@ -4895,6 +4904,8 @@ def describe_table_without_preload_content( :type delimiter: str :param with_table_uri: Whether to include the table URI in the response :type with_table_uri: bool + :param load_detailed_metadata: 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`. + :type load_detailed_metadata: bool :param _request_timeout: timeout setting for this request. If one number provided, it will be total request timeout. It can also be a pair (tuple) of @@ -4922,6 +4933,7 @@ def describe_table_without_preload_content( describe_table_request=describe_table_request, delimiter=delimiter, with_table_uri=with_table_uri, + load_detailed_metadata=load_detailed_metadata, _request_auth=_request_auth, _content_type=_content_type, _headers=_headers, @@ -4950,6 +4962,7 @@ def _describe_table_serialize( describe_table_request, delimiter, with_table_uri, + load_detailed_metadata, _request_auth, _content_type, _headers, @@ -4982,6 +4995,10 @@ def _describe_table_serialize( _query_params.append(('with_table_uri', with_table_uri)) + if load_detailed_metadata is not None: + + _query_params.append(('load_detailed_metadata', load_detailed_metadata)) + # process the header parameters # process the form parameters # process the body parameter diff --git a/python/lance_namespace_urllib3_client/lance_namespace_urllib3_client/models/describe_table_request.py b/python/lance_namespace_urllib3_client/lance_namespace_urllib3_client/models/describe_table_request.py index ebe4f18c..c01e078e 100644 --- a/python/lance_namespace_urllib3_client/lance_namespace_urllib3_client/models/describe_table_request.py +++ b/python/lance_namespace_urllib3_client/lance_namespace_urllib3_client/models/describe_table_request.py @@ -30,7 +30,8 @@ class DescribeTableRequest(BaseModel): id: Optional[List[StrictStr]] = None version: Optional[Annotated[int, Field(strict=True, ge=0)]] = Field(default=None, description="Version of the table to describe. If not specified, server should resolve it to the latest version. ") with_table_uri: Optional[StrictBool] = Field(default=False, description="Whether to include the table URI in the response. Default is false. ") - __properties: ClassVar[List[str]] = ["id", "version", "with_table_uri"] + load_detailed_metadata: Optional[StrictBool] = Field(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` which require reading the dataset. ") + __properties: ClassVar[List[str]] = ["id", "version", "with_table_uri", "load_detailed_metadata"] model_config = ConfigDict( populate_by_name=True, @@ -85,7 +86,8 @@ def from_dict(cls, obj: Optional[Dict[str, Any]]) -> Optional[Self]: _obj = cls.model_validate({ "id": obj.get("id"), "version": obj.get("version"), - "with_table_uri": obj.get("with_table_uri") if obj.get("with_table_uri") is not None else False + "with_table_uri": obj.get("with_table_uri") if obj.get("with_table_uri") is not None else False, + "load_detailed_metadata": obj.get("load_detailed_metadata") if obj.get("load_detailed_metadata") is not None else False }) return _obj diff --git a/python/lance_namespace_urllib3_client/lance_namespace_urllib3_client/models/describe_table_response.py b/python/lance_namespace_urllib3_client/lance_namespace_urllib3_client/models/describe_table_response.py index 9649bf24..7c3d7988 100644 --- a/python/lance_namespace_urllib3_client/lance_namespace_urllib3_client/models/describe_table_response.py +++ b/python/lance_namespace_urllib3_client/lance_namespace_urllib3_client/models/describe_table_response.py @@ -29,14 +29,14 @@ class DescribeTableResponse(BaseModel): """ DescribeTableResponse """ # noqa: E501 - table: Optional[StrictStr] = Field(default=None, description="Table name") - namespace: Optional[List[StrictStr]] = Field(default=None, description="The namespace identifier as a list of parts") - version: Optional[Annotated[int, Field(strict=True, ge=0)]] = None - location: Optional[StrictStr] = Field(default=None, description="Table storage location (e.g., S3/GCS path)") - table_uri: Optional[StrictStr] = Field(default=None, description="Table URI. Unlike location, this field must be a complete and valid URI ") - var_schema: Optional[JsonArrowSchema] = Field(default=None, alias="schema") + table: Optional[StrictStr] = Field(default=None, description="Table name. Only populated when `load_detailed_metadata` is true. ") + namespace: Optional[List[StrictStr]] = Field(default=None, description="The namespace identifier as a list of parts. Only populated when `load_detailed_metadata` is true. ") + version: Optional[Annotated[int, Field(strict=True, ge=0)]] = Field(default=None, description="Table version number. Only populated when `load_detailed_metadata` is true. ") + location: StrictStr = Field(description="Table storage location (e.g., S3/GCS path). This is the only required field and is always returned. ") + table_uri: Optional[StrictStr] = Field(default=None, description="Table URI. Unlike location, this field must be a complete and valid URI. Only returned when `with_table_uri` is true. ") + var_schema: Optional[JsonArrowSchema] = Field(default=None, description="Table schema in JSON Arrow format. Only populated when `load_detailed_metadata` is true. ", alias="schema") storage_options: Optional[Dict[str, StrictStr]] = Field(default=None, 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. ") - stats: Optional[TableBasicStats] = Field(default=None, description="Table statistics") + stats: Optional[TableBasicStats] = Field(default=None, description="Table statistics. Only populated when `load_detailed_metadata` is true. ") __properties: ClassVar[List[str]] = ["table", "namespace", "version", "location", "table_uri", "schema", "storage_options", "stats"] model_config = ConfigDict( diff --git a/python/lance_namespace_urllib3_client/test/test_describe_table_request.py b/python/lance_namespace_urllib3_client/test/test_describe_table_request.py index acfedd63..7484e912 100644 --- a/python/lance_namespace_urllib3_client/test/test_describe_table_request.py +++ b/python/lance_namespace_urllib3_client/test/test_describe_table_request.py @@ -39,7 +39,8 @@ def make_instance(self, include_optional) -> DescribeTableRequest: '' ], version = 0, - with_table_uri = True + with_table_uri = True, + load_detailed_metadata = True ) else: return DescribeTableRequest( diff --git a/python/lance_namespace_urllib3_client/test/test_describe_table_response.py b/python/lance_namespace_urllib3_client/test/test_describe_table_response.py index c75e3faf..59a797fa 100644 --- a/python/lance_namespace_urllib3_client/test/test_describe_table_response.py +++ b/python/lance_namespace_urllib3_client/test/test_describe_table_response.py @@ -66,6 +66,7 @@ def make_instance(self, include_optional) -> DescribeTableResponse: ) else: return DescribeTableResponse( + location = '', ) """ diff --git a/rust/lance-namespace-reqwest-client/docs/DescribeTableRequest.md b/rust/lance-namespace-reqwest-client/docs/DescribeTableRequest.md index 5b1f6e0d..fe56f587 100644 --- a/rust/lance-namespace-reqwest-client/docs/DescribeTableRequest.md +++ b/rust/lance-namespace-reqwest-client/docs/DescribeTableRequest.md @@ -7,6 +7,7 @@ Name | Type | Description | Notes **id** | Option<**Vec**> | | [optional] **version** | Option<**i64**> | Version of the table to describe. If not specified, server should resolve it to the latest version. | [optional] **with_table_uri** | Option<**bool**> | Whether to include the table URI in the response. Default is false. | [optional][default to false] +**load_detailed_metadata** | Option<**bool**> | 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][default to false] [[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) diff --git a/rust/lance-namespace-reqwest-client/docs/DescribeTableResponse.md b/rust/lance-namespace-reqwest-client/docs/DescribeTableResponse.md index 10f985f4..4923e603 100644 --- a/rust/lance-namespace-reqwest-client/docs/DescribeTableResponse.md +++ b/rust/lance-namespace-reqwest-client/docs/DescribeTableResponse.md @@ -4,14 +4,14 @@ Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- -**table** | Option<**String**> | Table name | [optional] -**namespace** | Option<**Vec**> | The namespace identifier as a list of parts | [optional] -**version** | Option<**i64**> | | [optional] -**location** | Option<**String**> | Table storage location (e.g., S3/GCS path) | [optional] -**table_uri** | Option<**String**> | Table URI. Unlike location, this field must be a complete and valid URI | [optional] -**schema** | Option<[**models::JsonArrowSchema**](JsonArrowSchema.md)> | | [optional] +**table** | Option<**String**> | Table name. Only populated when `load_detailed_metadata` is true. | [optional] +**namespace** | Option<**Vec**> | The namespace identifier as a list of parts. Only populated when `load_detailed_metadata` is true. | [optional] +**version** | Option<**i64**> | 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. | +**table_uri** | Option<**String**> | Table URI. Unlike location, this field must be a complete and valid URI. Only returned when `with_table_uri` is true. | [optional] +**schema** | Option<[**models::JsonArrowSchema**](JsonArrowSchema.md)> | Table schema in JSON Arrow format. Only populated when `load_detailed_metadata` is true. | [optional] **storage_options** | Option<**std::collections::HashMap**> | 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] -**stats** | Option<[**models::TableBasicStats**](TableBasicStats.md)> | Table statistics | [optional] +**stats** | Option<[**models::TableBasicStats**](TableBasicStats.md)> | Table statistics. Only populated when `load_detailed_metadata` is true. | [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) diff --git a/rust/lance-namespace-reqwest-client/docs/MetadataApi.md b/rust/lance-namespace-reqwest-client/docs/MetadataApi.md index 8cb871df..2d1d6a07 100644 --- a/rust/lance-namespace-reqwest-client/docs/MetadataApi.md +++ b/rust/lance-namespace-reqwest-client/docs/MetadataApi.md @@ -425,10 +425,10 @@ Name | Type | Description | Required | Notes ## describe_table -> models::DescribeTableResponse describe_table(id, describe_table_request, delimiter, with_table_uri) +> models::DescribeTableResponse describe_table(id, describe_table_request, delimiter, with_table_uri, load_detailed_metadata) Describe information of a table -Describe the detailed information for table `id`. REST NAMESPACE ONLY REST namespace passes `with_table_uri` as a query parameter instead of in the request body. +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. ### Parameters @@ -439,6 +439,7 @@ Name | Type | Description | Required | Notes **describe_table_request** | [**DescribeTableRequest**](DescribeTableRequest.md) | | [required] | **delimiter** | Option<**String**> | An optional delimiter of the `string identifier`, following the Lance Namespace spec. When not specified, the `$` delimiter must be used. | | **with_table_uri** | Option<**bool**> | Whether to include the table URI in the response | |[default to false] +**load_detailed_metadata** | Option<**bool**> | 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`. | |[default to false] ### Return type diff --git a/rust/lance-namespace-reqwest-client/docs/TableApi.md b/rust/lance-namespace-reqwest-client/docs/TableApi.md index 100f439e..aa9ea13d 100644 --- a/rust/lance-namespace-reqwest-client/docs/TableApi.md +++ b/rust/lance-namespace-reqwest-client/docs/TableApi.md @@ -494,10 +494,10 @@ Name | Type | Description | Required | Notes ## describe_table -> models::DescribeTableResponse describe_table(id, describe_table_request, delimiter, with_table_uri) +> models::DescribeTableResponse describe_table(id, describe_table_request, delimiter, with_table_uri, load_detailed_metadata) Describe information of a table -Describe the detailed information for table `id`. REST NAMESPACE ONLY REST namespace passes `with_table_uri` as a query parameter instead of in the request body. +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. ### Parameters @@ -508,6 +508,7 @@ Name | Type | Description | Required | Notes **describe_table_request** | [**DescribeTableRequest**](DescribeTableRequest.md) | | [required] | **delimiter** | Option<**String**> | An optional delimiter of the `string identifier`, following the Lance Namespace spec. When not specified, the `$` delimiter must be used. | | **with_table_uri** | Option<**bool**> | Whether to include the table URI in the response | |[default to false] +**load_detailed_metadata** | Option<**bool**> | 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`. | |[default to false] ### Return type diff --git a/rust/lance-namespace-reqwest-client/src/apis/metadata_api.rs b/rust/lance-namespace-reqwest-client/src/apis/metadata_api.rs index 3ca00acd..e90da4af 100644 --- a/rust/lance-namespace-reqwest-client/src/apis/metadata_api.rs +++ b/rust/lance-namespace-reqwest-client/src/apis/metadata_api.rs @@ -1128,13 +1128,14 @@ pub async fn describe_namespace(configuration: &configuration::Configuration, id } } -/// Describe the detailed information for table `id`. REST NAMESPACE ONLY REST namespace passes `with_table_uri` as a query parameter instead of in the request body. -pub async fn describe_table(configuration: &configuration::Configuration, id: &str, describe_table_request: models::DescribeTableRequest, delimiter: Option<&str>, with_table_uri: Option) -> Result> { +/// 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. +pub async fn describe_table(configuration: &configuration::Configuration, id: &str, describe_table_request: models::DescribeTableRequest, delimiter: Option<&str>, with_table_uri: Option, load_detailed_metadata: Option) -> Result> { // add a prefix to parameters to efficiently prevent name collisions let p_id = id; let p_describe_table_request = describe_table_request; let p_delimiter = delimiter; let p_with_table_uri = with_table_uri; + let p_load_detailed_metadata = load_detailed_metadata; let uri_str = format!("{}/v1/table/{id}/describe", configuration.base_path, id=crate::apis::urlencode(p_id)); let mut req_builder = configuration.client.request(reqwest::Method::POST, &uri_str); @@ -1145,6 +1146,9 @@ pub async fn describe_table(configuration: &configuration::Configuration, id: &s if let Some(ref param_value) = p_with_table_uri { req_builder = req_builder.query(&[("with_table_uri", ¶m_value.to_string())]); } + if let Some(ref param_value) = p_load_detailed_metadata { + req_builder = req_builder.query(&[("load_detailed_metadata", ¶m_value.to_string())]); + } if let Some(ref user_agent) = configuration.user_agent { req_builder = req_builder.header(reqwest::header::USER_AGENT, user_agent.clone()); } diff --git a/rust/lance-namespace-reqwest-client/src/apis/table_api.rs b/rust/lance-namespace-reqwest-client/src/apis/table_api.rs index 0376a559..35feb357 100644 --- a/rust/lance-namespace-reqwest-client/src/apis/table_api.rs +++ b/rust/lance-namespace-reqwest-client/src/apis/table_api.rs @@ -1292,13 +1292,14 @@ pub async fn deregister_table(configuration: &configuration::Configuration, id: } } -/// Describe the detailed information for table `id`. REST NAMESPACE ONLY REST namespace passes `with_table_uri` as a query parameter instead of in the request body. -pub async fn describe_table(configuration: &configuration::Configuration, id: &str, describe_table_request: models::DescribeTableRequest, delimiter: Option<&str>, with_table_uri: Option) -> Result> { +/// 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. +pub async fn describe_table(configuration: &configuration::Configuration, id: &str, describe_table_request: models::DescribeTableRequest, delimiter: Option<&str>, with_table_uri: Option, load_detailed_metadata: Option) -> Result> { // add a prefix to parameters to efficiently prevent name collisions let p_id = id; let p_describe_table_request = describe_table_request; let p_delimiter = delimiter; let p_with_table_uri = with_table_uri; + let p_load_detailed_metadata = load_detailed_metadata; let uri_str = format!("{}/v1/table/{id}/describe", configuration.base_path, id=crate::apis::urlencode(p_id)); let mut req_builder = configuration.client.request(reqwest::Method::POST, &uri_str); @@ -1309,6 +1310,9 @@ pub async fn describe_table(configuration: &configuration::Configuration, id: &s if let Some(ref param_value) = p_with_table_uri { req_builder = req_builder.query(&[("with_table_uri", ¶m_value.to_string())]); } + if let Some(ref param_value) = p_load_detailed_metadata { + req_builder = req_builder.query(&[("load_detailed_metadata", ¶m_value.to_string())]); + } if let Some(ref user_agent) = configuration.user_agent { req_builder = req_builder.header(reqwest::header::USER_AGENT, user_agent.clone()); } diff --git a/rust/lance-namespace-reqwest-client/src/models/describe_table_request.rs b/rust/lance-namespace-reqwest-client/src/models/describe_table_request.rs index 4abccd7f..fb9224ae 100644 --- a/rust/lance-namespace-reqwest-client/src/models/describe_table_request.rs +++ b/rust/lance-namespace-reqwest-client/src/models/describe_table_request.rs @@ -21,6 +21,9 @@ pub struct DescribeTableRequest { /// Whether to include the table URI in the response. Default is false. #[serde(rename = "with_table_uri", skip_serializing_if = "Option::is_none")] pub with_table_uri: Option, + /// 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. + #[serde(rename = "load_detailed_metadata", skip_serializing_if = "Option::is_none")] + pub load_detailed_metadata: Option, } impl DescribeTableRequest { @@ -29,6 +32,7 @@ impl DescribeTableRequest { id: None, version: None, with_table_uri: None, + load_detailed_metadata: None, } } } diff --git a/rust/lance-namespace-reqwest-client/src/models/describe_table_response.rs b/rust/lance-namespace-reqwest-client/src/models/describe_table_response.rs index cd9b897f..597924d6 100644 --- a/rust/lance-namespace-reqwest-client/src/models/describe_table_response.rs +++ b/rust/lance-namespace-reqwest-client/src/models/describe_table_response.rs @@ -13,37 +13,39 @@ use serde::{Deserialize, Serialize}; #[derive(Clone, Default, Debug, PartialEq, Serialize, Deserialize)] pub struct DescribeTableResponse { - /// Table name + /// Table name. Only populated when `load_detailed_metadata` is true. #[serde(rename = "table", skip_serializing_if = "Option::is_none")] pub table: Option, - /// The namespace identifier as a list of parts + /// The namespace identifier as a list of parts. Only populated when `load_detailed_metadata` is true. #[serde(rename = "namespace", skip_serializing_if = "Option::is_none")] pub namespace: Option>, + /// Table version number. Only populated when `load_detailed_metadata` is true. #[serde(rename = "version", skip_serializing_if = "Option::is_none")] pub version: Option, - /// Table storage location (e.g., S3/GCS path) - #[serde(rename = "location", skip_serializing_if = "Option::is_none")] - pub location: Option, - /// Table URI. Unlike location, this field must be a complete and valid URI + /// Table storage location (e.g., S3/GCS path). This is the only required field and is always returned. + #[serde(rename = "location")] + pub location: String, + /// Table URI. Unlike location, this field must be a complete and valid URI. Only returned when `with_table_uri` is true. #[serde(rename = "table_uri", skip_serializing_if = "Option::is_none")] pub table_uri: Option, + /// Table schema in JSON Arrow format. Only populated when `load_detailed_metadata` is true. #[serde(rename = "schema", skip_serializing_if = "Option::is_none")] pub schema: Option>, /// 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. #[serde(rename = "storage_options", skip_serializing_if = "Option::is_none")] pub storage_options: Option>, - /// Table statistics + /// Table statistics. Only populated when `load_detailed_metadata` is true. #[serde(rename = "stats", skip_serializing_if = "Option::is_none")] pub stats: Option>, } impl DescribeTableResponse { - pub fn new() -> DescribeTableResponse { + pub fn new(location: String) -> DescribeTableResponse { DescribeTableResponse { table: None, namespace: None, version: None, - location: None, + location, table_uri: None, schema: None, storage_options: None,