Batch ingest feature values

Batch ingestion lets you ingest feature values in bulk from a valid data source. For each request, you can import values for up to 100 features for a single entity type. Note that you can only have one batch ingestion job running per entity type to avoid any collisions.

In a batch ingestion request, specify the location of your source data and how it maps to features in your featurestore. Because each batch ingestion request is for a single entity type, your source data must also be for a single entity type.

After the import has successfully completed, feature values are available to subsequent read operations.

Ingestion job performance

Vertex AI Feature Store provides high throughput ingestion, but the minimum latency can take a few minutes. Each request to Vertex AI Feature Store starts a job to complete the work. An ingestion job takes a few minutes to complete even if you are ingesting a single record.

If you want to make adjustments to how a job performs, change the following two variables:

  • The number of featurestore online serving nodes.
  • The number of workers used for the ingestion job. Workers process and write data into the featurestore.

The recommended number of workers is one worker for every 10 online serving nodes on the featurestore. You can go higher if the online serving load is low. You can specify a maximum of 100 workers. For more guidance, see monitor and tune resources accordingly to optimize batch ingestion.

If the online serving cluster is under-provisioned, the ingestion job might fail. In the event of a failure, retry the import request when the online serving load is low, or increase the node count of your featurestore and then retry the request.

If the featurestore doesn't have an online store (zero online serving nodes), the ingestion job writes only to the offline store, and the performance of the job depends solely on the number of ingestion workers.

Data consistency

Inconsistencies can be introduced if the source data was modified during an import. Check to be sure that any source data modification are complete before you start an ingestion job. Also, duplicate features values can result in different values being served between online and batch requests. Check that you have one feature value for each entity ID and timestamp pair.

If an import operation fails, the featurestore might only have partial data, which can lead to inconsistent values being returned between online and batch serving requests. To avoid this inconsistency, retry the same import request again and wait until the request successfully completes.

Null/NaN values and empty arrays

For scalar null values, Vertex AI Feature Store ignores them during ingestion, such as an empty value in a CSV column. Vertex AI Feature Store doesn't support non-scalar null values like a null value in an array. If your source data for a non-scalar feature has an empty array or a null value, these values are skipped. At serving time, Vertex AI Feature Store returns the previous non-null value or null if there is no previous value.

Vertex AI Feature Store supports and ingests NaN (Not a Number) values for both scalars and non-scalars. For example, you can write NaN to represent a NaN value in a CSV file. For both online and batch serving, Vertex AI Feature Store returns NaN for NaN values.

Batch ingestion

Import values in bulk into a featurestore for one or more features of a single entity type.

Web UI

  1. In the Vertex AI section of the Google Cloud console, go to the Features page.

    Go to the Features page

  2. Select a region from the Region drop-down list.
  3. In the features table, view the Entity type column and find the entity type that contains the features that you want to ingest values for.
  4. Click the name of the entity type.
  5. From the action bar, click Ingest values.
  6. For Data source, select Cloud Storage for AVRO and CSV files or BigQuery table.
    • For Cloud Storage, specify the path and name of your file.
    • For BigQuery, browse and select a table to use, which takes the following form: PROJECT_ID.DATASET_ID.TABLE_ID.
  7. Click Continue.
  8. For Map column to features, specify which columns in your source data map to entities and features in your featurestore.
    1. Specify the column name in your source data that contains the entity IDs.
    2. For the timestamp, you can specify a timestamp column stored your source data or specify a single timestamp that will be associated with all feature values that you ingest.
    3. In the list of features, enter the source data column name that maps to each feature. By default, Vertex AI Feature Store assumes the feature name and column name match.
  9. Click Ingest.


