Snowflake Data Clean Room：使用者 API 参考指南¶

consumer.grant_run_on_cleanrooms_to_role¶

描述： 授予指定角色在指定 Clean Room 上运行过程子集的权限。Clean Room 必须 安装 在此账户中，而非由此账户 创建。（也就是说，仅限于您是使用者的 Clean Room。）

要授予 Clean Room 有限的使用权限，请授予用户指定角色而非 SAMOOHA_APP_ROLE。了解有关角色访问权限的详情。

以下过程可使用此处指定的角色运行：

• CONSUMER.VIEW_ADDED_TEMPLATES

• CONSUMER.VIEW_ADDED_TEMPLATE_CHAINS

• CONSUMER.GET_ARGUMENTS_FROM_TEMPLATE

• CONSUMER.VIEW_COLUMN_POLICY

• CONSUMER.VIEW_CONSUMER_DATASETS

• CONSUMER.VIEW_JOIN_POLICY

• CONSUMER.VIEW_PROVIDER_COLUMN_POLICY

• CONSUMER.VIEW_PROVIDER_DATASETS

• CONSUMER.VIEW_PROVIDER_JOIN_POLICY

• CONSUMER.VIEW_REMAINING_PRIVACY_BUDGET

• CONSUMER.RUN_ANALYSIS

• CONSUMER.VIEW_PROVIDER_ACTIVATION_POLICY

• CONSUMER.VIEW_ACTIVATION_POLICY

• CONSUMER.RUN_ACTIVATION

实参：

• cleanroom_names（字符串数组） – 要授予指定角色有限访问权限的所有 Clean Room 的名称。

• run_role_name（字符串） – 对指定 Clean Room 具有有限权限的角色的名称。必须在调用此过程之前创建角色。

返回： （字符串） – 成功或失败消息。

示例：

CREATE ROLE MARKETING_ANALYST_ROLE;
CALL samooha_by_snowflake_local_db.consumer.grant_run_on_cleanrooms_to_role(
  ['overlap_cleanroom', 'market_share_cleanroom'],
  'MARKETING_ANALYST_ROLE'
);

consumer.revoke_run_on_cleanrooms_from_role¶

描述： 撤销指定角色在指定 Clean Room 上的权限。请注意，如果用户有权访问未撤销的角色，或者拥有 SAMOOHA_APP_ROLE，则他们仍然可以在指定 Clean Room 中运行 Clean Room 过程。

实参：

• cleanroom_names（字符串数组） – 此账户中一个或多个 Clean Room 的名称。

• run_role_name（字符串） – 对此账户中指定的 Clean Room 上不应再拥有有限权限的角色名称。

返回： （字符串） – 成功或失败消息。

示例：

CALL samooha_by_snowflake_local_db.consumer.revoke_run_on_cleanrooms_from_role(
  ['overlap_cleanroom', 'market_share_cleanroom'],
  'TEMP_USERS_ROLE'
);

consumer.install_cleanroom¶

描述： 安装（联接）指定提供商创建的 Clean Room。请注意，多次调用此命令时，每次都会清理现有的 Clean Room；如果您在第二次安装完成前中断安装，则 Clean Room 将损坏，您需要完成此过程 Clean Room 才可用。

实参：

• cleanroom_name（字符串） – 要安装的 Clean Room 的名称。

• provider_account_locator（字符串） – 创建此 Clean Room 的提供商的账户定位器。

返回： （字符串） 成功消息。

示例：

call samooha_by_snowflake_local_db.consumer.install_cleanroom($cleanroom_name, $provider_locator);

consumer.is_enabled¶

描述：clean room 安装完毕后，提供商只需约 1 分钟即可完成设置并自行启用它。此函数允许用户检查 clean room 的状态，并查看其是否已启用。安装 clean room 约一分钟后，标志通常会切换为 True。

实参： cleanroom_name（字符串）

返回： 已启用（布尔值）

示例：

call samooha_by_snowflake_local_db.consumer.is_enabled($cleanroom_name);

consumer.uninstall_cleanroom¶

描述：卸载使用者账户中的 Clean Room。此操作这将移除与 Clean Room 相关的所有数据库，包括共享的 Clean Room 数据库。请注意，使用 consumer.install_cleanroom 可以随时重新安装 Clean Room。

实参： cleanroom_name（字符串）

返回： success message（字符串）

示例：

call samooha_by_snowflake_local_db.consumer.uninstall_cleanroom($cleanroom_name);

library.enable_laf_on_account¶

描述： 在当前账户上启用 Cross-Cloud Auto-Fulfillment。需要 ACCOUNTADMIN 角色。

实参： 无

返回：（字符串）成功消息。

示例：

USE ROLE ACCOUNTADMIN;
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.library.enable_laf_on_account();

consumer.is_laf_enabled_for_cleanroom¶

描述： 描述该 Clean Room 是否启用了 Cross-Cloud Auto-Fulfillment。Cross-Cloud Auto-Fulfillment 必须由账户管理员配置。

实参：

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

返回： 该 Clean Room 是否启用了 Cross-Cloud Auto-Fulfillment。

示例：

CALL samooha_by_snowflake_local_db.consumer.is_laf_enabled_for_cleanroom($cleanroom_name);

consumer.setup_cleanroom_request_share_for_laf¶

描述： 允许与特定 Clean Room 的指定提供商进行跨云请求共享。这是跨区域 Clean Room 具有完整功能（包括请求日志、使用者模板请求和提供商运行的分析）的必要条件。

实参：

• cleanroom_name（字符串） – Clean Room 名称。

• provider_account_name（字符串） – 提供商的 数据共享账户标识符。

返回： （字符串） 成功消息。

示例：

CALL samooha_by_snowflake_local_db.consumer.setup_cleanroom_request_share_for_laf(
      $cleanroom_name, $provider_account_name);

consumer.setup_activation_share_to_laf_consumer¶

