index_service.proto 9.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274
  1. // Copyright 2021 Google LLC
  2. //
  3. // Licensed under the Apache License, Version 2.0 (the "License");
  4. // you may not use this file except in compliance with the License.
  5. // You may obtain a copy of the License at
  6. //
  7. // http://www.apache.org/licenses/LICENSE-2.0
  8. //
  9. // Unless required by applicable law or agreed to in writing, software
  10. // distributed under the License is distributed on an "AS IS" BASIS,
  11. // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12. // See the License for the specific language governing permissions and
  13. // limitations under the License.
  14. syntax = "proto3";
  15. package google.cloud.aiplatform.v1beta1;
  16. import "google/api/annotations.proto";
  17. import "google/api/client.proto";
  18. import "google/api/field_behavior.proto";
  19. import "google/api/resource.proto";
  20. import "google/cloud/aiplatform/v1beta1/index.proto";
  21. import "google/cloud/aiplatform/v1beta1/operation.proto";
  22. import "google/longrunning/operations.proto";
  23. import "google/protobuf/field_mask.proto";
  24. option csharp_namespace = "Google.Cloud.AIPlatform.V1Beta1";
  25. option go_package = "google.golang.org/genproto/googleapis/cloud/aiplatform/v1beta1;aiplatform";
  26. option java_multiple_files = true;
  27. option java_outer_classname = "IndexServiceProto";
  28. option java_package = "com.google.cloud.aiplatform.v1beta1";
  29. option php_namespace = "Google\\Cloud\\AIPlatform\\V1beta1";
  30. option ruby_package = "Google::Cloud::AIPlatform::V1beta1";
  31. // A service for creating and managing Vertex AI's Index resources.
  32. service IndexService {
  33. option (google.api.default_host) = "aiplatform.googleapis.com";
  34. option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/cloud-platform";
  35. // Creates an Index.
  36. rpc CreateIndex(CreateIndexRequest) returns (google.longrunning.Operation) {
  37. option (google.api.http) = {
  38. post: "/v1beta1/{parent=projects/*/locations/*}/indexes"
  39. body: "index"
  40. };
  41. option (google.api.method_signature) = "parent,index";
  42. option (google.longrunning.operation_info) = {
  43. response_type: "Index"
  44. metadata_type: "CreateIndexOperationMetadata"
  45. };
  46. }
  47. // Gets an Index.
  48. rpc GetIndex(GetIndexRequest) returns (Index) {
  49. option (google.api.http) = {
  50. get: "/v1beta1/{name=projects/*/locations/*/indexes/*}"
  51. };
  52. option (google.api.method_signature) = "name";
  53. }
  54. // Lists Indexes in a Location.
  55. rpc ListIndexes(ListIndexesRequest) returns (ListIndexesResponse) {
  56. option (google.api.http) = {
  57. get: "/v1beta1/{parent=projects/*/locations/*}/indexes"
  58. };
  59. option (google.api.method_signature) = "parent";
  60. }
  61. // Updates an Index.
  62. rpc UpdateIndex(UpdateIndexRequest) returns (google.longrunning.Operation) {
  63. option (google.api.http) = {
  64. patch: "/v1beta1/{index.name=projects/*/locations/*/indexes/*}"
  65. body: "index"
  66. };
  67. option (google.api.method_signature) = "index,update_mask";
  68. option (google.longrunning.operation_info) = {
  69. response_type: "Index"
  70. metadata_type: "UpdateIndexOperationMetadata"
  71. };
  72. }
  73. // Deletes an Index.
  74. // An Index can only be deleted when all its
  75. // [DeployedIndexes][google.cloud.aiplatform.v1beta1.Index.deployed_indexes] had been undeployed.
  76. rpc DeleteIndex(DeleteIndexRequest) returns (google.longrunning.Operation) {
  77. option (google.api.http) = {
  78. delete: "/v1beta1/{name=projects/*/locations/*/indexes/*}"
  79. };
  80. option (google.api.method_signature) = "name";
  81. option (google.longrunning.operation_info) = {
  82. response_type: "google.protobuf.Empty"
  83. metadata_type: "DeleteOperationMetadata"
  84. };
  85. }
  86. }
  87. // Request message for [IndexService.CreateIndex][google.cloud.aiplatform.v1beta1.IndexService.CreateIndex].
  88. message CreateIndexRequest {
  89. // Required. The resource name of the Location to create the Index in.
  90. // Format: `projects/{project}/locations/{location}`
  91. string parent = 1 [
  92. (google.api.field_behavior) = REQUIRED,
  93. (google.api.resource_reference) = {
  94. type: "locations.googleapis.com/Location"
  95. }
  96. ];
  97. // Required. The Index to create.
  98. Index index = 2 [(google.api.field_behavior) = REQUIRED];
  99. }
  100. // Runtime operation information for [IndexService.CreateIndex][google.cloud.aiplatform.v1beta1.IndexService.CreateIndex].
  101. message CreateIndexOperationMetadata {
  102. // The operation generic information.
  103. GenericOperationMetadata generic_metadata = 1;
  104. // The operation metadata with regard to Matching Engine Index operation.
  105. NearestNeighborSearchOperationMetadata nearest_neighbor_search_operation_metadata = 2;
  106. }
  107. // Request message for [IndexService.GetIndex][google.cloud.aiplatform.v1beta1.IndexService.GetIndex]
  108. message GetIndexRequest {
  109. // Required. The name of the Index resource.
  110. // Format:
  111. // `projects/{project}/locations/{location}/indexes/{index}`
  112. string name = 1 [
  113. (google.api.field_behavior) = REQUIRED,
  114. (google.api.resource_reference) = {
  115. type: "aiplatform.googleapis.com/Index"
  116. }
  117. ];
  118. }
  119. // Request message for [IndexService.ListIndexes][google.cloud.aiplatform.v1beta1.IndexService.ListIndexes].
  120. message ListIndexesRequest {
  121. // Required. The resource name of the Location from which to list the Indexes.
  122. // Format: `projects/{project}/locations/{location}`
  123. string parent = 1 [
  124. (google.api.field_behavior) = REQUIRED,
  125. (google.api.resource_reference) = {
  126. type: "locations.googleapis.com/Location"
  127. }
  128. ];
  129. // The standard list filter.
  130. string filter = 2;
  131. // The standard list page size.
  132. int32 page_size = 3;
  133. // The standard list page token.
  134. // Typically obtained via
  135. // [ListIndexesResponse.next_page_token][google.cloud.aiplatform.v1beta1.ListIndexesResponse.next_page_token] of the previous
  136. // [IndexService.ListIndexes][google.cloud.aiplatform.v1beta1.IndexService.ListIndexes] call.
  137. string page_token = 4;
  138. // Mask specifying which fields to read.
  139. google.protobuf.FieldMask read_mask = 5;
  140. }
  141. // Response message for [IndexService.ListIndexes][google.cloud.aiplatform.v1beta1.IndexService.ListIndexes].
  142. message ListIndexesResponse {
  143. // List of indexes in the requested page.
  144. repeated Index indexes = 1;
  145. // A token to retrieve next page of results.
  146. // Pass to [ListIndexesRequest.page_token][google.cloud.aiplatform.v1beta1.ListIndexesRequest.page_token] to obtain that page.
  147. string next_page_token = 2;
  148. }
  149. // Request message for [IndexService.UpdateIndex][google.cloud.aiplatform.v1beta1.IndexService.UpdateIndex].
  150. message UpdateIndexRequest {
  151. // Required. The Index which updates the resource on the server.
  152. Index index = 1 [(google.api.field_behavior) = REQUIRED];
  153. // The update mask applies to the resource.
  154. // For the `FieldMask` definition, see [google.protobuf.FieldMask][google.protobuf.FieldMask].
  155. google.protobuf.FieldMask update_mask = 2;
  156. }
  157. // Runtime operation information for [IndexService.UpdateIndex][google.cloud.aiplatform.v1beta1.IndexService.UpdateIndex].
  158. message UpdateIndexOperationMetadata {
  159. // The operation generic information.
  160. GenericOperationMetadata generic_metadata = 1;
  161. // The operation metadata with regard to Matching Engine Index operation.
  162. NearestNeighborSearchOperationMetadata nearest_neighbor_search_operation_metadata = 2;
  163. }
  164. // Request message for [IndexService.DeleteIndex][google.cloud.aiplatform.v1beta1.IndexService.DeleteIndex].
  165. message DeleteIndexRequest {
  166. // Required. The name of the Index resource to be deleted.
  167. // Format:
  168. // `projects/{project}/locations/{location}/indexes/{index}`
  169. string name = 1 [
  170. (google.api.field_behavior) = REQUIRED,
  171. (google.api.resource_reference) = {
  172. type: "aiplatform.googleapis.com/Index"
  173. }
  174. ];
  175. }
  176. // Runtime operation metadata with regard to Matching Engine Index.
  177. message NearestNeighborSearchOperationMetadata {
  178. message RecordError {
  179. enum RecordErrorType {
  180. // Default, shall not be used.
  181. ERROR_TYPE_UNSPECIFIED = 0;
  182. // The record is empty.
  183. EMPTY_LINE = 1;
  184. // Invalid json format.
  185. INVALID_JSON_SYNTAX = 2;
  186. // Invalid csv format.
  187. INVALID_CSV_SYNTAX = 3;
  188. // Invalid avro format.
  189. INVALID_AVRO_SYNTAX = 4;
  190. // The embedding id is not valid.
  191. INVALID_EMBEDDING_ID = 5;
  192. // The size of the embedding vectors does not match with the specified
  193. // dimension.
  194. EMBEDDING_SIZE_MISMATCH = 6;
  195. // The `namespace` field is missing.
  196. NAMESPACE_MISSING = 7;
  197. }
  198. // The error type of this record.
  199. RecordErrorType error_type = 1;
  200. // A human-readable message that is shown to the user to help them fix the
  201. // error. Note that this message may change from time to time, your code
  202. // should check against error_type as the source of truth.
  203. string error_message = 2;
  204. // Cloud Storage URI pointing to the original file in user's bucket.
  205. string source_gcs_uri = 3;
  206. // Empty if the embedding id is failed to parse.
  207. string embedding_id = 4;
  208. // The original content of this record.
  209. string raw_record = 5;
  210. }
  211. message ContentValidationStats {
  212. // Cloud Storage URI pointing to the original file in user's bucket.
  213. string source_gcs_uri = 1;
  214. // Number of records in this file that were successfully processed.
  215. int64 valid_record_count = 2;
  216. // Number of records in this file we skipped due to validate errors.
  217. int64 invalid_record_count = 3;
  218. // The detail information of the partial failures encountered for those
  219. // invalid records that couldn't be parsed.
  220. // Up to 50 partial errors will be reported.
  221. repeated RecordError partial_errors = 4;
  222. }
  223. // The validation stats of the content (per file) to be inserted or
  224. // updated on the Matching Engine Index resource. Populated if
  225. // contentsDeltaUri is provided as part of [Index.metadata][google.cloud.aiplatform.v1beta1.Index.metadata]. Please note
  226. // that, currently for those files that are broken or has unsupported file
  227. // format, we will not have the stats for those files.
  228. repeated ContentValidationStats content_validation_stats = 1;
  229. }