Amazon S3 adds annotations to provide AI agents and analytics tools with context for data discovery
Attach up to 1 GB of queryable JSON/XML/YAML context per S3 object—no separate metadata system needed for AI agents or analytics.
View original announcement →Visual Summary
graph TD
A{{S3 Annotations}}:::announced
B(Amazon S3):::storage
C([S3 Metadata Tables]):::feature
D(Amazon Athena):::compute
E(SageMaker Unified Studio):::compute
F([Natural Language Search]):::feature
G((AI Agents)):::external
H((Analytics Tools)):::external
I([Apache Iceberg Tables]):::feature
G ==>|"discover data"| A
H -->|"query context"| A
A ==>|"attaches to"| B
A -->|"flows into"| C
C -->|"stored as"| I
I -->|"queried by"| D
E -->|"enables"| F
F -.->|"searches"| I
G -.->|"natural language"| E
classDef announced fill:#ff9900,stroke:#ec7211,color:#fff,font-weight:bold
classDef compute fill:#e3f2fd,stroke:#1565c0,color:#1565c0
classDef storage fill:#e8f5e9,stroke:#2e7d32,color:#2e7d32
classDef feature fill:#fff3e0,stroke:#e65100,color:#e65100
classDef external fill:#f5f5f5,stroke:#616161,color:#616161
What's New
Amazon S3 now supports annotations, a new metadata capability that lets you attach up to 1 GB of rich, structured business context (JSON, XML, YAML, or plain text) directly to any S3 object. Unlike existing metadata options, annotations are mutable, independently managed via dedicated APIs, and scale to thousands of entries per object without requiring object re-upload. They integrate natively with S3 Metadata's Apache Iceberg tables, enabling SQL and natural-language queries across petabyte-scale datasets for AI agents and analytics tools.
How It Works
- Structure: Each object supports up to 1,000 named annotations, each between 1 byte and 1 MiB in size, totaling up to 1 GB per object, stored in any UTF-8 text format (JSON, XML, YAML, or plain text).
- Independent lifecycle: Annotations are created, updated, or deleted via dedicated API operations (
PutObjectAnnotation,GetObjectAnnotation, etc.) without re-uploading or modifying the underlying object. - Durability and consistency: Annotations share the same durability and strong consistency guarantees as the S3 object they are attached to.
- Object lifecycle coupling: Annotations automatically move with the object during copy and cross-region replication operations, and are permanently removed when the object is deleted.
- S3 Metadata integration: When S3 Metadata is enabled, annotations automatically flow into fully managed, read-only Apache Iceberg annotation tables that are continuously kept up to date by S3.
- Queryability: Annotation tables can be queried at scale using Amazon Athena or any Iceberg-compatible analytics engine using standard SQL.
- Natural language search: Agents in Amazon SageMaker Unified Studio and any IDE using the S3 Tables MCP server can search objects by their annotations using natural language queries.
- Access methods: Annotations are accessible via the AWS CLI, S3 REST APIs, and AWS SDKs.
Why It's Important
- Eliminates separate metadata systems: Organizations no longer need to build, maintain, and synchronize external metadata databases or catalogs alongside their S3 data, reducing operational overhead and architectural complexity.
- Enables agentic AI workflows: AI agents can autonomously discover, understand, and act on the right data by querying rich, always-current context stored directly with the object—without human intervention or custom retrieval pipelines.
- Scales to enterprise data lakes: With support for up to 1,000 annotations per object and 1 GB of context, organizations can annotate petabytes of objects with detailed business, compliance, and AI-generated metadata.
- Keeps context current: Because annotations are mutable and independently managed, metadata can evolve alongside the data it describes—critical for dynamic use cases like AI inference results, compliance status, or processing pipeline state.
- Reduces data retrieval costs: Compliance and audit use cases (e.g., Life Sciences) can access full context for archived objects in S3 Glacier storage classes through annotation queries without incurring object retrieval charges.
- Accelerates analytics and discovery: Surfacing annotations in S3 Metadata's Iceberg tables enables fast, SQL-based discovery across trillions of objects without custom ETL or indexing infrastructure.
How It's Different
- Scale vs. object tags: Object tags are limited to 10 per object with a maximum value of 256 characters; annotations support up to 1,000 entries per object with payloads up to 1 MiB each—orders of magnitude more capacity.
- Rich format vs. key-value strings: Object tags are restricted to key-value string pairs; annotations support structured formats like JSON, XML, and YAML, enabling complex, nested business context.
- Post-upload mutability vs. user-defined metadata: User-defined metadata is immutable after upload and size-constrained; annotations can be added, modified, or deleted at any time without touching the object.
- Purpose-built for AI/analytics vs. operational metadata: Object tags are optimized for IAM policies, lifecycle rules, and cost allocation; annotations are purpose-built for data discovery, AI agent consumption, and analytics query patterns.
- Native query integration: Unlike any prior S3 metadata type, annotations automatically surface in managed Iceberg tables queryable via Athena and natural language—no custom indexing required.
- Independent API surface: Annotations have their own dedicated API operations, decoupling metadata management from object data plane operations and enabling fine-grained access control over context separately from the object.
When to Prefer It
- AI-generated metadata storage: When you need to store ML inference results, embeddings, content moderation labels, or AI-generated summaries alongside source objects and query them at scale.
- Structured, multi-field context: When your metadata requires JSON, XML, or YAML structure, nested fields, or payloads larger than 256 characters that object tags cannot accommodate.
- More than 10 metadata entries per object: When a single object requires many distinct metadata categories (e.g., transcripts, rights information, processing status, compliance flags) that exceed the 10-tag limit.
- Evolving metadata: When context must be updated frequently after upload—such as pipeline processing status, regulatory approval state, or iterative AI labeling—without re-uploading the object.
- Data discovery for AI agents: When building agentic workflows that need to autonomously find and understand relevant datasets using natural language or SQL queries across large object inventories.
- Compliance and audit trails: When you need to attach regulatory status, PII flags, retention policies, or approval chains to objects (including archived data) and make them queryable without object retrieval.
- Eliminating external metadata catalogs: When you want to consolidate business context into S3 itself rather than maintaining a separate metadata database, data catalog, or synchronization pipeline.
- Cross-region metadata consistency: When metadata must reliably follow objects through replication and copy operations without additional orchestration.
Availability
- GA status: Generally available as of June 16, 2026.
- Annotations (object-level): Available in all commercial AWS Regions and AWS China Regions (Beijing and Ningxia); not available in Middle East (UAE) and Middle East (Bahrain) Regions.
- Annotation tables (S3 Metadata integration): Available in all AWS Regions where S3 Metadata is currently supported.
- Pricing: Annotations are billed per the S3 pricing page; costs apply to annotation storage, API requests (PUT/GET/DELETE), and S3 Metadata table storage/query operations—refer to the [S3 pricing page](https://aws.amazon.com/s3/pricing/) for current rates.
- Limits: Maximum 1,000 annotations per object version; each annotation payload is 1 byte to 1 MiB; annotation names up to 512 bytes; total annotation data up to 1 GB per object.
- Constraints: Annotations can only be set after object upload via
PutObjectAnnotation; they cannot be attached inline duringPutObject(unlike object tags or user-defined metadata). - Access methods: AWS CLI, S3 REST APIs, and AWS SDKs; natural language search via Amazon SageMaker Unified Studio agents or the S3 Tables MCP server.
