snowflake.core.stage.StageResource

class snowflake.core.stage.StageResource(name: str, collection: StageCollection)

Bases: StageResourceBase

Represents a reference to a Snowflake stage.

With this stage reference, you can drop, list files, put files, get files, and fetch information about stages.

Attributes

database

The DatabaseResource this reference belongs to.

fully_qualified_name

Return the fully qualified name of the object this reference points to.

root

The Root object this reference belongs to.

Methods

delete() → None

The delete() method is deprecated; use drop() instead.

download_file(stage_path: str, file_folder_path: str) → None

The download_file() method is deprecated; use get() instead.

drop(if_exists: bool | None = None) → None

Delete a stage.

Parameters:

if_exists (bool) – Parameter that specifies how to handle the request for a resource that does not exist: - true: The endpoint does not throw an error if the resource does not exist. It returns a 200 success response, but does not take any action on the resource. - false: The endpoint throws an error if the resource doesn’t exist.

drop_async(if_exists: bool | None = None) → PollingOperation[None]

An asynchronous version of drop().

Refer to PollingOperation for more information on asynchronous execution and the return type.

fetch() → Stage

Fetch a stage.

fetch_async() → PollingOperation[Stage]

An asynchronous version of fetch().

Refer to PollingOperation for more information on asynchronous execution and the return type.

get(stage_location: str, target_directory: str | PathLike, *, parallel: int = 4, pattern: str | None = None) → None

Download the specified files from a path in the stage to a local directory.

References: Snowflake GET command.

Parameters:

  • stage_location (str) – A directory or filename on a stage, from which you want to download the files. e.g. /folder/file_name.txt or /folder

  • target_directory (str, PathLike) – The path to the local directory where the files should be downloaded. If target_directory does not already exist, the method creates the directory.

  • parallel (int, optional) – Specifies the number of threads to use for downloading the files. The granularity unit for downloading is one file. Increasing the number of threads might improve performance when downloading large files. Valid values: Any integer value from 1 (no parallelism) to 99 (use 99 threads for downloading files).

  • pattern (str, optional) – Specifies a regular expression pattern for filtering files to download. The command lists all files in the specified path and applies the regular expression pattern on each of the files found. Default: None (all files in the specified stage are downloaded).

Examples

Getting file from stage:

>>> stage_reference.get("/folder/file_name.txt", "/local_folder")
Copy

Getting files with a specific pattern:

>>> stage_reference.get("/folder", "/local_folder", pattern=".*.txt")
Copy
get_presigned_url(file_path: str, presigned_url_request: PresignedUrlRequest | None = None) → FileTransferMaterial

Generate a presigned url and optionally encryption materials.

Parameters:

  • file_path (str) – The full stage path of the file. (required)

  • presigned_url_request (PresignedUrlRequest)

get_presigned_url_async(file_path: str, presigned_url_request: PresignedUrlRequest | None = None) → PollingOperation[FileTransferMaterial]

An asynchronous version of get_presigned_url().

Refer to PollingOperation for more information on asynchronous execution and the return type.

list_files(pattern: str | None = None) → Iterable[StageFile]

List files in the stage.

Parameters:

pattern (str) – Parameter that filters the command output by a regular expression pattern.

list_files_async(pattern: str | None = None) → PollingOperation[Iterable[StageFile]]

An asynchronous version of list_files().

Refer to PollingOperation for more information on asynchronous execution and the return type.

put(local_file_name: str | PathLike, stage_location: str, *, parallel: int = 4, auto_compress: bool = True, source_compression: str = 'AUTO_DETECT', overwrite: bool = False) → None

Upload local files to a path in the stage.

References: Snowflake PUT command.

Parameters:

  • local_file_name (str, PathLike) – The path to the local files to upload. To match multiple files in the path, you can specify the wildcard characters * and ?.

  • stage_location (str) – The prefix where you want to upload the files. e.g. /folder or /

  • parallel (int, optional) –

    Specifies the number of threads to use for uploading files. The upload process separates batches of data files by size:

    • Small files (< 64 MB) are staged in parallel as individual files.

    • Larger files are automatically split into chunks, staged concurrently, and reassembled in the target stage. A single thread can upload multiple chunks.

    Increasing the number of threads can improve performance when uploading large files. Supported values: Any integer value from 1 (no parallelism) to 99 (use 99 threads for uploading files).

  • auto_compress (boolean, optional) – Specifies whether Snowflake uses gzip to compress files during upload. Default is True.

  • source_compression (str, optional) –

    Specifies the method of compression used on already-compressed files that are being staged.

    Values can be AUTO_DETECT, GZIP, BZ2, BROTLI, ZSTD, DEFLATE, RAW_DEFLATE, NONE, default is AUTO_DETECT.

  • overwrite (boolean, optional) – Specifies whether Snowflake will overwrite an existing file with the same name during upload. Default is False.

Examples

Putting file on stage and compressing it using the stage’s reference:

>>> stage_reference.put("local_file.csv", "/folder", auto_compress=True)
Copy
upload_file(file_path: str, stage_folder_path: str, *, auto_compress: bool = True, overwrite: bool = False) → None

The upload_file() method is deprecated; use put() instead.

Sprache: Deutsch