Tutorial: Desenvolvimento de um aplicativo com o Native Apps Framework

Introdução

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

O tutorial usa a interface da Web Snowsight, mas você pode usar qualquer cliente Snowflake que ofereça suporte à execução de SQL, por exemplo, SnowSQL.

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 na Snowsight.

  • Publique seu aplicativo criando uma listagem privada.

  • Instale o aplicativo a partir de uma listagem privada.

Sobre provedores e consumidores

No contexto do Native Apps 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 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 Native Apps 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 antes de executar o tutorial. Um warehouse deve ser especificado para uma sessão e o warehouse deve estar em execução antes que consultas e outras instruções DML possam ser executadas na sessão. Consulte USE WAREHOUSE para obter detalhes.

Criação dos arquivos do aplicativo

Nesta seção, você criará um script de configuração e um arquivo do manifesto. Ambos os arquivos são exigidos pelo Native Apps 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.

Você aprenderá mais sobre esses dois 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.

Criação do script de configuração

Para criar o script de configuração, faça o seguinte:

  1. Em seu sistema de arquivos local, crie uma pasta chamada tutorial. Este será o diretório raiz para os arquivos externos do seu aplicativo.

    Nota

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

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

  3. Nesta pasta crie um novo arquivo chamado setup.sql.

    Nota

    Este tutorial se referirá a esta estrutura e nome de arquivo 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.

  4. Adicione a seguinte instrução SQL para este arquivo:

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

Você está adicionando esta linha como um espaço reservado porque o script de configuração não pode estar vazio.

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.

Para criar o arquivo readme.md para seu aplicativo:

  1. Na pasta tutorial, crie um arquivo chamado readme.md.

  2. Adicione o seguinte conteúdo a este arquivo:

    This is the readme file for the Hello Snowflake Application!
    
    Copy

Criação do arquivo do manifesto

O Native Apps Framework exige um arquivo do manifesto para cada aplicativo. O arquivo do manifesto contém metadados e parâmetros de configuração para um aplicativo.

Para criar o arquivo do manifesto:

  1. Na pasta tutorial, crie um arquivo chamado manifest.yml.

    Nota

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

  2. Adicione o seguinte conteúdo a este arquivo:

    manifest_version: 1
    artifacts:
      setup_script: scripts/setup.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 do script de configuração criado acima.

    Nota

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

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
  manifest.yml
  readme.md
  /scripts/
    setup.sql
Copy

Nesta seção, você aprendeu como criar o script de configuração e os arquivos do manifesto exigidos pelo Native Apps Framework. Embora o conteúdo adicionado a esses dois arquivos 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.

Criação de um pacote de aplicativo

Nesta seção, você criará um pacote de aplicativo que funcionará como um contêiner para os recursos necessários para seu aplicativo. Você executará as seguintes tarefas:

  • Criar um pacote de aplicativo.

  • Criar um estágio nomeado no pacote de aplicativo.

Criação de um pacote de aplicativo

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:

  1. Para conceder o privilégio CREATE APPLICATION PACKAGE para sua função, execute o seguinte comando:

    GRANT CREATE APPLICATION PACKAGE ON ACCOUNT TO ROLE accountadmin;
    
    Copy

    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.

  2. Para criar o pacote de aplicativo, execute o seguinte comando:

    CREATE APPLICATION PACKAGE hello_snowflake_package;
    
    Copy

    Nota

    Depois de executar este comando, o contexto atual muda para HELLO_SNOWFLAKE_PACKAGE.

  3. Para verificar se o pacote de aplicativo foi criado com sucesso, execute o seguinte comando:

    SHOW APPLICATION PACKAGES;
    
    Copy

    Você deveria ver HELLO_SNOWFLAKE_PACKAGE na coluna name da saída. Consulte SHOW APPLICATION PACKAGES para obter informações adicionais sobre este comando.

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 criar um pacote de aplicativo.

Criação de um estágio nomeado