描述： 支持在不同云区域的提供商和使用者之间进行提供商激活。

实参：

• provider_account – 一个或多个以逗号分隔的提供商 数据共享账户标识符。

返回： （字符串） 成功消息。

示例：

CALL samooha_by_snowflake_local_db.consumer.setup_activation_share_to_laf_consumer('org1.locator1,org2.locator2');

library.is_provider_run_enabled¶

描述：检查此 Clean Room 是否允许提供商运行分析。注意：在提供商可在此 Clean Room 中运行分析之前，仍然需要通过调用 consumer.enable_templates_for_provider_run 给予明确批准。

实参： cleanroom_name（字符串）

输出： enabled message（字符串）

示例：

call samooha_by_snowflake_local_db.library.is_provider_run_enabled($cleanroom_name)

consumer.enable_templates_for_provider_run¶

描述：授予提供商在所请求的 Clean Room 中运行分析的权限。在提供商调用 provider.enable_provider_run_analysis 以允许提供商在 Clean Room 上运行分析之后，调用此函数。consumer.enable_templates_for_provider_run 授予提供商权限，允许其在指定 Clean Room 内的指定模板中运行分析，次数不限。

实参：

• cleanroom_name（字符串） – 提供商可以运行分析的 Clean Room 的名称。

• template_names（字符串数组） – 提供商可以运行的 Clean Room 中一个或多个模板的名称数组。

• enable_differential_privacy（布尔） – 如果为 TRUE，则为 template_names 中列出的所有模板启用差分隐私。只有为 Clean Room 本身启用差分隐私时，才能为这些模板启用差分隐私。您可以通过调用 consumer.is_dp_enabled 来查看 Clean Room 的差分隐私状态。您可以通过调用 consumer.set_privacy_settings 来自定义隐私设置。了解详情。

• template_configuration（对象，可选） – 一个可选对象，用于为每个模板指定其他设置。此对象包含键值对，其中键是模板名称（来自 template_names），值是具有以下属性的对象：

  • warehouse_type（字符串） – 提供商可以在此模板中使用的允许仓库类型。允许的值是为 WAREHOUSE_TYPE 定义的值。

  • warehouse_size（字符串数组） – 一种或多种允许的仓库规模，可用于该仓库类型和模板。允许的值是为 WAREHOUSE_SIZE 定义的值。

返回： （字符串） 成功或失败消息。

示例：

-- Simple example
CALL samooha_by_snowflake_local_db.consumer.enable_templates_for_provider_run($cleanroom_name, ['prod_overlap_analysis'], FALSE);

-- Specify warehouse types that the provider can request for each template.
call samooha_by_snowflake_local_db.CONSUMER.enable_templates_for_provider_run(
  $cleanroom_name,
  [$template1, $template2],
  TRUE,
  {
    $template1: {'warehouse_type': 'STANDARD', 'warehouse_size': ['MEDIUM', 'LARGE']},
    $template2: {'warehouse_type': 'SNOWPARK-OPTIMIZED', 'warehouse_size': ['MEDIUM', 'XLARGE']},
    $template3: {'warehouse_type': 'STANDARD', 'warehouse_size': ['MEDIUM', 'XLARGE']} 
  });

consumer.prepare_multiprovider_flow¶

描述： 向指定 Clean Room 的提供商发送运行多提供商查询的请求。此过程实际上并不运行请求；它只是通过调用 consumer.execute_multiprovider_flow 来向提供商请求将来运行此请求的权限。

如果提供商批准，使用者就可以随心所欲地调用 consumer.execute_multiprovider_flow 来运行查询（具体取决于任何配置的差分隐私设置）。如果您想在使用新值调用 prepare_multiprovider_flow 后重新运行之前批准的查询，则仍必须仍使用该之前的查询调用 prepare_multiprovider_flow，但无需等待提供商批准即可运行 consumer.execute_multiprovider_flow。

该请求的有效期为四小时；之后，该请求将从队列中删除。

实参：

• cleanroom_names（字符串数组） – 使用者账户中 Clean Room 名称的数组。必须安装这些 Clean Room。

• template_name（字符串） – 要在 cleanroom_names 中列出的每个 Clean Room 中运行的模板的名称。这可以是 Clean Room 提供商添加的 Snowflake 提供的模板，也可以是您之前通过调用 consumer.create_template_request 向 Clean Room 提交的自定义模板无论哪种情况，模板都必须已经存在于 Clean Room 中，才能将请求提交给 Clean Room 提供商。

• arguments（对象） – 具有以下字段的对象，用于填充模板：

  • source_table（字符串数组） – 用于填充模板可用的 source_table 数组的表名称数组。每个表名称的语法是 cleanroom_name.db.schema.table。在请求列出的表中，每个提供商只能看到其自己的 Clean Room 表。

  • my_table（字符串数组） – 您自己数据的表名称数组，用于填充模板可用的 my_table 数组。 使用与传递给 consumer.run_analysis 的 consumer_tables 实参相同的语法。

  • 任何其他模板变量 – 将模板的任何必填值作为键/值对传递。

返回： （字符串） 传递给 consumer.execute_multiprovider_flow 的请求 ID。

示例：

CALL samooha_by_snowflake_local_db.consumer.prepare_multiprovider_flow(
    [$cleanroom_name_1, $cleanroom_name_2],
    'prod_aggregate_data',
    object_construct(
        'source_table', [
            CONCAT($cleanroom_name_1, '.SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'), 
            CONCAT($cleanroom_name_2, '.SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS')
        ],
        'my_table', ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']),
        'hem_col', ['p1.HASHED_EMAIL', 'p2.HASHED_EMAIL'],
        'dimensions', ['p1.STATUS', 'p2.STATUS'],
        'consumer_join_col', 'HASHED_EMAIL'
    )
);

consumer.execute_multiprovider_flow¶

