feat: add match service in aiplatform v1beta1 match_service.proto

packages/google-cloud-aiplatform/README.md

@@ -404,6 +404,8 @@ Samples are in the [`samples/`](https://github.com/googleapis/google-cloud-node/
 | Job_service.resume_model_deployment_monitoring_job | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-aiplatform/samples/generated/v1beta1/job_service.resume_model_deployment_monitoring_job.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-cloud-aiplatform/samples/generated/v1beta1/job_service.resume_model_deployment_monitoring_job.js,samples/README.md) |
 | Job_service.search_model_deployment_monitoring_stats_anomalies | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-aiplatform/samples/generated/v1beta1/job_service.search_model_deployment_monitoring_stats_anomalies.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-cloud-aiplatform/samples/generated/v1beta1/job_service.search_model_deployment_monitoring_stats_anomalies.js,samples/README.md) |
 | Job_service.update_model_deployment_monitoring_job | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-aiplatform/samples/generated/v1beta1/job_service.update_model_deployment_monitoring_job.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-cloud-aiplatform/samples/generated/v1beta1/job_service.update_model_deployment_monitoring_job.js,samples/README.md) |
+| Match_service.find_neighbors | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-aiplatform/samples/generated/v1beta1/match_service.find_neighbors.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-cloud-aiplatform/samples/generated/v1beta1/match_service.find_neighbors.js,samples/README.md) |
+| Match_service.read_index_datapoints | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-aiplatform/samples/generated/v1beta1/match_service.read_index_datapoints.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-cloud-aiplatform/samples/generated/v1beta1/match_service.read_index_datapoints.js,samples/README.md) |
 | Metadata_service.add_context_artifacts_and_executions | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-aiplatform/samples/generated/v1beta1/metadata_service.add_context_artifacts_and_executions.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-cloud-aiplatform/samples/generated/v1beta1/metadata_service.add_context_artifacts_and_executions.js,samples/README.md) |
 | Metadata_service.add_context_children | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-aiplatform/samples/generated/v1beta1/metadata_service.add_context_children.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-cloud-aiplatform/samples/generated/v1beta1/metadata_service.add_context_children.js,samples/README.md) |
 | Metadata_service.add_execution_events | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-aiplatform/samples/generated/v1beta1/metadata_service.add_execution_events.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-cloud-aiplatform/samples/generated/v1beta1/metadata_service.add_execution_events.js,samples/README.md) |

packages/google-cloud-aiplatform/protos/google/cloud/aiplatform/v1beta1/match_service.proto

