Method: projects.locations.featureOnlineStores.featureViews.searchNearestEntities

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}/v1/{featureView}:searchNearestEntities

Where {service-endpoint} is one of the supported service endpoints.

Path parameters

Parameters
featureView

string

Required. FeatureView resource format projects/{project}/locations/{location}/featureOnlineStores/{featureOnlineStore}/featureViews/{featureView}

Request body

The request body contains data with the following structure:

JSON representation 
{
  "query": {
    object (NearestNeighborQuery)
  },
  "returnFullEntity": boolean
}
Fields
query

object (NearestNeighborQuery)

Required. The query.
returnFullEntity

boolean

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 (NearestNeighbors)
  }
}
Fields
nearestNeighbors

object (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 (StringFilter)
    }
  ],
  "perCrowdingAttributeNeighborCount": integer,
  "parameters": {
    object (Parameters)
  },

  // Union field instance can be only one of the following:
  "entityId": string,
  "embedding": {
    object (Embedding)
  }
  // End of list of possible types for union field instance.
}
Fields
neighborCount

integer

Optional. The number of similar entities to be retrieved from feature view for each query.
stringFilters[]

object (StringFilter)

Optional. The list of string filters.
perCrowdingAttributeNeighborCount

integer

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

object (Parameters)

Optional. Parameters that can be set to tune query on the fly.

Union field instance.

instance can be only one of the following:
entityId

string

Optional. The entity id whose similar entities should be searched for. If embedding is set, search will use embedding instead of entityId.
embedding

object (Embedding)

Optional. The embedding vector that be used for similar search.

Embedding

The embedding vector.

JSON representation 
{
  "value": [
    number
  ]
}
Fields
value[]

number

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

string

Required. column names in BigQuery that used as filters.
allowTokens[]

string

Optional. The allowed tokens.
denyTokens[]

string

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

integer

Optional. The number of neighbors to find via approximate search before exact reordering is performed; if set, this value must be > neighborCount.
leafNodesSearchFraction

number

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 (Neighbor)
    }
  ]
}
Fields
neighbors[]

object (Neighbor)

All its neighbors.

Neighbor

A neighbor of the query vector.

JSON representation 
{
  "entityId": string,
  "distance": number,
  "entityKeyValues": {
    object (FetchFeatureValuesResponse)
  }
}
Fields
entityId

string

The id of the similar entity.
distance

number

The distance between the neighbor and the query vector.
entityKeyValues

object (FetchFeatureValuesResponse)

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.