Tutorial: Desenvolvimento de um Snowflake Native App com o Snowflake Native App Framework

Introdução

Este tutorial descreve como usar o Snowflake Native App Framework para criar um Snowflake Native App para compartilhar dados e lógica de negócios relacionada com outras contas Snowflake.

O tutorial usa ambas as interface da Web Snowflake CLI e Snowsight.

O que você aprenderá

Neste tutorial, você aprenderá como:

  • Crie um pacote de aplicativo que contenha os dados e a lógica de negócios de seu aplicativo.

  • Compartilhe dados com um pacote de aplicativo.

  • Adicione a lógica de negócios a um pacote de aplicativo.

  • Teste o aplicativo localmente.

  • Visualize e teste o aplicativo em Snowsight.

  • Publique seu aplicativo criando uma listagem privada.

  • Instale o aplicativo a partir de uma listagem privada.

  • Use Snowflake CLI para executar muitas das etapas acima.

Sobre provedores e consumidores

No contexto do Snowflake Native App Framework, os provedores são as funções e organizações que possuem dados e lógica de negócios que desejam compartilhar com outros usuários do Snowflake, que são os consumidores. Um consumidor pode ser outra conta em sua organização, uma organização diferente em sua empresa ou um usuário do Snowflake em outra empresa.

No contexto deste tutorial, a maioria das tarefas que você executará são aquelas normalmente executadas por provedores, mas incluem tarefas que podem ser executadas por várias funções em sua organização, incluindo desenvolvedores de aplicativos e administradores de banco de dados.

Neste tutorial, você também executará tarefas que imitam as ações executadas pelos consumidores para instalar um aplicativo.

Pré-requisitos

  • Você deve ter o Snowflake CLI instalado na sua máquina.

  • Você deve executar todos os comandos SQL na mesma sessão de comando SQL porque o contexto da sessão é necessário.

    Para fazer isso na Snowsight, por exemplo, cole todo o seu código na mesma planilha à medida que avança. À medida que você avança de uma seção para outra, cada seção se baseia na anterior.

  • Você deve ser capaz de usar a função ACCOUNTADMIN.

    Neste tutorial, você executará todas as etapas usando a função ACCOUNTADMIN. Na prática geral, no entanto, você deve usar funções com privilégios especificamente definidos para a ação que está executando. Por exemplo, você pode ter funções separadas para desenvolvedores que criam UDFs e procedimentos armazenados, para administradores de banco de dados que gerenciam funções e permissões e para administradores que gerenciam listagens usando o Snowflake Collaboration.

  • Para instalar seu aplicativo a partir de uma listagem privada, você deve ter acesso a uma segunda conta Snowflake. Você usará essa conta para imitar como os consumidores instalariam um aplicativo.

    Nota

    Embora o Snowflake Native App Framework ofereça suporte ao compartilhamento de aplicativos com contas em diferentes organizações, para fins deste tutorial, ambas as contas devem estar na mesma organização.

  • Você deve definir um warehouse atual. Consulte USE WAREHOUSE.

Criação dos arquivos do aplicativo

Nesta seção, você criará um script de configuração, um arquivo de manifesto e um arquivo de definição de projeto. Os dois primeiros arquivos são exigidos pelo Snowflake Native App Framework.

Script de configuração

Um script SQL que é executado automaticamente quando um consumidor instala um aplicativo em sua conta.

Arquivo do manifesto

Um arquivo YAML que contém informações básicas de configuração sobre o aplicativo.

Arquivo de definição do projeto

Um arquivo YAML que contém informações sobre os objetos Snowflake que você deseja criar.

Você aprenderá mais sobre esses arquivos e seus conteúdos ao longo deste tutorial. Você também criará um arquivo leia-me que será útil ao visualizar e publicar seu aplicativo nas seções posteriores deste tutorial.

Inicialização de uma nova pasta de projeto

Você vai usar Snowflake CLI para inicializar um novo projeto do Snowflake Native App no seu sistema de arquivos local.

Para fazer isso, execute o seguinte comando:

snow init --template app_basic tutorial
Copy

Este comando cria uma pasta chamada tutorial dentro do diretório de trabalho atual e o preenche com um projeto Snowflake Native App básico baseado em um modelo básico. Este é o diretório raiz de todos os arquivos do seu aplicativo.

Nota

Você modificará e adicionará arquivos e subpastas a essa pasta em seções posteriores.

Nota

Há outros modelos disponíveis para ajudar você a começar a usar Native Applications rapidamente. Consulte snow init --help para obter maiores informações.

Criação do script de configuração

Modifique ou substitua o conteúdo do arquivo app/setup_script.sql, conforme mostrado no exemplo a seguir:

-- Setup script for the Hello Snowflake! app.
Copy

Esta linha é um espaço reservado porque o script de configuração não pode ficar vazio.

Nota

Este tutorial faz referência a uma estrutura e nome de arquivo específicos para o script de configuração. No entanto, ao criar seu próprio aplicativo, você pode escolher seu próprio nome e estrutura de diretório para esse arquivo.

