管理 Snowflake 暂存区¶

snow stage 命令允许您执行其他特定暂存区的任务：

如果命名暂存区还不存在，则创建该暂存区。
将所有文件从源目录复制到目标目录。
列出暂存区的内容。
从暂存区执行 SQL 文件。
从暂存区移除文件。

创建命名暂存区¶

如果命名暂存区尚不存在，则 snow stage create 命令会创建一个已命名的暂存区。

snow stage create <stage_name>

Copy

例如，要创建名为 new_stage 的暂存区，请输入以下命令：

snow stage create new_stage

Copy

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

下面的示例显示了如果您尝试创建一个已经存在的暂存区 packages，会发生什么情况。

# stage that already exists
snow stage create packages

Copy

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

将文件复制到暂存区或从暂存区复制文件¶

借助 snow stage copy 命令，您可以将文件从本地计算机复制到暂存区，也可以将文件从暂存区复制到本地计算机。

snow stage copy <source_path> <destination_path>

Copy

其中的一个 <source_path> or <destination_path> 必须是本地路径，而另一个必须是指向 Snowflake 暂存区的路径。请注意以下事项：

暂存区路径必须以 @ 开头，如以下示例所示。
复制单个文件时，<destination_path> 必须标识目录，而不是文件。如果指定的目录不存在，则命令将创建目录。
默认情况下，将本地目录复制到暂存区时，本地目录必须仅包含文件。您可以使用 --recursive 选项上传本地目录中的子目录。您可以使用带有 --recursive 选项的 glob 模式。
将目录从暂存区复制到本地文件系统时，该命令目前会将其内部树结构扁平化。举例来说，假设您的本地目录包含以下内容：
```
test_case.py
tests/abc.py
tests/test1/x1.txt
tests/test1/x2.txt
```
从暂存区复制目录后，本地文件系统目录包含以下内容：
```
test_case.py
abc.py
x1.txt
x2.txt
```
备注

如果要维护源目录中的文件结构，则可以添加 --recursive 选项。

将文件复制到暂存区¶

要将文件从本地计算机复制到暂存区，请输入类似于以下内容的命令：

snow 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             ...
+--------------------------------------------------------------------------------------

您可以使用 snow stage list-files 命令来验证命令是否成功复制了文件：

snow stage list-files 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 | ...
+------------------------------------------------------------------------------------

从暂存区复制文件¶

下面的示例将文件从暂存区复制到本地计算机上的一个目录：

mkdir local_app_backup
snow 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 |         |
+------------------------------------------------+

您可以列出目录内容以验证命令是否正确复制了文件：

ls local_app_backup

Copy

environment.yml  snowflake.yml    streamlit_app.py

请注意，本地目录必须存在。

您可以从用户暂存区 (@~) 进行复制：

snow stage copy "@~" . --recursive

Copy

+------------------------------------------------+
| file             | size | status     | message |
|------------------+------+------------+---------|
| environment.yml  | 62   | DOWNLOADED |         |
| snowflake.yml    | 252  | DOWNLOADED |         |
| streamlit_app.py | 109  | DOWNLOADED |         |
+------------------------------------------------+

使用 glob 模式指定文件¶

您可以通过对 source_path 实参使用 glob 模式来指定多个匹配正则表达式的文件。您必须将 glob 模式用单引号或双引号括起来。

以下示例将目录中的所有 .txt 文件复制到暂存区。

snow stage copy "testdir/*.txt" @TEST_STAGE_3

Copy

put file:///.../testdir/*.txt @TEST_STAGE_3 auto_compress=false parallel=4 overwrite=False
+------------------------------------------------------------------------------------------------------------+
| source | target | source_size | target_size | source_compression | target_compression | status   | message |
|--------+--------+-------------+-------------+--------------------+--------------------+----------+---------|
| b1.txt | b1.txt | 3           | 16          | NONE               | NONE               | UPLOADED |         |
| b2.txt | b2.txt | 3           | 16          | NONE               | NONE               | UPLOADED |         |
+------------------------------------------------------------------------------------------------------------+