描述： 运行使用者向 consumer.prepare_multiprovider_flow 提交的最新查询。该过程在提供商批准的每个指定 Clean Room 中运行查询，并返回所有查询结果的并集。运行此过程是判断提供商是否批准查询的唯一方法。

实参：

• cleanroom_names（字符串数组） – 应在其中运行准备好的查询的 Clean Room 名称数组。该数组必须与查询请求中 Clean Room 的完整列表相匹配。

• request_id（字符串，可选） –prepare_multiprovider_flow 返回的请求 ID。

返回： （表） 所有批准的 Clean Room 结果汇总。如果提供商从未批准过来自该使用者的查询，则查询将失败。但是，如果提供商批准了此使用者的不同查询，但未批准最新的查询，则该过程将返回一个空的结果集。

示例：

CALL samooha_by_snowflake_local_db.consumer.execute_multiprovider_flow([$cleanroom1, $cleanroom2], $request_id);

consumer.register_db¶

描述：将数据库添加到 Clean Room 后，您就可以链接数据库中的任何数据集。如果没有调用此函数，则必须单独向 samooha_app_role 授予权限。

实参： db_name（字符串）

返回： success message（字符串）

示例：

USE ROLE <ROLE_WITH_MANAGE GRANTS>;

call samooha_by_snowflake_local_db.consumer.register_db('SAMOOHA_SAMPLE_DATABASE');

library.register_schema¶

描述：与 register_db 类似，但在架构级运行。可以传入表示完全限定架构名称的数组或字符串，并授予 SAMOOHA_APP_ROLE 角色选择权限，使用户能够将架构中的对象链接到 Clean Room 中。

如果要注册托管访问架构（即使用 WITH MANAGED ACCESS 参数创建的架构），请改用 library.register_managed_access_schema。

实参： schema_name（数组）

返回： success message（字符串）

示例：

USE ROLE <ROLE_WITH_MANAGE GRANTS>;

call samooha_by_snowflake_local_db.library.register_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);

library.register_managed_access_schema¶

描述：类似于 register_schema，但注册了使用 WITH MANAGED ACCESS 参数创建的架构。可以传入表示完全限定架构名称的数组或字符串，并授予 SAMOOHA_APP_ROLE 角色选择权限，使用户能够将架构中的对象链接到 Clean Room 中。

实参： schema_name（数组）

返回： success message（字符串）

示例：

USE ROLE <ROLE_WITH_MANAGE GRANTS>;

call samooha_by_snowflake_local_db.library.register_managed_access_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);

library.register_objects¶

描述：授予 clean room 访问所有类型的表和视图的权限，使其可以通过调用 consumer.link_datasets 链接到 clean room。您可以通过调用 library.register_schema、library.register_managed_access_schema 或 consumer.register_db 注册更广泛的对象组。

实参：

• object_names（数组） – 完全限定的对象名称数组。然后可以将这些对象链接到 clean room。

返回： success message（字符串）

示例

要注册表和视图：

USE ROLE <ROLE_WITH_MANAGE GRANTS>;

call samooha_by_snowflake_local_db.library.register_objects(
    ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS','SAMOOHA_SAMPLE_DATABASE.INFORMATION_SCHEMA.FIELDS']);

library.enable_external_tables_on_account¶

描述： 允许在此账户的所有 Clean Room 中使用 Iceberg 表或外部表。必须 同时 由提供商和使用者账户中的 ACCOUNTADMIN 调用，以允许通过 任一 账户链接 Iceberg 表或外部表。要将此功能限制在此账户中的特定 Clean Room，请改为调用 enable_external_tables_for_cleanroom。

实参： 无

返回： （字符串） 成功或失败消息。

示例：

USE ROLE ACCOUNTADMIN;

CALL samooha_by_snowflake_local_db.library.enable_external_tables_on_account();

consumer.enable_external_tables_for_cleanroom¶

描述： 使使用者能够将 Iceberg Tables 或 External Tables 链接到此账户中的指定 Clean Room。要允许该账户中的所有 Clean Room 使用 Iceberg 表和外部表，请改为调用 enable_external_tables_on_account。

实参：

• cleanroom_name（字符串） - Clean Room 名称，提供商可将 Iceberg 表或外部表链接至该 Clean Room。

返回： （字符串） 成功或失败消息。如果成功，它将触发安全扫描，并提供安全扫描成功后生成的补丁编号。

示例：

CALL samooha_by_snowflake_local_db.provider.enable_external_tables_for_cleanroom(
    $cleanroom_name);

library.register_table_or_view – 已弃用¶

描述：注册所有类型的表和视图。

实参： object_names（数组）、is_view（布尔）、is_iceberg（布尔）、is_external（布尔）、is_under_managed_access_schema（布尔）

输出 success message（字符串）

示例

要注册表：

call samooha_by_snowflake_local_db.library.register_table_or_view(
    ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],
    false,
    false,
    false,
    false);

要注册 Iceberg 表：

call samooha_by_snowflake_local_db.library.register_table_or_view(
        ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'], 
        false, 
        true,
        false,
        false);

library.register_table – 已弃用¶

描述：与 register_db 类似，但在表级运行。可以传入表示完全限定表名称的数组或字符串，并授予 SAMOOHA_APP_ROLE 角色选择权限，使用户能够将表链接到 clean room 中。

如果要在托管访问架构（即使用 WITH MANAGED ACCESS 参数创建的架构）中注册表，请改用 library.register_managed_access_table。

实参： table_name（数组）

返回： success message（字符串）

示例：

call samooha_by_snowflake_local_db.library.register_table(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);

library.register_managed_access_table – 已弃用¶

描述：类似于 register_table，但在使用 WITH MANAGED ACCESS 参数创建的架构中注册表。可以传入表示完全限定表名称的数组或字符串，并授予 SAMOOHA_APP_ROLE 角色选择权限，使用户能够将表链接到 clean room 中。

实参： table_name（数组）

返回： success message（字符串）

示例：

call samooha_by_snowflake_local_db.library.register_managed_access_table(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);

