or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

bucket-access-control.mdbucket-features.mdbucket-operations.mdclient-config.mdindex.mdlist-operations.mdmultipart-upload.mdobject-operations.mdpaginators-waiters.mdpresigned-urls.mdtypes.md
tile.json

object-operations.mddocs/

AWS SDK for Go v2 - S3 Object Operations

Package: github.com/aws/aws-sdk-go-v2/service/s3

This document provides comprehensive API documentation for all S3 object operations in the AWS SDK for Go v2.

Table of Contents

  • Core Object Operations
  • Object ACL Operations
  • Object Metadata & Attributes
  • Object Tagging Operations
  • Object Lock Operations
  • Advanced Object Operations

Core Object Operations

PutObject

Uploads an object to an Amazon S3 bucket.

func (c *Client) PutObject(
    ctx context.Context,
    params *PutObjectInput,
    optFns ...func(*Options),
) (*PutObjectOutput, error)

PutObjectInput

type PutObjectInput struct {
    // Required fields
    Bucket *string  // Bucket name
    Key    *string  // Object key

    // Object data
    Body io.Reader

    // ACL settings
    ACL types.ObjectCannedACL

    // Encryption settings
    BucketKeyEnabled *bool
    ServerSideEncryption types.ServerSideEncryption
    SSECustomerAlgorithm *string
    SSECustomerKey *string
    SSECustomerKeyMD5 *string
    SSEKMSEncryptionContext *string
    SSEKMSKeyId *string

    // Checksum settings
    ChecksumAlgorithm types.ChecksumAlgorithm
    ChecksumCRC32 *string
    ChecksumCRC32C *string
    ChecksumCRC64NVME *string
    ChecksumSHA1 *string
    ChecksumSHA256 *string

    // Content metadata
    CacheControl *string
    ContentDisposition *string
    ContentEncoding *string
    ContentLanguage *string
    ContentLength *int64
    ContentMD5 *string
    ContentType *string

    // Object metadata
    Metadata map[string]string
    Tagging *string
    WebsiteRedirectLocation *string

    // Access control
    GrantFullControl *string
    GrantRead *string
    GrantReadACP *string
    GrantWriteACP *string

    // Object Lock settings
    ObjectLockLegalHoldStatus types.ObjectLockLegalHoldStatus
    ObjectLockMode types.ObjectLockMode
    ObjectLockRetainUntilDate *time.Time

    // Conditional headers
    IfMatch *string
    IfNoneMatch *string

    // Storage settings
    StorageClass types.StorageClass
    WriteOffsetBytes *int64  // For append operations in directory buckets

    // Other settings
    ExpectedBucketOwner *string
    Expires *time.Time
    RequestPayer types.RequestPayer
}

PutObjectOutput

type PutObjectOutput struct {
    // Checksums
    ChecksumCRC32 *string
    ChecksumCRC32C *string
    ChecksumCRC64NVME *string
    ChecksumSHA1 *string
    ChecksumSHA256 *string
    ChecksumType types.ChecksumType

    // Object metadata
    ETag *string
    VersionId *string
    Expiration *string

    // Encryption information
    BucketKeyEnabled *bool
    ServerSideEncryption types.ServerSideEncryption
    SSECustomerAlgorithm *string
    SSECustomerKeyMD5 *string
    SSEKMSEncryptionContext *string
    SSEKMSKeyId *string

    // Directory bucket specific
    Size *int64  // Size after append operations

    // Request information
    RequestCharged types.RequestCharged
    ResultMetadata middleware.Metadata
}

GetObject

Retrieves an object from Amazon S3.

func (c *Client) GetObject(
    ctx context.Context,
    params *GetObjectInput,
    optFns ...func(*Options),
) (*GetObjectOutput, error)

GetObjectInput

type GetObjectInput struct {
    // Required fields
    Bucket *string
    Key *string

    // Conditional headers
    IfMatch *string
    IfModifiedSince *time.Time
    IfNoneMatch *string
    IfUnmodifiedSince *time.Time

    // Range and part selection
    Range *string
    PartNumber *int32

    // Checksum settings
    ChecksumMode types.ChecksumMode

    // Response header overrides
    ResponseCacheControl *string
    ResponseContentDisposition *string
    ResponseContentEncoding *string
    ResponseContentLanguage *string
    ResponseContentType *string
    ResponseExpires *time.Time

    // Encryption settings (SSE-C)
    SSECustomerAlgorithm *string
    SSECustomerKey *string
    SSECustomerKeyMD5 *string

    // Version and permissions
    VersionId *string
    RequestPayer types.RequestPayer
    ExpectedBucketOwner *string
}

GetObjectOutput

