Gerenciamento de estágios Snowflake

Os comandos snow stage permitem que você execute tarefas adicionais específicas do estágio:

Criação de um estágio nomeado

O comando snow stage create cria um estágio nomeado se ele ainda não existir.

snow stage create <stage_name>

Por exemplo, para criar um estágio chamado new_stage, digite o seguinte comando:

snow stage create new_stage

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

O exemplo a seguir mostra o que acontece se você tentar criar um estágio, packages, que já existe.

# stage that already exists
snow stage create packages

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

Se quiser especificar o tipo de criptografia a ser usado para todos os arquivos armazenados no estágio, adicione a opção --encryption para especificar se deseja a criptografia completa (SNOWFLAKE_FULL) ou somente a criptografia do lado do servidor (SNOWFLAKE_SSE).

snow stage create new_stage --encryption SNOWFLAKE_FULL

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

Cópia de arquivos de e para um estágio

O comando snow stage copy copia um arquivo da máquina local para um estágio, de um estágio para uma máquina local ou entre estágios nomeados.

snow stage copy <source_path> <destination_path>

Observe as seguintes diretrizes:

  • O caminho do estágio deve começar com @, conforme mostrado nos exemplos a seguir.

  • Quando você copia um único arquivo, <destination_path> deve identificar um diretório, não um arquivo. Se o diretório especificado não existir, o comando o criará.

  • Por padrão, quando você copia um diretório local para um estágio, o diretório local deve conter apenas arquivos. Você pode usar a opção --recursive para carregar subdiretórios no diretório local. Você pode usar padrões glob com a opção --recursive.

  • Quando você copia um diretório de um estágio para um sistema de arquivos local, o comando atualmente simplifica sua estrutura de árvore interna. Para ilustrar, suponha que seu diretório local contenha o seguinte:

    test_case.py
tests/abc.py
tests/test1/x1.txt
tests/test1/x2.txt

    Após copiar o diretório do estágio, o diretório do sistema de arquivos local terá o seguinte:

    test_case.py
abc.py
x1.txt
x2.txt

    Nota

    Se você quiser manter a estrutura do arquivo do diretório de origem, você pode incluir a opção --recursive.

Como copiar arquivos para um estágio

  • Para copiar arquivos da máquina local para um estágio, insira um comando semelhante ao seguinte:

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

Você pode usar o comando snow stage list-files para verificar se o comando copiou os arquivos com sucesso:

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

Cópia de arquivos de um estágio

  • Para copiar arquivos de um estágio para um diretório na máquina local, digite um comando semelhante ao seguinte:

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

Você pode listar o conteúdo do diretório para verificar se o comando copiou os arquivos corretamente:

ls local_app_backup

environment.yml  snowflake.yml    streamlit_app.py

Observe que o diretório local deve existir.

É possível copiar de um estágio de usuário (@~):

snow stage copy "@~" . --recursive

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

Cópia de arquivos entre estágios

Você pode copiar arquivos diretamente entre dois estágios nomeados sem baixá-los primeiro para sua máquina local. Isto pode ser útil para organizar arquivos em diferentes estágios ou criar backups.

  • Para copiar arquivos de um estágio para outro, use a seguinte sintaxe:

    snow stage copy @source_stage @destination_stage

O exemplo a seguir copia todos os arquivos de production_stage para backup_stage:

snow stage copy @production_stage @backup_stage

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

Nota

Ao copiar entre estágios, o destino não pode ser um estágio de usuário (@~). Você deve especificar estágios nomeados para a origem e para o destino.

Use padrões glob para especificar arquivos

Você pode especificar vários arquivos que correspondem a uma expressão regular usando um padrão glob para o argumento source_path. Você deve colocar o padrão glob entre aspas simples ou duplas.

O exemplo a seguir copia todos os arquivos .txt em um diretório para um estágio.

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

Listagem do conteúdo de um estágio

O comando snow stage list-files lista o conteúdo do estágio.

snow stage list-files <stage_path>

Por exemplo, para listar os pacotes em um estágio, digite o seguinte comando:

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

Execução de arquivos de um estágio

Nota

Snowflake CLI não oferece suporte à execução de arquivos Python para as versões 3.12 e superiores do Python.

O comando snow stage execute executa arquivos SQL ou Python de um estágio.

snow stage execute <stage_path>

  • Para arquivos .sql, ele executa um comando EXECUTE IMMEDIATE FROM em arquivos .sql de um estágio.

  • Para arquivos .py, ele executa um procedimento Snowpark Python com escopo de sessão.

    Snowflake CLI executa o procedimento no Snowflake para garantir um ambiente de execução consistente. Se seus scripts Python exigirem requisitos adicionais, é necessário especificá-los em um arquivo requirements.txt que resida no mesmo diretório dos arquivos no estágio. O comando snow stage execute oferece suporte apenas a pacotes do canal Snowflake Anaconda.

    Por padrão, o comando procura o arquivo requirements.txt na seguinte precedência:

    • Caminho do estágio especificado no parâmetro stage_path do comando.

    • Diretórios pai da hierarquia de caminho do estágio especificado, até atingir o estágio.

    • Se você não especificar um arquivo requirements.txt, o comando assumirá que nenhum pacote adicional é necessário.

    Por exemplo, se você executar snow stage execute @my_stage/ml/app1/scripts, o comando procurará o arquivo da seguinte forma:

    • my_stage/ml/app1/scripts/requirements.txt

    • my_stage/ml/app1/requirements.txt

    • my_stage/ml/requirements.txt

    • my_stage/ml/requirements.txt

Os exemplos a seguir ilustram maneiras de executar diferentes conjuntos de arquivos .sql de um estágio:

  • Especifique apenas um nome de estágio para executar todos os arquivos .sql no estágio:

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

  • Especifique um estágio de usuário (@~) para executar os arquivos script.sql no estágio de usuário:

    snow stage execute "@~/script1.sql"

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

Use padrões glob para selecionar subconjuntos de arquivos

  • Especifique um padrão semelhante a um glob para executar todos os arquivos .sql no diretório dir:

    snow stage execute "@scripts/dir/*"

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

  • Especifique um padrão semelhante a um glob para executar somente arquivos .sql no diretório dir que começa com «script», seguido por um caractere:

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

  • Especifique um caminho de arquivo direto com a opção --silent:

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

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

Remoção de um arquivo de um estágio

O comando snow stage remove remove um arquivo de um estágio.

snow stage remove <stage_name> <file_name>

Por exemplo, para remover um arquivo de um estágio, digite um comando semelhante ao seguinte:

snow stage remove example_app_stage app/pages/my_page.py

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