To ingest feature values for existing features, send a POST request by using the featurestores.entityTypes.importFeatureValues method. Note that if the names of the source data columns and the destination feature IDs are different, include the sourceField parameter.

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

  • LOCATION: Region where the featurestore is created. For example, us-central1.
  • PROJECT: Your project ID.
  • FEATURESTORE_ID: ID of the featurestore.
  • ENTITY_TYPE_ID: ID of the entity type.
  • ENTITY_SOURCE_COLUMN_ID: ID of source column that contains entity IDs.
  • FEATURE_TIME_ID: ID of source column that contains the feature timestamps for the feature values.
  • FEATURE_ID: ID of an existing feature in the featurestore to import values for.
  • FEATURE_SOURCE_COLUMN_ID: ID of source column that contain feature values for the entities.
  • SOURCE_DATA_DETAILS: The source data format and location, such as "bigquerySource": { "inputUri": "bq://test.dataset.sourcetable" } for a BigQuery table.
  • WORKER_COUNT: The number of workers to use to write data to the featurestore.

HTTP method and URL:


Request JSON body:

  "entityIdField": "ENTITY_SOURCE_COLUMN_ID",
  "featureTimeField": "FEATURE_TIME_ID",
  "featureSpecs": [{
    "id": "FEATURE_ID",
    "sourceField": "FEATURE_SOURCE_COLUMN_ID"
  "workerCount": WORKER_COUNT

To send your request, choose one of these options:


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

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \


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

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

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "" | Select-Object -Expand Content

You should see output similar to the following. You can use the OPERATION_ID in the response to get the status of the operation.

  "name": "projects/PROJECT_NUMBER/locations/LOCATION/featurestores/FEATURESTORE_ID/entityTypes/ENTITY_TYPE_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "",
    "genericMetadata": {
      "createTime": "2021-03-02T00:04:13.039166Z",
      "updateTime": "2021-03-02T00:04:13.039166Z"


To learn how to install and use the client library for Vertex AI, see Vertex AI client libraries. For more information, see the Vertex AI Python API reference documentation.

import datetime
from typing import List, Union

from import aiplatform

def import_feature_values_sample(
    project: str,
    location: str,
    entity_type_id: str,
    featurestore_id: str,
    feature_ids: List[str],
    feature_time: Union[str, datetime.datetime],
    gcs_source_uris: Union[str, List[str]],
    gcs_source_type: str,

    aiplatform.init(project=project, location=location)

    my_entity_type = aiplatform.featurestore.EntityType(
        entity_type_name=entity_type_id, featurestore_id=featurestore_id


Additional languages

You can install and use the following Vertex AI client libraries to call the Vertex AI API. Cloud Client Libraries provide an optimized developer experience by using each supported language's natural conventions and styles.

View ingestion jobs

Use the console to view batch ingestion jobs in a Google Cloud project.

Web UI

  1. In the Vertex AI section of the Google Cloud console, go to the Features page.

    Go to the Features page

  2. Select a region from the Region drop-down list.
  3. From the action bar, click View ingestion jobs to list ingestion jobs for all featurestores.
  4. Click the ID of an ingestion job to view its details such as its data source, number of ingested entities, and number of ingested feature values.

Overwrite existing data in a featurestore

You can re-import values to overwrite existing feature values if they both have the same timestamps. You don't need to delete existing feature values first. For example, you might rely on an underlying source data that was recently changed. To keep your featurestore consistent with that underlying data, import your feature values again. If you have mismatched timestamps, the imported values are considered unique and the old values continue to exist (they aren't overwritten).

To ensure consistency between online and batch serving requests, wait until the ingestion job is complete before making any serving requests.

Backfill historical data

If you're backfilling data, where you're ingesting past feature values, disable online serving for your ingestion job. Online serving is for serving the latest feature values only, which backfilling doesn't include. Disabling online serving is useful because you eliminate any load on your online serving nodes and increase throughput for your ingestion job, which can decrease its completion time.

You can disable online serving for ingestion jobs when you use the API or client libraries. For more information, see the disableOnlineServing field for the importFeatureValue method.

What's next