将项目定义文件从版本 1.x 迁移到版本 2.0

要将版本 1.x 项目定义文件转换为版本 2 格式，请执行以下操作：

  1. 转到包含版本 1.x snowflake.yml 文件的项目目录。

  2. 输入 snow helpers v1-to-v2 命令。

    • 如果版本 1.x 文件转换成功，则该命令将显示一条类似于以下内容的消息：

      cd <project-directory>
snow helpers v1-to-v2

      Project definition migrated to version 2.

    • 如果您的项目定义文件已经更新到版本 2，则该命令会显示以下消息：

      cd <project-directory>
snow helpers v1-to-v2

      Project definition is already at version 2.

  • 如果您尝试在不使用 --[no]-migrate-local-overrides 选项的情况下转换包含 snowflake.local.yml 文件的项目文件，则该命令会生成类似于以下内容的错误：

  • 如果您尝试在不使用 --accept-templates 选项的情况下转换包含模板的项目文件，则该命令会生成类似于以下内容的错误：

    cd <project-directory>
snow helpers v1-to-v2

    +- Error-------------------------------------------------------------------+
| snowflake.local.yml file detected, please specify                        |
| --migrate-local-overrides to include or --no-migrate-local-overrides to  |
| exclude its values.                                                      |
+--------------------------------------------------------------------------+

  • 如果您转换包含模板的项目定义文件并使用 --accept-templates 选项，则该命令会转换该文件并显示一条类似于以下内容的警告消息：

    cd <project-directory>
snow helpers v1-to-v2

    WARNING  snowflake.cli._plugins.workspace.commands:commands.py:60 Your V1 definition contains templates. We cannot guarantee the correctness of the migration.
Project definition migrated to version 2

转换 Native App 项目

本节显示了 Snowflake Native App 项目从 V1 到 V2 转换的示例，列出了属性名称的变更，并提供了一些有助于迁移的技巧。

Snowflake Native App 转换示例

Native Apps 项目转换示例

V1 项目文件

