@google-cloud/vectorsearch 0.1.0

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

@@ -0,0 +1,631 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package google.cloud.vectorsearch.v1beta;
+
+import "google/api/annotations.proto";
+import "google/api/client.proto";
+import "google/api/field_behavior.proto";
+import "google/api/field_info.proto";
+import "google/api/resource.proto";
+import "google/cloud/vectorsearch/v1beta/common.proto";
+import "google/cloud/vectorsearch/v1beta/embedding_config.proto";
+import "google/longrunning/operations.proto";
+import "google/protobuf/empty.proto";
+import "google/protobuf/field_mask.proto";
+import "google/protobuf/struct.proto";
+import "google/protobuf/timestamp.proto";
+import "google/rpc/status.proto";
+
+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";
+
+// VectorSearchService provides methods for managing Collection resources, and
+// Collection Index resources. The primary resources offered by this service are
+// Collections which are a container for a set of related JSON data objects, and
+// Collection Indexes which enable efficient ANN search across data objects
+// within a Collection.
+service VectorSearchService {
+  option (google.api.default_host) = "vectorsearch.googleapis.com";
+  option (google.api.oauth_scopes) =
+      "https://www.googleapis.com/auth/cloud-platform";
+
+  // Lists Collections in a given project and location.
+  rpc ListCollections(ListCollectionsRequest)
+      returns (ListCollectionsResponse) {
+    option (google.api.http) = {
+      get: "/v1beta/{parent=projects/*/locations/*}/collections"
+    };
+    option (google.api.method_signature) = "parent";
+  }
+
+  // Gets details of a single Collection.
+  rpc GetCollection(GetCollectionRequest) returns (Collection) {
+    option (google.api.http) = {
+      get: "/v1beta/{name=projects/*/locations/*/collections/*}"
+    };
+    option (google.api.method_signature) = "name";
+  }
+
+  // Creates a new Collection in a given project and location.
+  rpc CreateCollection(CreateCollectionRequest)
+      returns (google.longrunning.Operation) {
+    option (google.api.http) = {
+      post: "/v1beta/{parent=projects/*/locations/*}/collections"
+      body: "collection"
+    };
+    option (google.api.method_signature) = "parent,collection,collection_id";
+    option (google.longrunning.operation_info) = {
+      response_type: "Collection"
+      metadata_type: "OperationMetadata"
+    };
+  }
+
+  // Updates the parameters of a single Collection.
+  rpc UpdateCollection(UpdateCollectionRequest)
+      returns (google.longrunning.Operation) {
+    option (google.api.http) = {
+      patch: "/v1beta/{collection.name=projects/*/locations/*/collections/*}"
+      body: "collection"
+    };
+    option (google.api.method_signature) = "collection,update_mask";
+    option (google.longrunning.operation_info) = {
+      response_type: "Collection"
+      metadata_type: "OperationMetadata"
+    };
+  }
+
+  // Deletes a single Collection.
+  rpc DeleteCollection(DeleteCollectionRequest)
+      returns (google.longrunning.Operation) {
+    option (google.api.http) = {
+      delete: "/v1beta/{name=projects/*/locations/*/collections/*}"
+    };
+    option (google.api.method_signature) = "name";
+    option (google.longrunning.operation_info) = {
+      response_type: "google.protobuf.Empty"
+      metadata_type: "OperationMetadata"
+    };
+  }
+
+  // Lists Indexes in a given project and location.
+  rpc ListIndexes(ListIndexesRequest) returns (ListIndexesResponse) {
+    option (google.api.http) = {
+      get: "/v1beta/{parent=projects/*/locations/*/collections/*}/indexes"
+    };
+    option (google.api.method_signature) = "parent";
+  }
+
+  // Gets details of a single Index.
+  rpc GetIndex(GetIndexRequest) returns (Index) {
+    option (google.api.http) = {
+      get: "/v1beta/{name=projects/*/locations/*/collections/*/indexes/*}"
+    };
+    option (google.api.method_signature) = "name";
+  }
+
+  // Creates a new Index in a given project and location.
+  rpc CreateIndex(CreateIndexRequest) returns (google.longrunning.Operation) {
+    option (google.api.http) = {
+      post: "/v1beta/{parent=projects/*/locations/*/collections/*}/indexes"
+      body: "index"
+    };
+    option (google.api.method_signature) = "parent,index,index_id";
+    option (google.longrunning.operation_info) = {
+      response_type: "Index"
+      metadata_type: "OperationMetadata"
+    };
+  }
+
+  // Deletes a single Index.
+  rpc DeleteIndex(DeleteIndexRequest) returns (google.longrunning.Operation) {
+    option (google.api.http) = {
+      delete: "/v1beta/{name=projects/*/locations/*/collections/*/indexes/*}"
+    };
+    option (google.api.method_signature) = "name";
+    option (google.longrunning.operation_info) = {
+      response_type: "google.protobuf.Empty"
+      metadata_type: "OperationMetadata"
+    };
+  }
+
+  // Initiates a Long-Running Operation to import DataObjects into a Collection.
+  rpc ImportDataObjects(ImportDataObjectsRequest)
+      returns (google.longrunning.Operation) {
+    option (google.api.http) = {
+      post: "/v1beta/{name=projects/*/locations/*/collections/*}:importDataObjects"
+      body: "*"
+    };
+    option (google.longrunning.operation_info) = {
+      response_type: "ImportDataObjectsResponse"
+      metadata_type: "ImportDataObjectsMetadata"
+    };
+  }
+}
+
+// Message describing Collection object
+message Collection {
+  option (google.api.resource) = {
+    type: "vectorsearch.googleapis.com/Collection"
+    pattern: "projects/{project}/locations/{location}/collections/{collection}"
+    plural: "collections"
+    singular: "collection"
+  };
+
+  // Identifier. name of resource
+  string name = 1 [(google.api.field_behavior) = IDENTIFIER];
+
+  // Optional. User-specified display name of the collection
+  string display_name = 8 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. User-specified description of the collection
+  string description = 9 [(google.api.field_behavior) = OPTIONAL];
+
+  // Output only. [Output only] Create time stamp
+  google.protobuf.Timestamp create_time = 2
+      [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. [Output only] Update time stamp
+  google.protobuf.Timestamp update_time = 3
+      [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Optional. Labels as key value pairs.
+  map<string, string> labels = 4 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Deprecated: JSON Schema for data. Please use data_schema instead.
+  google.protobuf.Struct schema = 5
+      [deprecated = true, (google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Schema for vector fields. Only vector fields in this schema will
+  // be searchable. Field names must contain only alphanumeric characters,
+  // underscores, and hyphens.
+  map<string, VectorField> vector_schema = 7
+      [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. JSON Schema for data.
+  // Field names must contain only alphanumeric characters,
+  // underscores, and hyphens.
+  google.protobuf.Struct data_schema = 10
+      [(google.api.field_behavior) = OPTIONAL];
+}
+
+// Message describing a vector field.
+message VectorField {
+  // Vector type configuration.
+  oneof vector_type_config {
+    // Dense vector field.
+    DenseVectorField dense_vector = 3;
+
+    // Sparse vector field.
+    SparseVectorField sparse_vector = 4;
+  }
+}
+
+// Message describing a dense vector field.
+message DenseVectorField {
+  // Dimensionality of the vector field.
+  int32 dimensions = 1;
+
+  // Optional. Configuration for generating embeddings for the vector field. If
+  // not specified, the embedding field must be populated in the DataObject.
+  VertexEmbeddingConfig vertex_embedding_config = 3
+      [(google.api.field_behavior) = OPTIONAL];
+}
+
+// Message describing a sparse vector field.
+message SparseVectorField {}
+
+// Message for requesting list of Collections
+message ListCollectionsRequest {
+  // Required. Parent value for ListCollectionsRequest
+  string parent = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      child_type: "vectorsearch.googleapis.com/Collection"
+    }
+  ];
+
+  // Optional. Requested page size. Server may return fewer items than
+  // requested. If unspecified, server will pick an appropriate default.
+  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. A token identifying a page of results the server should return.
+  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Filtering results
+  string filter = 4 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Hint for how to order the results
+  string order_by = 5 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// Message for response to listing Collections
+message ListCollectionsResponse {
+  // The list of Collection
+  repeated Collection collections = 1;
+
+  // A token identifying a page of results the server should return.
+  string next_page_token = 2;
+
+  // Unordered list. Locations that could not be reached.
+  repeated string unreachable = 3
+      [(google.api.field_behavior) = UNORDERED_LIST];
+}
+
+// Message for getting a Collection
+message GetCollectionRequest {
+  // Required. Name of the resource
+  string name = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "vectorsearch.googleapis.com/Collection"
+    }
+  ];
+}
+
+// Message for creating a Collection
+message CreateCollectionRequest {
+  // Required. Value for parent.
+  string parent = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      child_type: "vectorsearch.googleapis.com/Collection"
+    }
+  ];
+
+  // Required. ID of the Collection to create.
+  // The id must be 1-63 characters long, and comply with
+  // <a href="https://www.ietf.org/rfc/rfc1035.txt" target="_blank">RFC1035</a>.
+  // Specifically, it must be 1-63 characters long and match the regular
+  // expression `[a-z](?:[-a-z0-9]{0,61}[a-z0-9])?`.
+  string collection_id = 2 [(google.api.field_behavior) = REQUIRED];
+
+  // Required. The resource being created
+  Collection collection = 3 [(google.api.field_behavior) = REQUIRED];
+
+  // Optional. An optional request ID to identify requests. Specify a unique
+  // request ID so that if you must retry your request, the server will know to
+  // ignore the request if it has already been completed. The server will
+  // guarantee that for at least 60 minutes since the first request.
+  //
+  // For example, consider a situation where you make an initial request and the
+  // request times out. If you make the request again with the same request
+  // ID, the server can check if original operation with the same request ID
+  // was received, and if so, will ignore the second request. This prevents
+  // clients from accidentally creating duplicate commitments.
+  //
+  // The request ID must be a valid UUID with the exception that zero UUID is
+  // not supported (00000000-0000-0000-0000-000000000000).
+  string request_id = 4 [
+    (google.api.field_info).format = UUID4,
+    (google.api.field_behavior) = OPTIONAL
+  ];
+}
+
+// Message for updating a Collection
+message UpdateCollectionRequest {
+  // Optional. Field mask is used to specify the fields to be overwritten in the
+  // Collection resource by the update.
+  // The fields specified in the update_mask are relative to the resource, not
+  // the full request. A field will be overwritten if it is in the mask. If the
+  // user does not provide a mask then all fields present in the request will be
+  // overwritten.
+  //
+  // The following fields support update: `display_name`, `description`,
+  // `labels`, `data_schema`, `vector_schema`.
+  // For `data_schema` and `vector_schema`, fields can only be added, not
+  // modified or deleted.
+  // Partial updates for `data_schema` and `vector_schema` are also supported
+  // by using sub-field paths in `update_mask`, e.g.
+  // `data_schema.properties.foo` or `vector_schema.my_vector_field`.
+  //
+  // If `*` is provided in the update_mask, full replacement will be performed.
+  google.protobuf.FieldMask update_mask = 1
+      [(google.api.field_behavior) = OPTIONAL];
+
+  // Required. The resource being updated
+  Collection collection = 2 [(google.api.field_behavior) = REQUIRED];
+
+  // Optional. An optional request ID to identify requests. Specify a unique
+  // request ID so that if you must retry your request, the server will know to
+  // ignore the request if it has already been completed. The server will
+  // guarantee that for at least 60 minutes since the first request.
+  //
+  // For example, consider a situation where you make an initial request and the
+  // request times out. If you make the request again with the same request
+  // ID, the server can check if original operation with the same request ID
+  // was received, and if so, will ignore the second request. This prevents
+  // clients from accidentally creating duplicate commitments.
+  //
+  // The request ID must be a valid UUID with the exception that zero UUID is
+  // not supported (00000000-0000-0000-0000-000000000000).
+  string request_id = 3 [
+    (google.api.field_info).format = UUID4,
+    (google.api.field_behavior) = OPTIONAL
+  ];
+}
+
+// Message for deleting a Collection
+message DeleteCollectionRequest {
+  // Required. Name of the resource
+  string name = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "vectorsearch.googleapis.com/Collection"
+    }
+  ];
+
+  // Optional. An optional request ID to identify requests. Specify a unique
+  // request ID so that if you must retry your request, the server will know to
+  // ignore the request if it has already been completed. The server will
+  // guarantee that for at least 60 minutes after the first request.
+  //
+  // For example, consider a situation where you make an initial request and the
+  // request times out. If you make the request again with the same request
+  // ID, the server can check if original operation with the same request ID
+  // was received, and if so, will ignore the second request. This prevents
+  // clients from accidentally creating duplicate commitments.
+  //
+  // The request ID must be a valid UUID with the exception that zero UUID is
+  // not supported (00000000-0000-0000-0000-000000000000).
+  string request_id = 2 [
+    (google.api.field_info).format = UUID4,
+    (google.api.field_behavior) = OPTIONAL
+  ];
+}
+
+// Message describing Index object
+message Index {
+  option (google.api.resource) = {
+    type: "vectorsearch.googleapis.com/Index"
+    pattern: "projects/{project}/locations/{location}/collections/{collection}/indexes/{index}"
+    plural: "indexes"
+    singular: "index"
+  };
+
+  // Identifier. name of resource
+  string name = 1 [(google.api.field_behavior) = IDENTIFIER];
+
+  // Optional. User-specified display name of the index
+  string display_name = 8 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. User-specified description of the index
+  string description = 9 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Labels as key value pairs.
+  map<string, string> labels = 10 [(google.api.field_behavior) = OPTIONAL];
+
+  // Output only. [Output only] Create time stamp
+  google.protobuf.Timestamp create_time = 2
+      [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. [Output only] Update time stamp
+  google.protobuf.Timestamp update_time = 3
+      [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Optional. Distance metric used for indexing. If not specified, will default
+  // to DOT_PRODUCT.
+  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];
+
+  // Optional. The fields to push into the index to enable fast ANN inline
+  // filtering.
+  repeated string filter_fields = 6 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. The fields to push into the index to enable inline data
+  // retrieval.
+  repeated string store_fields = 7 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// Message for creating an Index.
+message CreateIndexRequest {
+  // Required. The resource name of the Collection for which to create the
+  // Index. Format:
+  // `projects/{project}/locations/{location}/collections/{collection}`
+  string parent = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "vectorsearch.googleapis.com/Collection"
+    }
+  ];
+
+  // Required. ID of the Index to create.
+  // The id must be 1-63 characters long, and comply with
+  // <a href="https://www.ietf.org/rfc/rfc1035.txt" target="_blank">RFC1035</a>.
+  // Specifically, it must be 1-63 characters long and match the regular
+  // expression `[a-z](?:[-a-z0-9]{0,61}[a-z0-9])?`.
+  string index_id = 2 [(google.api.field_behavior) = REQUIRED];
+
+  // Required. The resource being created
+  Index index = 3 [(google.api.field_behavior) = REQUIRED];
+
+  // Optional. An optional request ID to identify requests. Specify a unique
+  // request ID so that if you must retry your request, the server will know to
+  // ignore the request if it has already been completed. The server will
+  // guarantee that for at least 60 minutes since the first request.
+  //
+  // For example, consider a situation where you make an initial request and the
+  // request times out. If you make the request again with the same request
+  // ID, the server can check if original operation with the same request ID
+  // was received, and if so, will ignore the second request. This prevents
+  // clients from accidentally creating duplicate commitments.
+  //
+  // The request ID must be a valid UUID with the exception that zero UUID is
+  // not supported (00000000-0000-0000-0000-000000000000).
+  string request_id = 4 [
+    (google.api.field_info).format = UUID4,
+    (google.api.field_behavior) = OPTIONAL
+  ];
+}
+
+// Message for deleting an Index.
+message DeleteIndexRequest {
+  // Required. The resource name of the Index to delete.
+  // Format:
+  // `projects/{project}/locations/{location}/collections/{collection}/indexes/{index}`
+  string name = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "vectorsearch.googleapis.com/Index"
+    }
+  ];
+
+  // Optional. An optional request ID to identify requests. Specify a unique
+  // request ID so that if you must retry your request, the server will know to
+  // ignore the request if it has already been completed. The server will
+  // guarantee that for at least 60 minutes since the first request.
+  //
+  // For example, consider a situation where you make an initial request and the
+  // request times out. If you make the request again with the same request
+  // ID, the server can check if original operation with the same request ID
+  // was received, and if so, will ignore the second request. This prevents
+  // clients from accidentally creating duplicate commitments.
+  //
+  // The request ID must be a valid UUID with the exception that zero UUID is
+  // not supported (00000000-0000-0000-0000-000000000000).
+  string request_id = 2 [
+    (google.api.field_info).format = UUID4,
+    (google.api.field_behavior) = OPTIONAL
+  ];
+}
+
+// Message for requesting list of Indexes
+message ListIndexesRequest {
+  // Required. Parent value for ListIndexesRequest
+  string parent = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      child_type: "vectorsearch.googleapis.com/Index"
+    }
+  ];
+
+  // Optional. Requested page size. Server may return fewer items than
+  // requested. If unspecified, server will pick an appropriate default.
+  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. A token identifying a page of results the server should return.
+  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Filtering results
+  string filter = 4 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Hint for how to order the results
+  string order_by = 5 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// Message for response to listing Indexes
+message ListIndexesResponse {
+  // The list of Index
+  repeated Index indexes = 1;
+
+  // A token identifying a page of results the server should return.
+  string next_page_token = 2;
+}
+
+// Message for getting an Index
+message GetIndexRequest {
+  // Required. Name of the resource
+  string name = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "vectorsearch.googleapis.com/Index"
+    }
+  ];
+}
+
+// Represents the metadata of the long-running operation.
+message OperationMetadata {
+  // Output only. The time the operation was created.
+  google.protobuf.Timestamp create_time = 1
+      [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. The time the operation finished running.
+  google.protobuf.Timestamp end_time = 2
+      [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. Server-defined resource path for the target of the operation.
+  string target = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. Name of the verb executed by the operation.
+  string verb = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. Human-readable status of the operation, if any.
+  string status_message = 5 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. Identifies whether the user has requested cancellation
+  // of the operation. Operations that have been cancelled successfully
+  // have
+  // [google.longrunning.Operation.error][google.longrunning.Operation.error]
+  // value with a [google.rpc.Status.code][google.rpc.Status.code] of `1`,
+  // corresponding to `Code.CANCELLED`.
+  bool requested_cancellation = 6 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. API version used to start the operation.
+  string api_version = 7 [(google.api.field_behavior) = OUTPUT_ONLY];
+}
+
+// Request message for [DataObjectService.ImportDataObjects][].
+message ImportDataObjectsRequest {
+  // Google Cloud Storage configuration for the import.
+  message GcsImportConfig {
+    // Required. URI prefix of the Cloud Storage DataObjects to import.
+    string contents_uri = 1 [(google.api.field_behavior) = REQUIRED];
+
+    // Required. URI prefix of the Cloud Storage location to write any errors
+    // encountered during the import.
+    string error_uri = 2 [(google.api.field_behavior) = REQUIRED];
+  }
+
+  // The configuration for the import data and error results.
+  oneof config {
+    // The Cloud Storage location of the input content.
+    GcsImportConfig gcs_import = 2;
+  }
+
+  // Required. The resource name of the Collection to import DataObjects into.
+  // Format: `projects/{project}/locations/{location}/collections/{collection}`.
+  string name = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "vectorsearch.googleapis.com/Collection"
+    }
+  ];
+}
+
+// Metadata for [DataObjectService.ImportDataObjects][].
+message ImportDataObjectsMetadata {
+  // The time the operation was created.
+  google.protobuf.Timestamp create_time = 1;
+
+  // The time the operation was last updated.
+  google.protobuf.Timestamp update_time = 2;
+
+  // Number of DataObjects that were processed successfully.
+  int64 success_count = 3;
+
+  // Number of DataObjects that failed during processing.
+  int64 failure_count = 4;
+}
+
+// Response for [DataObjectService.ImportDataObjects][].
+message ImportDataObjectsResponse {
+  // Status of the LRO
+  google.rpc.Status status = 1;
+}