项目定义文件¶

名为 snowflake.yml 的项目定义文件将目录声明为 Snowflake Native App 项目。它是一个版本控制的文件，位于 Snowflake Native App 项目目录，可以手动创建，也可以由 Snowflake CLI 作为项目初始化的一部分创建。只要您可以在目录中提供这个结构化文件，但选择使用自己独立的项目结构，Snowflake CLI 便可以发现相关文件并像往常一样执行其功能。

对于 Native Apps，您的 snowflake.yml 与下面的内容相似：

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

Copy

通用实体属性¶

下表介绍了可用于 Native Apps 的项目定义实体的常见属性。有关项目定义实体的更多信息，请参阅指定实体。

通用实体属性¶
属性	定义
type 必填，字符串型	要管理的实体的类型。对于 Snowflake Native App，有效值包括： `application package`。有关应用程序包属性的更多信息，请参阅应用程序包实体属性。 `application`。有关应用程序属性的更多信息，请参阅应用程序实体属性。
identifier 可选，字符串型	支持实体的可选 Snowflake 标识符、不带引号的标识符和带引号的标识符。要使用带引号的标识符，请在 YAML 值中包含周围的引号（例如 `’”My Native Application Package”’`）。如果未指定，则项目定义中的实体 ID 用作标识符。
meta.warehouse 可选，字符串型	用于运行作为 `meta.post_deploy` 的一部分提供的脚本的仓库，如果这些脚本中的任何 SQL 命令需要使用仓库时即可使用。默认值：为 Snowflake CLI `config.toml` 文件中的连接指定的仓库。备注如果未指定仓库，应用程序将通过验证，但无法安装。通常，您可以按照项目定义替换中所述在 `snowflake.local.yml` 中指定此值。
meta.role 可选，字符串型	在创建实体和提供商端对象时使用的角色。备注如果不指定角色，Snowflake CLI 会尝试使用在您的 Snowflake 账户中分配给您的用户的默认角色。通常，您可以按照项目定义替换中所述在 `snowflake.local.yml` 中指定此值。默认值：在 Snowflake CLI 连接中指定的角色
meta.post_deploy 可选、序列	在创建实体后要执行的 SQL 脚本的列表。下面的示例展示了如何在项目定义文件中定义这些脚本： definition_version: 2 entities: myapp_pkg: type: application package ... meta: post_deploy: - sql_script: scripts/post_deploy1.sql - sql_script: scripts/post_deploy2.sql Copy 这些脚本由创建或更新实体的命令调用。例如，运行 `snow app deployment` 命令会在创建或更新包后执行这些脚本。如果应用程序实例不是从版本或发布指令直接安装，这些脚本还会由 `snow app run` 执行。您还可以在部署后的 SQL 脚本中使用模板，如以下示例脚本内容所示： GRANT reference_usage on database provider_data to share in entity <% fn.str_to_id(ctx.entities.myapp_pkg.identifier) %> Copy
meta.use_mixins 可选、序列	要应用于此实体的 mixin 的名称。有关更多信息，请参阅项目 mixin。

应用程序包实体属性¶

下表介绍了可用于 Native Apps 的应用程序包实体的常见属性。有关项目定义实体的更多信息，请参阅指定实体。

`应用程序包` 实体的属性¶
属性	定义
type 必填，字符串型	必须是 `application package`
manifest 可选，字符串型	项目中 Snowflake Native App `manifest.yml` 文件的位置。备注在版本 3.2 中，此属性从必需切换到可选。
deploy_root 可选，字符串型	位于项目根目录的子目录，构建步骤会将工件复制到该子目录中。复制到此位置后，您可以将它们部署到 Snowflake 暂存区。默认：`output/deploy`
generated_root 可选，字符串型	部署根的子目录，Snowflake CLI 在其中写入生成的文件。默认：`__generated`
stage 可选，字符串型	存储应用程序工件的暂存区的标识符。该值使用的形式为：codenowrap:`<schema_name>.<stage_name>`。暂存区位于应用程序包对象中。您可以更改名称以避免名称冲突。默认：`app_src.stage`
artifacts required、sequence	要添加到部署根的文件源和目标对的列表，以及可选的 Snowpark 注释处理器。您可以使用以下工件属性。 `src`：一个或多个代码源文件的路径。 `dest`：要部署工件的目录的路径。引用目录的目标路径必须以 `/` 结尾。如果 glob 模式的目标不是以 `/` 结尾，则会导致错误。如果省略，`dest` 默认为与 `src` 字符串相同。您还可以为每个项目传递一个字符串，而不是 `dict`，在这种情况下，该值将视为 `src` 和 `dest`。 `processors`：用于处理 `src` 代码文件的处理器的名称。有关更多详细信息，请参阅有关工件处理器的更多信息。如果 `src` 仅引用一个文件（而不是 glob），`dest` 可以引用目标 `<path>` or a `<path/name>`。您还可以为每个项目传递一个字符串，而不是 `dict`，在这种情况下，该值将被视为 `src` 和 `dest`。不采用处理器的示例： pkg: artifacts: - src: app/* dest: ./ - src: streamlit/* dest: streamlit/ - src: src/resources/images/snowflake.png dest: streamlit/ Copy 采用处理器的示例： pkg: artifacts: - src: qpp/* dest: ./ processors: - name: snowpark properties: env: type: conda name: <conda_name> Copy
distribution 可选，字符串型	分发由 Snowflake CLI 创建的应用程序包。运行 `snow app` 命令时，如果您正在使用的应用程序包的分发值与解析的项目定义中设置的值不同，Snowflake CLI 会发出警告。默认：`Internal`
scratch_stage 可选，字符串型	存储由 Snowflake CLI 使用的临时擦除数据的暂存区的标识符。该值使用形式 `<schema_name>.<stage_name>`。暂存区位于应用程序包对象中。您可以更改名称以避免名称冲突。默认：`app_src.stage_snowflake_cli_scratch`

应用程序实体属性¶

下表介绍了可用于 Native Apps 的应用程序实体的常见属性。有关项目定义实体的更多信息，请参阅指定实体。

`应用程序` 实体的属性¶
属性	定义
type 必填，字符串型	必须是 `application`
from.target 必填，字符串型	从中创建此应用程序实体的应用程序包。在下面的示例中，`target` 定义 `snowflake.yml` 文件中实体的名称。 from: target: my_pkg Copy
telemetry.share_mandatory_events 可选、布尔	是否在应用程序级别启用事件共享。当此值设置为 `true` 时，所有强制性事件将自动与应用程序包提供商共享。 telemetry: share_mandatory_events: true Copy
telemetry.optional_shared_events 可选、序列	除强制性事件外，要与提供商共享的可选事件的列表。此处列出的所有事件都必须在 `manifest.yml` 文件的 `configuration.telemetry_event_definitions` 部分中声明。仅当 `share_mandatory_events` 设置为 `true` 时，才支持此字段。 telemetry: share_mandatory_events: true optional_shared_events: - DEBUG_LOGS Copy
debug 可选、布尔	在使用命名暂存区创建应用程序时是否启用调试模式。默认：`True`

有关工件处理器的更多信息¶

如果您在项目定义文件中包含 artifacts.processors 字段，则 snow app bundle 命令会调用对 src 目录或文件中 Python 代码文件的自定义处理。

本节介绍支持的处理器的列表。

Snowpark 处理器¶

Snowflake CLI 支持的处理器之一是 snowpark，对 Python 文件进行 Snowpark 注释处理。下面显示了不同处理环境的基本结构和语法：

要在 conda 环境中执行代码，请使用以下命令：

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

Copy

其中 <conda_name> 是 conda 环境的名称，其中包含您要用于 Snowpark 注释处理的 Python 解释器和 Snowpark 库。

要在 Python 虚拟环境中执行代码，请使用以下命令：

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

Copy

其中 <venv_path> 是 Python 虚拟环境的路径，其中包含您要用于 Snowpark 注释处理的 Python 解释器和 Snowpark 库。路径可以是绝对路径，也可以是相对于项目目录的路径。

要在当前活动环境中执行代码，请使用以下任意等效定义：

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

Copy

或

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

Copy

或

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

Copy

有关自定义处理的更多信息，请参阅 SQL 代码自动生成和 snow app bundle 命令。

模板处理器¶

Snowflake Native App 项目支持任意文件中的模板，这允许您展开工件 src 目录中所有文件中的模板。您可以在所需的 artifacts 定义中包含 templates 处理器，如以下示例所示：

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

Copy

当 Snowflake CLI 将文件上传到暂存区时，它会在上传之前自动展开模板。例如，假设您的应用程序包含具有以下内容的 app/README.md 文件，其中包括 <% ctx.entities.pkg.identifier %> 模板：

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

Copy

然后，在将文件上传到暂存区之前，模板将展开成以下样子：

This is a README file for application package myapp_pkg.

Copy

项目定义替换¶

尽管您的项目目录必须具有 snowflake.yml 文件，但您可以选择通过向 snowflake.yml 提供本地替换来自定义 Snowflake CLI 的行为，例如提供一个新角色来测试您自己的应用程序包。这些替换必须放在基础项目定义旁边的 snowflake.local.yml 文件中。Snowflake 建议您将其添加到您的 .gitignore 文件，以便不会受到 git 的版本控制。Snowflake 提供的所有模板都已将其包含在 .gitignore 文件中。

此替换文件必须与您的 snowflake.yml 文件位于同一位置。

snowflake.local.yml 文件和 snowflake.yml 的架构完全相同，不同之处在于，除了已经是可选的值之外，每个必需的值现在都是可选的。下面显示了示例 snowflake.local.yml 文件：

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

Copy

每个 snow app 命令都将此文件中的参数优先于基础 snowflake.yml 配置文件中设置的参数。合理的默认值已经为使用相同的 Snowflake 账户开发相同应用程序项目的开发者提供了隔离，因此如果您刚刚开始，建议您不要包含替换文件。

使用 snowflake.local.yml 替换 snowflake.yml 后获得的最终定义架构称为已解析的项目定义。

限制¶

现在，Snowflake CLI 不受支持

多个替换文件。
空白的替换文件。仅当要替换 snowflake.yml 的值时才创建此文件。

项目定义文件¶

通用实体属性¶

应用程序包实体属性¶

应用程序实体属性¶

与提供商共享事件¶

有关工件处理器的更多信息¶

Snowpark 处理器¶

模板处理器¶

项目定义替换¶

限制¶