type GetObjectOutput struct {
    // Object data
    Body io.ReadCloser

    // Content metadata
    AcceptRanges *string
    CacheControl *string
    ContentDisposition *string
    ContentEncoding *string
    ContentLanguage *string
    ContentLength *int64
    ContentRange *string
    ContentType *string

    // Object metadata
    ETag *string
    LastModified *time.Time
    Metadata map[string]string
    MissingMeta *int32
    VersionId *string
    DeleteMarker *bool

    // Checksums
    ChecksumCRC32 *string
    ChecksumCRC32C *string
    ChecksumCRC64NVME *string
    ChecksumSHA1 *string
    ChecksumSHA256 *string
    ChecksumType types.ChecksumType

    // Encryption information
    BucketKeyEnabled *bool
    ServerSideEncryption types.ServerSideEncryption
    SSECustomerAlgorithm *string
    SSECustomerKeyMD5 *string
    SSEKMSKeyId *string

    // Object Lock settings
    ObjectLockLegalHoldStatus types.ObjectLockLegalHoldStatus
    ObjectLockMode types.ObjectLockMode
    ObjectLockRetainUntilDate *time.Time

    // Storage and lifecycle
    StorageClass types.StorageClass
    Expiration *string
    Expires *time.Time
    ExpiresString *string
    Restore *string

    // Replication and tagging
    ReplicationStatus types.ReplicationStatus
    TagCount *int32
    PartsCount *int32

    // Other metadata
    WebsiteRedirectLocation *string
    RequestCharged types.RequestCharged
    ResultMetadata middleware.Metadata
}

DeleteObject

Removes an object from a bucket.

func (c *Client) DeleteObject(
    ctx context.Context,
    params *DeleteObjectInput,
    optFns ...func(*Options),
) (*DeleteObjectOutput, error)

DeleteObjectInput

type DeleteObjectInput struct {
    // Required fields
    Bucket *string
    Key *string

    // Version control
    VersionId *string

    // Conditional headers
    IfMatch *string
    IfMatchLastModifiedTime *time.Time  // Directory buckets only
    IfMatchSize *int64                   // Directory buckets only

    // Object Lock bypass
    BypassGovernanceRetention *bool

    // MFA delete
    MFA *string

    // Other settings
    RequestPayer types.RequestPayer
    ExpectedBucketOwner *string
}

DeleteObjectOutput

type DeleteObjectOutput struct {
    DeleteMarker *bool
    VersionId *string
    RequestCharged types.RequestCharged
    ResultMetadata middleware.Metadata
}

DeleteObjects

Deletes multiple objects from a bucket in a single request (up to 1,000 objects).

func (c *Client) DeleteObjects(
    ctx context.Context,
    params *DeleteObjectsInput,
    optFns ...func(*Options),
) (*DeleteObjectsOutput, error)

DeleteObjectsInput

type DeleteObjectsInput struct {
    // Required fields
    Bucket *string
    Delete *types.Delete  // Contains list of objects to delete

    // Checksum for request integrity
    ChecksumAlgorithm types.ChecksumAlgorithm

    // Object Lock bypass
    BypassGovernanceRetention *bool

    // MFA delete
    MFA *string

    // Other settings
    RequestPayer types.RequestPayer
    ExpectedBucketOwner *string
}

DeleteObjectsOutput

type DeleteObjectsOutput struct {
    Deleted []types.DeletedObject  // Successfully deleted objects
    Errors []types.Error            // Failed deletions
    RequestCharged types.RequestCharged
    ResultMetadata middleware.Metadata
}

CopyObject

Copies an object within S3 (up to 5 GB in a single operation).

func (c *Client) CopyObject(
    ctx context.Context,
    params *CopyObjectInput,
    optFns ...func(*Options),
) (*CopyObjectOutput, error)

CopyObjectInput

type CopyObjectInput struct {
    // Required fields
    Bucket *string      // Destination bucket
    CopySource *string  // Source object (bucket/key or ARN)
    Key *string         // Destination key

    // ACL settings
    ACL types.ObjectCannedACL
    GrantFullControl *string
    GrantRead *string
    GrantReadACP *string
    GrantWriteACP *string

    // Metadata directives
    MetadataDirective types.MetadataDirective
    TaggingDirective types.TaggingDirective

    // Content metadata
    CacheControl *string
    ContentDisposition *string
    ContentEncoding *string
    ContentLanguage *string
    ContentType *string
    Metadata map[string]string
    Tagging *string

    // Encryption settings (destination)
    BucketKeyEnabled *bool
    ServerSideEncryption types.ServerSideEncryption
    SSECustomerAlgorithm *string
    SSECustomerKey *string
    SSECustomerKeyMD5 *string
    SSEKMSEncryptionContext *string
    SSEKMSKeyId *string

    // Encryption settings (source - for SSE-C)
    CopySourceSSECustomerAlgorithm *string
    CopySourceSSECustomerKey *string
    CopySourceSSECustomerKeyMD5 *string

    // Conditional copy
    CopySourceIfMatch *string
    CopySourceIfModifiedSince *time.Time
    CopySourceIfNoneMatch *string
    CopySourceIfUnmodifiedSince *time.Time

    // Checksum settings
    ChecksumAlgorithm types.ChecksumAlgorithm

    // Object Lock settings
    ObjectLockLegalHoldStatus types.ObjectLockLegalHoldStatus
    ObjectLockMode types.ObjectLockMode
    ObjectLockRetainUntilDate *time.Time

    // Storage settings
    StorageClass types.StorageClass
    WebsiteRedirectLocation *string

    // Other settings
    Expires *time.Time
    ExpectedBucketOwner *string
    ExpectedSourceBucketOwner *string
    RequestPayer types.RequestPayer
}

