Arquivos de definição de projeto

Um arquivo de definição de projeto chamado snowflake.yml declara um diretório como um projeto Snowflake Native App. É um arquivo com versão controlada que reside na raiz de um diretório do projeto Snowflake Native App e pode ser criado manualmente ou pelo Snowflake CLI como parte da inicialização do projeto. Contanto que você possa fornecer este arquivo estruturado no diretório, mas escolha usar sua própria estrutura de projeto independente, o Snowflake CLI pode descobrir os arquivos relevantes e executar sua funcionalidade normalmente.

Para Native Apps, seu snowflake.yml ficaria parecido com o seguinte:

definition_version: 2
entities:
  pkg:
    type: application package
    identifier: <name_of_app_pkg>
    stage: app_src.stage
    manifest: app/manifest.yml
    artifacts:
      - src: app/*
        dest: ./
      - src: src/module-add/target/add-1.0-SNAPSHOT.jar
        dest: module-add/add-1.0-SNAPSHOT.jar
      - src: src/module-ui/src/*
        dest: streamlit/
    meta:
      role: <your_app_pkg_owner_role>
      warehouse: <your_app_pkg_warehouse>
      post_deploy:
        - sql_script: scripts/any-provider-setup.sql
        - sql_script: scripts/shared-content.sql
  app:
    type: application
    identifier: <name_of_app>
    from:
      target: pkg
    debug: <true|false>
    meta:
      role: <your_app_owner_role>
      warehouse: <your_app_warehouse>
Copy

Propriedades comuns da entidade

A tabela a seguir descreve as propriedades comuns disponíveis para entidades de definição de projeto para o Native Apps. Consulte Especificação de entidades para obter mais informações sobre entidades de definição de projeto.

Propriedades comuns da entidade

Propriedade

Definição

tipo

obrigatório, cadeia de caracteres

O tipo de entidade a ser gerenciada. Para Snowflake Native App, os valores válidos incluem:

identifier

opcional, cadeia de caracteres

Identificador Snowflake opcional para a entidade; identificadores entre aspas e sem aspas são compatíveis. Para usar identificadores entre aspas, inclua as aspas ao redor do valor YAML (por exemplo ’”My Native Application Package”’).

Se não for especificado, o ID da entidade na definição do projeto será usado como identificador.

meta.warehouse

opcional, cadeia de caracteres

Warehouse usado para executar os scripts fornecidos como parte de meta.post_deploy, se houver comandos SQL dentro desses scripts exigem o uso do warehouse.

Padrão: warehouse especificado para a conexão no arquivo Snowflake CLI config.toml.

Nota

Se você não especificar um warehouse, o aplicativo passará na validação, mas não será instalado.

Normalmente, você especifica esse valor no snowflake.local.yml conforme descrito em Substituições de definição de projeto.

meta.role

opcional, cadeia de caracteres

Função a ser usada ao criar a entidade e os objetos do lado do provedor.

Nota

Se você não especificar uma função, o Snowflake CLI tenta usar a função padrão atribuída ao seu usuário na sua conta Snowflake.

Normalmente, você especifica esse valor no snowflake.local.yml conforme descrito em Substituições de definição de projeto.

Padrão: função especificada na conexão do Snowflake CLI

meta.post_deploy

opcional, sequência

Lista de scripts SQL a serem executados após a criação da entidade. O exemplo a seguir mostra como definir esses scripts no arquivo de definição do projeto:

definition_version: 2
entities:
  myapp_pkg:
    type: application package
    ...
    meta:
      post_deploy:
        - sql_script: scripts/post_deploy1.sql
        - sql_script: scripts/post_deploy2.sql
Copy

Esses scripts são invocados por comandos que criam ou atualizam uma entidade. Por exemplo, executar o comando snow app deploy executa esses scripts após a criação ou atualização de um pacote. Eles também são executados por snow app run se a instância do aplicativo não estiver sendo instalada diretamente de uma diretiva de versão ou lançamento.

Você também pode usar modelos nos scripts SQL pós-implementação, conforme mostrado no seguinte conteúdo de script de amostra:

GRANT reference_usage on database provider_data to share in entity <% fn.str_to_id(ctx.entities.myapp_pkg.identifier) %>
Copy

meta.use_mixins

opcional, sequência

Nomes de mixins a serem aplicados a esta entidade. Consulte Mixins de projeto para obter mais informações.

Propriedades da entidade do pacote de aplicativo

A tabela a seguir descreve as propriedades comuns disponíveis para entidades de pacote de aplicativo para o Native Apps. Consulte Especificação de entidades para obter mais informações sobre entidades de definição de projeto.

Propriedades para entidades de pacote de aplicativo

Propriedade

Definição

tipo

obrigatório, cadeia de caracteres

Deve ser application package.

manifest

obrigatório, cadeia de caracteres

A local do arquivo Snowflake Native App manifest.yml em seu projeto.

deploy_root

opcional, cadeia de caracteres

Subdiretório na raiz do projeto onde a etapa de construção copia os artefatos. Depois de copiados para este local, você pode implantá-los em um estágio Snowflake.

Padrão: output/deploy

generated_root

opcional, cadeia de caracteres

Subdiretório da raiz de implementação onde Snowflake CLI grava os arquivos gerados.

Padrão: __generated

stage

opcional, cadeia de caracteres

Identificador do estágio que armazena os artefatos do aplicativo. O valor usa o formato <schema_name>.<stage_name>. O estágio fica dentro do objeto do pacote de aplicativo. Você pode alterar o nome para evitar conflitos de nomes.

Padrão: app_src.stage

artifacts

obrigatório, sequência

Lista de pares de origem e destino do arquivo para adicionar à raiz de implantação, bem como um processador de anotação Snowpark opcional. É possível usar as seguintes propriedades de artefato:

  • src: Caminho para o arquivo ou arquivos de origem do código

  • dest: Caminho para o diretório para implementar os artefatos.

    Os caminhos de destino que fazem referência a diretórios devem terminar com um /. O destino de um padrão glob que não termina com um / resulta em um erro. Se omitido, dest tem como padrão a mesma cadeia de caracteres que src.

    Você também pode passar uma cadeia de caracteres para cada item em vez de um dict; nesse caso o valor será tratado como src e dest.

  • processors: Nome do processador a ser usado para processar os arquivos de código src. Consulte Mais informações sobre processadores de artefatos para obter mais detalhes.

Se src refere-se a apenas um arquivo (não um glob), dest pode se referir a um <caminho de destino> ou um <caminho/nome>.

Você também pode passar uma cadeia de caracteres para cada item em vez de um dict, caso em que o valor é tratado como ambos src e dest.

Exemplo sem processador:

pkg:
  artifacts:
    - src: app/*
      dest: ./
    - src: streamlit/*
      dest: streamlit/
    - src: src/resources/images/snowflake.png
      dest: streamlit/
Copy

Exemplo com um processador:

pkg:
  artifacts:
    - src: qpp/*
      dest: ./
      processors:
          - name: snowpark
            properties:
              env:
                type: conda
                name: <conda_name>
Copy

distribution

opcional, cadeia de caracteres

Distribuição do pacote de aplicativo criado pelo Snowflake CLI. Ao executar comandos snow app, o Snowflake CLI avisa se o pacote de aplicativo com o qual você está trabalhando tiver um valor diferente para distribuição do que o definido na definição do projeto resolvido.

Padrão: Internal

scratch_stage

opcional, cadeia de caracteres

Identificador do estágio que armazena dados temporários usados por Snowflake CLI. O valor usa o formato <nome_do_esquema>.<nome_do_estágio>. O estágio fica dentro do objeto do pacote de aplicativo. Você pode alterar o nome para evitar conflitos de nomes.

Padrão: app_src.stage_snowflake_cli_scratch

Propriedades da entidade do aplicativo

A tabela a seguir descreve propriedades comuns disponíveis para entidades de aplicativo para o Native Apps. Consulte Especificação de entidades para obter mais informações sobre entidades de definição de projeto.

Propriedades para entidades de aplicativo

Propriedade

Definição

tipo

obrigatório, cadeia de caracteres

Deve ser application.

from.target

obrigatório, cadeia de caracteres

Pacote de aplicativo a partir do qual criar esta entidade de aplicativo. No exemplo a seguir, target define o nome de uma entidade no arquivo snowflake.yml.

from:
  target: my_pkg
Copy

debug

opcional, booleano

Se deve habilitar o modo de depuração ao usar um estágio nomeado para criar um aplicativo.

Padrão: True

Mais informações sobre processadores de artefatos

Se você incluir o campo artifacts.processors no arquivo de definição do projeto, o comando snow app bundle invocará o processamento personalizado para arquivos de código Python no diretório ou arquivo src.

Esta seção abrange uma lista de processadores compatíveis.

Processador Snowpark

Um dos processadores compatíveis com Snowflake CLI é snowpark, que aplica o processamento de anotação do Snowpark a arquivos Python. A seguir, mostramos a estrutura básica e a sintaxe para diferentes ambientes de processamento:

  • Para executar código em um ambiente conda, use o seguinte:

    pkg:
  artifacts:
    - src: <some_src>
      dest: <some_dest>
      processors:
          - name: snowpark
            properties:
              env:
                type: conda
                name: <conda_name>
    Copy

    onde <conda_name> é o nome do ambiente conda com o interpretador Python e a biblioteca Snowpark que você deseja usar para o processamento de anotações do Snowpark.

  • Para executar código em um ambiente virtual Python, use o seguinte:

    pkg:
  artifacts:
    - src: <some_src>
      dest: <some_dest>
      processors:
          - name: snowpark
            properties:
              env:
                type: venv
                path: <venv_path>
    Copy

    onde <venv_path> é o caminho do ambiente virtual Python com o interpretador Python e a biblioteca Snowpark que você deseja usar para o processamento de anotações do Snowpark. O caminho pode ser absoluto ou relativo ao diretório do projeto.

  • Para executar código no ambiente atualmente ativo, use qualquer uma das seguintes definições equivalentes:

    pkg:
  artifacts:
    - src: <some_src>
      dest: <some_dest>
      processors:
          - name: snowpark
            properties:
              env:
                type: current
    Copy

    ou

    pkg:
  artifacts:
    - src: <some_src>
      dest: <some_dest>
      processors:
          - name: snowpark
    Copy

    ou

    pkg:
  artifacts:
    - src: <some_src>
      dest: <some_dest>
      processors:
          - snowpark
    Copy

Para obter mais informações sobre processamento personalizado, consulte Geração automática de código SQL e o comando snow app bundle.

Processador de modelos

Os projetos Snowflake Native App oferecem suporte a modelos em arquivos arbitrários, o que permite expandir modelos em todos os arquivos no diretório src de um artefato. É possível habilitar esse recurso incluindo um processador de modelos na definição de artefatos desejada, conforme mostrado no exemplo a seguir:

definition_version: 2
entities:
  pkg:
    type: application package
    identifier: myapp_pkg
    artifacts:
      - src: app/*
        dest: ./
        processors:
          - templates
    manifest: app/manifest.yml
  app:
    type: application
    identifier: myapp_<% fn.get_username() %>
    from:
      target: pkg
Copy

Quando Snowflake CLI carrega os arquivos para um estágio, ele expande automaticamente os modelos antes de carregá-los. Por exemplo, suponha que seu aplicativo contenha um arquivo app/README.md com o seguinte conteúdo que inclui o modelo codenowrap:<% ctx.entities.pkg.identifier %>:

This is a README file for application package <% ctx.entities.pkg.identifier %>.
Copy

O modelo é então expandido para o seguinte antes de carregar o arquivo para um estágio:

This is a README file for application package myapp_pkg.
Copy

Substituições de definição de projeto

Embora o diretório do seu projeto deva ter um arquivo snowflake.yml, você pode escolher personalizar o comportamento do Snowflake CLI fornecendo substituições locais para snowflake.yml, como uma nova função para testar seu próprio pacote de aplicativos. Essas substituições devem ser colocadas no arquivo snowflake.local.yml que fica ao lado da definição do projeto base. A Snowflake sugere que você adicione isso ao seu arquivo .gitignore para que ele não seja controlado por versão pelo git. Todos os modelos fornecidos pela Snowflake já o incluem no arquivo .gitignore.

Este arquivo de substituição deve estar no mesmo local que o seu arquivo snowflake.yml.

O arquivo snowflake.local.yml compartilha o esquema exato como snowflake.yml, exceto que cada valor que era obrigatório agora é opcional, além dos já opcionais. A seguir mostramos um exemplo do arquivo snowflake.local.yml:

entities:
  pkg:
    meta:
      role: <your_app_pkg_owner_role>
      name: <name_of_app_pkg>
      warehouse: <your_app_pkg_warehouse>
  app:
    debug: <true|false>
    meta:
      role: <your_app_owner_role>
      name: <name_of_app>
      warehouse: <your_app_warehouse>
Copy

Todo o comando snow app prioriza os parâmetros neste arquivo sobre aqueles definidos na base do arquivo de configuração snowflake.yml. Padrões sensíveis já fornecem isolamento entre desenvolvedores que usam a mesma conta Snowflake para desenvolver o mesmo projeto de aplicativo, portanto, se você estiver apenas começando, sugerimos não incluir um arquivo de substituição.

O esquema de definição final obtido após a substituição de snowflake.yml por snowflake.local.yml é chamado de definição de projeto resolvido.

Limitações

Atualmente, o Snowflake CLI não oferece suporte

  • Vários arquivos de substituição.

  • Um arquivo de substituição em branco. Crie este arquivo somente se desejar substituir um valor de snowflake.yml.

Linguagem: Português