V2 项目文件

 
definition_version: 1
native_app:
  name: myapp
  source_stage: app_src.stage
  artifacts:
    - src: app/*
      dest: ./
      processors:
        - native app setup
        - name: templates
          properties:
            foo: bar
  package:
    role: pkg_role
    distribution: external
  application:
    name: myapp_app
    warehouse: app_wh

definition_version: 2
entities:
  pkg:
    type: application package
    meta:
      role: pkg_role
    identifier: <% fn.concat_ids('myapp', '_pkg_', fn.sanitize_id(fn.get_username('unknown_user')) | lower) %>
    manifest: app/manifest.yml
    artifacts:
    - src: app/*
      dest: ./
      processors:
      - name: native app setup
      - name: templates
        properties:
          foo: bar
    stage: app_src.stage
  app:
    meta:
      warehouse: app_wh
    identifier: myapp_app
    type: application
    from:
      target: pkg

Native App 项目定义从 V1 到 V2 的属性变更

Native App 项目定义从 V1 到 V2 的属性变更

V1 属性

V2 属性

native_app.name

没有等效内容。如果需要，请使用模板变量进行移植。

native_app.deploy_root

<package entity>.deploy_root

native_app.generated_root

<package entity>.generated_root

native_app.bundle_root

<package entity>.bundle_root

native_app.source_stage

<package entity>.source_stage

native_app.scratch_stage

<package entity>.scratch_stage

native_app.artifacts

<package entity>.artifacts

native_app.application.debug

<application entity>.debug

native_app.application.name

<application entity>.identifier

native_app.application.post_deploy

:codenowrap:`<application entity>.meta.post_deploy`（请参阅上面的注释）

native_app.application.role

<application entity>.meta.role

native_app.application.warehouse

<application entity>.meta.warehouse

native_app.package.distribution

<package entity>.distribution

native_app.package.name

<package entity>.identifier

native_app.package.post_deploy

:codenowrap:`<package entity>.meta.post_deploy`（请参阅上面的注释）

native_app.package.role

<package entity>.meta.role

native_app.package.scripts

:codenowrap:`<package entity>.meta.post_deploy`（请参阅上面的注释）

native_app.package.warehouse

<package entity>.meta.warehouse

迁移技巧

  • 在迁移 Snowflake Native App 包脚本时，v1-to-v2 命令会将其转换为 package post-deploy hook，并将包脚本文件中的 {{package_name}} 替换为等效的模板表达式。

  • 迁移现有模板表达式时，ctx.native_app、ctx.streamlit 和:codenowrap:ctx.snowpark 变量不再被接受。具有等效模板表达式的 v1-to-v2 命令会改为引用特定的实体名称。例如，如果该包迁移到 snowflake.yml 文件中名为 pkg 的实体，则 ctx.native_app.package.name 可以被 ctx.entities.pkg.identifier 替换。

转换 Streamlit 项目

本节显示了 Streamlit 项目从 V1 到 V2 转换的示例，列出了属性名称的变更，并提供了一些有助于迁移的技巧。

Streamlit 转换示例

Streamlit 项目转换示例

V1 项目文件

V2 项目文件

 
definition_version: 1
streamlit:
  name: test_streamlit
  stage: streamlit
  query_warehouse: test_warehouse
  main_file: "streamlit_app.py"
  title: "My Fancy Streamlit"

definition_version: 2
entities:
  test_streamlit:
    identifier:
      name: test_streamlit
    type: streamlit
    title: My Fancy Streamlit
    query_warehouse: test_warehouse
    main_file: streamlit_app.py
    pages_dir: None
    stage: streamlit
    artifacts:
    - streamlit_app.py

Streamlit 项目定义从 V1 到 V2 的属性变更

Streamlit 项目定义从 V1 到 V2 的属性变更

V1 属性

V2 属性

streamlit.name

<streamlit entity>.identifier.name

streamlit.schema

<streamlit entity>.identifier.schema

streamlit.database

<streamlit entity>.identifier.database

streamlit.comment

<streamlit entity>.comment

streamlit.title

<streamlit entity>.title

streamlit.query_warehouse

<streamlit entity>.query_warehouse

streamlit.main_file

<streamlit entity>.main_file 和 <streamlit entity>.artifacts

streamlit.stage

<streamlit entity>.stage

streamlit.env_file

<streamlit entity>.artifacts

streamlit.pages_dir

<streamlit entity>.pages_dir 和 <streamlit entity>.artifacts

streamlit.additional_source_files

<streamlit entity>.artifacts

Streamlit 迁移技巧

无。

转换 Snowpark 项目

本节显示了 Snowpark 项目从 V1 到 V2 转换的示例，列出了属性名称的变更，并提供了一些有助于迁移的技巧。

Snowpark 转换示例

Snowpark 项目转换示例

V1 项目文件

V2 项目文件

 
definition_version: 1
snowpark:
  project_name: "my_snowpark_project"
  stage_name: "dev_deployment"
  src: "app/"
  functions:
    - name: func1
      handler: "app.func1_handler"
      signature:
        - name: "a"
          type: "string"
          default: "default value"
        - name: "b"
          type: "variant"
      returns: string
      runtime: 3.10
  procedures:
    - name: procedureName
      handler: "hello"
      signature:
        - name: "name"
          type: "string"
      returns: string

definition_version: 2
entities:
  procedureName:
    imports: []
    external_access_integrations: []
    secrets: {}
    meta:
      use_mixins:
      - snowpark_shared
    identifier:
      name: procedureName
    handler: hello
    returns: string
    signature:
    - name: name
      type: string
    stage: dev_deployment
    artifacts:
    - src: app
      dest: my_snowpark_project
    type: procedure
    execute_as_caller: false
  func1:
    imports: []
    external_access_integrations: []
    secrets: {}
    meta:
      use_mixins:
      - snowpark_shared
    identifier:
      name: func1
    handler: app.func1_handler
    returns: string
    signature:
    - name: a
      type: string
      default: default value
    - name: b
      type: variant
    runtime: '3.10'
    stage: dev_deployment
    artifacts:
    - src: app
      dest: my_snowpark_project
    type: function
mixins:
  snowpark_shared:
    stage: dev_deployment
    artifacts:
    - src: app/
      dest: my_snowpark_project

Snowpark 项目定义从 V1 到 V2 的属性变更

Snowpark 项目定义从 V1 到 V2 的属性变更

V1 属性

V2 属性

snowpark.project_name

<function or procedure entity>.artifacts.dest 用于从项目迁移的每个函数和/或过程。请参阅上面有关 Snowpark 迁移的备注。每个函数或过程都应声明一个工件，并将 dest 定义为 snowpark.project_name 值，并将 src 定义为 snowpark.src 值。建议使用 mixin。

snowpark.stage_name

<function or procedure entity>.stage 用于从项目迁移的每个函数和/或过程。

snowpark.src

<function or procedure entity>.artifacts.src 用于从项目迁移的每个函数和/或过程。（请参阅上面的 snowpark.project_name）

:codenowrap:`snowpark.functions`（列表）

<function entities>（顶级）

:codenowrap:`snowpark.procedures`（列表）

<procedure entities>（顶级）
Snowpark 函数和过程定义从 V1 到 V2 的属性变更

V1 属性

V2 属性

name

identifier.name

schema

identifier.schema

database

identifier.database

handler

handler

returns

returns

signature

signature

runtime

runtime

external_access_integrations

external_access_integrations

secrets

secrets

imports

imports

execute_as_caller

:codenowrap:`execute_as_caller`（仅适用于过程）

Snowpark 迁移技巧

  • 迁移 Snowpark 项目时，每个函数（来自 snowpark.functions 数组）或过程（来自 snowpark.procedures 数组）都会映射到顶级实体。

  • 现在，为每个函数和过程定义了所有顶级 Snowpark 项目属性（例如 src）。为了减少重复，Snowflake 建议您声明 mixin 并将其包含在每个迁移的函数和过程实体中。