使用模板引导项目

为了让您更容易实例化项目，Snowflake CLI 会实施项目模板化。您可以 创建自己的项目模板 或使用 Snowflake 在 Snowflake CLI 模板 (https://github.com/snowflakedb/snowflake-cli-templates/) 公共 Git 存储库中提供的示例。

snow init 命令会创建项目目录，并根据指定模板填充文件结构。

  • 如果未提供 --no-interactive 选项，则命令会为每个未通过 -D``（或 ``--variable）选项指定值的模板 (template.yml) 变量提示用户输入。

  • 如果您提供 --no-interactive 选项，则命令将使用变量的默认值（由模板定义）。如果模板没有定义变量的默认值，并且您没有使用 -D 选项进行提供，则命令将退出并显示错误。

snow init 命令使用以下语法：

snow init PATH [--template-source SOURCE] [--template NAME] [-D key1=value1 -D key2=value2...] [--no-interactive]

其中：

  • PATH 是一个新目录，命令在其中对项目进行初始化。如果您指定一个现有目录，则命令将退出并显示错误。

  • [--template-source SOURCE] 是以下其中一项：

    • 模板目录的本地文件路径。

    • 指向目录的有效 Git URL，包含项目模板。如果未指定，命令默认为 Snowflake CLI 模板 (https://github.com/snowflakedb/snowflake-cli-templates/) Git 存储库。

  • [--template NAME] 指定要用作模板的 SOURCE 子目录（对于远程源非常有用）。如果未提供，则将 SOURCE 视为单个模板。

  • [-D key1=value1 -D key2=value2...] 是一个包含一个或多个名称值对的列表，为模板中定义的变量提供值（在 template.yml 中）。该命令不会提示您提供此选项的变量。

  • [--no-interactive] 会禁用用户输入的提示。如果您使用此选项，则必须提供 [-D key1=value1 -D key2=value2...] 选项的所有必需值；否则，命令将以错误退出。

有关更多信息，请参阅 snow init 命令参考。

示例

  • 使用默认仓库的 example_snowpark 模板对项目进行初始化：

    snow init my_snowpark_test_app --template example_snowpark

    该命令会提示输入（默认值显示在方括号中）：

    Project identifier (used to determine artifacts stage path) [my_snowpark_project]:
What stage should the procedures and functions be deployed to? [dev_deployment]: snowpark
Initialized the new project in my_snowpark_test_app

  • 使用本地模板对项目进行初始化。

    snow init new_streamlit_project --template-source ../local_templates/example_streamlit -D query_warehouse=dev_wareshouse -D stage=testing

    在此示例中，query_warehouse 和 stage 变量是通过 -D 选项指定的，因此命令只提示以下内容：

    Name of the streamlit app [streamlit_app]:
Initialized the new project in new_streamlit_project

创建自定义模板

模板布局

项目模板需要 template.yml 文件，其中包含数据，并解释 snow init 命令应该如何呈现模板。如果文件未在模板的根目录中呈现，则 snow init 会以错误结束。有关更多信息，请参阅 template.yml 语法。

模板语法

模板变量和表达式应放在 <! ... !> 内。Snowflake CLI 还支持基本的 jinja2 表达式和筛选器，例如：

some_file_spec:
  filename: <! file_name !>
  size: "<! [ max_file_size_mb, 4 ] | max !> MB"

Snowflake CLI 项目模板还支持以下保留变量和筛选器：

  • project_dir_name 变量，自动解析为已创建项目的根目录。

    例如，假设您的 snowflake.yml 文件包含以下内容：

    definition_version: "1.1"
snowpark:
  project_name: <! project_dir_name !>
  ...

    如果您随后执行以下命令，以使用自定义模板对项目进行初始化：

    snow init examples/new_snowpark_project --template-source my_example_template/

    snow init 命令将 snowflake.yml 文件渲染如下：

    definition_version: "1.1"
snowpark:
  project_name: new_snowpark_project
  ...

  • to_snowflake_identifier 筛选器，可将用户提供的字符串格式化为格式正确的 Snowflake 标识符。

    Snowflake 强烈建议在变量引用 Snowflake 对象时使用此筛选器。

    例如，假设您的 snowflake.yml 文件包含以下内容：

    definition_version: "1.1"
streamlit:
  name: <! name | to_snowflake_identifier !>
  ...

    如果您随后执行以下命令，以使用自定义模板对项目进行初始化：

    snow init examples/streamlit --template-source my_example_template2/ -D name='My test streamlit'

    snow init 命令将 snowflake.yml 文件渲染如下：

    definition_version: "1.1"
streamlit:
  name: My_test_streamlit
  ...

    如果字符串无法转换为有效的 Snowlake 标识符，则 snow init 命令将退出并显示错误，如下所示：

    snow init examples/streamlit --template-source my_example_template2/ -D name=1234567890

    ╭─ Error ────────────────────────────────────────────────────────────────────────╮
│ Value '123456789' cannot be converted to valid Snowflake identifier.         │
│ Consider enclosing it in double quotes: ""                                   │
╰────────────────────────────────────────────────────────────────────────────────╯

关于 template.yml 项目模板文件

template.yml 项目模板文件会存储渲染项目所需的所有数据。例如：

minimum_cli_version: "2.7.0"
files_to_render:
  - snowflake.yml
variables:
  - name: name
    default: streamlit_app
    prompt: "Name of the streamlit app"
    type: string
  - name: stage
    default: my_streamlit_stage
    prompt: "What stage should the app be deployed to?"
    type: string
  - name: query_warehouse
    default: my_streamlit_warehouse
    prompt: "On which warehouse SQL queries issued by the application are run"
    type: string

以下表列出了 template.yml 项目模板文件中的属性。

模板属性

属性

定义

minimum_cli_version

可选，*字符串型*（默认值：None）

最低 Snowflake CLI 版本。如果指定，snow init 命令会检查已安装的 Snowflake CLI 版本，如果已安装的版本低于指定版本，则退出并显示错误。

files_to_render

可选，*字符串列表*（默认值：[]）

由 snow init 命令渲染的文件列表。每个路径应相对于模板根目录。

备注

未包含在此列表中的模板文件将被添加到新项目中，但其内容保持不变。

variables

可选，*变量列表*（默认值：[]）

模板变量列表。它支持自定义提示，可为可选变量提供默认值和基本类型检查。请参阅下面的 变量属性参数 表以获取更多详细信息。变量值应根据此列表的顺序确定。

如果您从此列表中省略了 snowflake.yml 文件中使用的任何变量，则 snow init 命令将退出并显示错误。

╭─ Error ─────────────────────────────────────────────────────────╮
│ Cannot determine value of variable undefined_variable         │
╰─────────────────────────────────────────────────────────────────╯

以下表列出了变量属性的参数。

变量属性参数

属性

定义

name

required、string

变量的名称。它可用于模板文件，例如 <! name !> and in -D option, such as -D name=value。

prompt

optional、string

提示用户获取值。如果您不设置此参数，则命令会显示参数的名称作为提示文本。

如果您将提示定义如下：

variables:
  - name: project_id
    prompt: The identifier for the project

snow init 会显示此提示以获取 project_id 变量。

The identifier for the project:

default

optional、string/int/float

Default value of the variable. If not provided, the variable is treated as required, so a user needs to provide the value after a prompt or by specifying it with the -D command-line option.

以下示例定义了两个具有默认值的变量：

variables:
  - name: max_file_size_mb
    default: 16
  - name: file_name
    default: 'default_file_name.zip'

当执行时，snow init 命令会显示这两个变量的以下提示：

file_name [default_file_name.zip]:
max_file_size_mb [16]: 5

在此示例中，命令使用默认值 (default_file_name.zip) 作为 file_name 变量的默认值，并将 max_file_size_mb 设置为用户提供的值 (5)。

type

optional、string

变量的数据类型。有效值包括：string、int 和 float。如果没有指定，该命令假定值为 string。

以下示例将变量定义为 int 数据类型：

variables:
  - name: max_file_size_mb
    type: int

当执行时，如果用户输入错误数据类型的值，snow init 命令将显示以下错误：

max_file_size_mb: not an int
Error: 'not an int' is not a valid integer.
max_file_size_mb: 14.5
Error: '14.5' is not a valid integer.
max_file_size_mb: 6
Initialized the new project in example_dir