CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/golang-github-com-aws-aws-sdk-go-v2--service-s3

AWS SDK for Go v2 S3 package provides a comprehensive, type-safe API client for Amazon Simple Storage Service enabling all S3 operations including object management, bucket configuration, multipart uploads, presigned URLs, and advanced features like S3 Express One Zone and metadata tables

Overview
Eval results
Files

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

Install with Tessl CLI

npx tessl i tessl/golang-github-com-aws-aws-sdk-go-v2--service-s3

docs

bucket-access-control.md

bucket-features.md

bucket-operations.md

client-config.md

index.md

list-operations.md

multipart-upload.md

object-operations.md

paginators-waiters.md

presigned-urls.md

types.md

tile.json