@@ -46,6 +46,17 @@ service FeatureOnlineStoreService {
4646 };
4747 option (google.api.method_signature ) = "feature_view, data_key" ;
4848 }
49+
50+ // Search the nearest entities under a FeatureView.
51+ // Search only works for indexable feature view; if a feature view isn't
52+ // indexable, returns Invalid argument response.
53+ rpc SearchNearestEntities (SearchNearestEntitiesRequest )
54+ returns (SearchNearestEntitiesResponse ) {
55+ option (google.api.http ) = {
56+ post : "/v1/{feature_view=projects/*/locations/*/featureOnlineStores/*/featureViews/*}:searchNearestEntities"
57+ body : "*"
58+ };
59+ }
4960}
5061
5162// Format of the data in the Feature View.
@@ -120,3 +131,126 @@ message FetchFeatureValuesResponse {
120131 google.protobuf.Struct proto_struct = 2 ;
121132 }
122133}
134+
135+ // A query to find a number of similar entities.
136+ message NearestNeighborQuery {
137+ // The embedding vector.
138+ message Embedding {
139+ // Optional. Individual value in the embedding.
140+ repeated float value = 1 [(google.api.field_behavior ) = OPTIONAL ];
141+ }
142+
143+ // String filter is used to search a subset of the entities by using boolean
144+ // rules on string columns.
145+ // For example: if a query specifies string filter
146+ // with 'name = color, allow_tokens = {red, blue}, deny_tokens = {purple}','
147+ // then that query will match entities that are red or blue, but if those
148+ // points are also purple, then they will be excluded even if they are
149+ // red/blue. Only string filter is supported for now, numeric filter will be
150+ // supported in the near future.
151+ message StringFilter {
152+ // Required. Column names in BigQuery that used as filters.
153+ string name = 1 [(google.api.field_behavior ) = REQUIRED ];
154+
155+ // Optional. The allowed tokens.
156+ repeated string allow_tokens = 2 [(google.api.field_behavior ) = OPTIONAL ];
157+
158+ // Optional. The denied tokens.
159+ repeated string deny_tokens = 3 [(google.api.field_behavior ) = OPTIONAL ];
160+ }
161+
162+ // Parameters that can be overrided in each query to tune query latency and
163+ // recall.
164+ message Parameters {
165+ // Optional. The number of neighbors to find via approximate search before
166+ // exact reordering is performed; if set, this value must be >
167+ // neighbor_count.
168+ int32 approximate_neighbor_candidates = 1
169+ [(google.api.field_behavior ) = OPTIONAL ];
170+
171+ // Optional. The fraction of the number of leaves to search, set at query
172+ // time allows user to tune search performance. This value increase result
173+ // in both search accuracy and latency increase. The value should be between
174+ // 0.0 and 1.0.
175+ double leaf_nodes_search_fraction = 2
176+ [(google.api.field_behavior ) = OPTIONAL ];
177+ }
178+
179+ oneof instance {
180+ // Optional. The entity id whose similar entities should be searched for.
181+ // If embedding is set, search will use embedding instead of
182+ // entity_id.
183+ string entity_id = 1 [(google.api.field_behavior ) = OPTIONAL ];
184+
185+ // Optional. The embedding vector that be used for similar search.
186+ Embedding embedding = 2 [(google.api.field_behavior ) = OPTIONAL ];
187+ }
188+
189+ // Optional. The number of similar entities to be retrieved from feature view
190+ // for each query.
191+ int32 neighbor_count = 3 [(google.api.field_behavior ) = OPTIONAL ];
192+
193+ // Optional. The list of string filters.
194+ repeated StringFilter string_filters = 4
195+ [(google.api.field_behavior ) = OPTIONAL ];
196+
197+ // Optional. Crowding is a constraint on a neighbor list produced by nearest
198+ // neighbor search requiring that no more than
199+ // sper_crowding_attribute_neighbor_count of the k neighbors returned have the
200+ // same value of crowding_attribute. It's used for improving result diversity.
201+ int32 per_crowding_attribute_neighbor_count = 5
202+ [(google.api.field_behavior ) = OPTIONAL ];
203+
204+ // Optional. Parameters that can be set to tune query on the fly.
205+ Parameters parameters = 7 [(google.api.field_behavior ) = OPTIONAL ];
206+ }
207+
208+ // The request message for
209+ // [FeatureOnlineStoreService.SearchNearestEntities][google.cloud.aiplatform.v1.FeatureOnlineStoreService.SearchNearestEntities].
210+ message SearchNearestEntitiesRequest {
211+ // Required. FeatureView resource format
212+ // `projects/{project}/locations/{location}/featureOnlineStores/{featureOnlineStore}/featureViews/{featureView}`
213+ string feature_view = 1 [
214+ (google.api.field_behavior ) = REQUIRED ,
215+ (google.api.resource_reference ) = {
216+ type : "aiplatform.googleapis.com/FeatureView"
217+ }
218+ ];
219+
220+ // Required. The query.
221+ NearestNeighborQuery query = 2 [(google.api.field_behavior ) = REQUIRED ];
222+
223+ // Optional. If set to true, the full entities (including all vector values
224+ // and metadata) of the nearest neighbors are returned; otherwise only entity
225+ // id of the nearest neighbors will be returned. Note that returning full
226+ // entities will significantly increase the latency and cost of the query.
227+ bool return_full_entity = 3 [(google.api.field_behavior ) = OPTIONAL ];
228+ }
229+
230+ // Nearest neighbors for one query.
231+ message NearestNeighbors {
232+ // A neighbor of the query vector.
233+ message Neighbor {
234+ // The id of the similar entity.
235+ string entity_id = 1 ;
236+
237+ // The distance between the neighbor and the query vector.
238+ double distance = 2 ;
239+
240+ // The attributes of the neighbor, e.g. filters, crowding and metadata
241+ // Note that full entities are returned only when "return_full_entity"
242+ // is set to true. Otherwise, only the "entity_id" and "distance" fields
243+ // are populated.
244+ FetchFeatureValuesResponse entity_key_values = 3 ;
245+ }
246+
247+ // All its neighbors.
248+ repeated Neighbor neighbors = 1 ;
249+ }
250+
251+ // Response message for
252+ // [FeatureOnlineStoreService.SearchNearestEntities][google.cloud.aiplatform.v1.FeatureOnlineStoreService.SearchNearestEntities]
253+ message SearchNearestEntitiesResponse {
254+ // The nearest neighbors of the query entity.
255+ NearestNeighbors nearest_neighbors = 1 ;
256+ }
![gcf-owl-bot[bot]](https://avatars.githubusercontent.com/in/99011?v=4&size=40){kind=avatar}
0 commit comments