Managing stages¶

Note

The snow object stage commands are now deprecated and will be removed when Snowflake releases Snowflake CLI 3.0.0. These commands are replaced with snow stage commands. Please consider migrating any existing scripts that use the snow object stage commands.

Also, information for managing stages with the new commands is now located at Managing Snowflake stages.

The snow object stage commands let you perform additional stage-specific tasks:

Create a named stage if it does not already exist.
Copy all files from source to target directory..
List the contents of a stage.
Remove a file from a stage.

Create a named stage¶

The snow object stage create command creates a named stage if it does not already exist.

snow object stage create NAME

Copy

For example, to create a stage called new_stage, enter the following command:

snow object stage create new_stage

Copy

+-----------------------------------------------------+
| key    | value                                      |
|--------+--------------------------------------------|
| status | Stage area NEW_STAGE successfully created. |
+-----------------------------------------------------+

The following example shows what happens if you try to create a stage, packages, that already exists.

# stage that already exists
snow object stage create packages

Copy

+--------------------------------------------------------+
| key    | value                                         |
|--------+-----------------------------------------------|
| status | PACKAGES already exists, statement succeeded. |
+--------------------------------------------------------+

Copy files to and from a stage¶

The snow object stage copy command copies a file from the local machine to a stage or from a stage to a local machine.

snow object stage copy @SOURCE_PATH DESTINATION_PATH

Copy

One of SOURCE_PATH or DESTINATION_PATH must be a local path, while the other must a path to the Snowflake stage. Note the following:

The stage path must start with @, as shown in the following examples.
When copying a single file, the DESTINATION_PATH must identify a directory, not a file. If the specified directory does not exist, the command creates it.
When copying a local directory to a stage, the local directory must contain only files; directories containing sub-directories are not supported.
When copying a directory from a stage to a local filesystem, the command currently flattens its internal tree structure. To illustrate, assume your local directory contains the following:
```
test_case.py
tests/abc.py
tests/test1/x1.txt
tests/test1/x2.txt
```
After copying the directory from the stage, the local filesystem directory contains the following:
```
test_case.py
abc.py
x1.txt
x2.txt
```

To copy files from the local machine to a stage, enter a commands similar to the following:

snow object stage copy local_example_app @example_app_stage/app

Copy

put file:///.../local_example_app/* @example_app_stage/app4 auto_compress=false parallel=4 overwrite=False
+--------------------------------------------------------------------------------------
| source           | target           | source_size | target_size | source_compression...
|------------------+------------------+-------------+-------------+--------------------
| environment.yml  | environment.yml  | 62          | 0           | NONE             ...
| snowflake.yml    | snowflake.yml    | 252         | 0           | NONE             ...
| streamlit_app.py | streamlit_app.py | 109         | 0           | NONE             ...
+--------------------------------------------------------------------------------------

You can use the snow object stage list command to verify the command copied the files successfully:

snow object stage list example_app_stage

Copy

ls @example_app_stage
​+------------------------------------------------------------------------------------
| name                                   | size | md5                              | ...
|----------------------------------------+------+----------------------------------+-
| example_app_stage/app/environment.yml  | 64   | 45409c8da098125440bfb7ffbcd900f5 | ...
| example_app_stage/app/snowflake.yml    | 256  | a510b1d59fa04f451b679d43c703b6d4 | ...
| example_app_stage/app/streamlit_app.py | 112  | e6c2a89c5a164e34a0faf60b086bbdfc | ...
+------------------------------------------------------------------------------------

The following example copies files from a stage to a directory on the local machine:

mkdir local_app_backup
snow object stage copy @example_app_stage/app local_app_backup

Copy

get @example_app_stage/app file:///.../local_app_backup/ parallel=4
+------------------------------------------------+
| file             | size | status     | message |
|------------------+------+------------+---------|
| environment.yml  | 62   | DOWNLOADED |         |
| snowflake.yml    | 252  | DOWNLOADED |         |
| streamlit_app.py | 109  | DOWNLOADED |         |
+------------------------------------------------+

You can list the directory contents to verify the command copied the files correctly:

ls local_app_backup

Copy

environment.yml  snowflake.yml    streamlit_app.py

Note that the local directory must exist.

List the contents of a stage¶

The snow object stage list command lists the stage contents.

snow object stage list NAME

Copy

For example, to list the packages in a stage, enter the following command:

snow object stage list packages

Copy

ls @packages
+-------------------------------------------------------------------------------------
| name                 | size     | md5                              | last_modified
|----------------------+----------+----------------------------------+----------------
| packages/plp.Ada.zip | 824736   | 90639175a0ac7735e67525118b81047c | Tue, 16 Jan ...
| packages/samrand.zip | 13721024 | 648f0bae2f65fd4c9f178b17c23de7e5 | Tue, 16 Jan ...
+-------------------------------------------------------------------------------------

Remove a file from a stage¶

The snow object stage remove command removes a file from a stage.

snow object stage remove STAGE_NAME FILE_NAME

Copy

For example, to remove a file from a stage, enter a command similar to the following:

snow object stage remove example_app_stage app/pages/my_page.py

Copy

+-------------------------------------------------+
| key    | value                                  |
|--------+----------------------------------------|
| name   | example_app_stage/app/pages/my_page.py |
| result | removed                                |
+-------------------------------------------------+