CopyObjectOutput

type CopyObjectOutput struct {
    CopyObjectResult *types.CopyObjectResult  // Contains ETag and LastModified

    // Checksums
    ChecksumCRC32 *string
    ChecksumCRC32C *string
    ChecksumCRC64NVME *string
    ChecksumSHA1 *string
    ChecksumSHA256 *string

    // Version information
    VersionId *string
    CopySourceVersionId *string

    // Encryption information
    BucketKeyEnabled *bool
    ServerSideEncryption types.ServerSideEncryption
    SSECustomerAlgorithm *string
    SSECustomerKeyMD5 *string
    SSEKMSEncryptionContext *string
    SSEKMSKeyId *string

    // Lifecycle information
    Expiration *string

    // Request information
    RequestCharged types.RequestCharged
    ResultMetadata middleware.Metadata
}

HeadObject

Retrieves metadata from an object without returning the object itself.

func (c *Client) HeadObject(
    ctx context.Context,
    params *HeadObjectInput,
    optFns ...func(*Options),
) (*HeadObjectOutput, error)

HeadObjectInput

type HeadObjectInput struct {
    // Required fields
    Bucket *string
    Key *string

    // Conditional headers
    IfMatch *string
    IfModifiedSince *time.Time
    IfNoneMatch *string
    IfUnmodifiedSince *time.Time

    // Part and range selection
    PartNumber *int32
    Range *string

    // Checksum settings
    ChecksumMode types.ChecksumMode

    // Response header overrides
    ResponseCacheControl *string
    ResponseContentDisposition *string
    ResponseContentEncoding *string
    ResponseContentLanguage *string
    ResponseContentType *string
    ResponseExpires *time.Time

    // Encryption settings (SSE-C)
    SSECustomerAlgorithm *string
    SSECustomerKey *string
    SSECustomerKeyMD5 *string

    // Version and permissions
    VersionId *string
    RequestPayer types.RequestPayer
    ExpectedBucketOwner *string
}

HeadObjectOutput

type HeadObjectOutput struct {
    // Content metadata
    AcceptRanges *string
    CacheControl *string
    ContentDisposition *string
    ContentEncoding *string
    ContentLanguage *string
    ContentLength *int64
    ContentType *string

    // Object metadata
    ETag *string
    LastModified *time.Time
    Metadata map[string]string
    MissingMeta *int32
    VersionId *string
    DeleteMarker *bool

    // Checksums
    ChecksumCRC32 *string
    ChecksumCRC32C *string
    ChecksumCRC64NVME *string
    ChecksumSHA1 *string
    ChecksumSHA256 *string

    // Encryption information
    BucketKeyEnabled *bool
    ServerSideEncryption types.ServerSideEncryption
    SSECustomerAlgorithm *string
    SSECustomerKeyMD5 *string
    SSEKMSKeyId *string

    // Object Lock settings
    ObjectLockLegalHoldStatus types.ObjectLockLegalHoldStatus
    ObjectLockMode types.ObjectLockMode
    ObjectLockRetainUntilDate *time.Time

    // Storage and lifecycle
    StorageClass types.StorageClass
    ArchiveStatus types.ArchiveStatus
    Expiration *string
    Expires *time.Time
    ExpiresString *string
    Restore *string

    // Replication and parts
    ReplicationStatus types.ReplicationStatus
    PartsCount *int32

    // Other metadata
    WebsiteRedirectLocation *string
    RequestCharged types.RequestCharged
    ResultMetadata middleware.Metadata
}

Object ACL Operations

GetObjectAcl

Returns the access control list (ACL) of an object.

func (c *Client) GetObjectAcl(
    ctx context.Context,
    params *GetObjectAclInput,
    optFns ...func(*Options),
) (*GetObjectAclOutput, error)

GetObjectAclInput

type GetObjectAclInput struct {
    // Required fields
    Bucket *string
    Key *string

    // Optional parameters
    VersionId *string
    RequestPayer types.RequestPayer
    ExpectedBucketOwner *string
}

GetObjectAclOutput

type GetObjectAclOutput struct {
    Owner *types.Owner
    Grants []types.Grant
    RequestCharged types.RequestCharged
    ResultMetadata middleware.Metadata
}

PutObjectAcl

Sets the access control list (ACL) permissions for an object.

func (c *Client) PutObjectAcl(
    ctx context.Context,
    params *PutObjectAclInput,
    optFns ...func(*Options),
) (*PutObjectAclOutput, error)

PutObjectAclInput

type PutObjectAclInput struct {
    // Required fields
    Bucket *string
    Key *string

    // ACL specification methods
    ACL types.ObjectCannedACL            // Canned ACL
    AccessControlPolicy *types.AccessControlPolicy  // Explicit ACL

    // Grant headers
    GrantFullControl *string
    GrantRead *string
    GrantReadACP *string
    GrantWrite *string
    GrantWriteACP *string

    // Checksum
    ChecksumAlgorithm types.ChecksumAlgorithm
    ContentMD5 *string

    // Optional parameters
    VersionId *string
    RequestPayer types.RequestPayer
    ExpectedBucketOwner *string
}

PutObjectAclOutput

type PutObjectAclOutput struct {
    RequestCharged types.RequestCharged
    ResultMetadata middleware.Metadata
}

Object Metadata & Attributes

GetObjectAttributes

Retrieves all metadata and attributes from an object without returning the object itself.

func (c *Client) GetObjectAttributes(
    ctx context.Context,
    params *GetObjectAttributesInput,
    optFns ...func(*Options),
) (*GetObjectAttributesOutput, error)

GetObjectAttributesInput

type GetObjectAttributesInput struct {
    // Required fields
    Bucket *string
    Key *string
    ObjectAttributes []types.ObjectAttributes  // Attributes to retrieve

    // Pagination for parts
    MaxParts *int32
    PartNumberMarker *string

    // Encryption settings (SSE-C)
    SSECustomerAlgorithm *string
    SSECustomerKey *string
    SSECustomerKeyMD5 *string

    // Optional parameters
    VersionId *string
    RequestPayer types.RequestPayer
    ExpectedBucketOwner *string
}

GetObjectAttributesOutput

type GetObjectAttributesOutput struct {
    // Object metadata
    ETag *string
    LastModified *time.Time
    VersionId *string
    DeleteMarker *bool

    // Checksums
    Checksum *types.Checksum

    // Object parts (for multipart objects)
    ObjectParts *types.GetObjectAttributesParts

    // Storage class
    StorageClass types.StorageClass

    // Object size
    ObjectSize *int64

    // Request information
    RequestCharged types.RequestCharged
    ResultMetadata middleware.Metadata
}

Object Tagging Operations

GetObjectTagging

Returns the tag set of an object.

func (c *Client) GetObjectTagging(
    ctx context.Context,
    params *GetObjectTaggingInput,
    optFns ...func(*Options),
) (*GetObjectTaggingOutput, error)

GetObjectTaggingInput

type GetObjectTaggingInput struct {
    // Required fields
    Bucket *string
    Key *string

    // Optional parameters
    VersionId *string
    RequestPayer types.RequestPayer
    ExpectedBucketOwner *string
}

GetObjectTaggingOutput

type GetObjectTaggingOutput struct {
    TagSet []types.Tag
    VersionId *string
    ResultMetadata middleware.Metadata
}

PutObjectTagging

Sets the tag set for an object (replaces any existing tags).

func (c *Client) PutObjectTagging(
    ctx context.Context,
    params *PutObjectTaggingInput,
    optFns ...func(*Options),
) (*PutObjectTaggingOutput, error)

PutObjectTaggingInput

type PutObjectTaggingInput struct {
    // Required fields
    Bucket *string
    Key *string
    Tagging *types.Tagging  // Tag set to apply

    // Checksum
    ChecksumAlgorithm types.ChecksumAlgorithm
    ContentMD5 *string

    // Optional parameters
    VersionId *string
    RequestPayer types.RequestPayer
    ExpectedBucketOwner *string
}

PutObjectTaggingOutput

type PutObjectTaggingOutput struct {
    VersionId *string
    ResultMetadata middleware.Metadata
}

DeleteObjectTagging

Removes the entire tag set from an object.

func (c *Client) DeleteObjectTagging(
    ctx context.Context,
    params *DeleteObjectTaggingInput,
    optFns ...func(*Options),
) (*DeleteObjectTaggingOutput, error)

DeleteObjectTaggingInput

type DeleteObjectTaggingInput struct {
    // Required fields
    Bucket *string
    Key *string

    // Optional parameters
    VersionId *string
    ExpectedBucketOwner *string
}

DeleteObjectTaggingOutput

type DeleteObjectTaggingOutput struct {
    VersionId *string
    ResultMetadata middleware.Metadata
}

Object Lock Operations

GetObjectLegalHold

Gets the legal hold status of an object.

func (c *Client) GetObjectLegalHold(
    ctx context.Context,
    params *GetObjectLegalHoldInput,
    optFns ...func(*Options),
) (*GetObjectLegalHoldOutput, error)

GetObjectLegalHoldInput

type GetObjectLegalHoldInput struct {
    // Required fields
    Bucket *string
    Key *string

    // Optional parameters
    VersionId *string
    RequestPayer types.RequestPayer
    ExpectedBucketOwner *string
}

