Project definition files¶
A project definition file called snowflake.yml
declares a directory as a Snowflake Native App project. It is a version-controlled file that resides at the root of a Snowflake Native App project directory and can either be created manually or by Snowflake CLI as part of project initialization. As long as you can provide this structured file in the directory but choose to use your own independent project structure, Snowflake CLI can discover the relevant files and carry out its functionality as usual.
For Native Apps, your snowflake.yml
would look similar to the following:
definition_version: 1.1
native_app:
name: my_first_nativeapp
source_stage: app_src.stage
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/
package:
role: <your_app_pkg_owner_role>
name: <name_of_app_pkg>
warehouse: <your_app_pkg_warehouse>
scripts:
- scripts/any-provider-setup.sql
- scripts/shared-content.sql
application:
role: <your_app_owner_role>
name: <name_of_app>
debug: <true|false>
warehouse: <your_app_warehouse>
Project definition properties¶
The following table describes the project definition properties.
Property |
Definition |
---|---|
definition_version required, int |
Version of the project definition schema, which is currently 1. |
native_app.name required, string |
Project identifier. This name allows Snowflake CLI to detect if an associated application package (derived from this name) exists in connected accounts and prevents tooling from interacting with unrelated (but identically named) objects in an account, by tagging the application or application package as belonging to this project. Both unquoted and quoted identifiers are supported. To use quoted identifiers, include the surrounding quotes in the YAML value (e.g. Default: |
native_app.deploy_root optional, string |
Subdirectory at the root of your project where the build step copies the artifacts. Once copied to this location, you can deploy them to a Snowflake stage. Default: |
native_app.generated_root optional, string |
Subdirectory of the deploy root where Snowflake CLI writes generated files. Default: |
native_app.source_stage optional, string |
Identifier of the stage that stores the application artifacts. The value uses the form Default: |
native_app.artifacts required, sequence |
List of file source and destination pairs to add to the deploy root, as well as an optional Snowpark annotation processor. You can use the following artifact properties”
If You can also pass in a string for each item instead of a Example without a processor: native_app:
artifacts:
- src: app/*
dest: ./
- src: streamlit/*
dest: streamlit/
- src: src/resources/images/snowflake.png
dest: streamlit/
Example with a processor: native_app:
artifacts:
- src: qpp/*
dest: ./
processors:
- name: snowpark
properties:
env:
type: conda
name: <conda_name>
|
native_app.package.distribution optional, string |
Distribution of the application package created by the Snowflake CLI. When running Default: |
native_app.package.name optional, string |
Name of the application created when you run the Based on your platform, Snowflake CLI uses the Typically, you specify this value in the Default: |
native_app.package.post_deploy optional, sequence |
List of SQL scripts to execute after an application package has been created. The following example shows how to define these scripts in the project definition file: definition_version: 1.1
native_app:
name: myapp
artifacts:
...
package:
post_deploy:
- sql_script: scripts/post_deploy1.sql
- sql_script: scripts/post_deploy2.sql
application:
...
These scripts are invoked by commands that create or update an application package. For example, running the You can also use templates in the post-deploy SQL scripts as well, as shown in the following sample script content: GRANT reference_usage on database provider_data to share in application package &{ fn.str_to_id(ctx.native_app.package.name) }
|
native_app.package.role optional, string |
Role to use when creating the application package and provider-side objects. Note If you do not specify a role, Snowflake CLI attempts to use the default role assigned to your user in your Snowflake account. Typically, you specify this value in the Default: Role specified in the Snowflake CLI connection |
native_app.package.warehouse optional, string |
Warehouse used to run the scripts provided as part of Default: Warehouse specified for the connection in the Snowflake CLI
|
native_app.package.scratch_stage optional, string |
Identifier of the stage that stores temporary scratch data used by Snowflake CLI. The value uses the form Default: |
native_app.package.scripts optional, string |
List of SQL file paths relative to the project root. These files are executed as the provider when you deploy the application package, such as to populate shared content. Note that these files must be idempotent. You can also use Jinja templates in place of SQL files, but currently, the only variable allowed in this file should be named Example: - scripts/schema1.sql
- scripts/schema2.sql
|
native_app.application.name optional, string |
Name of the application created when you run the Default: Based on your platform, Snowflake CLI uses the Typically, you specify this value in the |
native_app.application.post_deploy optional, sequence |
List of SQL scripts to execute locally after the definition_version: 1.1
native_app:
name: myapp
artifacts:
...
package:
...
application:
post_deploy:
- sql_script: scripts/post_deploy1.sql
- sql_script: scripts/post_deploy2.sql
Depending on the application, you might want to perform some actions after installing it. Some examples include:
|
native_app.application.role optional, string |
Role to use when creating the application instance and consumer-side objects. Default: Role specified for the connection in the Snowflake CLI Note If you do not specify a role, Snowflake CLI attempts to use the default role assigned to your user in your Snowflake account. Typically, you specify this value in the |
native_app.application.warehouse optional, string |
Warehouse used to install or upgrade the application. Default: Warehouse specified for the connection in the Snowflake CLI Note If you do not specify a warehouse, Snowflake CLI attempts to use the default warehouse assigned to your user in your Snowflake account. Typically, you specify this value in the |
native_app.application.debug optional, boolean |
Whether to enable debug mode when using a named stage to create an application. Default: |
More information about the native_app.artifacts.processors
parameter¶
If you include the native_app.artifacts.processors
parameter in the project definition file, the snow app bundle
command invokes custom processing for Python code files in the src
directory or file. Currently, Snowflake CLI supports only one processor, snowpark
, which applies Snowpark annotation processing to Python files. The following shows the basic structure and syntax different processing environments:
To execute code in a conda environment, use the following:
native_app: artifacts: - src: <some_src> dest: <some_dest> processors: - name: snowpark properties: env: type: conda name: <conda_name>
where
<conda_name>
is the name of the conda environment containing the Python interpreter and the Snowpark library you want to use for Snowpark annotation processing.To execute code in a Python virtual environment, use the following:
native_app: artifacts: - src: <some_src> dest: <some_dest> processors: - name: snowpark properties: env: type: venv path: <venv_path>
where
<venv_path>
is the path of the Python virtual environment containing the Python interpreter and the Snowpark library you want to use for Snowpark annotation processing. The path can be absolute or relative to the project directory.To execute code in the currently active environment, use any of the following equivalent definitions:
native_app: artifacts: - src: <some_src> dest: <some_dest> processors: - name: snowpark properties: env: type: current
or
native_app: artifacts: - src: <some_src> dest: <some_dest> processors: - name: snowpark
or
native_app: artifacts: - src: <some_src> dest: <some_dest> processors: - snowpark
Project definition overrides¶
Though your project directory must have a snowflake.yml
file, you can choose to customize the behavior of the Snowflake CLI by providing local overrides to snowflake.yml
, such as a new role to test out your own application package. These overrides must be put in the snowflake.local.yml
file that lives beside the base project definition. Snowflake suggests that you add it to your .gitignore
file so it won’t be version-controlled by git. All templates provided by Snowflake already include it in the .gitignore
file.
This overrides file must live in the same location as your snowflake.yml
file.
The snowflake.local.yml
file shares the exact schema as snowflake.yml
, except that every value that was required is now optional, in additional to the already optional ones. The following shows a sample snowflake.local.yml
file:
native_app:
package:
role: <your_app_pkg_owner_role>
name: <name_of_app_pkg>
warehouse: <your_app_pkg_warehouse>
application:
role: <your_app_owner_role>
name: <name_of_app>
debug: <true|false>
warehouse: <your_app_warehouse>
Every snow app
command prioritizes the parameters in this file over those set in base snowflake.yml
configuration file. Sensible defaults already provide isolation between developers using the same Snowflake account to develop the same application project, so if you are just getting started we suggest not including an overrides file.
The final definition schema obtained after overriding snowflake.yml
with snowflake.local.yml
is called the resolved project definition.
Limitations¶
Currently, Snowflake CLI does not support
Multiple override files.
A blank override file. Only create this file if you want to override a value from
snowflake.yml
.