教程 1：创建基本的 Snowflake Native App¶

在本教程中学习的内容¶

在本教程中，您将学习如何执行以下操作：

• 创建包含应用程序数据和业务逻辑的应用程序包。

• 与应用程序包共享数据。

• 向应用程序包中添加业务逻辑。

• 在本地测试应用程序。

• 在 Snowsight 中查看并测试应用程序。

• 通过创建专用列表来发布应用程序。

• 从专用列表安装应用程序。

• 使用 Snowflake CLI 执行上述许多步骤。

关于提供商和使用者¶

在 Snowflake Native App Framework 的上下文中，提供商是拥有数据和业务逻辑并希望与其他 Snowflake 用户（即使用者）共享的角色和组织。使用者可以是组织内的另一个账户、公司内的其他组织或另一家公司的 Snowflake 用户。

在本教程中，您要执行的大多数任务通常由提供商执行，但这些任务可能由您的组织内的多个角色执行，包括应用程序开发者和数据库管理员。

在本教程中，您还会执行任务，模拟使用者安装应用程序所执行的操作。

先决条件¶

• 您的计算机上必须已安装 Snowflake CLI。

• 必须在同一个 SQL 命令会话中运行所有 SQL 命令，因为需要会话上下文。

  例如，要在 Snowsight 中执行此操作，请将所有代码粘贴到同一个工作表中。在从一个部分推进到另外一个部分时，每个部分都以前一个部分为基础。

• 必须能够使用 ACCOUNTADMIN 角色。

  在本教程中，您将使用 ACCOUNTADMIN 角色执行所有步骤。但在一般情况下，您使用的角色具有专为正在执行的操作而定义的权限。例如，可以为创建 UDFs 和存储过程的开发者、管理角色和权限的数据库管理员以及使用 Snowflake Collaboration 管理列表 的管理员设置不同的角色。

• 要从专用列表安装应用程序，必须能够访问第二个 Snowflake 账户。您可以使用此账户来模拟使用者安装应用程序的方式。

  备注

  尽管 Snowflake Native App Framework 支持与不同组织中的账户共享应用程序，但就本教程而言，两个账户必须位于同一组织中。

• 您必须设置当前仓库。请参阅 USE WAREHOUSE。

初始化新项目文件夹¶

您可以使用 Snowflake CLI 在本地文件系统中初始化一个新的 Snowflake Native App 项目。

要执行此操作，请执行以下命令：

snow init --template app_basic tutorial

Copy

该命令在当前工作目录下创建一个名为 tutorial 的文件夹，并根据基本模板填充一个基本的 Snowflake Native App 项目。这是所有应用程序文件的根目录。

创建安装脚本¶

如以下示例所示，修改或替换 app/setup_script.sql 文件的内容：

-- Setup script for the Hello Snowflake! app.

Copy

这一行是占位符，因为安装脚本不能为空。

备注

本教程引用特定结构和文件名作为安装脚本。但是，在构建自己的应用程序时，可以为此文件选择自己的名称和目录结构。

为应用程序创建 README 文件¶

自述文件提供应用程序功能的描述。在 Snowsight 中查看应用程序时，将看到自述文件。

用以下内容修改或替换 app/README.md 的内容：

This is the readme file for the Hello Snowflake app.

Copy

创建清单文件¶

Snowflake Native App Framework 要求每个应用程序都有一个清单文件。清单文件包含应用程序的元数据和配置参数，会影响应用程序的运行时行为。

用以下内容修改或替换 app/manifest.yml 的内容：

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

setup_script 属性指定安装脚本相对于清单文件位置的位置。此处指定的路径和文件名必须与上面修改的安装脚本的相对位置相同。readme 属性遵循相同的规则。

创建项目定义文件¶

Snowflake CLI 使用项目定义文件来描述可部署到 Snowflake 的对象。此文件必须命名为 snowflake.yml。此文件控制部署的应用程序包和对象的名称，以及哪些文件会上传到项目暂存区。

备注

此文件必须命名为 snowflake.yml，并且必须位于项目的根级别。其他文件（如 manifest.yml 和安装脚本）的路径与此文件的位置相关。

用以下内容修改或替换 snowflake.yml 的内容：

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

Copy

本教程的下一部分将介绍如何使用这些属性。

回顾本部分所学内容¶

执行完本部分中的步骤后，现在应该拥有如下所示的目录结构：

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

在本部分中，学习了如何创建 Snowflake Native App Framework 所需的安装脚本和清单文件，以及 Snowflake CLI 所需的项目定义文件。

