Pacotes de aplicativo no compartilhamento declarativo do Native Application Framework¶
Como provedor, você cria um pacote de aplicativo para agrupar seu conteúdo de dados e notebooks em um pacote Declarative Native App. Este tópico explica o que é um pacote do app e descreve as etapas gerais para criar um, desde a criação do pacote inicial até a adição dos arquivos de manifesto e notebook.
O pacote do aplicativo e a versão ativa¶
O pacote do app é um contêiner para todos os arquivos que compõem o aplicativo, incluindo o arquivo de manifesto e quaisquer notebooks Snowflake. Quando você cria um pacote do app, uma versão ativa (em preparação) do pacote também é criada. A versão ativa é um espaço de trabalho de desenvolvimento em que é possível adicionar ou atualizar arquivos, como o arquivo de manifesto e os arquivos do notebook, assim como ver uma versão preliminar e testar a experiência antes de publicar.
Quando estiver satisfeito com a versão ativa do aplicativo, você poderá confirmar a versão ativa para criar uma nova versão imutável do pacote do aplicativo, que poderá ser publicada.
O uso da versão ativa no desenvolvimento simplifica o gerenciamento de versões, mantendo uma versão única e imutável do pacote do app que está pronta para ser publicada e uma versão única ativa para desenvolvimento. O Snowflake Native App Framework gerencia automaticamente o controle de versão do pacote do app, para que você não precise rastrear manualmente os números das versões.
O Snowflake Native App Framework automaticamente mantém uma versão ativa para qualquer pacote do app. Mesmo que a versão ativa seja removida, uma nova versão ativa será criada automaticamente a partir da última versão confirmada do pacote do app.
Criação de um pacote de aplicativo¶
Os provedores desenvolvem e testam um pacote de aplicativo (app). Um pacote do app inclui os arquivos necessários para compartilhar os dados no aplicativo e define como esses dados podem ser acessados pelos consumidores.
Esse processo envolve as seguintes etapas:
Criar um projeto de pacote do app (somente na primeira vez): cria um projeto de pacote do app que será publicado posteriormente. Isso também cria a versão ativa do pacote do app.
Adicionar conteúdo ao pacote do app:
Create or update a manifest file: este arquivo descreve o pacote do app e o conteúdo dele.
Download notebook files. Se você precisar incluir notebooks, baixe uma cópia para ser incluída no pacote do app.
Adicione os arquivos à versão ativa do pacote do app**.
Crie o pacote do app: permite verificar se o arquivo de manifesto é válido e se todos os links no arquivo de manifesto estão corretos.
Teste o app. Instale o aplicativo e experimente. Faça alterações e reconstrua.
Confirme o pacote do app: cria uma nova versão imutável do aplicativo que pode ser publicada.
Lance o pacote do app. Com um pacote lançado, você pode criar uma nova listagem de maneira privada ou pública no Snowflake Marketplace.
Esse processo é descrito em Tutorial: Introdução às Declarative Native Apps. Esta seção inclui mais detalhes sobre as opções disponíveis nas diferentes etapas de desenvolvimento.
Criação de um novo pacote de aplicativo¶
Primeiro, crie um novo pacote Declarative Native App para armazenar os arquivos do aplicativo, usando os comandos SQL ou Snowsight pela CLI do Snowflake, com o esquema do URL snow://package/<DECL_SHARE_APP_PKG>/versions/LIVE/.
Para usar o Snowsight para criar um novo pacote do app:
Faça login na Snowsight.
No menu de navegação, selecione Projects » App Packages.
No cartão Share Data + Code, selecione Create.
Insira um nome para o seu pacote do app e selecione Create.
Para usar SQL na CLI do Snowflake para criar um novo pacote do app:
Crie um pacote Declarative Native App usando o comando CREATE APPLICATION PACKAGE … TYPE=DATA, substituindo
<DECL_SHARE_APP_PKG>pelo nome que você deseja dar ao pacote do app:
snow sql -q "CREATE APPLICATION PACKAGE <DECL_SHARE_APP_PKG> TYPE = DATA;"
O novo pacote do app vazio é criado. Isso também cria uma versão ativa do pacote do app que você pode editar.
Reunir o conteúdo do pacote do aplicativo¶
Um pacote do app inclui os seguintes componentes:
Um arquivo de manifesto (obrigatório): um arquivo baseado em texto que define a estrutura do aplicativo.
Arquivos Snowflake Notebook (opcional): um ou mais arquivos baseados em texto que podem servir como interface para a experiência do usuário, referenciando as exibições e tabelas compartilhadas. Eles também podem incluir código, fazer referência a exibições e incluir lógica para ajudar a apresentar os dados.
Criação ou atualização de um arquivo de manifesto¶
Você pode criar ou atualizar um arquivo de manifesto, que descreve o pacote do app e o conteúdo compartilhado; por exemplo, notebooks, tabelas e exibições. Ele define outros metadados, como as funções de aplicativo incluídas.
O arquivo de manifesto deve ter o nome manifest.yml e ser adicionado à raiz do pacote do app.
Para obter mais informações, consulte Referência do manifesto Declarative Native App. O Tutorial: Introdução às Declarative Native Apps associado inclui um exemplo de arquivo de manifesto.
Obter arquivos de notebook¶
Caso seja necessário incluir os notebooks Snowflake no aplicativo, baixe uma cópia de cada arquivo de notebook para que você possa incluí-lo no pacote do app.
Pelo Snowsight:
No menu de navegação, selecione Projects » Notebooks e depois o notebook que você quer baixar.
No painel esquerdo, ao lado do notebook, selecione … » Download.
O arquivo é baixado na sua máquina local, com o nome <notebook_name>.ipynb.
Nota
O ambiente de notebook tem um conjunto de pacotes Anaconda pré-instalados, incluindo Python e Streamlit. Caso seu notebook use outros pacotes Anaconda, você deverá adicioná-los aos seus pacotes em seu notebook para que possam ser usados no ambiente do consumidor. Para saber como adicionar pacotes Anaconda ao seu notebook, consulte Adicionar pacotes Anaconda a um notebook.
Adicionar arquivos à versão ativa¶
Adicione os arquivos de manifesto e notebook à versão ativa do pacote do app:
Para usar o Snowsight para preencher o pacote do app:
Se você ainda não estiver visualizando a lista de pacotes do app, no menu de navegação, selecione Projects » App Packages e, em seguida, selecione o pacote do app ao qual deseja adicionar arquivos.
Selecione Upload files. (Se você estiver substituindo ou adicionando arquivos, selecione Manage files e, em seguida, Upload files.)
Arraste os arquivos do notebook e o manifesto do seu disco rígido para a caixa de diálogo Upload files onde indicado ou selecione Browse para localizar e selecionar os arquivos.
Selecione Upload para carregar os arquivos para a área de preparação ativa e acionar uma compilação.
Para usar SQL no Snowflake CLI para preencher o pacote do app, use os comandos a seguir, substituindo os caminhos dos arquivos pelos seus próprios e
<DECL_SHARE_APP_PKG>pelo nome do pacote do app:Arquivo do manifesto:
snow sql -q "PUT file:////Users/test_user/Documents/manifest.yml snow://package/<DECL_SHARE_APP_PKG>/versions/LIVE/ OVERWRITE=TRUE AUTO_COMPRESS=false;"
Arquivo do notebook:
snow sql -q "PUT file:////Users/test_user/Documents/NOTEBOOK.ipynb snow://package/<DECL_SHARE_APP_PKG>/versions/LIVE/ OVERWRITE=TRUE AUTO_COMPRESS=false;"
Verifique se os arquivos estão no pacote do app com o seguinte comando:
snow sql -q "LIST snow://package/<DECL_SHARE_APP_PKG>/versions/LIVE"
A saída mostra os arquivos na versão de produção do pacote do app, semelhante ao seguinte:
+--------------------------------------------------------------------------------+ | name | size | md5 | last_modified | |-------------------------------+------+---------+-------------------------------| | /versions/live/manifest.yml | 304 | 843a... | Wed, 23 Jul 2025 08:27:26 GMT | | /versions/live/NOTEBOOK.ipynb | 832 | b014... | Wed, 23 Jul 2025 04:32:22 GMT | +--------------------------------------------------------------------------------+
Baixe um arquivo do pacote do aplicativo¶
Você pode baixar um arquivo do pacote do app usando o comando GET SQL no Snowflake CLI:
snow sql -q "GET snow://package/<DECL_SHARE_APP_PKG>/versions/LIVE/manifest.yml file://manifest.yml"
Remover conteúdo do pacote do aplicativo¶
Você pode remover arquivos do pacote do aplicativo.
Usando Snowsight:
Se você ainda não estiver visualizando a lista de pacotes do aplicativo, no menu de navegação, selecione Projects » App Packages e, em seguida, o pacote do app do qual deseja remover arquivos.
Selecione Manage files » Remove files.
Selecione os arquivos que deseja remover e, em seguida, Delete.
Na caixa de diálogo Remove files, escolha os arquivos a serem removidos e, em seguida, selecione Remove & build.
Uso do comando SQL REMOVE (ou RM) no Snowflake CLI:
snow sql -q "RM snow://package/<DECL_SHARE_APP_PKG>/versions/LIVE/manifest.yml"
Criação do pacote de aplicativo¶
Em seguida, crie uma versão testável do app.
No Snowsight:
Quando você carrega um conjunto completo de arquivos para o pacote do app, uma compilação é iniciada automaticamente.
Para executar uma compilação a qualquer outro momento, selecione o botão Build na página do pacote do app.
Se houver algum erro no arquivo de manifesto, a compilação falhará e fornecerá informações sobre como corrigir o erro. Corrija os erros e recrie o pacote do app.
O comando ALTER APPLICATION PACKAGE … BUILD cria uma versão testável do pacote do app e verifica se o arquivo de manifesto é válido e se todos os links funcionam.
ALTER APPLICATION PACKAGE <DECL_SHARE_APP_PKG> BUILD;
Se houver algum erro no arquivo de manifesto, a compilação falhará e fornecerá informações sobre como corrigir o erro. Corrija esses erros e recrie o pacote do app.
O aplicativo criado permanece no estado ativo e você pode continuar fazendo alterações no pacote do aplicativo.
Pule para frente!¶
Para atualizações que não exigem testes adicionais, você pode pular etapas criando, confirmando e liberando um pacote do app de uma só vez usando o comando ALTER APPLICATION PACKAGE … RELEASE LIVE VERSION.
ALTER APPLICATION PACKAGE <DECL_SHARE_APP_PKG> RELEASE LIVE VERSION;
Testagem do aplicativo¶
Após criar o pacote do app, você pode realizar testes básicos nele a partir do ambiente de produção.
Instale o aplicativo a partir de um pacote do app usando o comando CREATE APPLICATION … FROM APPLICATION PACKAGE, substituindo <DECL_SHARE_APP> pelo nome do aplicativo. Por exemplo:
CREATE APPLICATION <DECL_SHARE_APP> FROM APPLICATION PACKAGE <DECL_SHARE_APP_PKG>
Atualize os arquivos no pacote do app conforme necessário e, em seguida, verifique se funcionou usando o comando: ALTER APPLICATION PACKAGE … UPGRADE USING VERSION LIVE.
ALTER APPLICATION PACKAGE <DECL_SHARE_APP_PKG> UPGRADE USING VERSION LIVE;
Para testar alguns recursos, como funções do aplicativo, você deve primeiro liberar uma nova versão do pacote de aplicativo e, em seguida, testar usando uma conta de consumidor separada. Para obter mais informações, consulte Instalação de um Declarative Native App e Acesso ao conteúdo de um Declarative Native App.
Opcional: Redefinição de edições em uma versão ativa¶
Se as edições feitas na versão ativa do pacote do app não forem mais necessárias, você pode redefini-lo para o estado anterior às edições com o comando ALTER APPLICATION PACKAGE … ABORT LIVE VERSION.
ALTER APPLICATION PACKAGE <DECL_SHARE_APP_PKG> ABORT LIVE VERSION;
Quando você usa o comando anterior para remover a versão ativa atual, uma nova versão ativa é criada com o mesmo conteúdo da última versão confirmada do pacote do app. A versão ativa é redefinida para a última versão confirmada e todas as alterações feitas na versão ativa são descartadas.
Confirmação e lançamento do pacote do aplicativo¶
A confirmação do pacote do aplicativo cria uma nova versão imutável do aplicativo que não pode ser editada e está pronta para ser publicada. Lançar o pacote do app faz o seguinte:
Prepara um aplicativo confirmado para ser compartilhado com os consumidores.
Se o provedor já tiver compartilhado o aplicativo com os consumidores, a nova versão estará automaticamente disponível para eles.
Se já houver uma versão ativa do app no Snowflake Marketplace, a nova versão estará automaticamente disponível para os consumidores que instalaram o aplicativo.
Para usar o Snowsight para confirmar e lançar o pacote do app:
Se você ainda não estiver visualizando a lista de pacotes do app, no menu de navegação, selecione Projects » App Packages e, em seguida, o pacote do app que deseja lançar.
Selecione Commit & release.
Na caixa de diálogo de confirmação, selecione Acknowledge & continue.
O pacote do app confirmado é lançado e a versão ativa dele é removida. Uma nova versão ativa do pacote do app é criada a partir da nova versão confirmada para desenvolvimento posterior.
Depois de confirmar e lançar o pacote do app, a guia Latest release mostra o conteúdo do lançamento, que é o mesmo conteúdo da última compilação.
Em SQL, use os comandos ALTER APPLICATION PACKAGE conforme mostrado:
ALTER APPLICATION PACKAGE <DECL_SHARE_APP_PKG> COMMIT;
A versão ativa do pacote do app é removida. Uma nova versão ativa do pacote do app é criada a partir da nova versão confirmada para desenvolvimento posterior.
Em seguida, lance o pacote do app confirmado:
ALTER APPLICATION PACKAGE <DECL_SHARE_APP_PKG> RELEASE;
Você também pode criar, confirmar e lançar uma versão ativa do pacote do app, tudo de uma só vez:
ALTER APPLICATION PACKAGE <DECL_SHARE_APP_PKG> RELEASE LIVE VERSION;
Após lançar o pacote do app, você pode criar uma nova listagem para o aplicativo, seja de maneira privada ou pública, no Snowflake Marketplace. Para obter mais informações, consulte Criação de uma listagem usando compartilhamento declarativo.