object_annotations

Creates, updates, deletes, gets or lists an object_annotations resource.

Overview

Name	object_annotations
Type	Resource
Id	aws.s3.object_annotations

Fields

The following fields are returned by SELECT queries:

get_object_annotation

Name	Datatype	Description
line_items	array

list_object_annotations

Name	Datatype	Description
annotation_name	string	The name of the annotation.
checksum_algorithm	string	The checksum algorithm used for the annotation.
e_tag	string	The entity tag of the annotation.
last_modified	string	The date and time the annotation was last modified.
replication_status	string	The replication status of the annotation.
size	integer	The size of the annotation payload, in bytes.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_object_annotation	select	bucket, key, annotationName, region	versionId, x-amz-request-payer, x-amz-expected-bucket-owner, x-amz-checksum-mode	Retrieves an annotation from an Amazon S3 object. To use this operation, you must have the s3:GetObjectAnnotation permission. If checksum mode is enabled via the x-amz-checksum-mode header, Amazon S3 returns the stored checksum in the response headers for client-side validation. Annotations are not supported by the following features: S3 Inventory Reports, API Gateway, S3 Storage Lens, Amazon S3 File Gateway, Amazon FSx, S3 on Outposts, and S3 Express One Zone (directory buckets). The following operations are related to GetObjectAnnotation: PutObjectAnnotation ListObjectAnnotations DeleteObjectAnnotation
list_object_annotations	select	bucket, key, region	versionId, max-annotation-results, annotation-prefix, continuation-token, x-amz-request-payer, x-amz-expected-bucket-owner	Lists the annotations attached to an Amazon S3 object. Results are paginated, with a maximum of 1,000 annotations per object. Use the AnnotationPrefix parameter to filter the results by name prefix. To use this operation, you must have the s3:ListObjectAnnotations permission. Annotations are not supported by the following features: S3 Inventory Reports, API Gateway, S3 Storage Lens, Amazon S3 File Gateway, Amazon FSx, S3 on Outposts, and S3 Express One Zone (directory buckets). The following operations are related to ListObjectAnnotations: PutObjectAnnotation GetObjectAnnotation DeleteObjectAnnotation
put_object_annotation	replace	bucket, key, annotationName, region, AnnotationPayload	versionId, x-amz-object-if-match, x-amz-sdk-checksum-algorithm, x-amz-checksum-crc32, x-amz-checksum-crc32c, x-amz-checksum-crc64nvme, x-amz-checksum-sha1, x-amz-checksum-sha256, x-amz-checksum-sha512, x-amz-checksum-md5, x-amz-checksum-xxhash64, x-amz-checksum-xxhash3, x-amz-checksum-xxhash128, Content-MD5, x-amz-request-payer, x-amz-expected-bucket-owner	Attaches an annotation to an Amazon S3 object. An annotation is a named payload of 1 byte to 1 MiB that you can associate with a specific object or object version. Each object can have up to 1,000 annotations. For annotation naming rules and restrictions, see Annotation naming guidelines in the Amazon S3 User Guide. Annotations inherit the encryption of their parent object. For objects without server-side encryption, annotations are encrypted with SSE-S3 (the default for new objects). Objects encrypted with SSE-C cannot have annotations. To use this operation, you must have the s3:PutObjectAnnotation permission. If the bucket has Requester Pays enabled, you must include the x-amz-request-payer header. Annotations are not supported by the following features: S3 Inventory Reports, API Gateway, S3 Storage Lens, Amazon S3 File Gateway, Amazon FSx, S3 on Outposts, and S3 Express One Zone (directory buckets). The following operations are related to PutObjectAnnotation: GetObjectAnnotation ListObjectAnnotations DeleteObjectAnnotation
delete_object_annotation	delete	bucket, key, annotationName, region	versionId, x-amz-request-payer, x-amz-expected-bucket-owner, x-amz-object-if-match	Deletes a specific annotation from an Amazon S3 object. Use the x-amz-object-if-match header to perform a conditional delete that only succeeds if the object's ETag matches the provided value, preventing race conditions during concurrent updates. Deleting an annotation is permanent. Annotations are not independently versioned, so there is no delete marker or way to recover a deleted annotation. To use this operation, you must have the s3:DeleteObjectAnnotation permission. If the object is protected by Object Lock in governance mode, you must also include the x-amz-bypass-governance-retention header. Annotations are not supported by the following features: S3 Inventory Reports, API Gateway, S3 Storage Lens, Amazon S3 File Gateway, Amazon FSx, S3 on Outposts, and S3 Express One Zone (directory buckets). The following operations are related to DeleteObjectAnnotation: PutObjectAnnotation GetObjectAnnotation ListObjectAnnotations

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
annotationName	string	The name of the annotation to delete. Annotation names are UTF-8 encoded and cannot start with aws or s3 (case-insensitive). Length Constraints: Minimum length of 1. Maximum length of 512 bytes.
bucket	string	The name of the bucket that contains the object.
key	string	The object key.
region	string	AWS region (default: us-east-1)
Content-MD5	string	Base64-encoded MD5 digest of the message.
annotation-prefix	string	Filter results to annotations whose name begins with the specified prefix.
continuation-token	string	Continuation token returned by a previous request to retrieve the next page.
max-annotation-results	integer	The maximum number of annotations to return in the response. Maximum is 1,000.
versionId	string	The version ID of the object.
x-amz-checksum-crc32	string	Base64-encoded CRC32 checksum of the annotation payload.
x-amz-checksum-crc32c	string	Base64-encoded CRC32C checksum of the annotation payload.
x-amz-checksum-crc64nvme	string	Base64-encoded CRC64NVME checksum of the annotation payload.
x-amz-checksum-md5	string	Base64-encoded MD5 checksum of the annotation payload.
x-amz-checksum-mode	string	Set to ENABLED to validate the checksum of the annotation payload on retrieval.
x-amz-checksum-sha1	string	Base64-encoded SHA1 checksum of the annotation payload.
x-amz-checksum-sha256	string	Base64-encoded SHA256 checksum of the annotation payload.
x-amz-checksum-sha512	string	Base64-encoded SHA512 checksum of the annotation payload.
x-amz-checksum-xxhash128	string	Base64-encoded XXHASH128 checksum of the annotation payload.
x-amz-checksum-xxhash3	string	Base64-encoded XXHASH3 checksum of the annotation payload.
x-amz-checksum-xxhash64	string	Base64-encoded XXHASH64 checksum of the annotation payload.
x-amz-expected-bucket-owner	string	The account ID of the expected bucket owner.
x-amz-object-if-match	string	If specified, the operation only succeeds if the object's ETag matches the provided value.
x-amz-request-payer	string
x-amz-sdk-checksum-algorithm	string	The checksum algorithm to use. Supported values: CRC32, CRC32C, CRC64NVME, SHA1, SHA256, SHA512, MD5, XXHASH64, XXHASH3, XXHASH128.