虽然添加到安装脚本和清单文件中的内容都是基本的，但所有应用程序都必须具有这些文件。

还添加了自述文件，在 Snowsight 中查看应用程序或以列表形式发布应用程序时会显示该文件。

向安装脚本添加存储过程¶

在本部分中，将通过将存储过程的代码添加到本地文件系统上的安装脚本，来向应用程序添加存储过程。

要将存储过程添加到安装脚本，请执行以下操作：

1. 在本教程之前部分中创建的 setup_script.sql 文件的末尾添加以下 SQL 语句：

   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

   当安装脚本在应用程序安装过程中运行时，这些语句会创建一个名为 app_public 的应用程序角色。应用程序角色与数据库角色类似，但只能在应用程序上下文中使用。它们用于向在使用者账户中创建的应用程序对象中的对象授予访问权限。

   此示例还创建了一个包含存储过程的架构，并将该架构的 USAGE 权限授予应用程序角色。创建应用程序角色并向应用程序角色授予对象（例如架构）的权限是安装脚本中的常见模式。

2. 在 setup_script.sql 文件的末尾添加存储过程的代码：

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

   Copy

   此示例创建一个输出字符串“Hello Snowflake!”的存储过程。

3. 将以下语句添加到 setup_script.sql 文件的末尾：

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

   Copy

   此示例将对存储过程的 USAGE 权限授予应用程序角色。

在本部分中，向安装脚本添加了一个存储过程。还创建了一个应用程序角色，并向该角色授予了 USAGE 权限。这样，安装脚本就可以在安装应用程序时创建存储过程。它还授予应用程序运行存储过程的权限。

在暂存区开发模式下安装并测试应用程序。¶

现在您已准备好创建应用程序包、应用程序和您在项目定义文件中指定的所有其他实体。

要执行这些任务，请运行以下 Snowflake CLI 命令：

snow app run -c connection_name

Copy

其中 connection_name 是您安装 Snowflake CLI 时在 config.toml 文件中指定的连接名称。

该命令执行以下任务：

1. 创建应用程序包，名称为 hello_snowflake_package，架构为 stage_content，暂存区为 hello_snowflake_stage。

2. 将所有所需文件上传到指定的暂存区。

3. 使用暂存区中的文件创建或升级应用程序 hello_snowflake_app。

如果命令运行成功，它将输出一个 URL，您可以在 Snowsight 中查看应用程序。要运行您在上一部分中添加到 setup_script.sql 的 HELLO 存储过程，请运行以下 Snowflake CLI 命令：

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

运行此命令后应该看到以下输出：

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

回顾本部分所学内容¶

恭喜！您已使用 Snowflake Native App Framework 创建、安装并测试了第一个 Snowflake Native App！尽管该应用程序仅具有基本功能，但用于构建应用程序的组件与更复杂的应用程序相同。

在本部分中，完成了以下操作：

• 在安装脚本中添加了存储过程。安装脚本指定了应用程序如何安装在使用者账户中。在后面的部分中，将向应用程序添加数据内容和其他类型的应用程序逻辑。

• 使用 Snowflake CLI 首次部署了应用程序。

• 通过运行存储过程测试了已安装的应用程序。

在后面的部分中，将了解查看和测试应用程序的其他方法。

创建与应用程序共享的表¶

在本部分中将了解如何与应用程序共享数据内容。具体来说，通过向应用程序包授予对架构和表的权限，在提供商账户中共享表。

1. 要在应用程序包中创建表并插入示例数据，请创建文件夹 tutorial/scripts，然后在文件夹内创建文件 shared_content.sql。在此文件中添加以下内容：

   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

   在此示例中，当您执行 Snowflake CLI 命令时，<% ctx.entities.hello_snowflake_package.identifier %> is a template that is replaced by the resolved identifier of your 应用程序包 来自 snowflake.yml 文件。

   授予应用程序包内对象的这些权限后，从该应用程序包创建的所有对象都可以使用 shared_data.accounts 表。这种共享是通过脚本末尾的权限 GRANT TO SHARE 命令实现的。

   备注

   对于要在应用程序中与使用者共享的每个架构，必须向应用程序包授予对每个架构的 USAGE 权限。然后，您必须在要共享的架构内授予对对象的 SELECT 权限。

2. 在项目定义文件中添加一个条目，以确保在更新应用程序包时运行此脚本。最终的项目定义文件应为：

   definition_version: 2
   entities:
      hello_snowflake_package:
         type: application package
         stage: stage_content.hello_snowflake_stage
         manifest: app/manifest.yml
         identifier: hello_snowflake_package
         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

添加视图以访问数据内容¶

在本部分中，将更新安装脚本以添加一个视图，允许安装了应用程序的用户访问在上一部分中创建的 ACCOUNTS 表中的数据。

要添加视图来访问数据内容，请执行以下操作：

1. 要为视图创建架构，请将以下内容添加到安装脚本中：

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

   Copy

   这些语句创建包含视图的版本化架构，并授予对架构的 USAGE 权限。Snowflake Native App Framework 使用版本化架构来处理不同版本的存储过程和函数。

2. 要创建视图，请将以下内容添加到安装脚本中：

   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

   这些语句在 code_schema 架构中创建视图，并将视图所需的权限授予应用程序角色。

   下次使用 Snowflake CLI 部署应用程序时，也会将此更新后的安装脚本上传到暂存区。

测试更新后的应用程序¶

在本子部分中，将升级应用程序，并使用已安装的应用程序中的视图查询示例表。

要测试更新后的应用程序，请按照以下步骤操作：

1. 要更新使用者账户中安装的应用程序包和应用程序对象，请运行以下命令：

   snow app run -c connection_name
   

   Copy

   其中 connection_name 是您安装 Snowflake CLI 时在 config.toml 文件中指定的连接名称。

   这将把所有编辑过的文件上传到暂存区，运行 scripts/shared_content.sql 脚本，并使用暂存区中的这些文件升级应用程序。

2. 要验证视图是否正常运行，请运行以下命令：

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

   Copy

   此命令的输出应为：

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

   Copy

回顾本部分所学内容¶

在本部分中，学习了如何通过执行以下任务在应用程序中包含共享数据内容：

• 在应用程序包中创建了 ACCOUNTS 表，并将数据插入表中。

• 授予了应用程序包对 ACCOUNTS 表的引用使用权。

• 创建了引用应用程序包中 ACCOUNTS 表的架构和视图。

• 授予了应用程序角色对该架构的使用权。

• 授予了应用程序角色对视图的选择权限。

还更新了安装脚本，以在安装应用程序时执行以下操作：

• 创建了应用程序用于访问示例数据的架构和视图。

• 授予了应用程序角色对该架构的使用权。

• 授予了应用程序角色对视图的选择权限。

将内联 Python 函数添加为用户定义的函数 (UDF)¶

在本部分中，将添加 Python 函数作为 UDF。

要在应用程序中包含 Python UDF，请将以下代码添加到安装文件中。

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

安装应用程序时，这些命令执行以下任务：

• 创建名为 code_schema 的版本化架构。

• 将架构使用权限授予 APP_PUBLIC 应用程序角色。

• 在 code_schema 架构中创建 ADDONE() UDF。

• 将函数使用权限授予 APP_PUBLIC 应用程序角色。

请注意，上面的代码示例中创建的架构是版本化架构。用户定义的函数和存储过程必须在版本化架构而不是普通架构中定义。这可以防止应用程序升级干扰并发代码执行。

添加外部 Python 模块¶

要向应用程序添加外部 Python 模块，请执行以下操作：

1. 将以下 Python 函数添加到安装脚本：

   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

   与前面的示例类似，这些语句在架构中创建一个 Python UDF，并将函数的权限授予应用程序角色。但是，此示例包含一个 IMPORTS 子句，该子句引用了一个外部 Python 文件，该文件是您创建并包含在命名暂存区中的。

2. 在 tutorial 文件夹中，创建名为 python 的子文件夹。

3. 在 python 子文件夹中，创建名为 hello_python.py 的文件。

4. 将以下内容添加到 hello_python.py 文件中：

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

   Copy

   该外部文件中定义的函数与安装脚本中定义的内联函数匹配。

5. 向项目定义文件中现有的 artifacts 部分添加以下内容：

   - python/hello_python.py
   

   Copy

在本部分中，向应用程序添加了一个 Python UDF。这个 UDF 指的是一个外部 Python 模块，可以被应用程序包引用。

安装并测试更新的应用程序¶

要安装和测试应用程序，请执行以下操作：

1. 要更新应用程序包和应用程序，请运行以下命令：

   snow app run -c connection_name
   

   Copy

   其中 connection_name 是您安装 Snowflake CLI 时在 config.toml 中指定的连接名称。

   此命令会将编辑过的文件和新文件上传到暂存区，并使用暂存区中的文件升级应用程序。

2. 要测试 Python 存储过程，请运行以下命令：

   snow sql -q "SELECT hello_snowflake_app.code_schema.addone(1)" -c connection_name
   

   Copy

3. 要测试引用的 Python 函数，请运行以下命令：

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

   Copy

回顾本部分所学内容¶

在本部分中，向应用程序添加了以下新功能：

• 定义为内联 UDF 的 Python 函数。

• 定义为引用外部代码的 UDF 的 Python 函数。

还通过安装应用程序的更新版本并运行每个函数来测试每个示例。

创建 Streamlit 应用程序文件¶

要创建 Streamlit 应用程序，请按照以下步骤操作：

1. 在 tutorial 文件夹中，创建名为 streamlit 的子文件夹。

2. 在 streamlit 文件夹中，创建名为 hello_snowflake.py 的文件。

3. 在此文件中添加以下代码：

   # 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. 向项目定义文件中现有的 artifacts 部分添加以下内容：

   - streamlit/hello_snowflake.py
   

   Copy

将 Streamlit 对象添加到安装脚本¶

要在应用程序中创建 Streamlit 对象，请按照以下步骤操作：

1. 在 setup_script.sql 文件的末尾添加以下语句以创建 Streamlit 对象：

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

   Copy

   该语句在核心架构中创建一个 STREAMLIT 对象。

2. 在 setup_script.sql 文件的末尾添加以下语句，以允许 APP_PUBLIC 角色访问 Streamlit 对象：

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

   Copy

安装更新的应用程序¶

1. 要更新应用程序包和应用程序，请运行以下命令：

   snow app run -c connection_name
   

   Copy

   其中 connection_name 是您安装 Snowflake CLI 时在 config.toml 文件中指定的连接名称。

   此命令会将编辑过的文件和新文件上传到暂存区，并使用暂存区中的这些文件升级应用程序。然后，您可以导航到此命令打印出的 URL，查看新 Streamlit 的运行情况；然后，点击应用程序名称旁边出现的名为 HELLO_SNOWFLAKE_STREAMLIT 的选项卡。

回顾本部分所学内容¶

在本部分中，通过执行以下操作将 Streamlit 应用程序添加到 Snowflake Native App 中：

• 创建了一个使用 Streamlit 库渲染用户界面的 Python 文件。

• 在 Snowflake Native App 中创建了一个 Streamlit 应用程序，显示共享数据。

设置默认发布指令¶

在为应用程序包创建列表之前，必须设置发布指令。发布指令指定应用程序的哪个版本和补丁可供使用者使用。

在本教程中，将使用上一部分中添加的版本设置默认发布指令。

要对应用程序包设置默认发布指令，请按照以下步骤操作：

1. 要查看应用程序包定义的版本和补丁，请运行以下命令：

   snow app version list -c connection_name
   

   Copy

   此命令显示为应用程序包定义的版本和补丁。

2. 要将默认发布指令设置为版本 v1_0 和补丁 0，请运行以下命令：

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

   Copy

   此命令的输出如以下示例所示：

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

   Copy

在本部分中，验证了应用程序包中存在哪些版本和补丁。使用这些信息，为应用程序包定义了默认发布指令。

为应用程序创建列表¶

现在已经为应用程序包指定了发布指令，将创建一个列表并将应用程序包添加为列表的数据内容。这样就可以与其他 Snowflake 用户共享应用程序，并允许他们在其账户中安装和使用该应用程序。

要为应用程序创建列表，请执行以下操作：

1. 登录 Snowsight。

2. 在导航菜单中，选择 Data Products » Provider Studio。

3. 选择 + Listing。创建列表窗口打开。

4. 输入列表名称。

5. 在 In the Who can discover the listing 部分，选择 Only specified consumers，以便与特定账户私下共享列表。

6. 点击 + Select，为列表选择应用程序包。

7. 输入列表的描述。

8. 在 Add consumer accounts 部分，为用于测试从列表安装应用程序的使用者体验的账户添加账户标识符。

在本部分中，创建了一个专用列表，其中包含作为共享数据内容的应用程序包。

在使用者账户中安装应用程序¶

在本部分中，将安装与在上一部分中创建的列表相关联的应用程序。将在不同的账户中安装列表，这将模拟使用者在其账户中安装应用程序的方式。

要从列表中安装应用程序，请按照以下步骤操作：

1. 登录 Snowsight。

2. 在导航菜单中，选择 Data Products » Apps。

3. 在 Recently shared with you 下，选择列表的磁贴。

4. 选择 Get。

5. 输入应用程序面向客户的名称。对于本教程，使用“Hello Snowflake App”。

6. 选择要安装应用程序的仓库。

7. 选择 Get。

8. 选择 Open 查看列表或选择 Done 结束。

在本部分中，学习了如何发布和安装列表，以便与其他 Snowflake 用户共享应用程序。