@@ -0,0 +1,176 @@
+// Copyright 2023 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.aiplatform.v1beta1;
+
+import "google/api/annotations.proto";
+import "google/api/client.proto";
+import "google/api/field_behavior.proto";
+import "google/api/resource.proto";
+import "google/cloud/aiplatform/v1beta1/index.proto";
+
+option csharp_namespace = "Google.Cloud.AIPlatform.V1Beta1";
+option go_package = "cloud.google.com/go/aiplatform/apiv1beta1/aiplatformpb;aiplatformpb";
+option java_multiple_files = true;
+option java_outer_classname = "MatchServiceProto";
+option java_package = "com.google.cloud.aiplatform.v1beta1";
+option php_namespace = "Google\\Cloud\\AIPlatform\\V1beta1";
+option ruby_package = "Google::Cloud::AIPlatform::V1beta1";
+
+// MatchService is a Google managed service for efficient vector similarity
+// search at scale.
+service MatchService {
+  option (google.api.default_host) = "aiplatform.googleapis.com";
+  option (google.api.oauth_scopes) =
+      "https://www.googleapis.com/auth/cloud-platform";
+
+  // Finds the nearest neighbors of each vector within the request.
+  rpc FindNeighbors(FindNeighborsRequest) returns (FindNeighborsResponse) {
+    option (google.api.http) = {
+      post: "/v1beta1/{index_endpoint=projects/*/locations/*/indexEndpoints/*}:findNeighbors"
+      body: "*"
+    };
+  }
+
+  // Reads the datapoints/vectors of the given IDs.
+  // A maximum of 1000 datapoints can be retrieved in a batch.
+  rpc ReadIndexDatapoints(ReadIndexDatapointsRequest)
+      returns (ReadIndexDatapointsResponse) {
+    option (google.api.http) = {
+      post: "/v1beta1/{index_endpoint=projects/*/locations/*/indexEndpoints/*}:readIndexDatapoints"
+      body: "*"
+    };
+  }
+}
+
+// The request message for
+// [MatchService.FindNeighbors][google.cloud.aiplatform.v1beta1.MatchService.FindNeighbors].
+message FindNeighborsRequest {
+  // A query to find a number of the nearest neighbors (most similar vectors)
+  // of a vector.
+  message Query {
+    // Required. The datapoint/vector whose nearest neighbors should be searched
+    // for.
+    IndexDatapoint datapoint = 1 [(google.api.field_behavior) = REQUIRED];
+
+    // The number of nearest neighbors to be retrieved from database for each
+    // query. If not set, will use the default from the service configuration
+    // (https://cloud.google.com/vertex-ai/docs/matching-engine/configuring-indexes#nearest-neighbor-search-config).
+    int32 neighbor_count = 2;
+
+    // Crowding is a constraint on a neighbor list produced by nearest neighbor
+    // search requiring that no more than some value k' of the k neighbors
+    // returned have the same value of crowding_attribute.
+    // It's used for improving result diversity.
+    // This field is the maximum number of matches with the same crowding tag.
+    int32 per_crowding_attribute_neighbor_count = 3;
+
+    // The number of neighbors to find via approximate search before
+    // exact reordering is performed. If not set, the default value from scam
+    // config is used; if set, this value must be > 0.
+    int32 approximate_neighbor_count = 4;
+
+    // The fraction of the number of leaves to search, set at query time allows
+    // user to tune search performance. This value increase result in both
+    // search accuracy and latency increase. The value should be between 0.0
+    // and 1.0. If not set or set to 0.0, query uses the default value specified
+    // in
+    // NearestNeighborSearchConfig.TreeAHConfig.fraction_leaf_nodes_to_search.
+    double fraction_leaf_nodes_to_search_override = 5;
+  }
+
+  // Required. The name of the index endpoint.
+  // Format:
+  // `projects/{project}/locations/{location}/indexEndpoints/{index_endpoint}`
+  string index_endpoint = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "aiplatform.googleapis.com/IndexEndpoint"
+    }
+  ];
+
+  // The ID of the DeploydIndex that will serve the request. This request is
+  // sent to a specific IndexEndpoint, as per the IndexEndpoint.network. That
+  // IndexEndpoint also has IndexEndpoint.deployed_indexes, and each such index
+  // has a DeployedIndex.id field.
+  // The value of the field below must equal one of the DeployedIndex.id
+  // fields of the IndexEndpoint that is being called for this request.
+  string deployed_index_id = 2;
+
+  // The list of queries.
+  repeated Query queries = 3;
+
+  // If set to true, the full datapoints (including all vector values and
+  // restricts) of the nearest neighbors are returned.
+  // Note that returning full datapoint will significantly increase the
+  // latency and cost of the query.
+  bool return_full_datapoint = 4;
+}
+
+// The response message for
+// [MatchService.FindNeighbors][google.cloud.aiplatform.v1beta1.MatchService.FindNeighbors].
+message FindNeighborsResponse {
+  // A neighbor of the query vector.
+  message Neighbor {
+    // The datapoint of the neighbor.
+    // Note that full datapoints are returned only when "return_full_datapoint"
+    // is set to true. Otherwise, only the "datapoint_id" and "crowding_tag"
+    // fields are populated.
+    IndexDatapoint datapoint = 1;
+
+    // The distance between the neighbor and the query vector.
+    double distance = 2;
+  }
+
+  // Nearest neighbors for one query.
+  message NearestNeighbors {
+    // The ID of the query datapoint.
+    string id = 1;
+
+    // All its neighbors.
+    repeated Neighbor neighbors = 2;
+  }
+
+  // The nearest neighbors of the query datapoints.
+  repeated NearestNeighbors nearest_neighbors = 1;
+}
+
+// The request message for
+// [MatchService.ReadIndexDatapoints][google.cloud.aiplatform.v1beta1.MatchService.ReadIndexDatapoints].
+message ReadIndexDatapointsRequest {
+  // Required. The name of the index endpoint.
+  // Format:
+  // `projects/{project}/locations/{location}/indexEndpoints/{index_endpoint}`
+  string index_endpoint = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "aiplatform.googleapis.com/IndexEndpoint"
+    }
+  ];
+
+  // The ID of the DeploydIndex that will serve the request.
+  string deployed_index_id = 2;
+
+  // IDs of the datapoints to be searched for.
+  repeated string ids = 3;
+}
+
+// The response message for
+// [MatchService.ReadIndexDatapoints][google.cloud.aiplatform.v1beta1.MatchService.ReadIndexDatapoints].
+message ReadIndexDatapointsResponse {
+  // The result list of datapoints.
+  repeated IndexDatapoint datapoints = 1;
+}