GCP: Add gcs.write.object-context.* catalog property support(parity with S3 write.tags)

[revanthgss]

GCS: add gcs.write.object-context.* catalog property support (parity with S3 write.tags)

Closes #16995

Overview

Adds write-time GCS object context annotation support to GCSFileIO, providing parity with
s3.write.tags.* in the AWS module. Object contexts are GCS's equivalent of S3 object tags —
key-value metadata serialized into the upload request and committed atomically with the object,
with no extra API call. Object Contexts are GA as of April 2026.

Changes

GCPProperties

• New constant: GCS_WRITE_OBJECT_CONTEXT_PREFIX = "gcs.write.object-context."
• Constructor parses all properties matching the prefix into an immutable
  Map<String, String> writeObjectContexts, stripping the prefix to yield plain context keys
• New accessor: writeObjectContexts()

GCSOutputStream

• New private method buildBlobInfo(BlobId, GCPProperties) — when writeObjectContexts() is
  non-empty, builds ObjectCustomContextPayload entries and sets them via
  BlobInfo.Builder.setContexts(ObjectContexts) before passing BlobInfo to storage.writer()
• When no contexts are configured, setContexts is never called — zero overhead on the existing path
• All stream mechanics (write, close, getPos) are unchanged

Example usage

spark.sql.catalog.my_catalog.gcs.write.object-context.env=prod
spark.sql.catalog.my_catalog.gcs.write.object-context.team=data-platform
spark.sql.catalog.my_catalog.gcs.write.object-context.iceberg-table=orders

Related

• S3 write-tags: AWS: Add S3 Tagging #4259
• GCS object contexts SDK commit: [googleapis/java-storage@485aefd](googleapis/java-storage@485aefd)
• GCS object context docs: https://cloud.google.com/storage/docs/use-object-contexts

Checklist

• Unit tests added and passing (./gradlew :iceberg-gcp:test)
• Spotless check passing (./gradlew :iceberg-gcp:spotlessCheck)
• google-cloud-storage resolved version confirmed ≥ 2.57
  (./gradlew :iceberg-gcp:dependencyInsight --dependency google-cloud-storage)
• Test File IO changes against a real GCS bucket

AI Disclosure

LLM is used to research the existing S3 implementation and draft the GCS File IO changes and drafting the PR description.

[revanthgss]

@danielcweeks Could you please review this PR?

Thanks.