使用模板引导项目

为了让您更容易实例化项目,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]
Copy

其中:

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

    该命令会提示输入(默认值显示在方括号中):

    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
    
    Copy

    在此示例中,query_warehousestage 变量是通过 -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"
Copy

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

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

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

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

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

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

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

    definition_version: "1.1"
    snowpark:
      project_name: new_snowpark_project
      ...
    
    Copy
  • to_snowflake_identifier 筛选器,可将用户提供的字符串格式化为格式正确的 Snowflake 标识符。

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

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

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

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

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

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

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

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

    snow init examples/streamlit --template-source my_example_template2/ -D name=1234567890
    
    Copy
    ╭─ 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
Copy

以下表列出了 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 undefinded_variable        │
╰─────────────────────────────────────────────────────────────────╯

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

变量属性参数

属性

定义

name

requiredstring

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

prompt

optionalstring

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

如果您将提示定义如下:

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

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

The identifier for the project:

default

optionalstring/int/float

变量的默认值。如果未提供,则变量被视为必填,因此用户需要在提示后提供值或通过 -D 命令行选项指定它。

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

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

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

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

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

type

optionalstring

变量的数据类型。有效值包括:stringintfloat。如果没有指定,该命令假定值为 string

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

variables:
  - name: max_file_size_mb
    type: int
Copy

当执行时,如果用户输入错误数据类型的值,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
语言: 中文