@google-cloud/vectorsearch 0.2.0 → 0.4.0

package/build/protos/google/cloud/vectorsearch/v1beta/common.proto

@@ -1,4 +1,4 @@
-// Copyright 2025 Google LLC
+// Copyright 2026 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -16,10 +16,13 @@ syntax = "proto3";
 
 package google.cloud.vectorsearch.v1beta;
 
+option csharp_namespace = "Google.Cloud.VectorSearch.V1Beta";
 option go_package = "cloud.google.com/go/vectorsearch/apiv1beta/vectorsearchpb;vectorsearchpb";
 option java_multiple_files = true;
 option java_outer_classname = "CommonProto";
 option java_package = "com.google.cloud.vectorsearch.v1beta";
+option php_namespace = "Google\\Cloud\\VectorSearch\\V1beta";
+option ruby_package = "Google::Cloud::VectorSearch::V1beta";
 
 // Distance metric for vector search.
 enum DistanceMetric {

package/build/protos/google/cloud/vectorsearch/v1beta/data_object.proto

@@ -21,10 +21,13 @@ import "google/api/resource.proto";
 import "google/protobuf/struct.proto";
 import "google/protobuf/timestamp.proto";
 
+option csharp_namespace = "Google.Cloud.VectorSearch.V1Beta";
 option go_package = "cloud.google.com/go/vectorsearch/apiv1beta/vectorsearchpb;vectorsearchpb";
 option java_multiple_files = true;
 option java_outer_classname = "DataObjectProto";
 option java_package = "com.google.cloud.vectorsearch.v1beta";
+option php_namespace = "Google\\Cloud\\VectorSearch\\V1beta";
+option ruby_package = "Google::Cloud::VectorSearch::V1beta";
 
 // A dataObject resource in Vector Search.
 message DataObject {
@@ -44,8 +47,7 @@ message DataObject {
   string name = 1 [(google.api.field_behavior) = IDENTIFIER];
 
   // Output only. The id of the dataObject.
-  string data_object_id = 2
-      [deprecated = true, (google.api.field_behavior) = OUTPUT_ONLY];
+  string data_object_id = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
 
   // Output only. Timestamp the dataObject was created at.
   google.protobuf.Timestamp create_time = 4
@@ -60,6 +62,9 @@ message DataObject {
 
   // Optional. The vectors of the dataObject.
   map<string, Vector> vectors = 7 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. The etag of the dataObject.
+  string etag = 8 [(google.api.field_behavior) = OPTIONAL];
 }
 
 // A vector which can be either dense or sparse.
@@ -73,7 +78,7 @@ message Vector {
     SparseVector sparse = 3;
   }
 
-  // The values of the vector.
+  // Deprecated: Use `dense` or `sparse` instead.
   repeated float values = 1 [deprecated = true];
 }
 

package/build/protos/google/cloud/vectorsearch/v1beta/data_object_search_service.proto

@@ -25,10 +25,13 @@ import "google/cloud/vectorsearch/v1beta/data_object.proto";
 import "google/cloud/vectorsearch/v1beta/embedding_config.proto";
 import "google/protobuf/struct.proto";
 
+option csharp_namespace = "Google.Cloud.VectorSearch.V1Beta";
 option go_package = "cloud.google.com/go/vectorsearch/apiv1beta/vectorsearchpb;vectorsearchpb";
 option java_multiple_files = true;
 option java_outer_classname = "DataObjectSearchServiceProto";
 option java_package = "com.google.cloud.vectorsearch.v1beta";
+option php_namespace = "Google\\Cloud\\VectorSearch\\V1beta";
+option ruby_package = "Google::Cloud::VectorSearch::V1beta";
 
 // Service for searching data objects.
 service DataObjectSearchService {
@@ -98,21 +101,60 @@ message OutputFields {
 message SearchHint {
   // Message to specify the index to use for the search.
   message IndexHint {
+    // Parameters for dense ScaNN.
+    message DenseScannParams {
+      // Optional. Dense ANN param overrides to control recall and latency.
+      // The percentage of leaves to search, in the range [0, 100].
+      int32 search_leaves_pct = 1 [(google.api.field_behavior) = OPTIONAL];
+
+      // Optional. The number of initial candidates. Must be a positive integer
+      // (> 0).
+      int32 initial_candidate_count = 2
+          [(google.api.field_behavior) = OPTIONAL];
+    }
+
+    // The parameters for the index.
+    oneof params {
+      // Optional. Dense ScaNN parameters.
+      DenseScannParams dense_scann_params = 2
+          [(google.api.field_behavior) = OPTIONAL];
+    }
+
     // Required. The resource name of the index to use for the search.
     // The index must be in the same project, location, and collection.
     // Format:
     // `projects/{project}/locations/{location}/collections/{collection}/indexes/{index}`
-    string name = 1 [(google.api.field_behavior) = REQUIRED];
+    string name = 1 [
+      (google.api.field_behavior) = REQUIRED,
+      (google.api.resource_reference) = {
+        type: "vectorsearch.googleapis.com/Index"
+      }
+    ];
   }
 
+  // KnnHint will be used if search should be explicitly done on system's
+  // default K-Nearest Neighbor (KNN) index engine.
+  message KnnHint {}
+
   // The type of index to use.
   oneof index_type {
-    // Optional. Specifies that the search should use a particular index.
-    IndexHint use_index = 1 [(google.api.field_behavior) = OPTIONAL];
+    // Optional. Deprecated: Use `index_hint` instead.
+    // Specifies that the search should use a particular index.
+    IndexHint use_index = 1
+        [deprecated = true, (google.api.field_behavior) = OPTIONAL];
+
+    // Optional. Deprecated: Use `knn_hint` instead.
+    // If set to true, the search will use the system's default
+    // K-Nearest Neighbor (KNN) index engine.
+    bool use_knn = 2
+        [deprecated = true, (google.api.field_behavior) = OPTIONAL];
 
-    // Optional. If set to true, the search will use the system's default
+    // Optional. If set, the search will use the system's default
     // K-Nearest Neighbor (KNN) index engine.
-    bool use_knn = 2 [(google.api.field_behavior) = OPTIONAL];
+    KnnHint knn_hint = 3 [(google.api.field_behavior) = OPTIONAL];
+
+    // Optional. Specifies that the search should use a particular index.
+    IndexHint index_hint = 4 [(google.api.field_behavior) = OPTIONAL];
   }
 }
 
@@ -161,8 +203,7 @@ message VectorSearch {
 
   // Optional. The distance metric to use for the KNN search. If not specified,
   // DOT_PRODUCT will be used as the default.
-  google.cloud.vectorsearch.v1beta.DistanceMetric distance_metric = 11
-      [(google.api.field_behavior) = OPTIONAL];
+  DistanceMetric distance_metric = 11 [(google.api.field_behavior) = OPTIONAL];
 }
 
 // Defines a semantic search operation.
@@ -174,8 +215,8 @@ message SemanticSearch {
   // Required. The vector field to search.
   string search_field = 2 [(google.api.field_behavior) = REQUIRED];
 
-  // Optional. The task type of the query embedding.
-  EmbeddingTaskType task_type = 5 [(google.api.field_behavior) = OPTIONAL];
+  // Required. The task type of the query embedding.
+  EmbeddingTaskType task_type = 5 [(google.api.field_behavior) = REQUIRED];
 
   // Optional. The fields to return in the search results.
   OutputFields output_fields = 3 [(google.api.field_behavior) = OPTIONAL];
@@ -235,7 +276,9 @@ message SearchDataObjectsRequest {
     }
   ];
 
-  // Optional. The standard list page size.
+  // Optional. The standard list page size. Only supported for KNN. If not set,
+  // up to search_type.top_k results will be returned. The maximum value is
+  // 1000; values above 1000 will be coerced to 1000.
   int32 page_size = 5 [(google.api.field_behavior) = OPTIONAL];
 
   // Optional. The standard list page token.
@@ -252,7 +295,8 @@ message SearchResult {
   // Output only. The matching data object.
   DataObject data_object = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // Output only. The similarity distance.
+  // Output only. Similarity distance or ranker score returned by
+  // BatchSearchDataObjects.
   optional double distance = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
@@ -263,7 +307,12 @@ message SearchResponseMetadata {
     // Output only. The resource name of the index used for the search.
     // Format:
     // `projects/{project}/locations/{location}/collections/{collection}/indexes/{index}`
-    string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
+    string name = 1 [
+      (google.api.field_behavior) = OUTPUT_ONLY,
+      (google.api.resource_reference) = {
+        type: "vectorsearch.googleapis.com/Index"
+      }
+    ];
   }
 
   // The type of index used.
@@ -315,8 +364,9 @@ message AggregateDataObjectsRequest {
 // Response message for
 // [DataObjectSearchService.AggregateDataObjects][google.cloud.vectorsearch.v1beta.DataObjectSearchService.AggregateDataObjects].
 message AggregateDataObjectsResponse {
-  // The aggregated results of the query.
-  repeated google.protobuf.Struct aggregate_results = 1;
+  // Output only. The aggregated results of the query.
+  repeated google.protobuf.Struct aggregate_results = 1
+      [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
 // Request message for
@@ -338,7 +388,8 @@ message QueryDataObjectsRequest {
   // Optional. Mask specifying which fields to return.
   OutputFields output_fields = 7 [(google.api.field_behavior) = OPTIONAL];
 
-  // Optional. The standard list page size.
+  // Optional. The standard list page size. Default is 100.
+  // The maximum value is 1000; values above 1000 will be coerced to 1000.
   int32 page_size = 5 [(google.api.field_behavior) = OPTIONAL];
 
   // Optional. The standard list page token.
@@ -353,13 +404,14 @@ message QueryDataObjectsRequest {
 // Response message for
 // [DataObjectSearchService.QueryDataObjects][google.cloud.vectorsearch.v1beta.DataObjectSearchService.QueryDataObjects].
 message QueryDataObjectsResponse {
-  // The list of dataObjects that match the query.
-  repeated DataObject data_objects = 4;
+  // Output only. The list of dataObjects that match the query.
+  repeated DataObject data_objects = 4
+      [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // A token to retrieve next page of results.
+  // Output only. A token to retrieve next page of results.
   // Pass to [DataObjectSearchService.QueryDataObjectsRequest.page_token][] to
   // obtain that page.
-  string next_page_token = 3;
+  string next_page_token = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
 // A request to perform a batch of search operations.
@@ -399,9 +451,6 @@ message Ranker {
   oneof ranker {
     // Reciprocal Rank Fusion ranking.
     ReciprocalRankFusion rrf = 1;
-
-    // Vertex AI ranking.
-    VertexRanker vertex = 2;
   }
 }
 
@@ -411,24 +460,6 @@ message ReciprocalRankFusion {
   repeated double weights = 1 [(google.api.field_behavior) = REQUIRED];
 }
 
-// Defines a ranker using the Vertex AI ranking service.
-// See https://cloud.google.com/generative-ai-app-builder/docs/ranking for
-// details.
-message VertexRanker {
-  // Required. The query against which the records are ranked and scored.
-  string query = 1 [(google.api.field_behavior) = REQUIRED];
-
-  // Optional. The template used to generate the record's title.
-  string title_template = 2 [(google.api.field_behavior) = OPTIONAL];
-
-  // Optional. The template used to generate the record's content.
-  string content_template = 3 [(google.api.field_behavior) = OPTIONAL];
-
-  // Required. The model used for ranking documents. If no model is specified,
-  // then semantic-ranker-default@latest is used.
-  string model = 4 [(google.api.field_behavior) = REQUIRED];
-}
-
 // A response from a batch search operation.
 message BatchSearchDataObjectsResponse {
   // Output only. A list of search responses, one for each request in the batch.

package/build/protos/google/cloud/vectorsearch/v1beta/data_object_service.proto

@@ -24,10 +24,13 @@ import "google/cloud/vectorsearch/v1beta/data_object.proto";
 import "google/protobuf/empty.proto";
 import "google/protobuf/field_mask.proto";
 
+option csharp_namespace = "Google.Cloud.VectorSearch.V1Beta";
 option go_package = "cloud.google.com/go/vectorsearch/apiv1beta/vectorsearchpb;vectorsearchpb";
 option java_multiple_files = true;
 option java_outer_classname = "DataObjectServiceProto";
 option java_package = "com.google.cloud.vectorsearch.v1beta";
+option php_namespace = "Google\\Cloud\\VectorSearch\\V1beta";
+option ruby_package = "Google::Cloud::VectorSearch::V1beta";
 
 // Service for creating and managing data objects.
 service DataObjectService {
@@ -146,8 +149,9 @@ message BatchCreateDataObjectsRequest {
 // Response message for
 // [DataObjectService.BatchCreateDataObjects][google.cloud.vectorsearch.v1beta.DataObjectService.BatchCreateDataObjects].
 message BatchCreateDataObjectsResponse {
-  // DataObjects created.
-  repeated DataObject data_objects = 1;
+  // Output only. DataObjects created.
+  repeated DataObject data_objects = 1
+      [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
 // Request message for
@@ -212,6 +216,11 @@ message DeleteDataObjectRequest {
       type: "vectorsearch.googleapis.com/DataObject"
     }
   ];
+
+  // Optional. The current etag of the DataObject.
+  // If an etag is provided and does not match the current etag of the
+  // DataObject, deletion will be blocked and an ABORTED error will be returned.
+  string etag = 2 [(google.api.field_behavior) = OPTIONAL];
 }
 
 // Request message for

package/build/protos/google/cloud/vectorsearch/v1beta/embedding_config.proto

@@ -18,10 +18,13 @@ package google.cloud.vectorsearch.v1beta;
 
 import "google/api/field_behavior.proto";
 
+option csharp_namespace = "Google.Cloud.VectorSearch.V1Beta";
 option go_package = "cloud.google.com/go/vectorsearch/apiv1beta/vectorsearchpb;vectorsearchpb";
 option java_multiple_files = true;
 option java_outer_classname = "EmbeddingConfigProto";
 option java_package = "com.google.cloud.vectorsearch.v1beta";
+option php_namespace = "Google\\Cloud\\VectorSearch\\V1beta";
+option ruby_package = "Google::Cloud::VectorSearch::V1beta";
 
 // Represents the task the embeddings will be used for.
 enum EmbeddingTaskType {

package/build/protos/google/cloud/vectorsearch/v1beta/vectorsearch_service.proto

@@ -30,10 +30,13 @@ import "google/protobuf/struct.proto";
 import "google/protobuf/timestamp.proto";
 import "google/rpc/status.proto";
 
+option csharp_namespace = "Google.Cloud.VectorSearch.V1Beta";
 option go_package = "cloud.google.com/go/vectorsearch/apiv1beta/vectorsearchpb;vectorsearchpb";
 option java_multiple_files = true;
 option java_outer_classname = "VectorSearchServiceProto";
 option java_package = "com.google.cloud.vectorsearch.v1beta";
+option php_namespace = "Google\\Cloud\\VectorSearch\\V1beta";
+option ruby_package = "Google::Cloud::VectorSearch::V1beta";
 
 // VectorSearchService provides methods for managing Collection resources, and
 // Collection Index resources. The primary resources offered by this service are
@@ -412,6 +415,19 @@ message Index {
     singular: "index"
   };
 
+  // The infrastructure type of the index.
+  oneof infra_type {
+    // Optional. Dedicated infrastructure for the index.
+    DedicatedInfrastructure dedicated_infrastructure = 11
+        [(google.api.field_behavior) = OPTIONAL];
+  }
+
+  // The type of the index.
+  oneof index_type {
+    // Optional. Dense ScaNN index.
+    DenseScannIndex dense_scann = 12 [(google.api.field_behavior) = OPTIONAL];
+  }
+
   // Identifier. name of resource
   string name = 1 [(google.api.field_behavior) = IDENTIFIER];
 
@@ -434,8 +450,7 @@ message Index {
 
   // Optional. Distance metric used for indexing. If not specified, will default
   // to DOT_PRODUCT.
-  google.cloud.vectorsearch.v1beta.DistanceMetric distance_metric = 4
-      [(google.api.field_behavior) = OPTIONAL];
+  DistanceMetric distance_metric = 4 [(google.api.field_behavior) = OPTIONAL];
 
   // Required. The collection schema field to index.
   string index_field = 5 [(google.api.field_behavior) = REQUIRED];
@@ -634,17 +649,19 @@ message ImportDataObjectsRequest {
 // Metadata for
 // [VectorSearchService.ImportDataObjects][google.cloud.vectorsearch.v1beta.VectorSearchService.ImportDataObjects].
 message ImportDataObjectsMetadata {
-  // The time the operation was created.
-  google.protobuf.Timestamp create_time = 1;
+  // Output only. The time the operation was created.
+  google.protobuf.Timestamp create_time = 1
+      [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // The time the operation was last updated.
-  google.protobuf.Timestamp update_time = 2;
+  // Output only. The time the operation was last updated.
+  google.protobuf.Timestamp update_time = 2
+      [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // Number of DataObjects that were processed successfully.
-  int64 success_count = 3;
+  // Output only. Number of DataObjects that were processed successfully.
+  int64 success_count = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // Number of DataObjects that failed during processing.
-  int64 failure_count = 4;
+  // Output only. Number of DataObjects that failed during processing.
+  int64 failure_count = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
 // Response for
@@ -660,7 +677,6 @@ message ExportDataObjectsRequest {
   // Google Cloud Storage configuration for the export.
   message GcsExportDestination {
     // Options for the format of the exported Data Objects.
-    // New formats may be added in the future.
     enum Format {
       // Unspecified format.
       FORMAT_UNSPECIFIED = 0;
@@ -696,12 +712,66 @@ message ExportDataObjectsRequest {
 
 // Metadata for the ExportDataObjects LRO.
 message ExportDataObjectsMetadata {
-  // The time the operation was created.
-  google.protobuf.Timestamp create_time = 1;
+  // Output only. The time the operation was created.
+  google.protobuf.Timestamp create_time = 1
+      [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // The time the operation finished.
-  google.protobuf.Timestamp finish_time = 2;
+  // Output only. The time the operation finished.
+  google.protobuf.Timestamp finish_time = 2
+      [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
 // Response for the ExportDataObjects LRO.
 message ExportDataObjectsResponse {}
+
+// Represents dedicated infrastructure for the index.
+message DedicatedInfrastructure {
+  // Specification for autoscaling.
+  message AutoscalingSpec {
+    // Optional. The minimum number of replicas. If not set or set to `0`,
+    // defaults to `2`. Must be >= `2` and <= `1000`.
+    int32 min_replica_count = 1 [(google.api.field_behavior) = OPTIONAL];
+
+    // Optional. The maximum number of replicas. If not set or set to `0`,
+    // defaults to the greater of `min_replica_count` and `5`. Must be >=
+    // `min_replica_count` and <= `1000`.
+    int32 max_replica_count = 2 [(google.api.field_behavior) = OPTIONAL];
+  }
+
+  // Mode of the dedicated infrastructure.
+  enum Mode {
+    // Default will use `PERFORMANCE_OPTIMIZED`.
+    MODE_UNSPECIFIED = 0;
+
+    // This is storage optimized variation.
+    STORAGE_OPTIMIZED = 1;
+
+    // This is Performance optimized on E2 or equivalent family.
+    PERFORMANCE_OPTIMIZED = 2;
+  }
+
+  // Optional. Mode of the dedicated infrastructure.
+  optional Mode mode = 1 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Autoscaling specification.
+  AutoscalingSpec autoscaling_spec = 2 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// Dense ScaNN index configuration.
+message DenseScannIndex {
+  // Feature norm type for ScaNN index.
+  enum FeatureNormType {
+    // Unspecified feature norm type.
+    FEATURE_NORM_TYPE_UNSPECIFIED = 0;
+
+    // No norm applied.
+    NONE = 1;
+
+    // Unit L2 norm.
+    UNIT_L2_NORM = 2;
+  }
+
+  // Optional. Feature norm type.
+  FeatureNormType feature_norm_type = 2
+      [(google.api.field_behavior) = OPTIONAL];
+}