library.register_view – 已弃用¶

描述：与 register_db 类似，但在视图级运行。可以传入表示完全限定视图名称的数组或字符串，并授予 SAMOOHA_APP_ROLE 角色选择权限，使用户能够将视图链接到 clean room 中。

如果要在托管访问架构（即使用 WITH MANAGED ACCESS 参数创建的架构）中注册视图，请改用 library.register_managed_access_view。

实参： view_name（数组）

返回： success message（字符串）

示例：

call samooha_by_snowflake_local_db.library.register_view(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);

library.register_managed_access_view – 已弃用¶

描述：类似于 register_view，但在使用 WITH MANAGED ACCESS 参数创建的架构中注册视图。可以传入表示完全限定视图名称的数组或字符串，并授予 SAMOOHA_APP_ROLE 角色选择权限，使用户能够将视图链接到 clean room 中。

实参： view_name（数组）

返回： success message（字符串）

示例：

call samooha_by_snowflake_local_db.library.register_managed_access_view(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);

library.unregister_db¶

描述：颠倒 register_db 过程，并移除向 SAMOOHA_APP_ROLE 角色和 Snowflake Data Clean Room 本地应用程序授予的数据库级权限。这样还会从 UI 下拉元素中移除所有数据库。

实参： db_name（字符串）

返回： success message（字符串）

示例：

USE ROLE <ROLE_WITH_MANAGE GRANTS>;

call samooha_by_snowflake_local_db.library.unregister_db('SAMOOHA_SAMPLE_DATABASE');

library.unregister_schema¶

描述：取消注册一个架构，以防止用户将其表和视图链接到 clean room。

如果要取消注册托管访问架构（即使用 WITH MANAGED ACCESS 参数创建的架构），请改用 library.unregister_managed_access_schema。

实参： schema_name（数组）

返回： success message（字符串）

示例：

USE ROLE <ROLE_WITH_MANAGE GRANTS>;

call samooha_by_snowflake_local_db.library.unregister_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);

library.unregister_managed_access_schema¶

描述：类似于 unregister_schema，但取消注册了使用 WITH MANAGED ACCESS 参数创建的架构。

实参： schema_name（数组）

返回： success message（字符串）

示例：

call samooha_by_snowflake_local_db.library.unregister_managed_access_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);

library.unregister_objects¶

描述：撤销 clean room 对所有类型的表和视图的访问权限。此账户管理的所有 clean room 中的任何用户将无法再使用这些对象。

实参：

• object_names（数组） – 应该撤销访问权限的完全限定对象名称数组。

返回： success message（字符串）

示例

要取消注册表和视图：

USE ROLE <ROLE_WITH_MANAGE GRANTS>;

call samooha_by_snowflake_local_db.library.unregister_objects(
    ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS','SAMOOHA_SAMPLE_DATABASE.INFORMATION_SCHEMA.FIELDS']);

library.unregister_table_or_view – 已弃用¶

描述：取消注册所有类型的表和视图。

实参： object_names（数组）、is_view（布尔）、is_iceberg（布尔）、is_external（布尔）、is_under_managed_access_schema（布尔）

输出 success message（字符串）

示例

要取消注册表：

call samooha_by_snowflake_local_db.library.unregister_table_or_view(
    ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],
    false,
    false,
    false,
    false);

library.unregister_table – 已弃用¶

描述：与 unregister_db 类似，但在表级运行。可以传入表示完全限定表名称的数组或字符串来取消注册表。用户无法将取消注册的表链接到 Clean Room 中。

如果要在托管访问架构（即使用 WITH MANAGED ACCESS 参数创建的架构）中取消注册表，请改用 library.unregister_managed_access_table。

实参： table_name（数组）

返回： success message（字符串）

示例：

call samooha_by_snowflake_local_db.library.unregister_table(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);

library.unregister_managed_access_table – 已弃用¶

描述：类似于 unregister_table，但在托管访问架构（即使用 WITH MANAGED ACCESS 创建的架构）中取消注册表。

实参： table_name（数组）

返回： success message（字符串）

示例：

call samooha_by_snowflake_local_db.library.unregister_managed_access_table(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);

library.unregister_view – 已弃用¶

描述：与 unregister_db 类似，但在视图级运行。可以传入表示完全限定视图名称的数组或字符串来取消注册视图。用户无法将取消注册的视图链接到 Clean Room 中。

如果要在托管访问架构（即使用 WITH MANAGED ACCESS 参数创建的架构）中注册视图，请改用 library.unregister_managed_access_view。

实参： view_name（数组）

返回： success message（字符串）

示例：

call samooha_by_snowflake_local_db.library.unregister_view(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);

library.unregister_managed_access_view – 已弃用¶

描述：类似于 unregister_view，但在托管访问架构（即使用 WITH MANAGED ACCESS 创建的架构）中取消注册视图。

实参： view_name（数组）

返回： success message（字符串）

示例：

call samooha_by_snowflake_local_db.library.unregister_managed_access_view(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);

consumer.link_datasets¶

描述：将表或视图链接到 Clean Room，根据您指定的任何联接和列策略，使该 Clean Room 内的模板可以访问该表。

实参：

• cleanroom_name（字符串） – Clean Room 的名称，用于授予权限。

• tables_list（字符串数组） – 要提供给 Clean Room 的完全限定表或视图名称的列表。这些对象必须首先用适当的 注册方法 注册（提供 Clean Room 环境）。

返回： success message（字符串）

示例：