SELECT examples

get_object_annotation

Retrieves an annotation from an Amazon S3 object. To use this operation, you must have the s3:GetObjectAnnotation permission. If checksum mode is enabled via the x-amz-checksum-mode header, Amazon S3 returns the stored checksum in the response headers for client-side validation. Annotations are not supported by the following features: S3 Inventory Reports, API Gateway, S3 Storage Lens, Amazon S3 File Gateway, Amazon FSx, S3 on Outposts, and S3 Express One Zone (directory buckets). The following operations are related to GetObjectAnnotation: PutObjectAnnotation ListObjectAnnotations DeleteObjectAnnotation

SELECT
line_items
FROM aws.s3.object_annotations
WHERE bucket = '{{ bucket }}' -- required
AND key = '{{ key }}' -- required
AND annotationName = '{{ annotationName }}' -- required
AND region = '{{ region }}' -- required
AND versionId = '{{ versionId }}'
AND `x-amz-request-payer` = '{{ x-amz-request-payer }}'
AND `x-amz-expected-bucket-owner` = '{{ x-amz-expected-bucket-owner }}'
AND `x-amz-checksum-mode` = '{{ x-amz-checksum-mode }}'
;

list_object_annotations

Lists the annotations attached to an Amazon S3 object. Results are paginated, with a maximum of 1,000 annotations per object. Use the AnnotationPrefix parameter to filter the results by name prefix. To use this operation, you must have the s3:ListObjectAnnotations permission. Annotations are not supported by the following features: S3 Inventory Reports, API Gateway, S3 Storage Lens, Amazon S3 File Gateway, Amazon FSx, S3 on Outposts, and S3 Express One Zone (directory buckets). The following operations are related to ListObjectAnnotations: PutObjectAnnotation GetObjectAnnotation DeleteObjectAnnotation

SELECT
annotation_name,
checksum_algorithm,
e_tag,
last_modified,
replication_status,
size
FROM aws.s3.object_annotations
WHERE bucket = '{{ bucket }}' -- required
AND key = '{{ key }}' -- required
AND region = '{{ region }}' -- required
AND versionId = '{{ versionId }}'
AND `max-annotation-results` = '{{ max-annotation-results }}'
AND `annotation-prefix` = '{{ annotation-prefix }}'
AND `continuation-token` = '{{ continuation-token }}'
AND `x-amz-request-payer` = '{{ x-amz-request-payer }}'
AND `x-amz-expected-bucket-owner` = '{{ x-amz-expected-bucket-owner }}'
;