Nesta seção, você criará um estágio nomeado para armazenar os arquivos exigidos pelo Native Apps Framework. Um estágio nomeado também é necessário para armazenar qualquer arquivo de código externo que você deseja incluir em seu aplicativo. O upload desses arquivos para um estágio nomeado os torna disponíveis ao criar seu aplicativo.

Para criar um estágio externo nomeado, faça o seguinte:

  1. Para definir o contexto para o pacote de aplicativo criado na seção anterior, execute o seguinte comando:

    USE APPLICATION PACKAGE hello_snowflake_package;
    
    Copy
  2. Para criar o esquema necessário para o estágio nomeado, execute o seguinte comando:

    CREATE SCHEMA stage_content;
    
    Copy
  3. Para criar o estágio nomeado, execute o seguinte comando.

    CREATE OR REPLACE STAGE hello_snowflake_package.stage_content.hello_snowflake_stage
      FILE_FORMAT = (TYPE = 'csv' FIELD_DELIMITER = '|' SKIP_HEADER = 1);
    
    Copy

    Esse comando cria o estágio nomeado no banco de dados e no esquema que você criou nas etapas anteriores.

    Nota

    Você deve incluir FILE_FORMAT = (TYPE = 'CSV' FIELD_DELIMITER = '|' SKIP_HEADER = 1); como parte deste comando. Estes não são opcionais.

Agora você tem um estágio nomeado dentro do pacote de aplicativo onde pode carregar os arquivos que usará para criar seu aplicativo.

Nota

Embora este tutorial use um estágio nomeado no pacote de aplicativo, isso não é um requisito. Você também pode usar um estágio nomeado que existe em um banco de dados e esquema fora do pacote de aplicativo.

Carregamento dos arquivos do aplicativo para o estágio nomeado

Na seção anterior, você criou um pacote de aplicativo que servirá como contêiner para seu aplicativo. Você também criou um estágio nomeado no pacote de aplicativo que contém os arquivos do aplicativo necessários.

Nesta seção, você fará upload desses arquivos para o estágio nomeado.

Para fazer upload de arquivos de aplicativo, siga um destes procedimentos:

  • Carregue os arquivos do aplicativo usando Snowsight conforme descrito em Preparação de arquivos usando o Snowsight

  • Carregue os arquivos do aplicativo usando SnowSQL executando os seguintes comandos:

    PUT file:///<path_to_your_root_folder>/tutorial/manifest.yml @hello_snowflake_package.stage_content.hello_snowflake_stage overwrite=true auto_compress=false;
    PUT file:///<path_to_your_root_folder>/tutorial/scripts/setup.sql @hello_snowflake_package.stage_content.hello_snowflake_stage/scripts overwrite=true auto_compress=false;
    PUT file:///<path_to_your_root_folder>/tutorial/readme.md @hello_snowflake_package.stage_content.hello_snowflake_stage overwrite=true auto_compress=false;
    
    Copy

    Nota

    Modifique o caminho nos exemplos acima para refletir o caminho para a pasta raiz do seu projeto.

Em sua planilha, execute o seguinte comando para verificar se o upload do arquivo foi bem-sucedido:

LIST @hello_snowflake_package.stage_content.hello_snowflake_stage;
Copy

Depois de executar este comando, você deve ver cada um dos arquivos listados conforme mostrado na saída a seguir:

+----------------------------------------+------+----------------------------------+-------------------------------+
| name                                   | size | md5                              | last_modified                 |
|----------------------------------------+------+----------------------------------+-------------------------------|
| hello_snowflake_stage/manifest.yml      |   80 | 9acab2ba718eebfa5f98f4e95c822db6 | Mon, 29 May 2023 22:51:04 GMT |
| hello_snowflake_stage/readme.md         |   64 | 1bc95f95109dc60a09b478dd95c31808 | Mon, 29 May 2023 22:51:05 GMT |
| hello_snowflake_stage/scripts/setup.sql |   64 | 7807ee1f2f27312799fc83c66ba775cf | Mon, 29 May 2023 22:51:04 GMT |
+----------------------------------------+------+----------------------------------+-------------------------------+
Copy

