管理 Snowflake 暂存区

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

创建命名暂存区

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

snow stage create <stage_name>

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

snow stage create new_stage

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

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

# stage that already exists
snow stage create packages

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

如果要为存储在暂存区中的所有文件指定加密类型，请添加 --encryption 选项，以指定要完全加密 (SNOWFLAKE_FULL) 还是仅使用服务器端加密 (SNOWFLAKE_SSE)。

snow stage create new_stage --encryption SNOWFLAKE_FULL

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

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

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

snow stage copy <source_path> <destination_path>

请注意以下准则：

  • 暂存区路径必须以 @ 开头，如以下示例所示。

  • 复制单个文件时，<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

    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

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

    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

environment.yml  snowflake.yml    streamlit_app.py

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

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

snow stage copy "@~" . --recursive

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

在暂存区之间复制文件

您可以直接在两个命名暂存区之间复制文件，而无需先将它们下载到本地计算机。这对于组织不同暂存区的文件或创建备份非常有用。

  • 要将文件从一个暂存区复制到另一个暂存区，请使用以下语法：

    snow stage copy @source_stage @destination_stage

以下实例将 production_stage 中的所有文件复制到 backup_stage：

snow stage copy @production_stage @backup_stage

+------------------------------------------------------------+
| file                                                       |
|------------------------------------------------------------|
| __init__.py                                                |
| main.py                                                    |
| procedure.py                                               |
+------------------------------------------------------------+

备注

当您在各个暂存区之间复制时，目标不能是用户暂存区 (@~)。您必须为源和目标指定命名暂存区。

使用 glob 模式指定文件

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

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

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

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>

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

snow stage list-files packages

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>

  • 对于 .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"

    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"

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

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

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

    snow stage execute "@scripts/dir/*"

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

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

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

    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

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

从暂存区移除文件

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

snow stage remove <stage_name> <file_name>

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

snow stage remove example_app_stage app/pages/my_page.py

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