Vector Search embeddings with metadata

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

This guide provides information about optional metadata for vector embeddings.Vector Search lets you define metadata for each embedding.

Metadata is non-filterable, arbitrary information that Vector Searchcan store for each embedding. This can provide embeddings with useful contextsuch as:

  • Product details, such as name, price, and an image URL.

  • Descriptions, snippets, dates, and authorship for text embeddings.

  • User information for user embeddings.

  • Coordinates for place embeddings.

Key features and benefits

Features and benefits of using metadata include:

  • Context with results: Information can be provided directly inyour search results, which eliminates the need for separate lookupsand reduces latency.

  • Flexible structure: Metadata is provided as aJSON object,which allows the metadata to be defined as complex, nested data.

  • Non-Filterable: Vector embedding metadata is for storing and retrievingnon-filterable information that's distinct fromrestricts andnumeric_restricts.

  • Efficient updates: Theupdate_mask field lets you specify that APIsonly update metadata to avoid resubmitting embedding vectors.

  • Decoupled Information: Non-filterable information can be separated fromfilterable attributes likerestricts.

  • Streamlined development: Search responses include metadata associatedwith a vector embedding, while reducing the complexity needed for featuressuch as displaying rich search results and performing context-basedpost-processing.

Data format

An optionalembedding_metadata field holds a JSON object thatflexibly associates rich, non-filterable information with embeddings inVector Search. This can streamline applications by returning contextwith results and allows efficient metadata-only updates usingupdate_maskfor theupsertDatapoints API.

Note: Userestricts andnumeric_restricts for filtering data.

Example data point structure:

{"id":"movie_001","embedding":[0.1,0.2,...,0.3],"sparse_embedding":{"values":[-0.4,0.2,-1.3],"dimensions":[10,20,30]},"numeric_restricts":[{'namespace':'year','value_int':2022}],"restricts":[{'namespace':'genre','allow':['action','comedy']}],#---Newembedding_metadatafield---"embedding_metadata":{"title":"Ballet Train","runtime":{"hours":2,"minutes":6},"review_info":{"review":"This movie is fun and...","rotten_potatoes_rating":76}}#------------------------------------},#...otherdatapoints

Ingesting data withembedding_metadata

When adding data points, you can includeembedding_metadata when one of thefollowing actions occurs:

Note:embedding_metadata has a size limit of 2 KB for each datapoint.

Retrievingembedding_metadata during queries

When performing a standard nearest-neighbor search using thefindNeighbors API, theembedding_metadata field for each neighbor isautomatically included in the response ifreturnFullDatapointis set toTrue.

curl

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \"https://${PUBLIC_ENDPOINT_DOMAIN}/v1/projects/${PROJECT_ID}/locations/${LOCATION}/indexEndpoints/${INDEX_ENDPOINT_ID}:findNeighbors" \-d '{deployedIndexId:"${DEPLOYED_INDEX_ID}", "queries":[{datapoint:{"featureVector":"<FEATURE_VECTOR>"}}], returnFullDatapoint:true}'

Updatingembedding_metadata

Update metadata using theupsertDatapoints API and anupdate_maskusing the valueembedding_metadata. Theupdate_mask field might alsoinclude additional mask values. For uses of a field mask, seeUpdate embedding metadata.

Theupdate_mask field helps to ensure that onlyembedding_metadata is updated,avoiding resubmission of restrict and embedding fields.

Note: This can also include existingFieldMask values, such asall_restricts,along withembedding_metadata in the request.

The following example demonstrates how to define and update metadata to create atargetedIndexDatapoint, specifyingupdate_mask, and callingupsertDatapoints.

curl

curl -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`" https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/indexes/${INDEX_ID}:upsertDatapoints \-d '{datapoints:[    {        datapoint_id: "'${DATAPOINT_ID_1}'",        feature_vector: [...],        embedding_metadata:{"title": "updated title", "rating": 4.5, "tags": ["updated", "reviewed"]    }, update_mask: "embedding_metadata"}'

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.