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

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

Project definition properties

The following table describes the project definition properties.

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. ’”My Native Application Project”’).

Default: <native_app_project_directory_name>

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: output/deploy

native_app.generated_root

optional, string

Subdirectory of the deploy root where Snowflake CLI writes generated files.

Default: __generated

native_app.source_stage

optional, string

Identifier of the stage that stores the application artifacts. The value uses the form <schema_name>.<stage_name>. The stage lives within the Application Package object. You can change the name to avoid name collisions.

Default: app_src.stage

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”

  • src: Path to the code source file or files

  • dest: Path to the directory to deploy the artifacts.

    Destination paths that reference directories must end with a /. A glob pattern’s destination that does not end with a / results in an error. If omitted, dest defaults to the same string as src.

    You can also pass in a string for each item instead of a dict, in which case the value is treated as both src and dest.

  • processors: Name of the processor to use to process the src code files. Currently, the only value supported is snowpark. For more information about custom processing, see Automatic SQL code generation and the snow app bundle command.

If src refers to just one file (not a glob), dest can refer to a target <path> or a <path/name>.

You can also pass in a string for each item instead of a dict, which case, the value is treated as both src and dest.

Example without a processor:

native_app:
  artifacts:
    - src: app/*
      dest: ./
    - src: streamlit/*
      dest: streamlit/
    - src: src/resources/images/snowflake.png
      dest: streamlit/
Copy

Example with a processor:

native_app:
  artifacts:
    - src: qpp/*
      dest: ./
      processors:
          - name: snowpark
            properties:
              env:
                type: conda
                name: <conda_name>
Copy

native_app.package.distribution

optional, string

Distribution of the application package created by the Snowflake CLI. When running snow app commands, Snowflake CLI warns you if the application package you are working with has a different value for distribution than is set in your resolved project definition.

Default: Internal

native_app.package.name

optional, string

Name of the application created when you run the snow app run command.

Based on your platform, Snowflake CLI uses the $USER, $USERNAME, or $LOGNAME environment variables. As with native_app.name, both unquoted and quoted identifiers are supported.

Typically, you specify this value in the snowflake.local.yml as described in Project definition overrides.

Default: <native_app.name>_pkg_$USER

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 snowflake.local.yml as described in Project definition overrides.

Default: Role specified in the Snowflake CLI connection

native_app.package.warehouse

optional, string

Warehouse used to run the scripts provided as part of native_app.package.scripts, if any SQL commands within these scripts require use of warehouse.

Default: Warehouse specified for the connection in the Snowflake CLI config.toml file.

Note

If you do not specify a warehouse, the application passes validation, but fails to install.

Typically, you specify this value in the snowflake.local.yml as described in Project definition overrides.

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 <schema_name>.<stage_name>. The stage lives within the Application Package object. You can change the name to avoid name collisions.

Default: app_src.stage_snowflake_cli_scratch

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 package_name, which will be replaced by native_app.package.name.

Example:

- scripts/schema1.sql
- scripts/schema2.sql
Copy

native_app.application.name

optional, string

Name of the application created when you run the snow app run command.

Default: <native_app.name>_$USER

Based on your platform, Snowflake CLI uses the $USER, $USERNAME, or $LOGNAME environment variables. As with native_app.name, both unquoted and quoted identifiers are supported.

Typically, you specify this value in the snowflake.local.yml as described in Project definition overrides.

native_app.application.post_deploy

optional, string

List of SQL scripts to execute locally after the snow app run command deploys the application. Example:

definition_version: 1
native_app:
  name: myapp
  artifacts:
    ...
  package:
    ...
  application:
    post_deploy:
      - sql_script: scripts/post_deploy1.sql
      - sql_script: scripts/post_deploy2.sql
Copy

Depending on the application, you might want to perform some actions after installing it. Some examples include:

  • Grant privileges needed to execute the application.

    GRANT EXECUTE TASK ON ACCOUNT TO APPLICATION hello_snowflake_app;
    Copy

  • Bind a reference so the app could use a resource you own.

    SELECT SYSTEM$REFERENCE('table', 'db1.schema1.table1', 'persistent', 'select', 'insert');
    Copy

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 config.toml file.

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 snowflake.local.yml as described in Project definition overrides.

native_app.application.warehouse

optional, string

Warehouse used to install or upgrade the application.

Default: Warehouse specified for the connection in the Snowflake CLI config.toml file.

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 snowflake.local.yml as described in Project definition overrides.

native_app.application.debug

optional, boolean

Whether to enable debug mode when using a named stage to create an application.

Default: True

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

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

    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
    Copy

    or

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

    or

    native_app:
artifacts:
  - src: <some_src>
    dest: <some_dest>
    processors:
        - snowpark
    Copy

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

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.

Language: English