Search using embeddings

If you've configured your online store to support embeddings, you can perform a vector similarity search to retrieve a list of semantically similar or related entities, also called approximate nearest neighbors. You can search based on either an entity ID or an embedding.

To search for approximate nearest neighbors, you need to first do the following:

This page describes how you can do the following:

Retrieve the public endpoint domain name for the online store

When you create and configure an online store instance for embedding management, Vertex AI Feature Store generates a public endpoint domain name for the online store. Before you can start searching for nearest neighbors from a feature view in the online store, you must retrieve the public endpoint domain name from the online store details.

Use the following sample to retrieve the details of an online store instance.

REST

To retrieve the details of a FeatureOnlineStore resource in your project, send a GET request by using the featureOnlineStores.get method.

Before using any of the request data, make the following replacements:

  • LOCATION_ID: Region where the online store is located, such as us-central1.
  • PROJECT_ID: Your project ID.
  • FEATUREONLINESTORE_NAME: The name of the online store instance.

HTTP method and URL: 

GET https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME

To send your request, choose one of these options:

curl

Execute the following command: 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME"

PowerShell

Execute the following command: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME_1",
  "createTime": "2023-09-06T23:25:04.256314Z",
  "updateTime": "2023-09-06T23:25:04.256314Z",
  "etag": "AMEw9yMgoV0bAsYuKwVxz4Y7lOmxV7riNVHg217KaQAKORqvdqGCrQ1DIt8yHgoGXf8=",
  "state": "STABLE",
  "dedicatedServingEndpoint": {
    "publicEndpointDomainName": "PUBLIC_ENDPOINT_DOMAIN_NAME"
  },
  "optimized": {}
}

You'll need the PUBLIC_ENDPOINT_DOMAIN_NAME from the response to retrieve approximate nearest neighbors in the following step.

Retrieve approximate nearest neighbors of an embedding

Use the following sample to use an embedding to perform search for semantically related entities by specifying an embedding.

REST

To search nearest neighbors for an embedding, send a POST request by using the featureViews.searchNearestEntities method.

Before using any of the request data, make the following replacements:

  • PUBLIC_ENDPOINT_DOMAIN_NAME: The public endpoint domain name for the online store instance that you retrieved using the featureOnlineStores.get method.
  • PROJECT_ID: Your project ID.
  • LOCATION_ID: Region where the online store instance is located, such as us-central1.
  • FEATUREONLINESTORE_NAME: The name of the online store instance containing the feature view where you want to search for approximate nearest neighbor matches.
  • FEATUREVIEW_NAME: The name of the feature view where you want to search for approximate nearest neighbor matches.
  • EMBEDDING: Embedding for which you want to retrieve approximate nearest neighbor matches. An embedding is represented by an array of double values.
  • BOOLEAN: Optional: Specify whether you want to include or exclude the features for the entities in the response. To include the features along with the entities in the response, enter true. The default value is false.
  • NEIGHBOR_COUNT: Number of approximate nearest neighbors you want to retrieve.

HTTP method and URL: 

POST https://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities

Request JSON body: 

{
  "query": {
    "embedding": {
      "value": EMBEDDING
    },
    "neighbor_count": NEIGHBOR_COUNT
  },
  "return_full_entity": BOOLEAN
}

To send your request, choose one of these options:

curl

Save the request body in a file named request.json, and execute the following command: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities"

PowerShell

Save the request body in a file named request.json, and execute the following command: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "nearestNeighbors": {
    "neighbors": [
    {
      "entityId": "305281",
      "distance": -41.115459442138672
    },
    {
      "entityId": "80280",
      "distance": -38.703567504882812
    },
    {
      "entityId": "80280",
      "distance":-38.703567504882812
    },
    {
      "entityId": "903779",
      "distance": -38.214759826660156
    },
    {
      "entityId": "1008145",
      "distance": -36.271354675292969
    },
    {
      "entityId": "606431",
      "distance": -34.791431427001953
    } ]
  }
}

Retrieve approximate nearest neighbors of an entity

Use the following sample to use an embedding to perform search for semantically related entities by specifying an entity ID.

REST

To search nearest neighbors for an entity ID, send a POST request by using the featureViews.searchNearestEntities method.

Before using any of the request data, make the following replacements:

  • PUBLIC_ENDPOINT_DOMAIN_NAME: The public endpoint domain name for the online store instance that you retrieved using the featureOnlineStores.get method.
  • PROJECT_ID: Your project ID.
  • LOCATION_ID: Region where the online store instance is located, such as us-central1.
  • FEATUREONLINESTORE_NAME: The name of the online store instance containing the feature view where you want to search for approximate nearest neighbor matches.
  • FEATUREVIEW_NAME: The name of the feature view where you want to search for approximate nearest neighbor matches.
  • ENTITY_ID: Entity ID of the entity for which you want to retrieve approximate nearest neighbor matches.
  • BOOLEAN: Optional: Specify whether you want to include or exclude the features for the entities in the response. To include the features along with the entities in the response, enter true. The default value is false.
  • NEIGHBOR_COUNT: Number of approximate nearest neighbors you want to retrieve.

HTTP method and URL: 

POST https://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities

Request JSON body: 

{
  "query": {
    "entity_id": ENTITY_ID,
    "neighbor_count": NEIGHBOR_COUNT
  },
  "return_full_entity": BOOLEAN
}

To send your request, choose one of these options:

curl

Save the request body in a file named request.json, and execute the following command: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities"

PowerShell

Save the request body in a file named request.json, and execute the following command: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "nearestNeighbors": {
    "neighbors": [
    {
      "entityId": "305281",
      "distance": -41.115459442138672
    },
    {
      "entityId": "80280",
      "distance": -38.703567504882812
    },
    {
      "entityId": "80280",
      "distance":-38.703567504882812
    },
    {
      "entityId": "903779",
      "distance": -38.214759826660156
    },
    {
      "entityId": "1008145",
      "distance": -36.271354675292969
    },
    {
      "entityId": "606431",
      "distance": -34.791431427001953
    } ]
  }
}