Object contexts

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

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

Overview

You can attach descriptive information as key-value pairs to your Cloud Storage objects using object contexts. You can embed contexts to improve how you categorize, track, and search your data. You can apply contexts when you create new objects or add them to existing objects.

For example, when you upload an invoice object, you can enrich it with customer_id and payment_status contexts:

{
  "contexts": {
    "custom": {
      "customer_id": {
        "value": "cust-78901"
      },
      "payment_status": {
        "value": "unpaid"
      }
    }
  }
}

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. This keeps all associated contextual data linked to your objects, regardless of any changes to their storage location or state.

  • 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.

Pricing

For more information about the fees for using and storing object contexts, see Cloud Storage pricing.

What's next