call samooha_by_snowflake_local_db.consumer.link_datasets($cleanroom_name, ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS', 'MY_DB.MY_SCH.EXPOSURES']);

consumer.unlink_datasets¶

描述：删除所有用户对指定 Clean Room 中指定表或视图的访问权限。这仅适用于使用者提供的数据。

实参：

• cleanroom_name（字符串） – 应删除访问权限 Clean Room 的名称。

• tables_list（字符串数组） – 应阻止访问权限的完全限定表或视图名称的列表。

返回： success message（字符串）

示例：

call samooha_by_snowflake_local_db.consumer.unlink_datasets($cleanroom_name, 
  ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS', 'MYDB.MYSCH.EXPOSURES']);

consumer.view_consumer_datasets¶

描述： 查看此账户中任何使用者链接到指定 Clean Room 的所有表和视图。

实参：

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

返回： 链接到指定 Clean Room 的对象表，以及每个对象的 Clean Room 内部视图名称。

示例：

call samooha_by_snowflake_local_db.consumer.view_consumer_datasets($cleanroom_name);

consumer.set_join_policy¶

描述：指定在使用 Provider Run Analysis 时，允许提供商在 Clean Room 内运行模板时对哪些列执行联接。请注意，列策略是 仅替换，因此如果再次调用该函数，先前设置的列策略将被当前策略完全替换。

请注意，进行检查的方式是解析为查找任何未经授权的列而要对数据运行的 SQL 查询。使用这些检查可能无法找出含有通配符的查询，因此，设计分析模板时仍应慎重。

实参： cleanroom_name（字符串）、table_and_col_names（数组）

返回： success message（字符串）

示例：

call samooha_by_snowflake_local_db.consumer.set_join_policy($cleanroom_name,
  ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:HASHED_EMAIL', 'MYDB.MYSCH.EXPOSURES:HASHED_EMAIL']);

consumer.set_column_policy¶

描述：设置提供商可对数据中的哪些列进行操作。只有在添加模板后才可调用此函数。这也是模板的一个函数，因此输入的形式必须是 template_name:full_table_name:column_name。请注意，列策略是 仅替换，因此如果再次调用该函数，先前设置的列策略将被当前策略完全替换。

不应在电子邮件地址等标识列上调用列策略。它只能用于聚合列和分组依据列。

请注意，进行检查的方式是解析为查找任何未经授权的列而要对数据运行的 SQL 查询。使用这些检查可能无法找出含有通配符的查询，因此，设计分析模板时仍应慎重。

检查在名为 dimensions 或 measure_columns 的 SQL Jinja 实参上进行。请确保使用这两个标签来启用此检查。

实参： cleanroom_name（字符串）、analysis_and_table_and_columns（数组）

返回： success message（字符串）

示例：

call samooha_by_snowflake_local_db.consumer.set_column_policy($cleanroom_name,
['prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:STATUS',
 'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:AGE_BAND',
 'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:DAYS_ACTIVE']);

consumer.view_column_policy¶

描述：查看使用者已应用于 Clean Room 的所有列策略。

实参： cleanroom_name（字符串）

返回： 列策略（表）

示例：

call samooha_by_snowflake_local_db.consumer.view_column_policy($cleanroom_name);

consumer.view_provider_column_policy¶

描述：查看提供商已应用于 Clean Room 的所有列策略。

实参： cleanroom_name（字符串）

返回： 列策略（表）

示例：

call samooha_by_snowflake_local_db.consumer.view_provider_column_policy($cleanroom_name);

consumer.view_template_definition¶

描述：Clean Room 模板定义可帮助确定哪些参数需要传递给模板。

如果应用 is_mbscated 实参 隐藏了 模板，则无法看到模板定义。

实参： cleanroom_name（字符串）、template_name（字符串）

返回： 模板定义（字符串）

示例：

call samooha_by_snowflake_local_db.consumer.view_template_definition($cleanroom_name, 'prod_overlap_analysis');

consumer.get_arguments_from_template¶

描述：定义应如何组织数据以及每个模板需要哪些数据，以确保输出易于理解。

实参： cleanroom_name（字符串）、template_name（字符串）

返回： 实参列表和规范（表）

示例：

call samooha_by_snowflake_local_db.consumer.get_arguments_from_template($cleanroom_name, 'prod_overlap_analysis');

consumer.view_added_template_chains¶

描述：查看 clean room 中当前激活的模板链。

实参： cleanroom_name（字符串）

返回： 添加的模板链（表）

示例：

call samooha_by_snowflake_local_db.consumer.view_added_template_chains($cleanroom_name);

consumer.view_template_chain_definition¶

描述：返回模板链的属性。

实参： cleanroom_name（字符串）、template_chain_name（字符串）

返回： 模板链定义（字符串）

示例：

call samooha_by_snowflake_local_db.consumer.view_template_chain_definition($cleanroom_name, 'insights_chain');

consumer.run_analysis¶

描述：使用模板或模板链执行分析并返回结果表。

如果启用了差分隐私，则在已达到此模板的预算限制时，查询可能会失败。

如果通过应用 is_obscated 实参 隐藏了 模板，则必须使用 Snowflake Enterprise Edition 或更高版本才能运行模板。

实参：

• cleanroom_name（字符串） – 拥有要运行模板的 Clean Room 的名称。

• template_name（字符串） – 要在 Clean Room 中运行的模板或模板链的名称。

• consumer_tables（字符串数组） – 完全限定使用者表名称数组。它们被分配给 my_table 模板变量。这些表必须已经链接到 Clean Room。通过调用 consumer.view_consumer_datasets 查看可用表。例如，如果您传入['mytable1','mytable2','mytable3']，则模板可以分别以 {{my_table[0]}}、{{my_table[1]}} 和 {my_table[2]} 的形式访问这些值。

• provider_tables（字符串数组） – 完全限定提供商表名称数组。它们被分配给 source_table 模板变量。这些表必须已经链接到 Clean Room。通过调用 consumer.view_provider_datasets 查看可用表。例如，如果您传入 ['sourcetable1','sourcetable2','sourcetable3']，则模板可以分别以 {{source_table[0]}}、{{source_table[1]}} 和{{source_table[2]}} 的形式访问这些值。

• analysis_arguments（对象） – 具有传递给模板的键/值对的对象。模板可以通过键名访问变量。如果您传递 {'age':20}，模板将以 {{age}} 的形式访问该值。如果不需要值，则传入空对象。要查看需要哪些值，请通过调用 consumer.view_template_definition 检查相关模板。如果提供列名，请检查模板以确定是否需要使用表名限定列名。如果表别名为 p 或 c，则为列名使用小写形式的 p 和 c 表别名。即使用 p.age_band，而非 P.age_band。此对象有一个可选的保留值：

  • epsilon （浮动，可选） – 如果对此 Clean Room 启用了差分隐私，则指定 差分隐私的 esilon 值 (link removed)。默认值为 0.1。

• use_cache（布尔，可选） – 是否对同一查询使用缓存结果。默认值为 FALSE。

返回： （表） 查询结果。

示例：

call samooha_by_snowflake_local_db.consumer.run_analysis(
  $cleanroom_name,
  'prod_overlap_analysis',
  ['SAMOOHA_SAMPLE_DATABASE.MYDATA.CONVERSIONS'],  -- Consumer tables
  ['MYDB.MYSCH.EXPOSURES'],      -- Provider tables
  object_construct(
    'max_age', 30
  )
);

library.view_external_activation_history¶

描述： 查看当前账户的激活请求历史记录。

实参： 无

返回： 包含激活请求的详细信息和状态的表。

示例：

call SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.LIBRARY.view_external_activation_history();

consumer.set_activation_policy¶

描述：定义哪些列可以在激活模板中使用。这可以确保只有使用者批准的列可以与激活模板一起使用。

输入：cleanroom_name（字符串）、columns（数组）

columns 实参以 <template_name>:<fully_qualified_table_name>:<column_name> 格式传递。

输出： 成功消息

示例：

call samooha_by_snowflake_local_db.consumer.set_activation_policy('my_cleanroom', [ 
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE_NAME.DEMO.CUSTOMERS:HASHED_EMAIL',  
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE_NAME.DEMO.CUSTOMERS:REGION_CODE' ]);

consumer.approve_provider_activation_consent¶

描述：批准提供商关于允许提供商激活的请求，即能够将结果推送到提供商的 Snowflake 账户。如果提供商没有使用指定的模板在此 Clean Room 中调用 provider.request_provider_activation_consent，则此过程将失败。

输入：cleanroom_name（字符串）、activation_template_name（字符串）

输出： 成功消息

示例：

call consumer.approve_provider_activation_consent('my_cleanroom', 'activation_my_template');

consumer.run_activation¶

描述：执行将结果推送回使用者或提供商 Snowflake 账户的模板。consumer_direct_activation 实参决定这是使用者激活还是提供商激活。

实参：

• cleanroom_name（字符串） – 要在其中运行激活的 Clean Room 的名称。

• segment_name（字符串） – 用于标记此次激活运行生成的行的任意字符串。每次激活运行都会向现有结果表中添加新行。每次调用此过程时，请在此字段中提供一个唯一的字符串，以便能够筛选特定运行的结果。

• template_name（字符串） – 要调用的激活模板的名称。

• consumer_tables（字符串数组） – 要传递给模板的完全限定使用者表名称数组。

• provider_tables（字符串数组） – 要传递给模板的完全限定提供商表名称数组。

• activation_arguments（对象） – 传递给模板的实参的键值集。

• consumer_direct_activation（布尔值，可选） – 为 TRUE 则将结果推送回使用者账户，为 FALSE 则将结果发送给提供商。默认值为 FALSE。

返回： （字符串） 如果成功，则返回成功消息。

示例：

-- Run a consumer activation, as specified by the final TRUE argument.
SET segment_name = 'my_activation_segment';
CALL samooha_by_snowflake_local_db.consumer.run_activation(
  $cleanroom_name,
  $segment_name,
  $template_name,
  ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'], 
  ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],
  object_construct(
    'c_join_col', 'c.hashed_email',
    'p_join_col', 'p.hashed_email'
  ),
  TRUE);

consumer.create_template_request¶

描述：向 Clean Room 提供商发送请求，要求他们批准自定义模板，以便将其添加到 Clean Room。请参阅 使用开发者 API 添加使用者定义的模板。

实参：

• cleanroom_name（字符串） – 适用此模板的 Clean Room 的名称。

• template_name（字符串） – 模板的名称。必须全部是小写字母、数字、空格或下划线。激活模板的名称必须以“activation”开头。

• template_Definition（字符串） – JinjaSQL 模板。了解模板语法。

返回： success message（字符串）

示例：

  CALL samooha_by_snowflake_local_db.consumer.create_template_request('dcr_cleanroom', 
  'my_analysis', 
  $$
  SELECT 
      identifier({{ dimensions[0] | column_policy }}) 
  FROM 
      identifier({{ my_table[0] }}) c 
    INNER JOIN
      identifier({{ source_table[0] }}) p 
        ON   
          c.identifier({{ consumer_id  }}) = identifier({{ provider_id | join_policy }}) 
        {% if where_clause %} where {{ where_clause | sqlsafe | join_and_column_policy }} {% endif %};
  $$);

consumer.get_sql_jinja¶

描述： 将 JinjaSQL 模板评估为有效的 SQL 语句。此过程只能处理标准 JinjaSQL (https://github.com/sripathikrishnan/jinjasql) 语句；不能处理 join_policy 或 column_policy 等 JinjaSQL Clean Room 扩展。

实参：

• template_string（字符串） – 待处理模板。仅支持标准 JinjaSQL。

• arguments（对象） – 一个对象，其中的字段名与模板中使用的变量相对应，值会插入到所生成查询中模板中相应的变量占位符中。

返回：（字符串）* 提交的模板生成的 SQL 语句，其中包含提供的变量值。

示例：

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.CONSUMER.GET_SQL_JINJA(
$$
SELECT COUNT(*), IDENTIFIER({{ group_by_col }})
  FROM IDENTIFIER({{ my_table | sqlsafe }})
  INNER JOIN IDENTIFIER({{ source_table | sqlsafe }})
  ON IDENTIFIER({{ consumer_join_col }}) = IDENTIFIER({{ provider_join_col }})
  GROUP BY IDENTIFIER({{ group_by_col }});
$$,
object_construct(
'group_by_col', 'city',
'consumer_join_col', 'hashed_email',
'provider_join_col', 'hashed_email',
'my_table', 'mydb.mysch.t1',
'source_table', 'mydb.mysch.t2'));

响应：

SELECT COUNT(*), IDENTIFIER('city')
  FROM IDENTIFIER(mydb.mysch.t1)
  INNER JOIN IDENTIFIER(mydb.mysch.t2)
  ON IDENTIFIER('hashed_email') = IDENTIFIER('hashed_email')
  GROUP BY IDENTIFIER('city');

consumer.generate_python_request_template¶

描述：生成包含自定义 Python 代码的使用者 Clean Room 模板。生成的模板包括您的 Python 代码和 JinjaSQL 模板的占位符。将最终模板传递给 consumer.create_template_request。

了解有关使用者定义模板的更多信息。

实参：

• function_name（字符串） – SQL 模板应调用 Python 函数的名称来执行函数。

• arguments（字符串数组） – Python 函数的实参列表，其中每个实参都是空格分隔的字符串对，格式为“<argument_name> <argument_type>”。例如：['data variant', 'scale integer']。

• packages（字符串数组） – Python 代码所需的包名称数组。如果没有，请指定一个空数组。示例：['pandas','numpy']。

• imports（字符串数组） – Python 代码所需的任何自定义 Python 库。应该是零个或多个暂存区地址的数组。示例：['@db.schema.stage/my_python_sproc.py']

• rettype（字符串） – 函数的 SQL 返回类型。示例：'integer'、'varchar'。

• handler（字符串） – Python 代码中主处理程序函数的名称。这通常是 'main'。

• code（字符串） – 您的 Python 代码实施。如果您包含一个导入，并且您的指定处理程序是在导入中定义的，则可以是空字符串。

返回： 生成的 Python 模板（字符串）。将占位符替换为 SQL 代码。

示例：

使用一个简单的 Python 示例调用辅助函数。

call SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.CONSUMER.GENERATE_PYTHON_REQUEST_TEMPLATE(
  'my_func',                         // SQL should use this name to call your function
  ['data variant', 'index integer'], // Arguments and types for the function
  ['pandas', 'numpy'],               // Standard libraries used
  [],                                // No custom libraries needed.
  'integer',                         // Return type integer
  'main',                            // Standard main handler
// Python implementation as UDF  
  $$
import pandas as pd
import numpy as np

def main(data, index):
    df = pd.DataFrame(data)  # you can do something with df but this is just an example
    return np.random.randint(1, 100)
    $$
);

这是对之前调用的响应。如占位符所示插入您的 JinjaSQL，并将其传递到 consumer.create_template_request。

BEGIN

-- First define the Python UDF
CREATE OR REPLACE FUNCTION CLEANROOM.my_func(data variant, index integer)
RETURNS integer
LANGUAGE PYTHON
RUNTIME_VERSION = 3.10
PACKAGES = ('pandas', 'numpy')

HANDLER = 'main'
AS '
import pandas as pd
import numpy as np

def main(data, index):
    df = pd.DataFrame(data)  # you can do something with df but this is just an example
    return np.random.randint(1, 100)
    ';
        

-- Then define and execute the SQL query
LET SQL_TEXT varchar := '<INSERT SQL TEMPLATE HERE>';

-- Execute the query and return the result
LET RES resultset := (EXECUTE IMMEDIATE :SQL_TEXT);
RETURN TABLE(RES);

END;

consumer.list_template_requests¶

描述：列出使用者向 Clean Room 添加模板的请求。

实参： cleanroom_name（字符串）

返回： request_id（字符串）、provider_identifier（字符串）、template_name（字符串）、template_definition（字符串）、request_status（字符串）、reason（字符串）

示例：

CALL samooha_by_snowflake_local_db.consumer.list_template_requests('dcr_cleanroom');

consumer.describe_cleanroom¶

描述：创建文本摘要，其中包含已添加到 Clean Room 的所有信息，包括模板、数据集、策略等。如果通过应用 is_obscated 实参 隐藏了 模板，则必须使用 Snowflake Enterprise Edition 或更高版本才能查看模板名称。

实参： cleanroom_name（字符串）

返回： clean room 的详细描述字符串（表）

示例：

call samooha_by_snowflake_local_db.consumer.describe_cleanroom($cleanroom_name);

consumer.view_provider_datasets¶

描述：查看提供商已添加到 clean room 的所有数据集。

实参： cleanroom_name（字符串）

返回： clean room 中的所有提供商数据集名称（表）

示例：

call samooha_by_snowflake_local_db.consumer.view_provider_datasets($cleanroom_name);

consumer.view_join_policy¶

描述：概述用户可以在 clean room 内安全地联接哪些列，由使用者在使用者数据集上设置。

实参： cleanroom_name（字符串）

返回： 联接策略（表）

示例：

call samooha_by_snowflake_local_db.consumer.view_join_policy($cleanroom_name);

consumer.view_provider_join_policy¶

描述：概述用户可以在 Clean Room 内安全地联接哪些列，由提供商在提供商数据集上设置。

实参： cleanroom_name（字符串）

返回： 联接策略（表）

示例：

call samooha_by_snowflake_local_db.consumer.view_provider_join_policy($cleanroom_name);

consumer.view_added_templates¶

描述：查看 Clean Room 中的所有活动模板。如果通过应用 is_obscated 实参 隐藏了 模板，则必须使用 Snowflake Enterprise Edition 或更高版本才能查看模板。

实参： cleanroom_name（字符串）

返回： 添加的模板（表）

示例：

call samooha_by_snowflake_local_db.consumer.view_added_templates($cleanroom_name);

library.is_consumer_run_enabled¶

描述：检查此 Clean Room 是否允许使用者运行分析。此标志确定 Clean Room 使用者（安装者）是否可在此 Clean Room 中运行分析。

实参： cleanroom_name（字符串）

输出： enabled message（字符串）

示例：

CALL samooha_by_snowflake_local_db.library.is_consumer_run_enabled($cleanroom_name);

consumer.view_cleanrooms¶

描述：显示此账户已联接（已安装）或可联接的所有 Clean Room。要仅查看已安装的 Clean Room，请运行 consumer.view_installed_cleanrooms。

实参： 无

返回： （表） 此账户已安装或邀请的所有 Clean Room。

示例：

call samooha_by_snowflake_local_db.consumer.view_cleanrooms();

consumer.view_installed_cleanrooms¶

描述： 列出此账户中已安装（联接）的所有 Clean Room。要查看已联接和未联接的 Clean Room，请调用 consumer.view_cleanrooms。要查看在此账户中创建的所有 Clean Room，请调 provider.view_cleanrooms。

实参： 无

返回：（表）此账户中安装的 Clean Room。

示例：

CALL samooha_by_snowflake_local_db.consumer.view_installed_cleanrooms();

consumer.is_dp_enabled¶

描述：检查是否已在 Clean Room 中启用了差分隐私。

实参： cleanroom_name（字符串）

返回： Clean Room 是否启用了 DP（布尔）

示例：

call samooha_by_snowflake_local_db.consumer.is_dp_enabled($cleanroom_name);

consumer.view_remaining_privacy_budget¶

描述：查看可用于从 Clean Room 进行查询的剩余隐私预算。一旦耗尽，在重置预算之前，将不允许继续调用 run_analysis。预算每日重置。

SELECT cleanroom_name FROM TABLE(RESULT_SCAN(LAST_QUERY_ID())) WHERE is_already_installed = TRUE;

实参： cleanroom_name（字符串）

返回： 剩余的隐私预算（浮点）

示例：

call samooha_by_snowflake_local_db.consumer.view_remaining_privacy_budget($cleanroom_name);

consumer.set_privacy_settings¶

描述： 为提供商运行的使用自定义模板的分析（包括激活）设置隐私设置。擦除所有先前设置的值。每次调用此方法时，它都会擦除所有先前的配置设置。

实参：

• cleanroom_name（字符串） – 应该应用这些设置的 Clean Room 的名称。

• privacy_settings（字符串） – 一个字符串 JSON 对象，用于在提供商运行自定义模板时指定隐私设置。以下是该对象的语法：

  '{
    "null" : <template_config>
  }'
  

  Copy

  template_config 是一个具有差分隐私和聚合设置的对象。请参阅 可用的隐私设置，了解您可以在此对象中提供哪些字段。

示例：

-- Apply differential privacy for provider-run analysis using all custom templates.
CALL samooha_by_snowflake_local_db.consumer.set_privacy_settings(
  $cleanroom_name,
  PARSE_JSON('{
    "null":{ "differential": 1, "epsilon": 0.1, "privacy_budget": 3 }
    }')
  );

返回： 字符串成功消息。

consumer.start_or_update_service¶

描述： 在此 Clean Room 中创建并启动提供商定义的最新 SPCS 版本。每当提供商调用 provider.load_service_into_cleanroom 来创建或更新容器时，使用者都必须调用 consumer.start_or_update_service 来更新服务。

在调用此过程之前，使用者必须先定义并启动该池。

实参：

• cleanroom_name（字符串） – 应在其中加载容器的 Clean Room 的名称。

• compute_pool_name（字符串） – 使用者此 Clean Room 中定义的计算池的名称。该池必须已经创建，并且 Clean Room 必须具有访问该池的权限。

• service_options（对象，可选） – 为此服务指定参数的对象。支持以下属性：

  • query_warehouse – （字符串，可选）用于此服务的仓库的名称。不必与运行 Clean Room 的仓库相同。

  • min_instances – （整数，可选）用于此服务的最小实例数。

  • max_instances – （整数，可选）用于此服务的最大实例数。

返回：（表）加载结果（如果成功）。如果不成功，则会引发错误。

示例：

CALL samooha_by_snowflake_local_db.consumer.start_or_update_service(
    $cleanroom_name,
    'dcr_lal_pool',
    object_construct(
        'query_warehouse', 'app_wh',
        'min_instances', '1',
        'max_instances', '1'
));

consumer.set_cleanroom_ui_accessibility¶

描述：为当前账户中的使用者显示或隐藏 Web 应用程序中的 clean room。

实参：

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

• visibility_status（字符串） – 以下区分大小写的值之一：

  • HIDDEN – 对当前使用者账户中的所有用户隐藏 Web 应用程序中的指定 clean room。Clean Room 仍可通过 API 调用访问。

  • EDITABLE – 让 clean room 在 Web 应用程序中可见。

返回： success message（字符串）

示例：

CALL samooha_by_snowflake_local_db.consumer.set_cleanroom_ui_accessibility($cleanroom_name, 'HIDDEN');

library.enable_local_db_auto_upgrades¶

描述：启用任务 samooha_by_snowflake_local_db.admin.expected_version_task，该任务会在新版本发布时自动升级 Snowflake Data Clean Room 的 Snowflake Native App。

实参： 无

返回： success message（字符串）

示例：

CALL samooha_by_snowflake_local_db.library.enable_local_db_auto_upgrades();

library.disable_local_db_auto_upgrades¶

描述：禁用任务 samooha_by_snowflake_local_db.admin.expected_version_task，该任务会在新版本发布时自动升级 Snowflake Data Clean Room 的 Snowflake Native App。

实参： 无

返回： success message（字符串）

示例：

CALL samooha_by_snowflake_local_db.library.disable_local_db_auto_upgrades();