Search the nearest entities under a FeatureView. Search only works for indexable feature view; if a feature view isn't indexable, returns Invalid argument response.
HTTP request
POST https://{service-endpoint}/v1beta1/{featureView}:searchNearestEntities
Where {service-endpoint}
is one of the supported service endpoints.
Path parameters
Parameters | |
---|---|
featureView |
Required. FeatureView resource format |
Request body
The request body contains data with the following structure:
JSON representation |
---|
{
"query": {
object ( |
Fields | |
---|---|
query |
Required. The query. |
returnFullEntity |
Optional. If set to true, the full entities (including all vector values and metadata) of the nearest neighbors are returned; otherwise only entity id of the nearest neighbors will be returned. Note that returning full entities will significantly increase the latency and cost of the query. |
Response body
Response message for FeatureOnlineStoreService.SearchNearestEntities
If successful, the response body contains data with the following structure:
JSON representation |
---|
{
"nearestNeighbors": {
object ( |
Fields | |
---|---|
nearestNeighbors |
The nearest neighbors of the query entity. |
Authorization scopes
Requires the following OAuth scope:
https://www.googleapis.com/auth/cloud-platform
For more information, see the Authentication Overview.
IAM Permissions
Requires the following IAM permission on the featureView
resource:
aiplatform.featureViews.searchNearestEntities
For more information, see the IAM documentation.
NearestNeighborQuery
A query to find a number of similar entities.
JSON representation |
---|
{ "neighborCount": integer, "stringFilters": [ { object ( |
Fields | |
---|---|
neighborCount |
Optional. The number of similar entities to be retrieved from feature view for each query. |
stringFilters[] |
Optional. The list of string filters. |
perCrowdingAttributeNeighborCount |
Optional. Crowding is a constraint on a neighbor list produced by nearest neighbor search requiring that no more than sper_crowding_attribute_neighbor_count of the k neighbors returned have the same value of crowdingAttribute. It's used for improving result diversity. |
parameters |
Optional. Parameters that can be set to tune query on the fly. |
Union field
|
|
entityId |
Optional. The entity id whose similar entities should be searched for. If embedding is set, search will use embedding instead of entityId. |
embedding |
Optional. The embedding vector that be used for similar search. |
Embedding
The embedding vector.
JSON representation |
---|
{ "value": [ number ] } |
Fields | |
---|---|
value[] |
Optional. Individual value in the embedding. |
StringFilter
String filter is used to search a subset of the entities by using boolean rules on string columns. For example: if a query specifies string filter with 'name = color, allowTokens = {red, blue}, denyTokens = {purple}',' then that query will match entities that are red or blue, but if those points are also purple, then they will be excluded even if they are red/blue. Only string filter is supported for now, numeric filter will be supported in the near future.
JSON representation |
---|
{ "name": string, "allowTokens": [ string ], "denyTokens": [ string ] } |
Fields | |
---|---|
name |
Required. column names in BigQuery that used as filters. |
allowTokens[] |
Optional. The allowed tokens. |
denyTokens[] |
Optional. The denied tokens. |
Parameters
Parameters that can be overrided in each query to tune query latency and recall.
JSON representation |
---|
{ "approximateNeighborCandidates": integer, "leafNodesSearchFraction": number } |
Fields | |
---|---|
approximateNeighborCandidates |
Optional. The number of neighbors to find via approximate search before exact reordering is performed; if set, this value must be > neighborCount. |
leafNodesSearchFraction |
Optional. 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. |
NearestNeighbors
Nearest neighbors for one query.
JSON representation |
---|
{
"neighbors": [
{
object ( |
Fields | |
---|---|
neighbors[] |
All its neighbors. |
Neighbor
A neighbor of the query vector.
JSON representation |
---|
{
"entityId": string,
"distance": number,
"entityKeyValues": {
object ( |
Fields | |
---|---|
entityId |
The id of the similar entity. |
distance |
The distance between the neighbor and the query vector. |
entityKeyValues |
The attributes of the neighbor, e.g. filters, crowding and metadata Note that full entities are returned only when "returnFullEntity" is set to true. Otherwise, only the "entityId" and "distance" fields are populated. |