列出暂存区的内容¶

snow stage list-files 命令用于列出暂存区内容。

snow stage list-files <stage_path>

Copy

例如，要列出暂存区中的包，请输入以下命令：

snow stage list-files 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 ...
+-------------------------------------------------------------------------------------

从暂存区执行文件¶

备注

Snowflake CLI 不支持执行 Python 3.12 及以上版本的 Python 文件。

snow stage execute 命令会执行 SQL 或从暂存区执行 Python 文件。

snow stage execute <stage_path>

Copy

对于 .sql 文件，它对暂存区的 .sql 文件执行 EXECUTE IMMEDIATE FROM 命令。
对于 .py 文件，它执行一个会话范围的 Snowpark Python 过程。

Snowflake CLI 会在 Snowflake 中执行该过程，以确保一致的执行环境。如果您的 Python 脚本需要额外的要求，您应该在与暂存区上的文件位于同一目录中的 requirements.txt 文件中指定这些要求。snow stage execute 命令仅支持来自 Snowflake Anaconda 通道的包。

默认情况下，该命令按以下优先顺序查找 requirements.txt 文件。
- 命令的 stage_path 参数中指定的暂存区路径。
- 指定暂存区路径层次结构的父目录，直到到达该暂存区。
- 如果您不指定 requirements.txt 文件，则该命令假定不需要其他包。
例如，如果您运行 snow stage execute @my_stage/ml/app1/scripts，命令将按如下方式查找文件：
- my_stage/ml/app1/scripts/requirements.txt
- my_stage/ml/app1/requirements.txt
- my_stage/ml/requirements.txt
- my_stage/ml/requirements.txt

下面的示例说明了从暂存区执行不同 .sql 文件集的方法：

只指定暂存区名称，执行该暂存区中的所有 .sql 文件：

snow stage execute "@scripts"

Copy

SUCCESS - scripts/script1.sql
SUCCESS - scripts/script2.sql
SUCCESS - scripts/dir/script.sql
+------------------------------------------+
| File                   | Status  | Error |
|------------------------+---------+-------|
| scripts/script1.sql    | SUCCESS | None  |
| scripts/script2.sql    | SUCCESS | None  |
| scripts/dir/script.sql | SUCCESS | None  |
+------------------------------------------+

指定用户暂存区 (@~)，执行用户暂存区中的 script.sql 文件：

snow stage execute "@~/script1.sql"

Copy

SUCCESS - scripts/script1.sql
+------------------------------------------+
| File                   | Status  | Error |
|------------------------+---------+-------|
| @~/script.sql          | SUCCESS | None  |
+------------------------------------------+

使用 glob 模式，选择文件的子集¶

指定一个类 glob 模式，以执行 dir 目录中的所有 .sql 文件：

snow stage execute "@scripts/dir/*"

Copy

SUCCESS - scripts/dir/script.sql
+------------------------------------------+
| File                   | Status  | Error |
|------------------------+---------+-------|
| scripts/dir/script.sql | SUCCESS | None  |
+------------------------------------------+

指定类 glob 的模式，只执行 dir 目录中以“script”开头、后跟一个字符的 .sql 文件：

snow stage execute "@scripts/script?.sql"

Copy

SUCCESS - scripts/script1.sql
SUCCESS - scripts/script2.sql
+---------------------------------------+
| File                | Status  | Error |
|---------------------+---------+-------|
| scripts/script1.sql | SUCCESS | None  |
| scripts/script2.sql | SUCCESS | None  |
+---------------------------------------+

使用 --silent 选项指定直接文件路径：

snow stage execute "@scripts/script1.sql" --silent

Copy

+---------------------------------------+
| File                | Status  | Error |
|---------------------+---------+-------|
| scripts/script1.sql | SUCCESS | None  |
+---------------------------------------+

从暂存区移除文件¶

snow stage remove 命令会从暂存区中移除文件。

snow stage remove <stage_name> <file_name>

Copy

例如，要从暂存区移除文件，请输入类似于以下内容的命令：

snow stage remove example_app_stage app/pages/my_page.py

Copy

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