---
title: "Data governance with annotations in Amazon S3"
description: "Amazon S3 Annotations lets you attach governance context directly to S3 objects without rewriting them. Each object version can hold up to 1,000 annotations, each 1 byte to 1 MB in UTF-8 format such as JSON. Annotations travel with the object during copy or replication, remain readable in cold storage like Glacier Deep Archive without restoration, and can be updated in place without changing the object’s ETag. The pattern uses a governance annotation payload capturing classification, retention, jurisdiction, PII, and rationale, and supports backfill of existing objects. At scale, an S3 Metadata annotation table backed by Apache Iceberg enables SQL querying via Amazon Athena for governance questions like which objects hold PII and have expired retention across large object populations."
---

# Data governance with annotations in Amazon S3

[AWS](https://yomu.fyi/company/aws) · Aditya Jain · Oct 26, 2026

**Type:** Tutorial

## Summary

Amazon S3 Annotations lets you attach governance context directly to S3 objects without rewriting them. Each object version can hold up to 1,000 annotations, each 1 byte to 1 MB in UTF-8 format such as JSON. Annotations travel with the object during copy or replication, remain readable in cold storage like Glacier Deep Archive without restoration, and can be updated in place without changing the object’s ETag. The pattern uses a governance annotation payload capturing classification, retention, jurisdiction, PII, and rationale, and supports backfill of existing objects. At scale, an S3 Metadata annotation table backed by Apache Iceberg enables SQL querying via Amazon Athena for governance questions like which objects hold PII and have expired retention across large object populations.

## Context

Traditional data governance in S3 required storing context in a separate database, disconnected from the objects it describes.

## Approach / What changed

Use the PutObjectAnnotation API to write a governance annotation payload (JSON) on each object version, update it in place as context changes, backfill existing objects, and optionally enable an S3 Metadata annotation table for SQL querying at scale.

## Takeaways

- Annotations store governance context with the object version, traveling with copies and replication without requiring a separate database.
- Annotations can be updated in place without rewriting the object or changing its ETag, and remain readable even when the object is in cold storage.
- The S3 Metadata annotation table, an Apache Iceberg table, enables SQL querying of annotations across a bucket using Athena, with eventual consistency and typical hourly refresh.

## FAQ

### Can annotations be updated after the object is written?

Yes, annotations are mutable after write via PutObjectAnnotation, without rewriting the object or changing its ETag.

### Are annotations readable when the object is in cold storage?

Yes, annotations are directly readable for objects in Glacier Flexible Retrieval or Glacier Deep Archive without restoring the object. You pay S3 Standard rates for annotation storage regardless of the parent's storage class.

### How does querying annotations at scale work?

Enable an S3 Metadata annotation table, an Apache Iceberg table that S3 maintains asynchronously. You query it with Athena or Iceberg-compatible engines. Results are eventually consistent and typically reflect annotations within about an hour.

**Tags:** [Apache Iceberg](https://yomu.fyi/topic/apache-iceberg), [AWS](https://yomu.fyi/topic/aws), [Data Governance](https://yomu.fyi/topic/data-governance), [S3](https://yomu.fyi/topic/s3)

- Source: [AWS](https://aws.amazon.com/blogs/architecture/data-governance-with-annotations-in-amazon-s3)
- Source URL: https://aws.amazon.com/blogs/architecture/data-governance-with-annotations-in-amazon-s3
- Ingested by Yomu: 2026-10-26T21:00:15.453Z

[Read original post](https://aws.amazon.com/blogs/architecture/data-governance-with-annotations-in-amazon-s3)