GetObjectLegalHoldOutput

type GetObjectLegalHoldOutput struct {
    LegalHold *types.ObjectLockLegalHold
    ResultMetadata middleware.Metadata
}

PutObjectLegalHold

Applies a legal hold configuration to an object.

func (c *Client) PutObjectLegalHold(
    ctx context.Context,
    params *PutObjectLegalHoldInput,
    optFns ...func(*Options),
) (*PutObjectLegalHoldOutput, error)

PutObjectLegalHoldInput

type PutObjectLegalHoldInput struct {
    // Required fields
    Bucket *string
    Key *string

    // Legal hold configuration
    LegalHold *types.ObjectLockLegalHold

    // Checksum
    ChecksumAlgorithm types.ChecksumAlgorithm
    ContentMD5 *string

    // Optional parameters
    VersionId *string
    RequestPayer types.RequestPayer
    ExpectedBucketOwner *string
}

PutObjectLegalHoldOutput

type PutObjectLegalHoldOutput struct {
    RequestCharged types.RequestCharged
    ResultMetadata middleware.Metadata
}

GetObjectRetention

Retrieves an object's retention settings.

func (c *Client) GetObjectRetention(
    ctx context.Context,
    params *GetObjectRetentionInput,
    optFns ...func(*Options),
) (*GetObjectRetentionOutput, error)

GetObjectRetentionInput

type GetObjectRetentionInput struct {
    // Required fields
    Bucket *string
    Key *string

    // Optional parameters
    VersionId *string
    RequestPayer types.RequestPayer
    ExpectedBucketOwner *string
}

GetObjectRetentionOutput

type GetObjectRetentionOutput struct {
    Retention *types.ObjectLockRetention
    ResultMetadata middleware.Metadata
}

PutObjectRetention

Places an object retention configuration on an object.

func (c *Client) PutObjectRetention(
    ctx context.Context,
    params *PutObjectRetentionInput,
    optFns ...func(*Options),
) (*PutObjectRetentionOutput, error)

PutObjectRetentionInput

type PutObjectRetentionInput struct {
    // Required fields
    Bucket *string
    Key *string

    // Retention configuration
    Retention *types.ObjectLockRetention

    // Governance bypass
    BypassGovernanceRetention *bool

    // Checksum
    ChecksumAlgorithm types.ChecksumAlgorithm
    ContentMD5 *string

    // Optional parameters
    VersionId *string
    RequestPayer types.RequestPayer
    ExpectedBucketOwner *string
}

PutObjectRetentionOutput

type PutObjectRetentionOutput struct {
    RequestCharged types.RequestCharged
    ResultMetadata middleware.Metadata
}

GetObjectLockConfiguration

Gets the Object Lock configuration for a bucket.

func (c *Client) GetObjectLockConfiguration(
    ctx context.Context,
    params *GetObjectLockConfigurationInput,
    optFns ...func(*Options),
) (*GetObjectLockConfigurationOutput, error)

GetObjectLockConfigurationInput

type GetObjectLockConfigurationInput struct {
    // Required field
    Bucket *string

    // Optional parameter
    ExpectedBucketOwner *string
}

GetObjectLockConfigurationOutput

type GetObjectLockConfigurationOutput struct {
    ObjectLockConfiguration *types.ObjectLockConfiguration
    ResultMetadata middleware.Metadata
}

PutObjectLockConfiguration

Places an Object Lock configuration on a bucket.

func (c *Client) PutObjectLockConfiguration(
    ctx context.Context,
    params *PutObjectLockConfigurationInput,
    optFns ...func(*Options),
) (*PutObjectLockConfigurationOutput, error)

PutObjectLockConfigurationInput

type PutObjectLockConfigurationInput struct {
    // Required field
    Bucket *string

    // Object Lock configuration
    ObjectLockConfiguration *types.ObjectLockConfiguration

    // Checksum
    ChecksumAlgorithm types.ChecksumAlgorithm
    ContentMD5 *string

    // Optional parameters
    Token *string
    RequestPayer types.RequestPayer
    ExpectedBucketOwner *string
}

PutObjectLockConfigurationOutput

type PutObjectLockConfigurationOutput struct {
    RequestCharged types.RequestCharged
    ResultMetadata middleware.Metadata
}

Advanced Object Operations

GetObjectTorrent

Returns torrent files from a bucket.

func (c *Client) GetObjectTorrent(
    ctx context.Context,
    params *GetObjectTorrentInput,
    optFns ...func(*Options),
) (*GetObjectTorrentOutput, error)

GetObjectTorrentInput

type GetObjectTorrentInput struct {
    // Required fields
    Bucket *string
    Key *string

    // Optional parameters
    RequestPayer types.RequestPayer
    ExpectedBucketOwner *string
}

GetObjectTorrentOutput

type GetObjectTorrentOutput struct {
    Body io.ReadCloser
    RequestCharged types.RequestCharged
    ResultMetadata middleware.Metadata
}