Nesta seção, você carregou os arquivos do aplicativo para um estágio nomeado. Esses arquivos agora estão disponíveis para o pacote de aplicativo à medida que você continua a desenvolver seu aplicativo. Nas seções posteriores, à medida que adicionar recursos ao seu aplicativo, você retornará a esta seção para fazer upload de versões revisadas desses arquivos e de novos arquivos.

Adicione a lógica do aplicativo e instale seu primeiro aplicativo

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

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

  • Adicione uma versão ao aplicativo.

  • Instale e teste o aplicativo.

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

Na seção anterior, você criou um pacote de aplicativo. No entanto, o pacote de aplicativo ainda não contém nenhum conteúdo de dados ou arquivos de aplicativos.

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.sql que você criou em uma seção anterior:

    CREATE APPLICATION ROLE 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, 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 aplicativo.

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

  4. Carregue o script de configuração revisado para o estágio nomeado.

    Consulte a seção anterior Carregamento dos arquivos do aplicativo para o estágio nomeado para fazer upload do script de configuração revisado e retorne aqui para continuar o tutorial.

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

Instalação do aplicativo

Na seção anterior, você modificou o script de configuração para incluir um procedimento armazenado.

Nesta seção, você instalará o aplicativo e executará o procedimento armazenado usando Snowsight.

Para instalar um aplicativo, faça o seguinte:

  1. Para criar o aplicativo, execute o seguinte comando:

    CREATE APPLICATION HELLO_SNOWFLAKE_APP
      FROM APPLICATION PACKAGE HELLO_SNOWFLAKE_PACKAGE
      USING '@hello_snowflake_package.stage_content.hello_snowflake_stage';
    
    Copy
  2. Para verificar se o aplicativo foi criado com sucesso, execute o seguinte comando:

    SHOW APPLICATIONS;
    
    Copy

    Você deve ver o HELLO_SNOWFLAKE_APP listado sob a coluna name da saída.

  3. Para executar o procedimento armazenado HELLO que você adicionou a setup.sql em uma seção anterior, execute o seguinte comando:

    CALL core.hello();
    
    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 aplicativo usando o Native Apps 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.

  • Instalou e testou seu aplicativo executando o 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_PACAKAGE e concedendo privilégios para compartilhar esse banco de dados com o aplicativo.

Criação de um banco de dados para compartilhar com um aplicativo

Nesta seção, você aprenderá como compartilhar conteúdo de dados com um aplicativo. Especificamente, você compartilhará uma tabela no pacote do aplicativo.

Para criar uma tabela e inserir os dados de amostra no pacote do aplicativo:

  1. Para definir o contexto para o pacote de aplicativo, execute o seguinte comando:

    USE APPLICATION PACKAGE hello_snowflake_package;
    
    Copy
  2. Para criar uma tabela e adicionar o conteúdo de dados compartilhados, execute os seguintes comandos:

    CREATE SCHEMA IF NOT EXISTS shared_data;
    CREATE TABLE IF NOT EXISTS accounts (ID INT, NAME VARCHAR, VALUE VARCHAR);
    INSERT INTO accounts VALUES
      (1, 'Nihar', 'Snowflake'),
      (2, 'Frank', 'Snowflake'),
      (3, 'Benoit', 'Snowflake'),
      (4, 'Steven', 'Acme');
    
    Copy
  3. Para verificar se o conteúdo dos dados foi inserido corretamente na tabela, execute o seguinte comando:

    SELECT * FROM accounts;
    
    Copy

    Na saída deste comando, você deve ver três colunas chamadas ID, NAME e VALUE. Você também deve ver os dados de cada linha, conforme mostrado no exemplo de saída a seguir:

    +----+----------+-----------+
    | ID | NAME     | VALUE     |
    |----+----------+-----------|
    |  1 | Nihar    | Snowflake |
    |  2 | Frank    | Snowflake |
    |  3 | Benoit   | Snowflake |
    |  4 | Steven   | Acme      |
    +----+----------+-----------+
    
    Copy
  4. Para conceder uso na tabela ACCOUNTS, execute os seguintes comandos:

    GRANT USAGE ON SCHEMA shared_data TO SHARE IN APPLICATION PACKAGE hello_snowflake_package;
    GRANT SELECT ON TABLE accounts TO SHARE IN APPLICATION PACKAGE hello_snowflake_package;
    
    Copy

    Conceder esses privilégios nos objetos dentro do pacote de aplicativo faz com que a tabela accounts fique disponível para todos os aplicativos instalados a partir do pacote de aplicativo.

    Nota

    Você deve conceder o privilégio USAGE em cada objeto dentro de um pacote de aplicativo que você deseja compartilhar com um consumidor em um aplicativo.

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 permite que o aplicativo acesse os dados na tabela ACCOUNTS que você criou na subseçã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 Native Apps 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.

  3. Carregue o script de configuração revisado para o estágio nomeado.

    Consulte a seção anterior Carregamento dos arquivos do aplicativo para o estágio nomeado para carregar os arquivos que você atualizou nesta seção, então retorne aqui para continuar o tutorial.

