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:
Go to your project directory that contains the version 1.x
snowflake.yml
file.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
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
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+- 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-v2WARNING 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¶
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
|
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 project definition V1 to V2 property changes¶
V1 property |
V2 property |
---|---|
|
No equivalent. Use a template variable to port, if required. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Migration tips¶
When migrating Snowflake Native App package scripts, the
v1-to-v2
command converts them topackage 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
, andctx.snowpark
variables are no longer accepted. Thev1-to-v2
command with equivalent template expressions that reference the specific entity name instead. For example,ctx.native_app.package.name
could be replaced withctx.entities.pkg.identifier
if the package was migrated to an entity namedpkg
in thesnowflake.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¶
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"
|
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 project definition V1 to V2 property changes¶
V1 property |
V2 property |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Streamlit migration tips¶
(update)
tbd.
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¶
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
|
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 project definition V1 to V2 property changes¶
V1 property |
V2 property |
---|---|
|
|
|
|
|
|
|
|
|
|
V1 property |
V2 property |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Snowpark migration tips¶
When migrating Snowpark projects, each function (from the
snowpark.functions
array) or procedure (from thesnowpark.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 amixin
and include it in each of the migrated function and procedure entities.