For online store instances created for Optimized online serving, 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:
Set up the BigQuery data source to support embeddings by including the
embedding
column. Optionally, include filtering and crowding columns. For more information, see Data source preparation guidelines.Create an online store instance for Optimized online serving..
Specify the
embedding
column while creating the feature view. For more information about how to create a feature view that supports embeddings, see Configure vector retrieval for a feature view.
This page describes how you can do the following:
Before you begin
Authenticate to Vertex AI, unless you've done so already.
To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
For more information, see Authenticate for using REST in the Google Cloud authentication documentation.
Retrieve the public endpoint domain name for the online store
When you create an online store instance for Optimized online serving, 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. - RETURN_FULL_ENTITY: 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 isfalse
. - 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": RETURN_FULL_ENTITY }
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.
- RETURN_FULL_ENTITY: 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 isfalse
. - 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": RETURN_FULL_ENTITY }
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 } ] } }