使用模板函数

要启用数据库名称和架构名称等 SQL 标识符的连接，并提供在不同上下文中使用加引号或未加引号的标识符的灵活性，Snowflake CLI 提供了以下一组效用函数，您可以在项目模板定义模板中使用：

fn.concat_ids()

  • 输入：一个或多个字符串实参（SQL ID 或纯字符串）

  • 输出：有效的 SQL ID（加引号或未加引号）

fn.concat_ids() 函数用于将多个字符串字符串连接成一个表示 SQL ID（加引号或未加引号）的字符串。如果任何输入字符串是有效的加引号标识符，则它将在连接之前取消转义。如果结果字符串中包含非 SQL 安全字符或任何输入字符串包含有效的加引号标识符，则会对结果字符串进行转义和加引号处理。

示例：

  • 调用 :fn.concat_ids('id1_', '"quoted_id2"') outputs "id1_quoted_id2"，因为其中一个输入值是加引号的标识符。

  • 调用 fn.concat_ids('id1_', 'id2') outputs id1_id2 因为没有一个输入值是加引号的标识符，也没有一个输入值包含非 SQL 安全字符。

fn.str_to_id()

  • 输入：一个或多个字符串实参（SQL ID 或纯字符串）

  • 输出：有效的 SQL ID（加引号或未加引号）

fn.str_to_id() 函数会返回一个字符串作为 ID。如果输入字符串包含有效的加引号或未加引号的标识符，该函数将按原样返回它。但是，如果输入字符串包含未正确加引号的不安全 SQL 字符，该函数会返回加引号的 ID，可用于转义不安全的字符。

示例：

  • 调用 fn.str_to_id('id1') 会返回 id1，因为它是一个有效的未加引号的标识符。

  • 调用 fn.str_to_id('unsafe"id') 会返回 "unsafe""id"，因为它包含不安全 SQL 字符。

fn.id_to_str()

  • 输入：一个字符串实参（SQL ID 或纯字符串）

  • 输出：一个纯字符串

如果输入是有效的 SQL ID，该函数会返回一个未转义的纯字符串。否则，该函数将按原样返回输入字符串。

示例：

  • 调用 fn.id_to_str('id1') 会返回 id1，因为它已经未加引号了。

  • 调用 fn.id_to_str('"quoted""id.example"') 会返回 quoted"id.example。

fn.get_username()

  • 输入：一个包含回退值的可选字符串

  • 输出：从操作系统检测到的当前用户名

从操作系统环境变量返回当前用户名。如果未找到当前用户名或为空，它将返回一个空值或使用回退值（如果提供了回退值）。

示例：

  • 如果找到，则 fn.get_username('default_user') 会返回当前用户名，否则，返回 default_user。

fn.sanitize_id()

  • 输入：一个字符串实参

  • 输出：有效的未加引号 SQL ID

函数 fn.sanitize_id() 会移除来自输入的任何不安全 SQL 的字符并将其作为有效的未加引号的 SQL ID。如果结果不是以字母或下划线开头，则会在其后附加一个下划线。对于非常长的字符串，该函数会将字符串截断为 255 个字符。

示例：

  • 使用 fn.sanitize_id('Some.id"With_Special_Chars') 时，输出是 SomeidWith_Special_Chars。

  • 使用 fn.sanitize_id('1abc') 时，输出是 _1abc。

用例示例

下面的示例展示了如何在 snowflake.yml 项目定义文件中使用这些函数：

definition_version: 2
entities:
  pkg:
    type: application package
    identifier: <% fn.concat_ids(ctx.env.app_name, ctx.env.pkg_suffix) %>
    artifacts:
      - src: app/*
        dest: ./
  app:
    type: application
    identifier: <% fn.concat_ids(ctx.env.app_name, ctx.env.app_suffix) %>

env:
  app_name: myapp_base_name_<% fn.sanitize_id(fn.get_username()) %>
  app_suffix: _app_instance
  pkg_suffix: _pkg
Copy

下面的示例演示如何在 SQL 文件中使用函数：

DESC APPLICATION <% fn.str_to_id(ctx.entities.app.identifier) %>;
DESC APPLICATION PACKAGE <% fn.str_to_id(ctx.entities.pkg.identifier) %>;
Copy
语言: 中文