Downloads objects from a specified bucket to a local environment or external application.

Stored Procedure-Specific Information

To download a specific object that resides in a subfolder rather than the whole bucket, provide the full key. For example:

Object = 'FolderName/SubfolderName/FileName'

You can also match multiple objects with a wildcard (*) in Object, or set UseExactObjectName to true to treat Object as a literal key even when it contains a wildcard character.

Note: If you do not specify Object, the CData Power BI Connector for Amazon S3 retrieves every object in the bucket.

The downloaded data is written to the FileStream output stream if one is supplied, saved to LocalFolderPath if that path is set, or returned Base64-encoded in the Content output column otherwise. Set ByteRangeStart and ByteRangeEnd to download only part of an object, and use UpdatedStartDate and UpdatedEndDate to restrict the download to objects modified within a date range.

The following example shows how to run this procedure:

EXECUTE DownloadObjects
     @Bucket='BucketName',
     @Object='ObjectName',
     @LocalFolderPath='C:/Users/User/Desktop/LocalFolderName'

Input

Name	Type	Required	Description
Bucket	String	True	The name of the S3 bucket that contains the object or objects to be downloaded.
Object	String	False	The key (name) of a specific object to download. If not provided, all objects in the specified bucket are retrieved.
LocalFolderPath	String	False	The local directory path where the downloaded object files are saved.
ByteRangeStart	Long	False	The starting byte position for a partial object download, used to fetch a specific byte range.
ByteRangeEnd	Long	False	The ending byte position for a partial object download. Paired with ByteRangeStart.
UpdatedStartDate	Datetime	False	The earliest last-modified date for filtering which objects to download from the bucket.
UpdatedEndDate	Datetime	False	The latest last-modified date for filtering which objects to download from the bucket.
CreateFolders	Boolean	False	Automatically create the destination folder. Used when LocalFolderPath is specified.
EncodeFileName	Boolean	False	Specifies whether the local file path should be encoded. Useful when the object name contains invalid characters for the operating system the object is being downloaded on. Used when LocalFolderPath is specified.
UseExactObjectName	Boolean	False	When set to true, the Object value is treated as a literal S3 key even if it contains wildcard characters such as '*'. Use this when downloading an object whose key literally contains an asterisk. The default value is false.

Result Set Columns

Name	Type	Description
Status	String	Indicates the result of the download operation, such as success or failure.
Content	String	When LocalFolderPath is not specified, provides the downloaded object's content, encoded in Base64.
Object	String	The key (name) of the object that was downloaded.
LocalFile	String	The local file path for the downloaded object. Used when LocalFolderPath is specified.
FailureReason	String	Reason why object downloading failed.