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 @talatuyarer Could you please review this PR?

Thanks.

[github-actions]

This pull request has been marked as stale due to 30 days of inactivity. It will be closed in 1 week if no further activity occurs. If you think that’s incorrect or this pull request requires a review, please simply write any comment. If closed, you can revive the PR at any time and @mention a reviewer or discuss it on the dev@iceberg.apache.org list. Thank you for your contributions.

[revanthgss]

Marking as not stale.

[revanthgss]

@nastra @talatuyarer Could you please take a look at this PR? Let me know if you have any concerns.

Thanks.

[talatuyarer]

@revanthgss i will take a look next week.