Method: featureViews.searchNearestEntities

Full name: 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.

Endpoint

post https://{service-endpoint}/v1/{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:

Fields
query object (NearestNeigrQuery)

Required. The query.

returnFullEntity boolean

Optional. If set to true, the full entities (including all vector values and metadata) of the nearest neigrs are returned; otherwise only entity id of the nearest neigrs 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:

Fields
nearestNeigrs object (NearestNeigrs)

The nearest neigrs of the query entity.

JSON representation
{
  "nearestNeigrs": {
    object (NearestNeigrs)
  }
}

NearestNeigrQuery

A query to find a number of similar entities.

Fields
neigrCount 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.

numericFilters[] object (NumericFilter)

Optional. The list of numeric filters.

perCrowdingAttributeNeigrCount integer

Optional. Crowding is a constraint on a neigr list produced by nearest neigr search requiring that no more than sper_crowding_attribute_neigr_count of the k neigrs 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.

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.

embedding object (Embedding)

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

JSON representation
{
  "neigrCount": integer,
  "stringFilters": [
    {
      object (StringFilter)
    }
  ],
  "numericFilters": [
    {
      object (NumericFilter)
    }
  ],
  "perCrowdingAttributeNeigrCount": integer,
  "parameters": {
    object (Parameters)
  },

  // instance
  "entityId": string,
  "embedding": {
    object (Embedding)
  }
  // Union type
}

Embedding

The embedding vector.

Fields
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.

Fields
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

Fields
name string

Required. column name in BigQuery that used as filters.

Value Union type
The type of Value must be consistent for all datapoints with a given name. This is verified at runtime. Value can be only one of the following:
valueInt string (int64 format)

int value type.

valueFloat number

float value type.

valueDouble number

double value type.

op enum (Operator)

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)
}

Operator

Datapoints for which Operator is true relative to the query's value field will be allowlisted.

Enums
OPERATOR_UNSPECIFIEDUnspecified operator.
LESSEntities are eligible if their value is < the query's.
LESS_EQUALEntities are eligible if their value is <= the query's.
EQUALEntities are eligible if their value is == the query's.
GREATER_EQUALEntities are eligible if their value is >= the query's.
GREATEREntities are eligible if their value is > the query's.
NOT_EQUALEntities are eligible if their value is != the query's.

Parameters

Parameters that can be overrided in each query to tune query latency and recall.

Fields
approximateNeigrCandidates integer

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

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
{
  "approximateNeigrCandidates": integer,
  "leafNodesSearchFraction": number
}

NearestNeigrs

Nearest neigrs for one query.

Fields
neigrs[] object (Neigr)

All its neigrs.

JSON representation
{
  "neigrs": [
    {
      object (Neigr)
    }
  ]
}

Neigr

A neigr of the query vector.

Fields
entityId string

The id of the similar entity.

distance number

The distance between the neigr and the query vector.

entityKeyValues object (FetchFeatureValuesResponse)

The attributes of the neigr, 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 (FetchFeatureValuesResponse)
  }
}