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

Object contexts let you attach descriptive information as key-value pairs to your Cloud Storage objects. You can embed contexts in your objects to improve how you categorize, track, and search your data. You can apply contexts when you create new objects or add contexts 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: Object contexts help with filtering of object listings, limiting inputs for workloads to only the objects of interest.

  • Interoperability: Object contexts accept string values without predefinition, to support interoperability with object tags from other cloud providers and simplifying migrations.

  • Data persistence: Context data persists across the object's lifecycle. When you copy, rewrite, compose, move, or restore objects, contexts are automatically transferred. Preserving object contexts helps all associated contextual data remain linked to the objects, regardless of any changes to their storage location or state.

  • Identity and Access Management control over context modification: Use Identity and Access Management (IAM) permissions to define who can add, change, or remove contexts to maintain a reliable audit trail.

What's next