Teste do aplicativo atualizado

Nesta subseção, você irá reinstalar 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 excluir o aplicativo existente, execute o seguinte comando:

    DROP APPLICATION hello_snowflake_app;
    
    Copy
  2. Para criar uma nova versão do aplicativo, execute os seguintes comandos:

    CREATE APPLICATION hello_snowflake_app
      FROM APPLICATION PACKAGE hello_snowflake_package
      USING '@hello_snowflake_package.stage_content.hello_snowflake_stage';
    
    Copy
  3. Para verificar se a exibição funciona corretamente, execute o seguinte comando:

    SELECT * FROM code_schema.accounts_view;
    
    Copy

    A saída deste comando é idêntica ao comando SELECT que você executou ao configurar os dados de exemplo:

    +----+----------+-----------+
    | ID | NAME     | VALUE     |
    |----+----------+-----------|
    |  1 | Nihar    | Snowflake |
    |  2 | Frank    | Snowflake |
    |  3 | Benoit   | Snowflake |
    |  4 | Steven   | 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 uso de referência na tabela ACCOUNTS para o pacote de aplicativo.

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

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

  • Conceder a seleção na exibição para a 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 para a função de aplicativo.

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

Observe que os comandos executados para configurar o banco de dados HELLO_SNOWFLAKE_DATA tem paralelos no script de configuração.

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.

Adicione 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 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.8'
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 na amostra 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.

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.8
      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, essas instruções criam uma UDF Python em um esquema e concedem 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á.

  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.

Nesta seção, você adicionou uma UDF 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

  1. Carregue os arquivos novos e revisados para o estágio nomeado.

    Consulte a seção Carregamento dos arquivos do aplicativo para o estágio nomeado para fazer upload do arquivo Python externo e, em seguida, retorne aqui para continuar o tutorial.

    Se você estiver usando SnowSQL para fazer upload do arquivo, execute os seguintes comandos:

    PUT file:///<path_to_your_root_folder>/tutorial/scripts/setup.sql @hello_snowflake_package.stage_content.hello_snowflake_stage/scripts overwrite=true auto_compress=false;
    PUT file:///<path_to_your_root_folder>/tutorial/python/hello_python.py @hello_snowflake_package.stage_content.hello_snowflake_stage/python overwrite=true auto_compress=false;
    
    Copy
  2. Para remover o aplicativo existente, execute o seguinte comando:

    DROP APPLICATION hello_snowflake_app;
    
    Copy
  3. Para criar uma nova versão do aplicativo, execute os seguintes comandos:

    CREATE APPLICATION hello_snowflake_app
      FROM APPLICATION PACKAGE hello_snowflake_package
      USING '@hello_snowflake_package.stage_content.hello_snowflake_stage';
    
    Copy
  4. Para testar o procedimento armazenado do Python, execute o seguinte comando:

    SELECT code_schema.addone(1);
    
    Copy
  5. Para testar a função Python referenciada, execute o seguinte comando:

    SELECT code_schema.multiply(1,2);
    
    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 aplicativo 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 nativo 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.context import get_active_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 = get_active_session()
    
    #  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

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.sql para criar o objeto Streamlit:

    CREATE STREAMLIT 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.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
  3. Carregue os arquivos de aplicativo novos e atualizados para o estágio nomeado:

    Consulte a seção anterior Carregamento dos arquivos do aplicativo para o estágio nomeado para carregar o arquivo Streamlit que você acabou de criar, então retorne aqui para continuar o tutorial.

    Se você estiver usando SnowSQL para fazer upload do arquivo, execute o seguinte comando:

    PUT file:///<path_to_your_root_folder>/tutorial/scripts/setup.sql @hello_snowflake_package.stage_content.hello_snowflake_stage/scripts overwrite=true auto_compress=false;
    PUT file:///<path_to_your_root_folder>/tutorial/streamlit/hello_snowflake.py @hello_snowflake_package.stage_content.hello_snowflake_stage/streamlit overwrite=true auto_compress=false;
    
    Copy

