Migrating project definition files from version 1.x to 2.0

To convert a version 1.x project definition file to the version 2 format, do the following:

  1. Go to your project directory that contains the version 1.x snowflake.yml file.

  2. Enter the snow helpers v1-to-v2 command.

    • If the version 1.x file conversion succeeds, the command displays a message similar to the following:

      cd <project-directory> snow helpers v1-to-v2
      Copy
      Project definition migrated to version 2.

    • If your project definition file is already updated to version 2, the command displays the following message:

      cd <project-directory> snow helpers v1-to-v2
      Copy
      Project definition is already at version 2.

  • If you try to convert a project file that contains a snowflake.local.yml file, without using the --[no]-migrate-local-overrides option, the command generates an error similar to the following:

  • If you try to convert a project file that contains templates, without using the --accept-templates option, the command generates an error similar to the following:

    cd <project-directory> snow helpers v1-to-v2
    Copy
    +- Error-------------------------------------------------------------------+ | snowflake.local.yml file detected, please specify | | --migrate-local-overrides to include or --no-migrate-local-overrides to | | exclude its values. | +--------------------------------------------------------------------------+

  • If you convert a project definition file that contains templates, and use the --accept-templates option, the command converts the file and displays a warning message similar to the following:

    cd <project-directory> snow helpers v1-to-v2
    Copy
    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

Convert Native App projects

This section shows an example from a V1 to V2 conversion of a Snowflake Native App project, lists the changes in property names, and offers some tips to help with migration.

Snowflake Native App conversion example

Native Apps project conversion example

V1 project file

V2 project file

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

Native App project definition V1 to V2 property changes

Native App project definition V1 to V2 property changes

V1 property

V2 property

native_app.name

No equivalent. Use a template variable to port, if required.

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

<application entity>.meta.post_deploy (see above notes)

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

<package entity>.meta.post_deploy (see above notes)

native_app.package.role

<package entity>.meta.role

native_app.package.scripts

<package entity>.meta.post_deploy (see above notes)

native_app.package.warehouse

<package entity>.meta.warehouse

Migration tips

  • When migrating Snowflake Native App package scripts, the v1-to-v2 command converts them to package post-deploy hooks and replaces {{package_name}} in the package script file with the equivalent template expression.

  • When migrating existing template expressions, ctx.native_app, ctx.streamlit, and ctx.snowpark variables are no longer accepted. The v1-to-v2 command with equivalent template expressions that reference the specific entity name instead. For example, ctx.native_app.package.name could be replaced with ctx.entities.pkg.identifier if the package was migrated to an entity named pkg in the snowflake.yml file.

Convert Streamlit projects

This section shows an example from a V1 to V2 conversion of a Streamlit project, lists the changes in property names, and offers some tips to help with migration.

Streamlit conversion example

Streamlit project conversion example

V1 project file

V2 project file

 
definition_version: 1 streamlit:  name: test_streamlit  stage: streamlit  query_warehouse: test_warehouse  main_file: "streamlit_app.py"  title: "My Fancy Streamlit"
Copy
 
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
Copy

Streamlit project definition V1 to V2 property changes

Streamlit project definition V1 to V2 property changes

V1 property

V2 property

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 and <streamlit entity>.artifacts

streamlit.stage

<streamlit entity>.stage

streamlit.env_file

<streamlit entity>.artifacts

streamlit.pages_dir

<streamlit entity>.pages_dir and <streamlit entity>.artifacts

streamlit.additional_source_files

<streamlit entity>.artifacts

Streamlit migration tips

None.

Convert Snowpark projects

This section shows an example from a V1 to V2 conversion of a Snowpark project, lists the changes in property names, and offers some tips to help with migration.

Snowpark conversion example

Snowpark project conversion example

V1 project file

V2 project file

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

Snowpark project definition V1 to V2 property changes

Snowpark project definition V1 to V2 property changes

V1 property

V2 property

snowpark.project_name

<function or procedure entity>.artifacts.dest for each function and/or procedure migrated from the project. See above notes regarding Snowpark migration. Each function or procedure should declare an artifact with dest defined as the snowpark.project_name value, and src defined as the snowpark.src value. Use of a mixin is recommended.

snowpark.stage_name

<function or procedure entity>.stage for each function and/or procedure migrated from the project.

snowpark.src

<function or procedure entity>.artifacts.src for each function and/or procedure migrated from the project. (see snowpark.project_name above)

snowpark.functions (list)

<function entities> (top-level)

snowpark.procedures (list)

<procedure entities> (top-level)
Snowpark function and procedure definition V1 to V2 property changes

V1 property

V2 property

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

execute_as_caller (only for procedures)

Snowpark migration tips

  • When migrating Snowpark projects, each function (from the snowpark.functions array) or procedure (from the snowpark.procedures array) maps to a top-level entity.

  • All top-level Snowpark project properties (e.g. src) are now defined for each function and procedure. To reduce duplication, Snowflake recommends that you declare a mixin and include it in each of the migrated function and procedure entities.

Language: English