Serve feature values

Vertex AI Feature Store lets you online serve feature values from a feature view within an online store. For example, you can serve feature values from a feature view for online predictions. A feature view must be synced at least once before you can online serve features from that feature.

If the feature view is defined based on feature groups and features, Vertex AI Feature Store fetches the latest feature values corresponding to a specific entity ID. If there are multiple records with the same value in the ID column, Vertex AI Feature Store fetches the most recent non-null feature values, based on the feature_timestamp column.

If the feature view is directly associated with a BigQuery data source without associating feature groups and features, then Vertex AI Feature Store fetches all the feature values from the data source. In this case, every row in the data source must contain a unique ID.

You can only serve feature values from one ID per request.

Depending on the type of online serving configured for your online store, you can serve feature values in one of the following ways:

• Fetch feature values using Bigtable online serving: Choose this option only if the online store is configured for Bigtable online serving.

• Fetch feature values using Optimized online serving with a public endpoint: Choose this option only if the online store is configured for Optimized online serving from a public endpoint.

• Fetch feature values using Optimized online serving with a Private Service Connect endpoint: Choose this option only if the online store is configured for Optimized online serving from a dedicated serving endpoint over Private Service Connect.

Fetch feature values using Bigtable online serving

Use the following sample to fetch feature values based on a specific entity ID using Bigtable online serving.

REST

To fetch all the latest feature values for a specific entity ID from a FeatureView instance, send a POST request by using the featureViews.fetchFeatureValues 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 containing the feature view.
• FEATUREVIEW_NAME: The name of the feature view from which you want to serve feature values.
• ENTITY_ID: The value of the ID column in the feature record from which you want to serve the latest feature values.
• FORMAT: Optional: The format in which you want to fetch the feature values. Supported formats include JSON key-value pair and proto Struct formats.

HTTP method and URL:

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:fetchFeatureValues

Request JSON body:

{
  data_key: "ENTITY_ID",
  data_format: "FORMAT"
}

To send your request, choose one of these options:

curl

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

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://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:fetchFeatureValues"

PowerShell

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

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://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:fetchFeatureValues" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

key_values {
  features {
    value {
      int64_value: 258348
    }
    name: "feature_0"
  }
  features {
    value {
      double_value: 0.96300036744534068
    }
    name: "feature_1"
  }
  features {
    value {
      double_value: 0.42787383695351083
    }
    name: "feature_2"
  }
  features {
    value {
      double_value: 0.12219888824743128
    }
    name: "feature_3"
  }
  features {
    value {
      double_value: 0.037523154697944622
    }
    name: "feature_4"
  }
  features {
    value {
      double_value: 0.1766952509448767
    }
    name: "feature_5"
  }
}

Python

Note: You'll need to install or upgrade to the latest version of the Python SDK to complete this step. To do this, run the following command:
pip3 install --upgrade --quiet google-cloud-aiplatform.
To learn more about online serving using the Python SDK, see the Online feature serving and fetching of BigQuery data with Bigtable online serving notebook tutorial

Use the following sample to fetch feature values based on a specific entity ID using Bigtable online serving.

from google.cloud.aiplatform_v1 import FeatureOnlineStoreServiceClient
from google.cloud.aiplatform_v1.types import feature_online_store_service as feature_online_store_service_pb2

data_client = FeatureOnlineStoreServiceClient(
  client_options={"api_endpoint": f"LOCATION_ID-aiplatform.googleapis.com"}
)
data_client.fetch_feature_values(
  request=feature_online_store_service_pb2.FetchFeatureValuesRequest(
    feature_view=f"projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME",
    data_key=feature_online_store_service_pb2.FeatureViewDataKey(key="ENTITY_ID"),
    data_format=feature_online_store_service_pb2.FeatureViewDataFormat.FORMAT,
  )
)

Replace the following:

• 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 containing the feature view.

• FEATUREVIEW_NAME: The name of the feature view from which you want to serve feature values.

• ENTITY_ID: The value of the ID column in the feature record from which you want to serve the latest feature values.

• FORMAT: Optional: The format in which you want to fetch the feature values. Supported formats include JSON KEY_VALUE pair and proto PROTO_STRUCT formats.

Fetch feature values using Optimized online serving from a public endpoint

If you've configured your online store instance to serve feature values using Optimized online serving from a public endpoint, then you need to perform the following steps to fetch feature values from a feature view within the online store:

1. Retrieve the public endpoint domain name for the FeatureOnlineStore instance.

2. Fetch feature values from an entity ID using the public endpoint domain name.

Retrieve the public endpoint domain name for the online store

When you create and configure an online store instance for Optimized online serving with a public endpoint, Vertex AI Feature Store generates the public endpoint domain name for the online store. Before you can start serving feature values from a feature view in the online store, you need to 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

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

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

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

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 fetch feature values in the following step.

Fetch feature values from an entity ID

After you retrieve the public endpoint domain name for the online store instance, use the following sample to fetch feature values for a specific entity ID using Optimized online serving.

REST

To fetch all the latest feature values for a specific entity ID from a FeatureView instance, send a POST request by using the featureViews.fetchFeatureValues 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.
• 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 containing the feature view.
• FEATUREVIEW_NAME: The name of the feature view from which you want to serve feature values.
• ENTITY_ID: The value of the ID column in the feature record from which you want to serve the latest feature values.
• FORMAT: Optional: The format in which you want to fetch the feature values. Supported formats include JSON key-value pair and proto Struct formats.

HTTP method and URL:

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

Request JSON body:

{
  id: "ENTITY_ID",
  data_format: "FORMAT"
}

To send your request, choose one of these options:

curl

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

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:fetchFeatureValues"

PowerShell

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

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:fetchFeatureValues" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