RenameObject

Renames an object (directory buckets only).

func (c *Client) RenameObject(
    ctx context.Context,
    params *RenameObjectInput,
    optFns ...func(*Options),
) (*RenameObjectOutput, error)

RenameObjectInput

type RenameObjectInput struct {
    // Required fields
    Bucket *string
    SourceKey *string
    TargetKey *string

    // Checksum
    ChecksumAlgorithm types.ChecksumAlgorithm

    // Optional parameters
    ExpectedBucketOwner *string
    ExpectedSourceBucketOwner *string
}

RenameObjectOutput

type RenameObjectOutput struct {
    ETag *string
    LastModified *time.Time
    ResultMetadata middleware.Metadata
}

RestoreObject

Restores an archived copy of an object back into Amazon S3.

func (c *Client) RestoreObject(
    ctx context.Context,
    params *RestoreObjectInput,
    optFns ...func(*Options),
) (*RestoreObjectOutput, error)

RestoreObjectInput

type RestoreObjectInput struct {
    // Required fields
    Bucket *string
    Key *string

    // Restore configuration
    RestoreRequest *types.RestoreRequest

    // Checksum
    ChecksumAlgorithm types.ChecksumAlgorithm

    // Optional parameters
    VersionId *string
    RequestPayer types.RequestPayer
    ExpectedBucketOwner *string
}

RestoreObjectOutput

type RestoreObjectOutput struct {
    RestoreOutputPath *string
    RequestCharged types.RequestCharged
    ResultMetadata middleware.Metadata
}

SelectObjectContent

Filters the contents of an object using SQL expressions.

func (c *Client) SelectObjectContent(
    ctx context.Context,
    params *SelectObjectContentInput,
    optFns ...func(*Options),
) (*SelectObjectContentOutput, error)

SelectObjectContentInput

type SelectObjectContentInput struct {
    // Required fields
    Bucket *string
    Key *string
    Expression *string
    ExpressionType types.ExpressionType
    InputSerialization *types.InputSerialization
    OutputSerialization *types.OutputSerialization

    // Request progress
    RequestProgress *types.RequestProgress

    // Scan range
    ScanRange *types.ScanRange

    // Encryption settings (SSE-C)
    SSECustomerAlgorithm *string
    SSECustomerKey *string
    SSECustomerKeyMD5 *string

    // Optional parameters
    ExpectedBucketOwner *string
}

SelectObjectContentOutput

type SelectObjectContentOutput struct {
    // Event stream reader
    EventStream *types.SelectObjectContentEventStream
    ResultMetadata middleware.Metadata
}

Example Usage:

// Query CSV data from S3 object
result, err := client.SelectObjectContent(ctx, &s3.SelectObjectContentInput{
    Bucket:         aws.String("my-bucket"),
    Key:            aws.String("data.csv"),
    ExpressionType: types.ExpressionTypeSql,
    Expression:     aws.String("SELECT * FROM S3Object WHERE age > 25"),
    InputSerialization: &types.InputSerialization{
        CSV: &types.CSVInput{
            FileHeaderInfo: types.FileHeaderInfoUse,
        },
    },
    OutputSerialization: &types.OutputSerialization{
        CSV: &types.CSVOutput{},
    },
})

// Process event stream
for event := range result.EventStream.Events() {
    switch e := event.(type) {
    case *types.RecordsEvent:
        // Process records
        fmt.Println(string(e.Payload))
    case *types.StatsEvent:
        // Process statistics
        fmt.Printf("Processed: %d bytes\n", e.Details.BytesProcessed)
    }
}

SelectObjectContent Event Stream Types

The following types are used for handling event streams in SelectObjectContent operations.

SelectObjectContentEventStreamReader { .api }
type SelectObjectContentEventStreamReader interface {
    Events() <-chan types.SelectObjectContentEventStream
    Close() error
    Err() error
}

Interface for reading events from a SelectObjectContent stream.

Methods:

  • Events() - Returns a channel that receives event stream events. Close the channel when done reading.
  • Close() - Closes the event stream reader. Must allow multiple concurrent calls.
  • Err() - Returns any error that occurred while reading the event stream.

Usage Example:

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/aws/aws-sdk-go-v2/aws"
    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/service/s3"
    "github.com/aws/aws-sdk-go-v2/service/s3/types"
)

