Object contexts

This document describes how object contexts let you associate contextual information with your objects to help you manage and discover data.

To learn how to attach and manage object contexts, see Use object contexts.

Overview

Object contexts let you associate key-value pairs with your Cloud Storage objects to categorize, track, and search your data. You can attach contexts when you create or update objects, or let Google services attach them automatically.

In the objects resource, all object contexts appear under the contexts.custom field. Within contexts.custom, there are two types of contexts:

  • Custom contexts without extended data: Contexts that consist of a key, a string value, and timestamps. You can use these contexts to organize, filter, and track objects across your storage buckets.

  • Custom contexts with extended data (Preview): Contexts that consist of a key, a string value, timestamps, and an optional structured JSON payload. Google services attach these contexts during automated analysis, such as machine learning labeling.

Context components

Each context entry consists of the following components:

  • Key: A unique identifier for the context on the object (up to 256 bytes). Keys starting with google: (for example, google:annotation:face-detector-v1) are reserved for Google-generated contexts. You can't create or update contexts with the google: prefix. To remove contexts with the google: prefix, you must discard them by using the dropContextGroups parameter during a rewrite operation.

  • Value: A string value associated with the key (up to 256 bytes) to control workflows and filter object listings.

  • Timestamps: Output-only timestamps (createTime and updateTime) indicating when the context was created and last modified.

  • Extended data (Preview): An optional structured JSON payload (up to 128 KiB) containing detailed information, such as machine learning labels or automated annotations.

Standard get and list requests return context keys, values, and timestamps. If a context has extended data, standard requests include an extendedDataTypeUrl field (type.googleapis.com/google.protobuf.Struct). To retrieve the full extended data payload, use the viewFullContext method (Preview).

For example, an object with custom contexts, both with and without extended data, has the following JSON representation:

{
  "contexts": {
    "custom": {
      "customer_id": {
        "value": "cust-78901",
        "createTime": "2026-01-01T00:00:00.000Z",
        "updateTime": "2026-01-01T00:00:00.000Z"
      },
      "payment_status": {
        "value": "unpaid",
        "createTime": "2026-01-01T00:00:00.000Z",
        "updateTime": "2026-01-01T00:00:00.000Z"
      },
      "google:annotation:face-detector-v1": {
        "value": "SUCCESS",
        "createTime": "2026-09-29T17:20:00.000Z",
        "updateTime": "2026-09-29T17:20:00.000Z",
        "extendedDataTypeUrl": "type.googleapis.com/google.protobuf.Struct"
      }
    }
  }
}

In this example:

  • customer_id and payment_status are custom contexts without extended data.
  • google:annotation:face-detector-v1 is a Google-generated custom context with extended data.

All contexts can be retrieved and used to filter object listings by their keys and values.

Use cases for object contexts

Object contexts let you classify, track, and enrich your data. The following sections describe the scenarios for using object contexts to manage different types of information.

Group and classify objects

Classify and organize objects across buckets and projects. Use contexts to tag data by attributes, such as dataset origin, ownership, or cost center.

  • Example 1: Assign the context data_classification: PII to objects containing personally identifiable information (PII) so that compliance policies can handle them.

  • Example 2: Group new training images during ingestion by assigning batch_id: 2025_Q4_Model_Run context to enable efficient model testing and retrieval.

Track workflows

To optimize custom workflows and prevent redundant operations, embed workflow state information directly onto objects to track their journey through a processing pipeline.

  • Example 1: Use processing_status: awaiting_review to indicate objects pending external release approval.

  • Example 2: Use processed_by: analytics_pipeline to prevent your custom data processing service from re-scanning files that have already completed a stage.

Enrich objects with application-specific context

Attach specific information about an application or business process to provide additional context and data lineage for each object.

  • Example 1: For a satellite image, record capture details, such as capture_angle: 45deg_NW, or track the file's history with lineage: ingested_from_s3.

  • Example 2: Embed details about a file's contents, such as document_type: service_manual and vehicle_model: f250.

Benefits of object contexts

Object contexts extend the capabilities of your Cloud Storage objects. By associating custom key-value pairs directly with stored objects, you can achieve the following benefits:

  • Data discovery: Filter object listings to limit inputs for your workloads to only the objects of interest.

  • Interoperability: Support interoperability with object tags from other cloud providers and help simplify migrations, as object contexts accept string values without predefinition.

  • Data persistence: Preserve context data across the object's lifecycle. When you copy, rewrite, compose, move, or restore objects, contexts are automatically transferred. You can also selectively discard contexts during copy, rewrite, and compose operations using the dropContextGroups query parameter (for example, dropContextGroups=custom) if you want to prevent them from carrying over to the destination object.

  • Context modification control: Define who can add, change, or remove contexts using Identity and Access Management (IAM) permissions to maintain an audit trail.

  • Batch operations: Manage object contexts in bulk across billions of objects using storage batch operations.

  • Bulk analysis with BigQuery: Query and analyze object contexts and extended data (such as labels, face detections, and bounding boxes) across your storage buckets using the Object Contexts Catalog view (object_contexts_catalog_view) in Storage Insights datasets.

Pricing

For pricing details, see Cloud Storage pricing.

What's next