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.
Endpoint
posthttps://{endpoint}/v1beta1/{featureView}:searchNearestEntities
Where {service-endpoint}
is one of the supported service endpoints.
Path 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:
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:
The nearest neighbors of the query entity.
JSON representation |
---|
{
"nearestNeighbors": {
object ( |
NearestNeighborQuery
A query to find a number of similar entities.
neighborCount
integer
Optional. The number of similar entities to be retrieved from feature view for each query.
Optional. The list of string filters.
Optional. The list of numeric 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.
Optional. Parameters that can be set to tune query on the fly.
instance
Union type
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.
Optional. The embedding vector that be used for similar search.
JSON representation |
---|
{ "neighborCount": integer, "stringFilters": [ { object ( |
Embedding
The embedding vector.
value[]
number
Optional. Individual value in the embedding.
JSON representation |
---|
{ "value": [ number ] } |
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.
name
string
Required. column names in BigQuery that used as filters.
allowTokens[]
string
Optional. The allowed tokens.
denyTokens[]
string
Optional. The denied tokens.
JSON representation |
---|
{ "name": string, "allowTokens": [ string ], "denyTokens": [ string ] } |
NumericFilter
Numeric filter is used to search a subset of the entities by using boolean rules on numeric columns. For example: Database Point 0: {name: "a" valueInt: 42} {name: "b" valueFloat: 1.0} Database Point 1: {name: "a" valueInt: 10} {name: "b" valueFloat: 2.0} Database Point 2: {name: "a" valueInt: -1} {name: "b" valueFloat: 3.0} Query: {name: "a" valueInt: 12 operator: LESS} // Matches Point 1, 2 {name: "b" valueFloat: 2.0 operator: EQUAL} // Matches Point 1
name
string
Required. column name in BigQuery that used as filters.
Value
Union type
Value
can be only one of the following:int value type.
valueFloat
number
float value type.
valueDouble
number
double value type.
Optional. This MUST be specified for queries and must NOT be specified for database points.
JSON representation |
---|
{
"name": string,
// Value
"valueInt": string,
"valueFloat": number,
"valueDouble": number
// Union type
"op": enum ( |
Operator
Datapoints for which Operator is true relative to the query's value field will be allowlisted.
Enums | |
---|---|
OPERATOR_UNSPECIFIED |
Unspecified operator. |
LESS |
Entities are eligible if their value is < the query's. |
LESS_EQUAL |
Entities are eligible if their value is <= the query's. |
EQUAL |
Entities are eligible if their value is == the query's. |
GREATER_EQUAL |
Entities are eligible if their value is >= the query's. |
GREATER |
Entities are eligible if their value is > the query's. |
NOT_EQUAL |
Entities are eligible if their value is != the query's. |
Parameters
Parameters that can be overrided in each query to tune query latency and recall.
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.
JSON representation |
---|
{ "approximateNeighborCandidates": integer, "leafNodesSearchFraction": number } |
NearestNeighbors
Neighbor
A neighbor of the query vector.
entityId
string
The id of the similar entity.
distance
number
The distance between the neighbor and the query vector.
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.
JSON representation |
---|
{
"entityId": string,
"distance": number,
"entityKeyValues": {
object ( |