func queryS3Data() error {
    cfg, err := config.LoadDefaultConfig(context.TODO())
    if err != nil {
        return err
    }

    client := s3.NewFromConfig(cfg)

    result, err := client.SelectObjectContent(context.TODO(), &s3.SelectObjectContentInput{
        Bucket:         aws.String("my-bucket"),
        Key:            aws.String("data.csv"),
        ExpressionType: types.ExpressionTypeSql,
        Expression:     aws.String("SELECT name, age FROM S3Object WHERE age > 18"),
        InputSerialization: &types.InputSerialization{
            CSV: &types.CSVInput{
                FileHeaderInfo: types.FileHeaderInfoUse,
            },
        },
        OutputSerialization: &types.OutputSerialization{
            CSV: &types.CSVOutput{},
        },
    })
    if err != nil {
        return err
    }

    // Get the event stream
    stream := result.GetStream()
    defer stream.Close()

    // Read events from the stream
    for event := range stream.Events() {
        switch e := event.(type) {
        case *types.RecordsEvent:
            // Process query results
            fmt.Printf("Records: %s\n", string(e.Payload))

        case *types.StatsEvent:
            // Process statistics
            fmt.Printf("Bytes scanned: %d\n", *e.Details.BytesScanned)
            fmt.Printf("Bytes processed: %d\n", *e.Details.BytesProcessed)
            fmt.Printf("Bytes returned: %d\n", *e.Details.BytesReturned)

        case *types.ProgressEvent:
            // Process progress updates
            fmt.Printf("Progress: %d bytes processed\n", *e.Details.BytesProcessed)

        case *types.EndEvent:
            // Query completed
            fmt.Println("Query completed successfully")
        }
    }

    // Check for errors
    if err := stream.Err(); err != nil {
        return fmt.Errorf("stream error: %w", err)
    }

    return nil
}
SelectObjectContentOutput.GetStream() { .api }
func (o *SelectObjectContentOutput) GetStream() *SelectObjectContentEventStream

Returns the type to interact with the event stream from SelectObjectContent.

Returns:

  • *SelectObjectContentEventStream - Event stream for reading SelectObjectContent results

Usage:

result, err := client.SelectObjectContent(ctx, input)
if err != nil {
    return err
}

stream := result.GetStream()
defer stream.Close()

for event := range stream.Events() {
    // Process events
}
NewSelectObjectContentEventStream() { .api }
func NewSelectObjectContentEventStream(
    optFns ...func(*SelectObjectContentEventStream)
) *SelectObjectContentEventStream

Initializes a SelectObjectContentEventStream for testing and mocking purposes only.

Parameters:

  • optFns - Optional configuration functions for the event stream

Returns:

  • *SelectObjectContentEventStream - A new event stream instance

Important: This function should only be used for testing and mocking the SelectObjectContentEventStream within your application. The Reader member must be set before reading events from the stream.

Example (Testing):

package mypackage_test

import (
    "testing"

    "github.com/aws/aws-sdk-go-v2/service/s3"
    "github.com/aws/aws-sdk-go-v2/service/s3/types"
)

func TestSelectObjectContentHandling(t *testing.T) {
    // Create a mock event stream for testing
    mockStream := s3.NewSelectObjectContentEventStream()

    // In a real test, you would set up the Reader and inject mock events
    // This allows you to test your event handling logic without making actual S3 calls

    // Example: Test your event processing logic
    // processEvents(mockStream)
}

SelectObjectContent Error Handling

When working with SelectObjectContent event streams, handle errors appropriately:

func processSelectResults(client *s3.Client, bucket, key, query string) error {
    result, err := client.SelectObjectContent(context.TODO(), &s3.SelectObjectContentInput{
        Bucket:         aws.String(bucket),
        Key:            aws.String(key),
        ExpressionType: types.ExpressionTypeSql,
        Expression:     aws.String(query),
        InputSerialization: &types.InputSerialization{
            CSV: &types.CSVInput{
                FileHeaderInfo: types.FileHeaderInfoUse,
            },
        },
        OutputSerialization: &types.OutputSerialization{
            JSON: &types.JSONOutput{},
        },
    })
    if err != nil {
        return fmt.Errorf("select object content failed: %w", err)
    }

    stream := result.GetStream()
    defer func() {
        if err := stream.Close(); err != nil {
            log.Printf("failed to close stream: %v", err)
        }
    }()

    for event := range stream.Events() {
        switch e := event.(type) {
        case *types.RecordsEvent:
            // Process records
            if err := processRecords(e.Payload); err != nil {
                return fmt.Errorf("failed to process records: %w", err)
            }

        case *types.StatsEvent:
            log.Printf("Stats: scanned=%d, processed=%d, returned=%d",
                *e.Details.BytesScanned,
                *e.Details.BytesProcessed,
                *e.Details.BytesReturned)
        }
    }

    // Always check for stream errors
    if err := stream.Err(); err != nil {
        return fmt.Errorf("stream error: %w", err)
    }

    return nil
}

WriteGetObjectResponse

Passes transformed object data back to GetObject requests (for Object Lambda).

func (c *Client) WriteGetObjectResponse(
    ctx context.Context,
    params *WriteGetObjectResponseInput,
    optFns ...func(*Options),
) (*WriteGetObjectResponseOutput, error)

WriteGetObjectResponseInput