REPLACE examples

put_object_annotation

Attaches an annotation to an Amazon S3 object. An annotation is a named payload of 1 byte to 1 MiB that you can associate with a specific object or object version. Each object can have up to 1,000 annotations. For annotation naming rules and restrictions, see Annotation naming guidelines in the Amazon S3 User Guide. Annotations inherit the encryption of their parent object. For objects without server-side encryption, annotations are encrypted with SSE-S3 (the default for new objects). Objects encrypted with SSE-C cannot have annotations. To use this operation, you must have the s3:PutObjectAnnotation permission. If the bucket has Requester Pays enabled, you must include the x-amz-request-payer header. Annotations are not supported by the following features: S3 Inventory Reports, API Gateway, S3 Storage Lens, Amazon S3 File Gateway, Amazon FSx, S3 on Outposts, and S3 Express One Zone (directory buckets). The following operations are related to PutObjectAnnotation: GetObjectAnnotation ListObjectAnnotations DeleteObjectAnnotation

REPLACE aws.s3.object_annotations
SET 
AnnotationPayload = '{{ AnnotationPayload }}'
WHERE 
bucket = '{{ bucket }}' --required
AND key = '{{ key }}' --required
AND annotationName = '{{ annotationName }}' --required
AND region = '{{ region }}' --required
AND AnnotationPayload = '{{ AnnotationPayload }}' --required
AND versionId = '{{ versionId}}'
AND `x-amz-object-if-match` = '{{ x-amz-object-if-match}}'
AND `x-amz-sdk-checksum-algorithm` = '{{ x-amz-sdk-checksum-algorithm}}'
AND `x-amz-checksum-crc32` = '{{ x-amz-checksum-crc32}}'
AND `x-amz-checksum-crc32c` = '{{ x-amz-checksum-crc32c}}'
AND `x-amz-checksum-crc64nvme` = '{{ x-amz-checksum-crc64nvme}}'
AND `x-amz-checksum-sha1` = '{{ x-amz-checksum-sha1}}'
AND `x-amz-checksum-sha256` = '{{ x-amz-checksum-sha256}}'
AND `x-amz-checksum-sha512` = '{{ x-amz-checksum-sha512}}'
AND `x-amz-checksum-md5` = '{{ x-amz-checksum-md5}}'
AND `x-amz-checksum-xxhash64` = '{{ x-amz-checksum-xxhash64}}'
AND `x-amz-checksum-xxhash3` = '{{ x-amz-checksum-xxhash3}}'
AND `x-amz-checksum-xxhash128` = '{{ x-amz-checksum-xxhash128}}'
AND `Content-MD5` = '{{ Content-MD5}}'
AND `x-amz-request-payer` = '{{ x-amz-request-payer}}'
AND `x-amz-expected-bucket-owner` = '{{ x-amz-expected-bucket-owner}}'
RETURNING
line_items;

DELETE examples

delete_object_annotation

Deletes a specific annotation from an Amazon S3 object. Use the x-amz-object-if-match header to perform a conditional delete that only succeeds if the object's ETag matches the provided value, preventing race conditions during concurrent updates. Deleting an annotation is permanent. Annotations are not independently versioned, so there is no delete marker or way to recover a deleted annotation. To use this operation, you must have the s3:DeleteObjectAnnotation permission. If the object is protected by Object Lock in governance mode, you must also include the x-amz-bypass-governance-retention header. Annotations are not supported by the following features: S3 Inventory Reports, API Gateway, S3 Storage Lens, Amazon S3 File Gateway, Amazon FSx, S3 on Outposts, and S3 Express One Zone (directory buckets). The following operations are related to DeleteObjectAnnotation: PutObjectAnnotation GetObjectAnnotation ListObjectAnnotations

DELETE FROM aws.s3.object_annotations
WHERE bucket = '{{ bucket }}' --required
AND key = '{{ key }}' --required
AND annotationName = '{{ annotationName }}' --required
AND region = '{{ region }}' --required
AND versionId = '{{ versionId }}'
AND `x-amz-request-payer` = '{{ x-amz-request-payer }}'
AND `x-amz-expected-bucket-owner` = '{{ x-amz-expected-bucket-owner }}'
AND `x-amz-object-if-match` = '{{ x-amz-object-if-match }}'
;