Instalação do aplicativo atualizado

  1. Carregue o script de configuração revisado para o estágio nomeado.

    Consulte a seção anterior Carregamento dos arquivos do aplicativo para o estágio nomeado para fazer upload do script de configuração revisado e retorne aqui para continuar o tutorial.

  2. Para remover o aplicativo anterior, execute o seguinte comando:

    DROP APPLICATION hello_snowflake_app;
    
    Copy
  3. Para criar uma nova versão do aplicativo, execute o seguinte comando:

    CREATE APPLICATION hello_snowflake_app
      FROM APPLICATION PACKAGE hello_snowflake_package
      USING '@hello_snowflake_package.stage_content.hello_snowflake_stage';
    
    Copy

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

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

  • Criar um aplicativo Streamlit.

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

Nesta seção, você adicionará uma versão ao seu aplicativo que inclui todas as funcionalidades adicionadas neste tutorial. Para fazer isso, você usará o comando ALTER APPLICATION PACKAGE para atualizar o pacote de aplicativo que você criou anteriormente.

Para adicionar uma versão ao seu aplicativo:

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

    ALTER APPLICATION PACKAGE hello_snowflake_package
      ADD VERSION v1_0 USING '@hello_snowflake_package.stage_content.hello_snowflake_stage';
    
    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. Para obter mais informações, consulte ALTER APPLICATION PACKAGE.

    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:

    SHOW VERSIONS IN APPLICATION PACKAGE hello_snowflake_package;
    
    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    | 2023-05-30 10:33:39.768 -0700 | NULL       | OFF       | OFF         | READY | NOT_REVIEWED  |
    +---------+-------+-------+---------+-------------------------------+------------+-----------+-------------+-------+---------------+
    
    Copy

    Para obter mais informações, consulte SHOW VERSIONS.

  3. Para instalar o aplicativo com base em uma versão, execute o seguinte comando:

    DROP APPLICATION hello_snowflake_app;
    CREATE APPLICATION hello_snowflake_app
      FROM APPLICATION PACKAGE hello_snowflake_package
      USING VERSION V1_0;
    
    Copy

Nesta seção, você modificou o pacote de aplicativo para incluir uma versão para seu aplicativo.

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. Entre em Snowsight.

  2. Mude para 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 readme.md em uma seção anterior.

  5. Para visualizar seu aplicativo Streamlit, selecione HELLOSNOWFLAKE_STREAMLIT.

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

  6. Selecione Projects » Worksheets para abrir o aplicativo em uma planilha Snowflake.

  7. Selecione HELLO_SNOWFLAKE_APP, em seguida selecione um esquema na lista.

    A lista de esquema corresponde ao esquema que você adicionou ao seu aplicativo durante o tutorial.

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.

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 uma diretriz de versão. Uma diretriz de versão especifica qual versão do seu aplicativo ficará disponível 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:

    SHOW VERSIONS IN APPLICATION PACKAGE hello_snowflake_package;
    
    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:

    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 permite que eles instalem e usem o aplicativo em suas contas.

Para criar uma listagem para seu aplicativo:

  1. Entre em 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

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. Entre em 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 onde 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 Native Apps Framework.

Ao longo do caminho, você: