模板规范¶

定义协作中的单个模板。通过调用 REGISTER_TEMPLATE 并提供模板规范来注册模板。

架构：

api_version: 2.0.0              # Required: Must be "2.0.0"
spec_type: template             # Required: Must be "template"
name: <template_name>           # Required: Unique name (max 75 chars)
version: <version_string>       # Required: Version identifier (max 20 chars)
type: <template_type>           # Required: sql_analysis or sql_activation
description: <template_description>  # Optional: High-level description (max 1,000 chars)
methodology: <methodology_description>  # Optional: Detailed description (max 1,000 chars)

parameters:                     # Optional: User-provided parameters
  - name: <parameter_name>      # One or more parameter items...
    description: <parameter_description>  # Optional: Description (max 500 chars)
    required: <true_or_false>   # Optional: Whether required (default: false)
    default: <default_value>    # Optional: Default value
    type: <data_type>           # Optional: String, integer, number, Boolean, array, or object

code_specs:             # Optional: List of code bundles used by this template
  - <code_spec_id>        # One or more code spec IDs.

template: |                     # Required: JinjaSQL template content
  <template_content>

api_version

所使用的 Collaboration API 的版本。必须是 2.0.0

spec_type

规范类型标识符。必须是 template

name: template_name

此模板的唯一且用户友好名称。必须遵循 Snowflake 标识符规则，最多 75 个字符。name_version 对在此账户的所有模板中必须是唯一的。

version: version_string

此模板的版本标识符（最多 20 个字符）。必须遵循 Snowflake 标识符规则。版本字符串在对 VIEW_TEMPLATES 和 VIEW_REGISTERED_TEMPLATES 的响应中拥有自己的列，因此请使用可按递增值排序的值。示例：V0

type

模板类型。以下值之一：

sql_analysis：选择使用时默认使用的角色和仓库。数据分析操作模板。
sql_activation：选择使用时默认使用的角色和仓库。数据激活操作模板。

:samp:`description: {template_description}`（可选）

对此模板功能的简要描述（最多 1,000 个字符）。

:samp:`methodology: {methodology_description}`（可选）

关于此模板工作原理的更详细说明（最多 1,000 个字符）。

``parameters``（可选）

此模板中所有用户提供的参数列表。每个项目可以具有以下字段：

name：选择使用时默认使用的角色和仓库。参数名称，需为有效的 Snowflake 标识符，最多 255 个字符。
``description``（可选）：人类可读的参数描述（最多 500 个字符）。
``required``（可选）：参数是否为必填项。默认值为 false。
``default``（可选）：参数默认值，可以是任何数据类型。
``type``（可选）：参数的预期数据类型。以下之一：string、integer、number、boolean、array 或 object。

``code_specs``（可选）

一个或多个代码捆绑包，用于定义此模板所引用的任何函数。当模板调用自定义函数时为必填项。代码规范 IDs 具有版本属性；如果您想访问函数的新版本，必须在此处更新代码规范 ID，而无需修改模板本身（模板中调用的是不带版本属性的函数名）。代码规范名称中必须包含下划线，且符合正则表达式模式 [A-Za-z]\w{0,74}_\w{1,20}。

template

模板内容。对于 SQL 模板，这包含 JinjaSQL 模板。有关更多信息，请参阅模板设计。

向模板公开的列名由数据产品规范中该列的 category 和 column_type 值决定。有关更多信息，请参阅源列重命名。

示例¶

api_version: 2.0.0
spec_type: template
name: trivial_template
version: V1
type: sql_analysis
description: Simple one-row template.
methodology: Always returns "1". Requires one source table.

parameters:
  - name: row_count
    description: Count of rows
    required: true

template: |
    SELECT 1 FROM IDENTIFIER( {{ source_table[0] }} ) LIMIT {{ row_count }};