key_values {
  features {
    value {
      int64_value: 258348
    }
    name: "feature_0"
  }
  features {
    value {
      double_value: 0.96300036744534068
    }
    name: "feature_1"
  }
  features {
    value {
      double_value: 0.42787383695351083
    }
    name: "feature_2"
  }
  features {
    value {
      double_value: 0.12219888824743128
    }
    name: "feature_3"
  }
  features {
    value {
      double_value: 0.037523154697944622
    }
    name: "feature_4"
  }
  features {
    value {
      double_value: 0.1766952509448767
    }
    name: "feature_5"
  }
}

Python

Note: You'll need to install or upgrade to the latest version of the Python SDK to complete this step. To do this, run the following command:
pip3 install --upgrade --quiet google-cloud-aiplatform.
To learn more about online serving using the Python SDK, see the Online feature serving and fetching of BigQuery data with Optimized online serving notebook tutorial.

Use the following sample to fetch feature values based on a specific entity ID using Optimized online serving.

from google.cloud.aiplatform_v1 import FeatureOnlineStoreServiceClient
from google.cloud.aiplatform_v1.types import feature_online_store_service as feature_online_store_service_pb2

data_client = FeatureOnlineStoreServiceClient(
  client_options={"api_endpoint": f"PUBLIC_ENDPOINT_DOMAIN_NAME"}
)
data_client.fetch_feature_values(
  request=feature_online_store_service_pb2.FetchFeatureValuesRequest(
    feature_view=f"projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME",
    id=f"ENTITY_ID",
    format=feature_online_store_service_pb2.FetchFeatureValuesRequest.Format.FORMAT,
  )
)

Replace the following:

• PUBLIC_ENDPOINT_DOMAIN_NAME: The public endpoint domain name for the online store instance that you retrieved using the featureOnlineStores.get method.

• 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 containing the feature view.

• FEATUREVIEW_NAME: The name of the feature view from which you want to serve feature values.

• ENTITY_ID: The value of the ID column in the feature record from which you want to serve the latest feature values.

• FORMAT: Optional: The format in which you want to fetch the feature values. Supported formats include JSON KEY_VALUE pair and proto PROTO_STRUCT formats.

Note: If you encounter a serving error following a failed sync, contact Support.

Fetch feature values using Optimized online serving from a Private Service Connect endpoint

If you've configured your online store instance to serve feature values using Optimized online serving from a Private Service Connect endpoint, then you need to perform the following steps to fetch feature values from a feature view within the online store:

1. Retrieve the Private Service Connect configuration for the FeatureOnlineStore instance.

2. Add an endpoint for Private Service Connect to your network configuration.

3. Connect to the Private Service Connect endpoint over gRPC.

4. Fetch feature values from an entity ID.

Retrieve the service attachment string for the online store

When you create and configure an online store instance for Optimized online serving with a Private Service Connect endpoint, Vertex AI Feature Store generates a service attachment string that you can use to set up the Private Service Connect endpoint. You can retrieve the service attachment string 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

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

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

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

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": {
    "privateServiceConnectConfig": {
      "enablePrivateServiceConnect": "true",
      "projectAllowlist": [
        "PROJECT_NAME"
      ]
    },
    serviceAttachment: "SERVICE_ATTACHMENT_STRING"
  },
  "optimized": {}
}

You'll need the SERVICE_ATTACHMENT_STRING from the response to fetch feature values in the following step.

Add an endpoint for Private Service Connect

To add a Private Service Connect endpoint for Optimized online serving to your network configuration, perform the following steps:

1. On the Google Cloud console, select the project containing the online store instance.

2. Create an endpoint for Private Service Connect by specifying the SERVICE_ATTACHMENT_STRING as the Target service. For information about how to create an endpoint for Private Service Connect, see Create an endpoint.

After you create the endpoint, it appears in the Connected endpoints tab on the Private Service Connect page. The IP address of the endpoint appears in the IP addresses column.

Go to the Connected endpoints tab

You'll need to use this IP address to connect to the endpoint for your online store instance to the Private Service Connect endpoint over gRPC in the following step.

Connect to the Private Service Connect endpoint over gRPC

Note: You'll need to install or upgrade to the latest version of the Python SDK to complete this step. To do this, run the following command:
pip3 install --upgrade --quiet google-cloud-aiplatform

Use the following code sample to connect to the Private Service Connect endpoint created for your online store over gRPC.

Python

from google.cloud.aiplatform_v1 import FeatureOnlineStoreServiceClient
from google.cloud.aiplatform_v1.services.feature_online_store_service.transports.grpc import FeatureOnlineStoreServiceGrpcTransport
import grpc

data_client = FeatureOnlineStoreServiceClient(
  transport = FeatureOnlineStoreServiceGrpcTransport(
    # Add the IP address of the Endpoint you just created.
    channel = grpc.insecure_channel("ENDPOINT_IP:10002")
  )
)

Replace the following:

• ENDPOINT_IP: The IP address of the endpoint in the IP addresses column on the Private Service Connect page.

Fetch feature values from an entity ID

After you've connected to the Private Service Connect endpoint over gRPC, use the following sample to fetch feature values for a specific entity ID using Optimized online serving.

Python

data_client.fetch_feature_values(
  feature_view=f"projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME", id=ENTITY_ID)

Replace the following:

• 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 containing the feature view.

• FEATUREVIEW_NAME: The name of the feature view from which you want to serve feature values.

• ENTITY_ID: The value of the ID column in the feature record from which you want to serve the latest feature values.

• FORMAT: Optional: The format in which you want to fetch the feature values. Supported formats include JSON key-value pair and proto Struct formats.

Note: If you encounter a serving error following a failed sync, contact Support.

What's next

• Learn how to sync data for a feature view.

• Learn how to update an online store.