使用开发者 APIs 按顺序执行模板

复杂的分析可能需要按特定顺序执行多个模板，有时使用一个模板的输出作为另一个模板的输入。提供商可以创建 模板链 来定义一系列需要按特定顺序执行的模板。在定义此模板链时，提供商可以指定特定模板的结果是否可供链中的后续模板使用。

Clean Room 用户执行模板链来开展分析，该分析以预定义的顺序运行链中的模板。

关于中间结果

如果提供商希望一个模板的结果可供模板链中的后续模板可用，他们可以为模板的结果创建缓存。每个具有缓存的模板也有该缓存的过期时间。

如果提供商指定模板具有缓存，则用户首次执行模板链时，该模板的结果将存储在 Clean Room 内的表中。此基础表仅供 Clean Room 本身访问。下次用户执行模板链时，Snowflake Data Clean Rooms 会在执行模板之前检查缓存是否已过期。具有缓存结果的模板不会再次执行，除非缓存已过期。

模板链中的后续模板可以在模板中包含适当的 Jinja 参数，以使用缓存作为输入。

定义模板链

提供商使用 provider.add_template_chain 命令创建模板链。提供商要添加到新模板链的模板必须存在，才能创建模板链。

provider.add_template_chain 命令接受以下实参：

  • Clean Room 的名称（字符串）。

  • 模板链的名称（字符串）。

  • 模板链中的模板（JSON 对象的数组）。

有关使用 provider.add_template_chain 命令创建模板链的示例，请参阅 示例。

将模板添加到模板链

提供商将 JSON 对象数组传递到 provider.add_template_chain，其中每个 JSON 对象代表一个模板，从而定义哪些模板是模板链的一部分。JSON 对象的顺序决定了模板的执行顺序。

模板的 JSON 对象可以包括以下字段：

:code:`template_name`（字符串）

指定要添加到模板链的模板。模板必须已存在。

此字段为必填字段。

:code:`cache_results`（布尔值）

确定模板的结果是否 已缓存，以便模板链中的其他模板可以访问它们。要缓存结果，请指定 TRUE。

此字段为必填字段。如果为 TRUE，则 output_table_name 和 cache_expiration_hours 字段也是必填字段。

:code:`output_table_name`（字符串）

如果 cache_results = TRUE，则指定已存储模板结果的 Snowflake 表的名称。

如果 cache_results = TRUE，则此字段为必填字段。

:code:`jinja_output_table_param`（字符串）

如果 cache_results = TRUE，则指定其他模板必须包括的 Jinja 参数的名称，以接受 output_table_name 中存储的结果。

此字段是可选字段。

:code:`cache_expiration_hours`（整数）

如果 cache_results = TRUE，则指定删除缓存中结果之前的小时数。当缓存过期时，那么下次执行模板链时，缓存会使用模板的结果刷新。

如果 cache_results = TRUE，则此字段为必填字段。

示例

在此示例中，提供商希望：

  • 在 Clean Room collab_clean_room 中创建模板链 insights_chain。

  • 定义模板链，以便 crosswalk 模板在 transaction_insights 模板之前执行。

  • 缓存 crosswalk 模板的结果，以便用作 transaction_insights 模板的输入。

CALL samooha_by_snowflake_local_db.provider.add_template_chain(
  'collab_clean_room',
  'insights_chain',
  [
    {
      'template_name': 'crosswalk',
      'cache_results': True,
      'output_table_name': 'crosswalk',
      'jinja_output_table_param': 'crosswalk_table_name',
      'cache_expiration_hours': 2190
    },
    {
      'template_name': 'transaction_insights',
      'cache_results': False
    }
  ]
);
Copy

有关每个 JSON 对象的更多信息，请参阅 将模板添加到模板链。

执行模板链

Clean Room 用户运行 consumer.run_analysis 命令来执行模板链，该命令与用于执行单个模板的命令相同。执行模板链会按照预定义的顺序运行链中的每个模板，以获得最终结果。

consumer.run_analysis 命令接受传递到模板链中 Jinja 模板的实参。您可以执行 consumer.get_arguments_from_template_chain 命令，确定链中的模板期望的实参。

传递到 consumer.run_analysis 的实参可能是链中特定模板的特定实参，也可能是针对链中每个模板的实参。

通用实参

如果您要将实参传递到模板链中的每个模板，句法类似于使用 consumer.run_analysis 运行单个模板。例如，以下命令将 where_clause 实参的值传递到模板链中的所有模板：

CALL samooha_by_snowflake_local_db.consumer.run_analysis(
  'collab_clean_room',
  'insights_chain',
  ['MY_CONSUMER_DB.C_SCHEMA.CONVERSIONS'],
  ['PROVIDER_DB.P_SCHEMA.EXPOSURES'],
  object_construct(
    'where_clause', 'p.EMAIL=c.EMAIL'
  )
);
Copy
特定于模板的实参

如果您要将实参传递到特定模板，请将另一个 object_construct 作为顶层 object_construct 的子级添加，并以模板的名称作为字段名称。例如，以下命令仅将 dimensions 实参的值传递到 crosswalk_template 模板：

CALL samooha_by_snowflake_local_db.consumer.run_analysis(
  'collab_clean_room',
  'insights_chain',
  ['MY_CONSUMER_DB.C_SCHEMA.CONVERSIONS'],
  ['PROVIDER_DB.P_SCHEMA.EXPOSURES'],
  object_construct(
    'where_clause', 'p.EMAIL=c.EMAIL',
    'crosswalk_template', object_construct(
      'dimensions', ['p.CAMPAIGN']
    )
  )
);
Copy

模板链命令

您可以使用以下命令处理模板链：

命令

描述

provider.add_template_chain

创建新的模板链。

provider.view_added_template_chains

consumer.view_added_template_chains

返回已添加到 Clean Room 的所有模板链。

provider.view_template_chain_definition

consumer.view_template_chain_definition

返回模板链的定义。

provider.clear_template_chain

从 Clean Room 中删除一个模板链。

provider.clear_all_template_chains

从 Clean Room 中删除所有模板链。

consumer.get_arguments_from_template_chain

返回模板链中所有模板的预期实参。

有关这些命令的更多信息，请参阅：

语言: 中文