Managing Snowflake stages with Python

You can use Python to manage Snowflake stages, which are locations of data files in cloud storage. For an overview of stages, see Overview of data loading.

The Snowflake Python API represents stages with two separate types:

  • Stage: Exposes a stage’s properties such as its name, encryption type, credentials, and directory table settings.

  • StageResource: Exposes methods you can use to fetch a corresponding Stage object, upload and list files on the stage, and delete the stage.

Prerequisites

The examples in this topic assume that you’ve added code to connect with Snowflake and to create a Root object from which to use the Snowflake Python API.

For example, the following code uses connection parameters defined in a configuration file to create a connection to Snowflake:

from snowflake.core import Root
from snowflake.snowpark import Session

session = Session.builder.config("connection_name", "myconnection").create()
root = Root(session)
Copy

Using the resulting Session object, the code creates a Root object to use the API’s types and methods. For more information, see Connect to Snowflake with the Snowflake Python API.

Creating a stage

To create a stage, first create a Stage object, and then create a StageCollection object from the API Root object. Using StageCollection.create, add the new stage to Snowflake.

Code in the following example creates a Stage object that represents a stage named my_stage with an encryption type of SNOWFLAKE_SSE (server-side encryption only):

from snowflake.core.stage import Stage, StageEncryption

my_stage = Stage(
  name="my_stage",
  encryption=StageEncryption(type="SNOWFLAKE_SSE")
)
stages = root.databases["my_db"].schemas["my_schema"].stages
stages.create(my_stage)
Copy

The code creates a StageCollection variable stages and uses StageCollection.create to create a new stage in Snowflake.

Getting stage details

You can get information about a stage by calling the StageResource.fetch method, which returns a Stage object.

Code in the following example gets information about a stage named my_stage:

my_stage = root.databases["my_db"].schemas["my_schema"].stages["my_stage"].fetch()
print(my_stage.to_dict())
Copy

Listing stages

You can list stages using the StageCollection.iter method, which returns a PagedIter iterator of Stage objects.

Code in the following example lists stages whose name includes the text my and prints the name of each:

from snowflake.core.stage import StageCollection

stages: StageCollection = root.databases["my_db"].schemas["my_schema"].stages
stage_iter = stages.iter(like="my%")  # returns a PagedIter[Stage]
for stage_obj in stage_iter:
  print(stage_obj.name)
Copy

Performing stage operations

You can perform common stage operations—such as uploading a file to a stage and listing files on a stage—with a StageResource object.

To demonstrate some operations you can do with a stage resource, code in the following example does the following:

  1. Uploads a file named my-file.yaml to the my_stage stage with the specified auto-compress and overwrite options.

  2. Lists all files on the stage to verify that the file was uploaded successfully.

  3. Deletes the stage.

my_stage_res = root.databases["my_db"].schemas["my_schema"].stages["my_stage"]

my_stage_res.upload_file("./my-file.yaml", "/", auto_compress=False, overwrite=True)

stageFiles = root.databases["my_db"].schemas["my_schema"].stages["my_stage"].list_files()
for stageFile in stageFiles:
  print(stageFile)

my_stage_res.delete()
Copy