type WriteGetObjectResponseInput struct {
    // Required field
    RequestRoute *string
    RequestToken *string

    // Object data
    Body io.Reader

    // Content metadata
    ContentLength *int64
    ContentType *string
    ContentDisposition *string
    ContentEncoding *string
    ContentLanguage *string
    CacheControl *string

    // Object metadata
    ETag *string
    LastModified *time.Time
    Metadata map[string]string
    MissingMeta *int32

    // Checksums
    ChecksumCRC32 *string
    ChecksumCRC32C *string
    ChecksumSHA1 *string
    ChecksumSHA256 *string

    // Storage class
    StorageClass types.StorageClass

    // Object Lock settings
    ObjectLockLegalHoldStatus types.ObjectLockLegalHoldStatus
    ObjectLockMode types.ObjectLockMode
    ObjectLockRetainUntilDate *time.Time

    // Encryption information
    ServerSideEncryption types.ServerSideEncryption
    SSECustomerAlgorithm *string
    SSEKMSKeyId *string
    BucketKeyEnabled *bool

    // Version and lifecycle
    VersionId *string
    Expiration *string
    Expires *time.Time
    Restore *string

    // Range and parts
    AcceptRanges *string
    ContentRange *string
    PartsCount *int32

    // Replication and tagging
    ReplicationStatus types.ReplicationStatus
    TagCount *int32

    // Error information (when returning errors)
    StatusCode *int32
    ErrorCode *string
    ErrorMessage *string

    // Other metadata
    DeleteMarker *bool
    RequestCharged types.RequestCharged
}

WriteGetObjectResponseOutput

type WriteGetObjectResponseOutput struct {
    ResultMetadata middleware.Metadata
}

Example Usage:

// Lambda function handler for Object Lambda
func handler(ctx context.Context, event events.S3ObjectLambdaEvent) error {
    // Get the original object
    originalObject, _ := s3Client.GetObject(ctx, &s3.GetObjectInput{
        Bucket: aws.String(event.UserRequest.URL),
        Key:    aws.String(event.GetObjectContext.InputS3URL),
    })

    // Transform the object data
    transformedData := transformData(originalObject.Body)

    // Write the response back
    _, err := s3Client.WriteGetObjectResponse(ctx, &s3.WriteGetObjectResponseInput{
        RequestRoute: aws.String(event.GetObjectContext.OutputRoute),
        RequestToken: aws.String(event.GetObjectContext.OutputToken),
        Body:         transformedData,
        StatusCode:   aws.Int32(200),
    })

    return err
}

Common Types

types.Delete

type Delete struct {
    Objects []ObjectIdentifier  // Objects to delete (max 1,000)
    Quiet   *bool               // Enable quiet mode
}

type ObjectIdentifier struct {
    Key       *string  // Object key
    VersionId *string  // Object version ID (optional)
}

types.DeletedObject

type DeletedObject struct {
    Key                   *string
    VersionId             *string
    DeleteMarker          *bool
    DeleteMarkerVersionId *string
}

types.Tag

type Tag struct {
    Key   *string  // Tag key (required)
    Value *string  // Tag value (required)
}

types.Tagging

type Tagging struct {
    TagSet []Tag  // Set of tags
}

types.ObjectLockLegalHold

type ObjectLockLegalHold struct {
    Status types.ObjectLockLegalHoldStatus  // ON or OFF
}

types.ObjectLockRetention

type ObjectLockRetention struct {
    Mode            types.ObjectLockRetentionMode  // GOVERNANCE or COMPLIANCE
    RetainUntilDate *time.Time                     // Retention expiration date
}

types.ObjectLockConfiguration

type ObjectLockConfiguration struct {
    ObjectLockEnabled types.ObjectLockEnabled  // Enabled status
    Rule              *ObjectLockRule           // Default retention rule
}

type ObjectLockRule struct {
    DefaultRetention *DefaultRetention
}

type DefaultRetention struct {
    Mode  types.ObjectLockRetentionMode
    Days  *int32
    Years *int32
}

types.RestoreRequest

type RestoreRequest struct {
    Days                 *int32                  // Lifetime of restored copy
    GlacierJobParameters *GlacierJobParameters   // Glacier job settings
    Tier                 types.Tier              // Retrieval tier
    Type                 types.RestoreRequestType // SELECT or restore
    SelectParameters     *SelectParameters        // For SELECT restores
    OutputLocation       *OutputLocation          // Output location
    Description          *string
}

Notes

  • Directory buckets: Many operations have specific behaviors or limitations for directory buckets. Check the AWS documentation for details.
  • Versioning: Operations that support versioning accept an optional VersionId parameter.
  • Object Lock: Object Lock operations are not supported for directory buckets.
  • SSE-C: Server-Side Encryption with Customer-Provided Keys requires all three headers: algorithm, key, and key MD5.
  • Checksums: Multiple checksum algorithms are supported (CRC32, CRC32C, CRC64NVME, SHA1, SHA256).
  • Request Payer: Requester Pays buckets are not supported for directory buckets.

See Also

  • Multipart Upload Operations
  • Bucket Operations
  • S3 Client Configuration