Criação de um arquivo README para seu aplicativo

Um arquivo leia-me fornece uma descrição do que seu aplicativo faz. Você verá o leia-me quando visualizar seu aplicativo na Snowsight.

Modifique ou substitua o conteúdo do arquivo app/README.md pelo seguinte:

This is the readme file for the Hello Snowflake app.
Copy

Criação do arquivo de manifesto

O Snowflake Native App Framework requer um arquivo de manifesto para cada aplicativo. O arquivo de manifesto contém metadados e parâmetros de configuração para um aplicativo e influencia o comportamento de tempo de execução do seu aplicativo.

Nota

Este arquivo deve ser nomeado manifest.yml. Os caminhos para outros arquivos, incluindo o script de configuração, são relativos ao local desse arquivo.

Modifique ou substitua o conteúdo do app/manifest.yml pelo seguinte:

manifest_version: 1
artifacts:
   setup_script: setup_script.sql
   readme: README.md
Copy

A propriedade setup_script especifica o local do script de configuração em relação ao local do arquivo do manifesto. O caminho e o nome do arquivo especificados aqui devem ser iguais ao local relativo do script de configuração que você modificou acima. A propriedade readme segue as mesmas regras.

Nota

As propriedades manifest_version, artifacts e setup_script são exigidas. A propriedade readme é opcional.

Criação do arquivo de definição do projeto

O Snowflake CLI usa um arquivo de definição de projeto para descrever objetos que podem ser implantados no Snowflake. Este arquivo deve ser nomeado snowflake.yml. Este arquivo controla o nome do pacote e do objeto do aplicativo implantado, bem como quais arquivos são carregados no estágio do projeto.

Nota

Este arquivo deve ser chamado snowflake.yml e deve existir no nível raiz do seu projeto. Os caminhos para outros arquivos, como manifest.yml e o script de configuração, são relativos ao local desse arquivo.

Modifique ou substitua o conteúdo do snowflake.yml pelo seguinte:

definition_version: 2
entities:
   hello_snowflake_package:
      type: application package
      stage: stage_content.hello_snowflake_stage
      manifest: app/manifest.yml
      artifacts:
         - src: app/*
           dest: ./
   hello_snowflake_app:
      type: application
      from:
         target: hello_snowflake_package
      debug: false
Copy

A próxima seção deste tutorial descreverá como usar cada uma dessas propriedades.

Revisão do que você aprendeu nesta seção

Depois de executar as etapas desta seção, você deve ter uma estrutura de diretório semelhante à seguinte:

/tutorial
  snowflake.yml
  README.md
  /app/
    manifest.yml
    README.md
    setup_script.sql
Copy

Nesta seção, você aprendeu a criar o script de configuração e os arquivos de manifesto exigidos pelo Snowflake Native App Framework e o arquivo de definição de projeto exigido pelo Snowflake CLI.

Embora o conteúdo adicionado ao script de configuração e ao arquivo de manifesto seja básico, todos os aplicativos devem ter esses arquivos.

Você também adicionou um arquivo leia-me que é exibido ao visualizar seu aplicativo na Snowsight ou ao publicar seu aplicativo como uma listagem.

Como é o arquivo de definição do projeto

Nesta seção você aprenderá sobre o conteúdo do arquivo de definição do projeto (snowflake.yml) que você criou na seção anterior. Você também executará tarefas de configuração adicionais para sua conta de provedor.

Basicamente, um pacote de aplicativo é um banco de dados Snowflake estendido para incluir informações adicionais sobre um aplicativo. Nesse sentido, é um contêiner para um aplicativo que inclui:

  • Conteúdo de dados compartilhados

  • Arquivos de aplicativos

Para criar um pacote de aplicativo, sua função deve ter o privilégio CREATE APPLICATION PACKAGE. Para conceder esse privilégio usando o Snowflake CLI, execute o seguinte comando:

snow sql -q 'GRANT CREATE APPLICATION PACKAGE ON ACCOUNT TO ROLE accountadmin' -c connection_name
Copy

onde connection_name é o nome da conexão que você especificou em seu arquivo config.toml quando instalou Snowflake CLI.

Nota

Apesar da função ACCOUNTADMIN ter esse privilégio por padrão, para poder criar um pacote de aplicativo, você deve garantir que sua função tenha esse privilégio concedido.

O arquivo de definição do projeto (snowflake.yml) define os nomes dos objetos que são criados na sua conta Snowflake:

  • O pacote de aplicativo (hello_snowflake_package)

  • O objeto de aplicativo (hello_snowflake_app) que é criado a partir do pacote do aplicativo

  • O estágio que contém os arquivos do aplicativo (stage_content.hello_snowflake_stage)

Observe que o nome do estágio é especificado como um nome qualificado pelo esquema. Este esquema é criado dentro do pacote do aplicativo. Este estágio nomeado é usado para armazenar os arquivos necessários para o Snowflake Native App Framework. Este estágio deve incluir todos os arquivos que você deseja disponibilizar para o script de configuração do seu aplicativo ou em tempo de execução.

Há também uma seção chamada artifacts no arquivo de definição do projeto, que é uma lista de regras que especificam quais arquivos são copiados para o estágio nomeado.

A regra especifica que qualquer coisa na subpasta app/ é copiada para a raiz do estágio. Isso significa o seguinte:

  • tutorial/app/manifest.yml é carregado para a raiz de @hello_snowflake_package.stage_content.hello_snowflake_stage.

  • tutorial/app/README.md é carregado para a raiz de @hello_snowflake_package.stage_content.hello_snowflake_stage.

  • tutorial/app/setup_script.sql é carregado para a raiz de @hello_snowflake_package.stage_content.hello_snowflake_stage.

Você ainda não está criando o pacote do aplicativo ou executando quaisquer comandos SQL que executam essas tarefas. Em uma seção posterior, você executará o comando do Snowflake CLI para executar essas tarefas.

Por fim, você define debug: false dentro da definição do aplicativo. Para aplicativos implantados usando o Snowflake CLI, o modo de depuração é habilitado por padrão.

Nesta seção você aprendeu que um pacote de aplicativo é um contêiner para os recursos usados por um aplicativo. Você também aprendeu como definir os campos no arquivo de definição do projeto.

Adição de lógica de aplicativo e instalação de seu primeiro aplicativo

Nesta seção, você adicionará código ao pacote do aplicativo e instalará seu primeiro aplicativo. Para fazer isso, você executará as seguintes tarefas:

  • Adicione um procedimento armazenado ao script de configuração.

  • Instale e teste o aplicativo no modo de desenvolvimento de estágio.

Adição de um procedimento armazenado ao script de configuração

Nesta seção, você adicionará um procedimento armazenado ao aplicativo adicionando o código do procedimento armazenado ao script de configuração em seu sistema de arquivos local.

Para adicionar um procedimento armazenado ao script de configuração:

  1. Adicione as seguintes instruções SQL no fim do arquivo setup_script.sql que você criou em uma seção anterior deste tutorial:

    CREATE APPLICATION ROLE IF NOT EXISTS app_public;
    CREATE SCHEMA IF NOT EXISTS core;
    GRANT USAGE ON SCHEMA core TO APPLICATION ROLE app_public;
    
    Copy

    Quando o script de configuração é executado durante a instalação do aplicativo, essas instruções criam uma função de aplicativo chamada app_public. As funções de aplicativo são semelhantes às funções de banco de dados, mas só podem ser usadas no contexto de um aplicativo. Elas são usadas para conceder acesso a objetos dentro do objeto do aplicativo criado na conta do consumidor.

    Este exemplo também cria um esquema para conter o procedimento armazenado e concede o privilégio USAGE no esquema para a função do aplicativo. Criar uma função de aplicativo e conceder privilégios em um objeto, por exemplo, um esquema, para a função de aplicativo é um padrão comum no script de configuração.

  2. Adicione o código para o procedimento armazenado no fim do arquivo setup_script.sql:

    CREATE OR REPLACE PROCEDURE CORE.HELLO()
      RETURNS STRING
      LANGUAGE SQL
      EXECUTE AS OWNER
      AS
      BEGIN
        RETURN 'Hello Snowflake!';
      END;
    
    Copy

    Este exemplo cria um procedimento armazenado que gera a cadeia de cadeia de caracteres «Hello Snowflake!».

  3. Adicione a seguinte instrução ao fim do arquivo setup_script.sql:

    GRANT USAGE ON PROCEDURE core.hello() TO APPLICATION ROLE app_public;
    
    Copy

    Este exemplo concede o privilégio USAGE no procedimento armazenado para a função de aplicativo.

Nesta seção, você adicionou um procedimento armazenado ao script de configuração. Você também criou uma função de aplicativo e concedeu o privilégio USAGE a esta função. Isso permite que o script de configuração crie o procedimento armazenado quando o aplicativo for instalado. Ele também dá permissão ao aplicativo para executar o procedimento armazenado.

Instalação e teste do aplicativo no modo de desenvolvimento de estágio

Agora você está pronto para criar o pacote do aplicativo, o aplicativo e todas as outras entidades especificadas no arquivo de definição do projeto.

Para executar essas tarefas, execute o seguinte comando do Snowflake CLI:

snow app run -c connection_name
Copy

onde connection_name é o nome da conexão que você especificou em seu arquivo config.toml quando instalou Snowflake CLI.

Este comando executa as seguintes tarefas:

  1. Crie um nome de pacote de aplicativo hello_snowflake_package com esquema stage_content e estágio hello_snowflake_stage.

  2. Carregue todos os arquivos necessários para o estágio nomeado.

  3. Crie ou atualize o aplicativo hello_snowflake_app usando arquivos desta estágio.

Se o comando for executado com sucesso, ele emitirá um URL onde você pode ver seu aplicativo em Snowsight. Para executar o procedimento armazenado HELLO que você adicionou a setup_script.sql em uma seção anterior, execute o seguinte comando do Snowflake CLI:

snow sql -q "call hello_snowflake_app.core.hello()" -c connection_name
Copy

Você deve ver a seguinte saída após executar este comando:

+------------------+
| HELLO            |
|------------------|
| Hello Snowflake! |
+------------------+
Copy

Revisão do que você aprendeu nesta seção

Parabéns! Você criou, instalou e testou seu primeiro Snowflake Native App usando o Snowflake Native App Framework ! Embora o aplicativo tenha apenas uma funcionalidade básica, os componentes usados para criar o aplicativo são os mesmos para aplicativos mais complexos.

Nesta seção, você concluiu o seguinte:

  • Adicionou um procedimento armazenado ao script de configuração. O script de configuração especifica como seu aplicativo é instalado na conta do consumidor. Nas seções seguintes, você adicionará conteúdo de dados e outros tipos de lógica de aplicativo ao seu aplicativo.

  • Implantou seu aplicativo pela primeira vez usando o Snowflake CLI.

  • Testou seu aplicativo instalado executando um procedimento armazenado.

Nas seções seguintes, você aprenderá sobre outras maneiras de visualizar e testar seu aplicativo.

Adição do conteúdo de dados ao seu aplicativo

Na seção anterior, você criou um aplicativo contendo um procedimento armazenado que demonstra como adicionar a lógica do aplicativo a um aplicativo.

Nesta seção, você incluirá conteúdo de dados em seu aplicativo criando um banco de dados dentro do pacote de aplicativo HELLO_SNOWFLAKE_PACKAGE e concedendo privilégios para compartilhar esse banco de dados com o aplicativo.

Criação de uma tabela para compartilhar com um aplicativo

Nesta seção, você aprenderá como compartilhar conteúdo de dados com um aplicativo. Especificamente, você compartilhará uma tabela na conta do provedor concedendo privilégios no esquema e na tabela ao pacote do aplicativo.

  1. Para criar uma tabela e inserir os dados de amostra no pacote do aplicativo, crie uma pasta tutorial/scripts e, em seguida, um arquivo shared_content.sql dentro da pasta. Adicione o seguinte conteúdo a este arquivo:

    USE APPLICATION PACKAGE <% ctx.entities.hello_snowflake_package.identifier %>;
    
    CREATE SCHEMA IF NOT EXISTS shared_data;
    USE SCHEMA shared_data;
    CREATE TABLE IF NOT EXISTS accounts (ID INT, NAME VARCHAR, VALUE VARCHAR);
    TRUNCATE TABLE accounts;
    INSERT INTO accounts VALUES
      (1, 'Joe', 'Snowflake'),
      (2, 'Nima', 'Snowflake'),
      (3, 'Sally', 'Snowflake'),
      (4, 'Juan', 'Acme');
    -- grant usage on the ``ACCOUNTS`` table
    GRANT USAGE ON SCHEMA shared_data TO SHARE IN APPLICATION PACKAGE <% ctx.entities.hello_snowflake_package.identifier %>;
    GRANT SELECT ON TABLE accounts TO SHARE IN APPLICATION PACKAGE <% ctx.entities.hello_snowflake_package.identifier %>;
    
    Copy

    Neste exemplo, <% ctx.entities.hello_snowflake_package.identifier %> é um modelo que é substituído pelo identificador resolvido de seu application package a partir do arquivo snowflake.yml ao executar um comando na Snowflake CLI.

    A concessão desses privilégios nos objetos do pacote de aplicativo torna a tabela shared_data.accounts disponível para todos os objetos criados a partir desse pacote de aplicativo. Este compartilhamento ocorre devido aos privilégios do comando GRANT TO SHARE no fim do script.

    Nota

    Você deve conceder o privilégio USAGE em cada esquema a um pacote de aplicativos para cada esquema que deseja compartilhar com um consumidor em um aplicativo. Você deve então conceder o privilégio SELECT nos objetos dentro do esquema que você deseja compartilhar.

  2. Adicione uma entrada ao arquivo de definição do projeto para garantir que este script seja executado quando você atualizar seu pacote de aplicativo. O arquivo de definição final do projeto deve ser:

    definition_version: 2
    entities:
       hello_snowflake_package:
          type: application package
          stage: stage_content.hello_snowflake_stage
          manifest: app/manifest.yml
          artifacts:
             - src: app/*
               dest: ./
          meta:
             post_deploy:
                - sql_script: scripts/shared_content.sql
       hello_snowflake_app:
          type: application
          from:
             target: hello_snowflake_package
          debug: false
    
    Copy

Nota

Como o script é executado diretamente da sua máquina local, não é necessário (nem recomendado) adicionar ganchos após a implementação à seção artifacts de seu arquivo de definição de projeto.

Nota

Como os ganchos pós-implementação são executados toda vez que você implementa um aplicativo, eles devem ser escritos de maneira idempotente.

Adição de uma exibição para acessar o conteúdo de dados

Nesta seção, você atualizará o script de configuração para adicionar uma exibição que permita que o consumidor que instalou o aplicativo acesse os dados na tabela ACCOUNTS que você criou na seção anterior.

Para adicionar uma exibição para acessar o conteúdo de dados:

  1. Para criar um esquema para a exibição, adicione o seguinte ao script de configuração:

    CREATE OR ALTER VERSIONED SCHEMA code_schema;
    GRANT USAGE ON SCHEMA code_schema TO APPLICATION ROLE app_public;
    
    Copy

    Essas instruções criam um esquema com versão para conter a exibição e conceder o privilégio USAGE no esquema. O Snowflake Native App Framework usa o esquema com versão para lidar com diferentes versões de funções e procedimentos armazenados.

  2. Para criar a exibição, adicione o seguinte ao script de configuração:

    CREATE VIEW IF NOT EXISTS code_schema.accounts_view
      AS SELECT ID, NAME, VALUE
      FROM shared_data.accounts;
    GRANT SELECT ON VIEW code_schema.accounts_view TO APPLICATION ROLE app_public;
    
    Copy

    Essas instruções criam a exibição no esquema code_schema e concedem o privilégio necessário na exibição para a função do aplicativo.

    Este script de configuração atualizado também será carregado no estágio na próxima vez que você implantar seu aplicativo usando o Snowflake CLI.

Teste do aplicativo atualizado

Nesta subseção, você atualizará o aplicativo e consultará a tabela de exemplo usando a exibição dentro do aplicativo instalado.

Para testar o aplicativo atualizado, faça o seguinte:

  1. Para atualizar o pacote do aplicativo e o objeto do aplicativo instalado na conta do consumidor, execute o seguinte comando:

    snow app run -c connection_name
    
    Copy

    onde connection_name é o nome da conexão que você especificou no arquivo config.toml quando você instalou o Snowflake CLI.

    Isso carrega todos os arquivos editados para o estágio, executa o script scripts/shared_content.sql e atualize o aplicativo usando esses arquivos no estágio.

  2. Para verificar se a exibição está funcionando corretamente, execute o seguinte comando:

    snow sql -q "SELECT * FROM hello_snowflake_app.code_schema.accounts_view" -c connection_name
    
    Copy

    A saída desse comando deveria ser:

    +----+----------+-----------+
    | ID | NAME     | VALUE     |
    |----+----------+-----------|
    |  1 | Joe      | Snowflake |
    |  2 | Nima     | Snowflake |
    |  3 | Sally    | Snowflake |
    |  4 | Juan     | Acme      |
    +----+----------+-----------+
    
    Copy

Revisão do que você aprendeu nesta seção

Nesta seção, você aprendeu como incluir conteúdo de dados compartilhados em seu aplicativo ao executar as seguintes tarefas:

  • Criar a tabela ACCOUNTS dentro do pacote de aplicativo e inserir dados na tabela.

  • Conceder o uso de referência na tabela ACCOUNTS para o pacote de aplicativo.

  • Criar um esquema e visualizar essas referências à tabela ACCOUNTS no pacote do aplicativo.

  • Conceder uso no esquema à função de aplicativo.

  • Conceder a seleção na exibição à função do aplicativo.

Você também atualizou o script de configuração para executar o seguinte quando o aplicativo é instalado:

  • Criar um esquema e exibição que o aplicativo usa para acessar os dados de exemplo.

  • Conceder uso no esquema à função de aplicativo.

  • Conceder a seleção na exibição à função do aplicativo.

Adição do código Python ao seu aplicativo

Nesta seção, você expandirá a funcionalidade de seu aplicativo adicionando o código Python para aprimorar a lógica do aplicativo. Nesta seção, você incluirá o código Python como o seguinte:

  • Uma UDF inline Python que é uma função autocontida no script de configuração.

  • Uma UDF Python que faz referência a um arquivo Python fora do script de configuração.

Nota

Embora esta seção apresente exemplos usando Python, as mesmas técnicas são aplicáveis a Java e JavaScript.

Adição de uma função Python inline como uma função definida pelo usuário (UDF)

Nesta seção, você adicionará uma função Python como uma UDF.

Para incluir uma UDF de Python em seu aplicativo, adicione o seguinte código ao seu arquivo de configuração.

CREATE OR REPLACE FUNCTION code_schema.addone(i int)
RETURNS INT
LANGUAGE PYTHON
RUNTIME_VERSION = '3.11'
HANDLER = 'addone_py'
AS
$$
def addone_py(i):
  return i+1
$$;

GRANT USAGE ON FUNCTION code_schema.addone(int) TO APPLICATION ROLE app_public;
Copy

Esses comandos executam as seguintes tarefas quando o aplicativo é instalado:

  • Criar um esquema com versão chamado code_schema.

  • Conceder o privilégio de uso no esquema à função de aplicativo APP_PUBLIC.

  • Criar a UDF ADDONE() no esquema code_schema.

  • Conceder o privilégio de uso na função à função de aplicativo APP_PUBLIC.

Observe que o esquema criado no exemplo de código acima é um esquema com versão. Funções definidas pelo usuário e procedimentos armazenados devem ser definidos em um esquema com versão em vez de um esquema normal. Isso evita que atualizações de aplicativos interfiram na execução simultânea de código.

Adição de um módulo Python externo

Para adicionar um módulo Python externo ao seu aplicativo:

  1. Adicione a seguinte função Python ao seu script de configuração:

    CREATE or REPLACE FUNCTION code_schema.multiply(num1 float, num2 float)
      RETURNS float
      LANGUAGE PYTHON
      RUNTIME_VERSION = 3.9
      IMPORTS = ('/python/hello_python.py')
      HANDLER='hello_python.multiply';
    
    GRANT USAGE ON FUNCTION code_schema.multiply(FLOAT, FLOAT) TO APPLICATION ROLE app_public;
    
    Copy

    Semelhante ao exemplo anterior, essa instrução cria uma UDF Python em um esquema e concede privilégios na função para a função de aplicativo. No entanto, este exemplo contém uma cláusula IMPORTS que se refere a um arquivo Python externo que você criará e incluirá em seu estágio nomeado.

  2. Na pasta tutorial, crie uma subpasta chamada python.

  3. Na subpasta python, crie um arquivo chamado hello_python.py.

  4. Adicione o seguinte ao arquivo hello_python.py:

    def multiply(num1, num2):
      return num1*num2
    
    Copy

    A função definida neste arquivo externo corresponde à função inline definida no script de configuração.

  5. Adicione o seguinte à seção artifacts existente do arquivo de definição do projeto:

    - python/hello_python.py
    
    Copy

Nesta seção, você adicionou uma UDF de Python ao seu aplicativo. Essa UDF refere-se a um módulo Python externo que pode ser referenciado por seu pacote de aplicativo.

Instalação e teste do aplicativo atualizado

Para instalar e testar o aplicativo:

  1. Para atualizar o pacote de aplicativo e o aplicativo, execute o seguinte comando:

    snow app run -c connection_name
    
    Copy

    onde connection_name é o nome da conexão que você especificou em seu config.toml ao instalar a Snowflake CLI.

    Este comando carrega os arquivos editados e novos para o estágio e atualiza seu aplicativo usando os arquivos no estágio.

  2. Para testar o procedimento armazenado do Python, execute o seguinte comando:

    snow sql -q "SELECT hello_snowflake_app.code_schema.addone(1)" -c connection_name
    
    Copy
  3. Para testar a função Python referenciada, execute o seguinte comando:

    snow sql -q "SELECT hello_snowflake_app.code_schema.multiply(1,2)" -c connection_name
    
    Copy

Revisão do que você aprendeu nesta seção

Nesta seção, você adicionou a seguinte nova funcionalidade ao seu aplicativo:

  • Uma função Python definida como uma UDF inline.

  • Uma função Python definida como uma UDF que faz referência ao código externo.

Você também testou cada um desses exemplos instalando uma versão atualizada de seu aplicativo e executando cada uma das funções.

Adição de um aplicativo Streamlit ao seu aplicativo

Nesta seção, você completará seu Snowflake Native App adicionando um aplicativo Streamlit. Streamlit é o framework Python de código aberto para o desenvolvimento de aplicativos de ciência de dados e aprendizado de máquina. Você pode incluir aplicativos Streamlit em um aplicativo para adicionar interação do usuário e visualização de dados.

Criação do arquivo do aplicativo Streamlit

Para criar um aplicativo Streamlit, faça o seguinte:

  1. Na pasta tutorial, crie uma subpasta chamada streamlit.

  2. Na pasta streamlit, crie um arquivo chamado hello_snowflake.py.

  3. Adicione o seguinte código a este arquivo:

    # Import python packages
    import streamlit as st
    from snowflake.snowpark import Session
    
    # Write directly to the app
    st.title("Hello Snowflake - Streamlit Edition")
    st.write(
       """The following data is from the accounts table in the application package.
          However, the Streamlit app queries this data from a view called
          code_schema.accounts_view.
       """
    )
    
    # Get the current credentials
    session = Session.builder.getOrCreate()
    
    #  Create an example data frame
    data_frame = session.sql("SELECT * FROM code_schema.accounts_view")
    
    # Execute the query and convert it into a Pandas data frame
    queried_data = data_frame.to_pandas()
    
    # Display the Pandas data frame as a Streamlit data frame.
    st.dataframe(queried_data, use_container_width=True)
    
    Copy
  4. Adicione o seguinte à seção artifacts existente do arquivo de definição do projeto:

    - streamlit/hello_snowflake.py
    
    Copy

Adição do objeto Streamlit ao script de configuração

Para criar o objeto Streamlit no aplicativo, faça o seguinte:

  1. Adicione a seguinte instrução no final do arquivo setup_script.sql para criar o objeto Streamlit:

    CREATE STREAMLIT IF NOT EXISTS code_schema.hello_snowflake_streamlit
      FROM '/streamlit'
      MAIN_FILE = '/hello_snowflake.py'
    ;
    
    Copy

    Esta instrução cria um objeto STREAMLIT no esquema principal.

  2. Adicione a seguinte instrução no fim do arquivo setup_script.sql para permitir que a função APP_PUBLIC acesse o objeto Streamlit:

    GRANT USAGE ON STREAMLIT code_schema.hello_snowflake_streamlit TO APPLICATION ROLE app_public;
    
    Copy

Instalação do aplicativo atualizado

  1. Para atualizar o pacote de aplicativo e o aplicativo, execute o seguinte comando:

    snow app run -c connection_name
    
    Copy

    onde connection_name é o nome da conexão que você especificou no arquivo config.toml quando você instalou o Snowflake CLI.

    Este comando carrega os arquivos editados e novos para o estágio e atualiza seu aplicativo usando esses arquivos no estágio. Você pode então navegar até o URL que esse comando imprime para ver seu novo Streamlit em ação; quando estiver lá, clique na guia chamada HELLO_SNOWFLAKE_STREAMLIT que aparece ao lado do nome do seu aplicativo.

Revisão do que você aprendeu nesta seção

Nesta seção, você adicionou um aplicativo Streamlit ao seu Snowflake Native App fazendo o seguinte:

  • Criando um arquivo python que usa a biblioteca Streamlit para renderizar uma interface de usuário.

  • Criando um aplicativo Streamlit em seu Snowflake Native App que exibe dados compartilhados.

Adição de uma versão ao seu aplicativo

Nas seções anteriores, você usou um modo de «desenvolvimento de estágio» para enviar alterações. O modo de desenvolvimento de estágio permite que você itere rapidamente o desenvolvimento do aplicativo sem precisar criar novas versões ou patches. No entanto, você deve criar uma versão de aplicativo para listar seu pacote de aplicativo e compartilhá-lo com outros usuários do Snowflake.

Nesta seção, você adicionará uma versão ao seu aplicativo que inclui todas as funcionalidades adicionadas neste tutorial.

  1. Para adicionar uma versão ao pacote de aplicativo HELLO_SNOWFLAKE_PACKAGE, execute o seguinte comando:

    snow app version create v1_0 -c connection_name
    
    Copy

    Neste comando, você modificou seu pacote de aplicativo para incluir uma versão com base nos arquivos do aplicativo que você carregou no estágio nomeado em uma seção anterior.

    Nota

    O valor especificado para VERSION é um rótulo, não um valor numérico ou cadeia de caracteres.

    Nota

    O número do patch para a nova versão que você adicionou é criado automaticamente em 0. À medida que você adiciona patches adicionais para uma versão, eles são incrementados automaticamente. No entanto, quando você cria uma nova versão, por exemplo V1_1, o número do patch dessa versão é redefinido para 0.

  2. Para verificar se a versão foi adicionada ao pacote de aplicativo, execute o seguinte comando:

    snow app version list -c connection_name
    
    Copy

    Este comando mostra informações adicionais sobre a versão, conforme mostrado na saída a seguir:

    +---------+-------+-------+---------+-------------------------------+------------+-----------+-------------+-------+---------------+
    | version | patch | label | comment | created_on                    | dropped_on | log_level | trace_level | state | review_status |
    |---------+-------+-------+---------+-------------------------------+------------+-----------+-------------+-------+---------------|
    | V1_0    |     0 | NULL  | NULL    | 2024-05-09 10:33:39.768 -0700 | NULL       | OFF       | OFF         | READY | NOT_REVIEWED  |
    +---------+-------+-------+---------+-------------------------------+------------+-----------+-------------+-------+---------------+
    
    Copy
  3. Para instalar o aplicativo com base em uma versão, execute o seguinte comando:

    snow app run --version V1_0 -c connection_name
    
    Copy

    Como o aplicativo existente foi criado usando arquivos no estágio nomeado, atualizar o aplicativo usando uma versão exige que o aplicativo existente seja descartado e recriado com esta versão. Responda sim ao prompt correspondente.

Nesta seção, você modificou o pacote de aplicativo para incluir uma versão para o seu aplicativo e recriou o objeto de aplicativo usando o modo de desenvolvimento com controle de versão.

Visualização de seu aplicativo no Snowsight

Nesta seção, você verá seu aplicativo na Snowsight. Nas seções anteriores, você usou instruções SQL para testar ou encontrar informações sobre seu aplicativo. No entanto, você também pode visualizar informações sobre seu aplicativo na Snowsight. Você também pode visualizar seu aplicativo Streamlit implantado.

Para visualizar seu aplicativo na Snowsight, faça o seguinte:

  1. Faça login no Snowsight.

  2. Mude para a função ACCOUNTADMIN fazendo o seguinte:

    1. No menu de navegação, selecione seu nome de usuário para abrir o menu da conta.

    2. Selecione a função ativa. Por exemplo, PUBLIC.

      O seletor de funções é exibido.

    3. Selecione a função ACCOUNTADMIN.

  3. Selecione Data Products » Apps.

  4. Selecione HELLO_SNOWFLAKE_APP.

    A aba Read Me exibe o conteúdo que você adicionou ao arquivo app/README.md em uma seção anterior.

  5. Para visualizar seu aplicativo Streamlit, selecione HELLO_SNOWFLAKE_STREAMLIT.

    O conteúdo do banco de dados HELLO_SNOWFLAKE_DATA é exibido em um dataframe Streamlit.

  6. Para abrir o aplicativo em uma planilha, selecione Projects » Worksheets.

  7. Selecione HELLO_SNOWFLAKE_APP na lista de planilhas.

  8. Se necessário, selecione o warehouse onde você instalou o aplicativo.

A partir da planilha Snowflake, você pode testar seu aplicativo usando comandos SQL. Por exemplo, você pode executar novamente os comandos executados nas seções anteriores para testar os recursos adicionados ao seu aplicativo:

LIST @hello_snowflake_package.stage_content.hello_snowflake_stage;
CALL core.hello();
SELECT * FROM code_schema.accounts_view;
SELECT code_schema.addone(10);
SELECT code_schema.multiply(2,3);
Copy

Nota

Qualquer instrução SQL que você adiciona a esta planilha é perdida quando você navega para uma página diferente na Snowsight.

Nota

Você também pode visualizar diretamente a interface do usuário do seu aplicativo usando o comando snow app open no Snowflake CLI. Este comando abre o URL apropriado no navegador da web configurado no seu sistema.

Publicação e instalação de seu aplicativo

Nesta seção, você publicará seu aplicativo criando uma listagem privada que usa o pacote de aplicativo como conteúdo de dados. Depois de criar a listagem, você fará login em outra conta para instalar a listagem.

Definição da diretriz de versão padrão

Antes de poder criar uma listagem para o pacote de aplicativo, você deve definir a diretriz de versão. Uma diretriz de versão especifica quais versões do seu aplicativo ficarão disponíveis para consumidores.

Neste tutorial, você definirá a diretriz de versão padrão usando a versão adicionada na seção anterior.

Para definir a diretriz de versão padrão para seu pacote de aplicativo, faça o seguinte:

  1. Para visualizar as versões e patches definidos para seu pacote de aplicativo, execute o seguinte comando:

    snow app version list -c connection_name
    
    Copy

    Este comando exibe as versões e patches definidos para o pacote de aplicativo.

  2. Para definir a diretriz de versão padrão para a versão v1_0 e patch 0, execute o seguinte comando:

    snow sql -q "ALTER APPLICATION PACKAGE hello_snowflake_package SET DEFAULT RELEASE DIRECTIVE VERSION = v1_0 PATCH = 0"
    
    Copy

    A saída desse comando é mostrada no exemplo a seguir:

    +-----------------------------------------------------------+
    | status                                                    |
    |-----------------------------------------------------------|
    | Default release directive set to version 'V1_0', patch 0. |
    +-----------------------------------------------------------+
    
    Copy

Nesta seção, você verificou quais versões e patches existem em seu pacote de aplicativo. Usando essas informações, você definiu a diretriz de versão padrão para o pacote de aplicativo.

Criação de uma listagem para seu aplicativo

Agora que você especificou uma diretriz de versão para seu pacote de aplicativo, criará uma listagem e incluirá o pacote de aplicativo como o conteúdo de dados da listagem. Isso permite que você compartilhe seu aplicativo com outros usuários do Snowflake e que eles instalem e usem o aplicativo em suas contas.

Para criar uma listagem para seu aplicativo:

  1. Faça login no Snowsight.

  2. No menu de navegação, selecione Data Products » Provider Studio.

  3. Selecione + Listing. A janela Criar listagem é aberta.

  4. Digite um nome para sua listagem.

  5. Na seção In the Who can discover the listing, selecione Only specified consumers para compartilhar privadamente a listagem com contas específicas.

  6. Clique em + Select para selecionar o pacote de aplicativo para a listagem.

  7. Digite uma descrição para sua listagem.

  8. Na seção Add consumer accounts, adicione o identificador da conta que você está usando para testar a experiência do consumidor de instalar o aplicativo a partir de uma listagem.

Nesta seção, você criou uma listagem privada contendo seu pacote de aplicativo como conteúdo de dados compartilhados.

Instalação do aplicativo em uma conta de consumidor

Nesta seção você instalará o aplicativo associado à listagem que você criou na seção anterior. Você instalará a listagem em uma conta diferente, que imitará como um consumidor instalaria o aplicativo em sua conta.

Para instalar seu aplicativo da listagem, faça o seguinte:

  1. Faça login no Snowsight.

  2. No menu de navegação, selecione Data Products » Apps.

  3. Selecione o bloco para a listagem em Recently shared with you.

  4. Selecione Get.

  5. Digite um nome voltado ao cliente para o aplicativo. Para este tutorial, use «Hello Snowflake App».

  6. Selecione o warehouse em que deseja instalar o aplicativo.

  7. Selecione Get.

  8. Selecione Open para ver sua listagem ou Done para terminar.

Nesta seção, você aprendeu como publicar e instalar uma listagem que permite compartilhar seu aplicativo com outros usuários do Snowflake.

Saiba mais

Parabéns! Você não apenas concluiu este tutorial, mas também trabalhou no ciclo de vida de desenvolvimento e publicação de um aplicativo usando o Snowflake Native App Framework.

Ao longo do caminho, você: