Snowflakeデータクリーンルーム:コンシューマーAPIリファレンスガイド

このページでは、clean room API のコンシューマーが、clean roomを管理するために使用するプロシージャについて説明します。コーディングのセットアップ方法については、 コーディング設定 をご参照ください。

ロールアクセス管理

grant_run_on_cleanrooms_to_role

スキーマ:

CONSUMER

説明: 指定されたclean roomでプロシージャのサブセットを実行する権限を指定されたロールに付与します。Clean roomをこのアカウントで 作成 するのではなく、このアカウントに インストール する必要があります。(つまり、自分がコンシューマーであるclean roomに限定されます)。

クリーンルームへの制限付きの使用を許可するには、SAMOOHA_APP_ROLEではなく指定されたロールをユーザーに付与します。ロールアクセスの詳細については、 制限付き API アクセスの許可をご参照ください。

ここで指定したロールを使用すると、以下のプロシージャを実行できます:

  • 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 (文字列) - 指定されたロールに制限付きアクセスを付与するすべてのクリーンルームの名前。

  • 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'
);
Copy

revoke_run_on_cleanrooms_from_role

スキーマ:

CONSUMER

説明: 指定されたクリーンルームの指定されたロールから権限を取り消します。ユーザーが取り消されていないロールにアクセスできる場合、またはSAMOOHA_APP_ROLEを持っている場合でも、指定されたクリーンルームでクリーンルームプロシージャを実行することができます。

引数:

  • cleanroom_names (文字列) - このアカウントの1つ以上のクリーンルームの名前。

  • 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'
);
Copy

クリーンルームをインストールする

クリーンルームをインストールまたはアンインストールする手順。

install_cleanroom

スキーマ:

CONSUMER

説明: 指定されたプロバイダーによって作成されたクリーンルームをインストール(参加)します。これを複数回呼び出すと、毎回既存のクリーンルームがクリアされます。2回目のインストールが完了する前に中断すると、クリーンルームは破損します。クリーンルームを使用できるようにするには、この手順を完了する必要があります。

引数:

  • cleanroom_name (文字列) - インストールするクリーンルームの名前。

  • provider_account_locator (文字列) - このclean roomを作成したプロバイダーのアカウントロケーター。

戻り値: (String) 成功メッセージ。

エラー処理:

「このアカウントではクロスクラウドの自動フルフィルメントが有効になっていません」というエラーが表示された場合は、プロバイダーが別のクラウドホスティングリージョンにあることを意味します。Snowflake Data Clean Rooms におけるクロスクラウドの自動複製の管理の説明に従って、クロスクラウドの自動フルフィルメントを有効にする必要があります。

例:

CALL samooha_by_snowflake_local_db.consumer.install_cleanroom(
  $cleanroom_name,
  $provider_locator);
Copy

is_enabled

スキーマ:

CONSUMER

説明: クリーンルームのインストール後、使用できるようになるまでに少し時間がかかることがあります。インストール後、クリーンルームが使用できるかどうかを確認するために、このプロシージャを呼び出す場合があります。

引数:

  • cleanroom_name (文字列) - ステータスをチェックするクリーンルームの名前。

戻り値: (ブール) 指定されたクリーンルームがインストールされ、使用可能かどうか。

例:

CALL samooha_by_snowflake_local_db.consumer.is_enabled($cleanroom_name);
Copy

uninstall_cleanroom

スキーマ:

CONSUMER

**説明:**コンシューマーアカウントのクリーンルームをアンインストールします。これにより、共有クリーンルームデータベースを含む、クリーンルームに関連するすべてのデータベースが削除されます。クリーンルームはconsumer.install_cleanroomで随時再インストールできます。

引数:

  • cleanroom_name**(文字列) - アンインストールするクリーンルームの名前。

戻り値: (String) 成功メッセージ。

例:

CALL samooha_by_snowflake_local_db.consumer.uninstall_cleanroom($cleanroom_name);
Copy

クロスクラウドコラボレーション

別のクラウドリージョンで作成されたクリーンルームをインストールします。

詳細はこちら

enable_laf_on_account

スキーマ:

LIBRARY

説明: 現在のアカウントでクロスクラウド自動フルフィルメントを有効にします。ACCOUNTADMIN ロールが必要です。

重要

最初に、SYSTEM$ENABLE_GLOBAL_DATA_SHARING_FOR_ACCOUNTを呼び出して、アカウントのクロスクラウドの自動フルフィルメントを有効にする必要があります。 自動フルフィルメントの詳細 および 自動フルフィルメント権限の管理について詳細はこちら。

引数: なし

戻り値: (String) 成功メッセージ。

例:

USE ROLE ACCOUNTADMIN;
CALL samooha_by_snowflake_local_db.library.enable_laf_on_account();
Copy

disable_laf_on_account

スキーマ:

LIBRARY

説明: 現在のアカウントのクロスクラウドの自動フルフィルメントを無効にします。ACCOUNTADMIN ロールが必要です。

重要

このプロシージャを呼び出す前に、 SYSTEM$ENABLE_GLOBAL_DATA_SHARING_FOR_ACCOUNT を呼び出す必要があります。自動フルフィルメントの詳細 および 自動フルフィルメント権限の管理について詳細はこちら。

引数: なし

戻り値: (String) 成功メッセージ。

例:

USE ROLE ACCOUNTADMIN;
CALL samooha_by_snowflake_local_db.library.disable_laf_on_account();
Copy

is_laf_enabled_for_cleanroom

スキーマ:

CONSUMER

説明: このclean roomでクロスクラウド自動フルフィルメントが有効になっているかどうかを記述します。クロスクラウド自動フルフィルメントは アカウント管理者が構成する必要があります

引数:

戻り値: このclean roomでクロスクラウド自動フルフィルメントが有効になっているかどうか。

例:

CALL samooha_by_snowflake_local_db.consumer.is_laf_enabled_for_cleanroom($cleanroom_name);
Copy

request_laf_cleanroom

スキーマ:

CONSUMER

説明: 別のクラウドリージョンで作成されたクリーンルームをインストールするための前提条件を設定します。このプロシージャを呼び出す前にconsumer.install_cleanroomを呼び出すと失敗します。このプロシージャは、呼び出すたびに現在のステータスを返します。ステータスがFULFILLED になるまで、定期的に呼び出します。その後、consumer.install_cleanroomを呼び出します。ステータスがFULFILLEDになるまで最大10分かかる場合があります。

引数:

  • cleanroom_name (文字列) - インストールされるクロスリージョンのクリーンルームの名前。

  • provider_locator (文字列) - このclean roomを作成したプロバイダーのアカウントロケーター。

Returns: (文字列) リクエストのステータスメッセージ。ステータスが FULFILLED になるまで呼び出しを続けます。

例:

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.consumer.request_laf_cleanroom(
  $cleanroom_name,$provider_locator);
Copy

setup_cleanroom_request_share_for_laf

スキーマ:

CONSUMER

説明: 指定したclean roomの、指定したプロバイダーとのクロスクラウドでのリクエスト共有を有効にします。これは、クロスリージョンのclean roomが、リクエストログ、コンシューマーテンプレートリクエスト、プロバイダーが実行する分析など、すべての機能を使用するために必要です。

引数:

戻り値: (String) 成功メッセージ。

例:

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

setup_activation_share_to_laf_consumer

スキーマ:

CONSUMER

説明: 異なるクラウドリージョンのプロバイダーとコンシューマー間のプロバイダーアクティベーションを有効にします。

引数:

戻り値: (String) 成功メッセージ。

例:

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

プロバイダーデータ分析

プロバイダーが実行する分析について、詳細はプロバイダーデータ分析をご覧ください。

is_provider_run_enabled

スキーマ:

LIBRARY

説明: このクリーンルームがプロバイダーが実行する分析を許可しているかどうかをチェックします。プロバイダーがこのクリーンルームで分析を実行する前に、コンシューマーはconsumer.enable_templates_for_provider_runを呼び出して引き続き明示的な権限を付与する必要があります。

引数:

戻り値: (文字列) クリーンルームがプロバイダーが実行する分析をサポートしているかどうかの説明。

例:

CALL samooha_by_snowflake_local_db.library.is_provider_run_enabled($cleanroom_name)
Copy

approve_template

スキーマ:

CONSUMER

説明: 指定されたクリーンルームでプロバイダーが実行する分析のための単一のテンプレートを承認します。クリーンルームのプロバイダーは通常、クリーンルームで特定のテンプレートを実行する権限を得るために、事前に連絡を行います。プロバイダーが実行する分析を承認する前に、テンプレートに結合ポリシーと列ポリシーをセットしてください。

  • コンシューマーの結合ポリシーがないクリーンルームとは、プロバイダーがすべてのコンシューマー列に結合できることを意味します。

  • コンシューマー列ポリシーのないクリーンルームとは、プロバイダーがすべてのコンシューマー列を投影できることを意味します。

  • この承認済みテンプレートを含まない コンシューマー列ポリシーを持つクリーンルームは、プロバイダーがこのテンプレートを使用する場合に、コンシューマー列を投影できないことを意味します。

引数:

  • cleanroom_name(文字列) - 承認するテンプレートがあるクリーンルームの名前。

  • template_name(文字列) - 指定されたクリーンルームで、プロバイダーが実行できるテンプレートの名前。

戻り値: (String) 成功メッセージ。

例:

CALL samooha_by_snowflake_local_db.consumer.approve_template(
  $cleanroom_name,
  $template_name);
Copy

set_provider_run_configuration

スキーマ:

CONSUMER

**説明:**プロバイダーがクリーンルームで指定されたテンプレートを実行する方法を制御するテンプレートに設定を適用します。コンシューマーがテンプレートの構成を提供しない場合は、デフォルト値が適用されます。コンシューマーがconsumer.approve_templateを呼び出してプロバイダー実行の分析用のテンプレートを承認するまで、プロバイダーはテンプレートを実行できません。

引数:

  • cleanroom_name(文字列) - クリーンルームの名前。テンプレートがこのクリーンルームに存在しない場合、プロシージャはエラーをスローします。テンプレートはプロバイダーが実行する分析についてまだ承認される必要はありませんが、コンシューマーがテンプレートを承認するまでプロバイダーはテンプレートを実行できません。

  • template_configuration(オブジェクト) -プロバイダーがこのクリーンルームで特定のテンプレートを実行する方法に制限を与えるオブジェクト。プロバイダーが実行する分析はコンシューマーのアカウントで実行され、コンシューマーに請求されるため、コンシューマーは与えられたテンプレートに使用できるウェアハウスに制限を設定することができます。構成オブジェクトの形式は次のとおりです。

    {
      <template_name>: {
        "warehouse_type": <warehouse_type>,
        "warehouse_size": <warehouse_size>
      }
    }
    
    Copy

    以下の値をすべて指定する必要があります。

    • template_name- オブジェクトキーはテンプレート名です。構成はこのテンプレートに適用されます。このテンプレートはクリーンルームに存在する必要があります。

    • warehouse_type文字列)- プロバイダーがこのテンプレートを実行するために使用できるウェアハウスタイプ。許可された値:

      • ALL -(デフォルト)任意のウェアハウスタイプを許可します。

      • STANDARD - 標準ウェアハウスのみを許可します。

      • SNOWPARK-OPTIMIZED - Snowpark用に最適化されたウェアハウスのみを許可します。XLARGE または X-LARGEがサポートされています。

      • ALL -(デフォルト)任意のウェアハウスサイズが許可されます。

      • WAREHOUSE_SIZEに定義された任意のサイズ、またはそれらの同義語(例: XLARGE または X-LARGE)がサポートされています。

戻り値: (String) 成功メッセージ。

例:

CALL samooha_by_snowflake_local_db.consumer.set_provider_run_configuration(
  $cleanroom_name,
  {
    "some_template": {
      "warehouse_type": "STANDARD",
      "warehouse_size": ["MEDIUM", "LARGE"]
    }
  }
);
Copy

enable_templates_for_provider_run

スキーマ:

CONSUMER

**説明:**プロバイダーにリクエストされたクリーンルームで分析を実行す権限を付与します。これは、プロバイダーがprovider.enable_provider_run_analysis を呼び出した後に呼び出され、クリーンルームでプロバイダーが実行する分析ができるようにします。consumer.enable_templates_for_provider_runは、指定されたクリーンルームで指定されたテンプレートを何度でも実行する権限をプロバイダーに付与します。

プロバイダーはコンシューマーのアカウントで 有効になったテンプレートを実行し、コンシューマーに請求されます。特定のテンプレートを実行する際に、プロバイダーに許可されるウェアハウスのタイプやサイズを制限したい場合は、set_provider_run_configurationを呼び出します。

引数:

  • cleanroom_name (文字列) - プロバイダーが分析を実行できるクリーンルームの名前。

  • template_names (文字列の配列) - プロバイダーに実行が許可されたclean room内の1つまたは複数のテンプレートの名前の配列。

  • enable_differential_privacy (ブール) - TRUE の場合、 template_names にリストされているすべてのテンプレートに対して、差分プライバシーを有効にします。差分プライバシーは、差分プライバシーがクリーンルーム自体で有効になっている場合にのみ、これらのテンプレートで有効にすることができます。consumer.is_dp_enabled を呼び出すことで、クリーンルームの差分プライバシーステータスを確認できます。consumer.set_privacy_settings を呼び出すことで、プライバシー設定をカスタマイズできます。詳細情報。

  • template_configuration (Object, Optional) - template_namesの各テンプレートに追加設定を指定するオプションのオブジェクト。このオブジェクトには、キーと値のペアが含まれます。キーはテンプレート名です(template_names)。値は、プロバイダーがこのテンプレートを使用する方法に制限を設定するオブジェクトです。テンプレート構成を提供しない場合、'ALL' は、template_names内のすべてのテンプレートのすべてのプロパティのデフォルトです。テンプレート構成を提供する場合template_namesにリストされているすべてのテンプレートの構成を提供する必要があり、そのテンプレートの構成に対するすべてのプロパティを定義します。consumer.set_provider_run_configurationを呼び出すことで、テンプレートの許容値を設定することもできます。

    次のプロパティがサポートされています。

    • warehouse_type文字列)- プロバイダーがこのテンプレートで使用できる許可されたウェアハウスタイプ。許可された値:

      • ALL - 任意のウェアハウスタイプを許可します。

      • STANDARD - 標準ウェアハウスのみを許可します。

      • SNOWPARK-OPTIMIZED - Snowpark用に最適化されたウェアハウスのみ許可します。

    • warehouse_size文字列の配列)- このウェアハウスタイプおよびテンプレートで使用できる1つ以上の許可されたウェアハウスサイズ。許可された値は、WAREHOUSE_SIZEまたはその同義語(例: XLARGE または X-LARGEのいずれか)に対して定義された値です。'ALL' を指定して、任意のウェアハウスサイズを許可します。

戻り値: (String) 成功メッセージ。

例:

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

-- Specify what types of warehouse the provider can use to run these templates.
CALL samooha_by_snowflake_local_db.CONSUMER.enable_templates_for_provider_run(
  $cleanroom_name,
  ['template1', 'template2', 'template3'],
  TRUE,
  {
    'template1': {'warehouse_type': 'ALL', 'warehouse_size': ['MEDIUM', 'LARGE']},
    'template2': {'warehouse_type': 'SNOWPARK-OPTIMIZED', 'warehouse_size': ['MEDIUM', 'XLARGE']},
    'template3': {'warehouse_type': 'STANDARD', 'warehouse_size': ['MEDIUM', 'XLARGE']}
  });
Copy

マルチプロバイダー分析

以下のプロシージャは、 マルチプロバイダー分析 を有効にします。

prepare_multiprovider_flow

スキーマ:

CONSUMER

説明: 指定されたクリーンルームのプロバイダーに対して、マルチプロバイダークエリを実行するリクエストを送信します。このプロシージャは実際にはリクエストを実行しません。consumer.execute_multiprovider_flowを呼び出して、将来このリクエストを実行する権限をプロバイダーに求めるだけです。

プロバイダーが許可すると、コンシューマーはconsumer.execute_multiprovider_flowを呼び出すことで必要なだけ何度でもクエリを実行できます(構成された差分プライバシー設定による)。新しい値でprepare_multiprovider_flowを呼び出した後に、以前に承認したクエリを再実行するには、コンシューマーは前と全く同じクエリで prepare_multiprovider_flow を呼び出す必要があります。ただし、 consumer.execute_multiprovider_flowを実行する前にプロバイダーの承認を待つ必要はありません。

リクエストは4時間有効で、それ以降はキューから削除されます。

引数:

  • cleanroom_names (文字列) - コンシューマーアカウント内のクリーンルーム名の配列。これらのクリーンルームはインストールする必要があります。

  • template_name(文字列) - cleanroom_namesにリストされた各クリーンルームで実行するテンプレートの名前。これは、クリーンルームプロバイダーによって追加されたSnowflakeが提供するテンプレートでも、以前にconsumer.create_template_requestを呼び出してクリーンルームに送信したカスタムテンプレートでもかまいません。いずれの場合も、クリーンルームプロバイダーにリクエストを提出するために、テンプレートがすでにクリーンルームに存在している必要があります。

  • arguments (オブジェクト) - テンプレートへの入力に使用される、以下のフィールドを持つオブジェクト:

    • source_table文字列配列)- テンプレートで使用可能なsource_table配列に入力するために使用されるテーブル名の配列。各テーブル名の構文は cleanroom_name.db.schema.tableです。各プロバイダーは、リクエストにリストされた各プロバイダーのクリーンルームテーブルのみを確認することができます。

    • my_table文字列配列)- テンプレートで使用可能な my_table 配列に入力するために使用される独自データのテーブル名の配列。consumer.run_analysisconsumer_tables引数に渡されたのと同じ構文を使用します。

    • その他のテンプレート変数 - テンプレートに必要な値をキーと値のペアとして渡します。

戻り値: (文字列) 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'
    )
);
Copy

execute_multiprovider_flow

スキーマ:

CONSUMER

説明: コンシューマーから consumer.prepare_multiprovider_flow に送信された最新のクエリを実行します。プロシージャは、プロバイダーによってクエリが承認されたclean roomごとにクエリを実行し、すべてのクエリ結果を結合して返します。このプロシージャを実行する以外に、プロバイダーがクエリを承認したかどうかを知る方法はありません。

引数:

  • cleanroom_names (文字列) - 準備されたクエリを実行するクリーンルーム名の配列。この配列は、クエリリクエストにあるクリーンルームの完全なリストと一致する必要があります。

  • request_id (文字列、オプション) - prepare_multiprovider_flow によって返されるリクエストID。

戻り値: (テーブル) 承認されたすべてのclean roomによる結果を結合したデータ。このコンシューマーからのクエリをプロバイダーが一度も承認しなかった場合、クエリは失敗します。ただし、プロバイダーがこのコンシューマーから別のクエリを承認しているが、それが最新のクエリではない場合、プロシージャは空の結果セットを返します。

例:

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

データの登録および登録解除

以下のプロシージャを使用して、データベース、スキーマ、オブジェクトの登録および登録解除を行います。テーブルとビューは、クリーンルームにリンクする前に登録する必要があります。データベースまたはスキーマを登録すると、そのデータベースまたはスキーマ内のすべてのオブジェクトが登録されます。データ登録の詳細については、 データの登録をご参照ください。

register_db

スキーマ:

CONSUMER

説明: アカウントにデータベースを登録し、そのデータベースからそのアカウントのクリーンルームにオブジェクトをリンクできるようにします。より細かい制御をするには、代わりにregister_schemaregister_managed_access_schema、またはregister_objectを呼び出すことができます。登録後にデータベースに追加されたオブジェクトは、リンクできない場合があります。その場合は、データベースを再登録(またはオブジェクト自体を登録)する必要があります。

このプロシージャを実行するには、データベースに MANAGE GRANTS 権限が必要です。

引数:

  • db_name(文字列) - このアカウントに登録するデータベース名。

戻り値: (String) 成功メッセージ。

例:

USE ROLE <ROLE_WITH_MANAGE GRANTS>;
CALL samooha_by_snowflake_local_db.consumer.register_db('SAMOOHA_SAMPLE_DATABASE');
Copy

register_schema

スキーマ:

LIBRARY

説明: アカウントにスキーマを登録し、そのスキーマからそのアカウントのクリーンルームにオブジェクトをリンクできるようにします。より細かい制御をするには、代わりにregister_object を呼び出すことができます。登録後にスキーマに追加されたオブジェクトは、リンクできない場合があります。その場合は、スキーマを再登録(またはオブジェクト自体を登録)する必要があります。

管理アクセススキーマ(つまり、 WITH MANAGED ACCESS パラメーターで作成されたスキーマ)を登録したい場合は、代わりに library.register_managed_access_schema を使用します。

引数:

  • schema_names(文字列の配列) - 登録する完全修飾スキーマの配列。

戻り値: (String) 成功メッセージ。

例:

USE ROLE <ROLE_WITH_MANAGE GRANTS>;
CALL samooha_by_snowflake_local_db.library.register_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);
Copy

register_managed_access_schema

スキーマ:

LIBRARY

説明: アカウントにマネージドアクセススキーマを登録し、そのスキーマからそのアカウントのクリーンルームにオブジェクトをリンクできるようにします。より細かい制御をするには、代わりにregister_object を呼び出すことができます。登録後にスキーマに追加されたオブジェクトは、リンクできない場合があります。その場合は、スキーマを再登録(またはオブジェクト自体を登録)する必要があります。

引数:

  • schema_names(文字列の配列) - 登録する完全修飾マネージドスキーマの配列。

戻り値: (String) 成功メッセージ。

例:

USE ROLE <ROLE_WITH_MANAGE GRANTS>;
CALL samooha_by_snowflake_local_db.library.register_managed_access_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);
Copy

register_objects

スキーマ:

LIBRARY

説明: consumer.link_datasetsを呼び出すことで、クリーンルームにすべてのタイプのテーブルとビューへのアクセスを付与し、それらをクリーンルームにリンクできるようにします。library.register_schemalibrary.register_managed_access_schema、またはconsumer.register_dbを呼び出すことで、より広範なオブジェクトグループを登録することができます。このプロシージャを実行するためには、データベースに対してMANAGEGRANTS権限が必要です。

引数:

  • object_names(配列) - 完全修飾オブジェクト名の配列。これらのオブジェクトは、クリーンルームにリンクすることができます。

戻り値: (String) 成功メッセージ。

テーブルとビューを登録するには

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']);
Copy

enable_external_tables_on_account

スキーマ:

LIBRARY

説明: このアカウントのすべてのclean roomでIcebergまたは外部テーブルを有効にします。Icebergまたは外部テーブルを、プロバイダーとコンシューマーの いずれか のアカウントからリンクするために、その 両方 のアカウントのACCOUNTADMIN から呼び出す必要があります。この機能をこのアカウント内の特定のclean roomに制限するには、 enable_external_tables_for_cleanroom を呼び出してください。

引数: なし

戻り値: (String) 成功メッセージ。

例:

USE ROLE ACCOUNTADMIN;
CALL samooha_by_snowflake_local_db.library.enable_external_tables_on_account();
Copy

enable_external_tables_for_cleanroom

スキーマ:

CONSUMER

説明: コンシューマーがこのアカウントで指定したclean roomにIcebergまたは外部テーブルをリンクすることを可能にします。このアカウントのすべてのclean roomでIcebergと外部テーブルのリンクを許可するには、 enable_external_tables_on_account を呼び出します。

引数:

  • cleanroom_name (文字列) - プロバイダーがIcebergテーブルや外部テーブルをリンクできるクリーンルームの名前。

戻り値: (文字列) 成功メッセージ。成功すると、セキュリティスキャンがトリガーされ、セキュリティスキャンが成功した場合に生成されるパッチ番号も提供されます。

例:

CALL samooha_by_snowflake_local_db.provider.enable_external_tables_for_cleanroom(
    $cleanroom_name);
Copy

unregister_db

スキーマ:

LIBRARY

説明: SAMOOHA_APP_ROLEロールとSnowflake Data Clean Roomネイティブアプリケーションに与えられたデータベースレベルの付与を削除します。クリーンルームにリンクされたこのデータベースのデータは、このアカウントではアクセスできなくなります。このプロシージャを実行するには、データベースにMANAGEGRANTS権限が必要です。

引数:

  • db_name(文字列) - 登録解除するデータベース名。

戻り値: (String) 成功メッセージ。

例:

USE ROLE <ROLE_WITH_MANAGE GRANTS>;
CALL samooha_by_snowflake_local_db.library.unregister_db('SAMOOHA_SAMPLE_DATABASE');
Copy

unregister_schema

スキーマ:

LIBRARY

説明: 1つ以上のスキーマの登録を解除し、ユーザーがテーブルやビューをクリーンルームにリンクすることを防ぎます。

マネージドアクセススキーマ(つまり、WITHMANAGEDACCESS パラメーターで作成されたスキーマ)を登録解除する場合は、library.unregister_managed_access_schemaを代わりに使用します。このプロシージャを実行するためには、データベースにMANAGEGRANTS権限が必要です。

引数:

  • schema_names(文字列の配列) - 登録解除する完全修飾スキーマの名前。

戻り値: (String) 成功メッセージ。

例:

USE ROLE <ROLE_WITH_MANAGE GRANTS>;
CALL samooha_by_snowflake_local_db.library.unregister_schema(['SAMOOHA_SAMPLE_DATABASE.PUBLIC', 'MY_DB.MY_SCH']);
Copy

unregister_managed_access_schema

スキーマ:

LIBRARY

説明: 1つ以上のマネージドアクセススキーマの登録を解除します。これにより、ユーザーはテーブルやビューをクリーンルームにリンクすることができなくなります。

引数:

  • schema_names(文字列の配列) - 登録解除する完全修飾スキーマの名前。

戻り値: (String) 成功メッセージ。

例:

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

unregister_objects

スキーマ:

LIBRARY

説明: すべてのタイプのテーブルとビューへのクリーンルームのアクセス権を取り消します。このアカウントで管理されているクリーンルームのユーザーは、オブジェクトを利用できなくなります。

引数:

  • object_names(配列) - アクセス権を取り消す完全修飾オブジェクト名の配列。

戻り値: (String) 成功メッセージ。

テーブルとビューの登録を解除するには

USE ROLE <ROLE_WITH_MANAGE GRANTS>;
CALL samooha_by_snowflake_local_db.library.unregister_objects(
    ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS','MY_DB.MY_SCH.MY_VIEW']);
Copy

ポリシーを管理して表示する

インストールしたクリーンルームのデータに対するポリシーの管理

set_join_policy

スキーマ:

CONSUMER

説明: プロバイダーがクリーンルーム内でテンプレートを実行するとき、およびプロバイダーが実行する分析を使用するときに、プロバイダーが結合を許可される列を指定します。列ポリシーは 置換のみ です。したがって、この関数が再度呼び出された場合、以前に設定された列ポリシーは現在のものに完全に置き換えられます。データの結合ポリシーを指定しない場合、すべての列が結合可能です。

ワイルドカードを使用したクエリは、結合ポリシーが回避される可能性があるため、分析テンプレートを設計する際は慎重に行ってください。

引数:

  • cleanroom_name *(文字列)- 結合ポリシーが適用されるクリーンルームの名前。

  • table_col_names(文字列配列) - database name.schema name:column nameの形式で結合できる、列の完全修飾名。

戻り値: (String) 成功メッセージ。

例:

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

view_join_policy

スキーマ:

CONSUMER

説明: コンシューマーデータセットでコンシューマーが設定する、クリーンルーム内でユーザーが安全に参加できる列の概要を示します。

引数:

戻り値: 結合ポリシー(テーブル)

例:

CALL samooha_by_snowflake_local_db.consumer.view_join_policy($cleanroom_name);
Copy

view_provider_join_policy

スキーマ:

CONSUMER

説明: プロバイダーがプロバイダーのデータセットに設定した、ユーザーがクリーンルーム内で安全に結合できる列の概要を示します。

引数:

戻り値: 結合ポリシー(テーブル)

例:

CALL samooha_by_snowflake_local_db.consumer.view_provider_join_policy($cleanroom_name);
Copy

set_column_policy

スキーマ:

CONSUMER

説明: コンシューマーデータのどの列を投影できるかを定義します。列ポリシーは、クリーンルームのテンプレートに適用されます。列ポリシーが 置換のみ であるため、関数が呼び出された場合、以前に設定された列ポリシーは現在のものに完全に置き換えられます。列ポリシーを指定しない場合、すべての列を投影することができます。

ID列やメールのような機密性の高い列には、列ポリシーを設定しないでください。一般的にこの種のデータが投影されるのは望ましくありません。

ワイルドカードを使用したクエリは、これらのチェックでは検出されない可能性があるため、分析テンプレートを設計する際は慎重に行ってください。

引数:

  • cleanroom_name (文字列) - 列ポリシーが適用されたクリーンルームの名前。

  • analysis_table_cols(文字列配列) - database name.schema name:column nameの形式で投影可能な、列の完全修飾名。

戻り値: (String) 成功メッセージ。

例:

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'
  ]
);
Copy

view_column_policy

スキーマ:

CONSUMER

説明: 指定されたクリーンルームのすべての コンシューマー 列ポリシーを表示します。プロバイダーによって設定された列ポリシーを表示するには、consumer.view_provider_column_policyを呼び出します。

引数:

  • cleanroom_name (文字列) - 説明するクリーンルームの名前。

戻り値: (テーブル) クリーンルーム内のすべてのコンシューマー列ポリシーに関する情報。

例:

CALL samooha_by_snowflake_local_db.consumer.view_column_policy($cleanroom_name);
Copy

view_provider_column_policy

スキーマ:

CONSUMER

説明: プロバイダーによってクリーンルームに適用されたすべての列ポリシーを表示します。

引数:

戻り値: 列ポリシー(テーブル)

例:

CALL samooha_by_snowflake_local_db.consumer.view_provider_column_policy($cleanroom_name);
Copy

テンプレート

以下のプロシージャでは、ユーザーがクリーンルームでテンプレートを操作できます。

view_template_definition

スキーマ:

CONSUMER

説明: 指定されたテンプレートの生JinjaSQLを表示します。テンプレートが is_obfuscated引数の適用によって 不明瞭の 場合、テンプレートのソースコードは確認できません。

引数:

  • cleanroom_name *(文字列) - テンプレートを保持するクリーンルームの名前。

  • template_name(文字列) - 表示するテンプレートの名前。

戻り値 (文字列) テンプレート定義。

例:

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

get_arguments_from_template

スキーマ:

CONSUMER

**説明:**テンプレートで使用される引数のリストを取得します。consumer.run_analysisを呼び出すときに、これらの引数の値をテンプレートに渡すことができます。

引数:

  • cleanroom_name *(文字列) - テンプレートがあるクリーンルームの名前。

  • template_name(文字列) - 引数を返すテンプレートの名前。

戻り値: (テーブル) 引数リストと仕様。

例:

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

テンプレートチェーン

以下のプロシージャでは、ユーザーがクリーンルームで テンプレートチェーンを操作できます。

view_added_template_chains

スキーマ:

CONSUMER

説明: 指定されたクリーンルームで定義されているすべてのテンプレートチェーンをリストします。

引数:

  • cleanroom_name (文字列) - テンプレートチェーンをリストするクリーンルームの名前。

戻り値: (テーブル) 指定されたクリーンルームのテンプレートチェーンに関する情報。

例:

CALL samooha_by_snowflake_local_db.consumer.view_added_template_chains(
  $cleanroom_name);
Copy

view_template_chain_definition

スキーマ:

CONSUMER

説明: 指定されたテンプレートチェーンの属性を返します。

引数:

  • cleanroom_name (文字列) - 記述するテンプレートチェーンがあるクリーンルームの名前。

  • template_chain_name(文字列) - 記述するテンプレートチェーンの名前。

戻り値: (文字列) 指定されたテンプレートチェーンの定義。

例:

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

分析の実行

以下のプロシージャは、指定されたテンプレートに基づいて分析またはアクティベーションを実行します。

run_analysis

スキーマ:

CONSUMER

説明: テンプレートまたはテンプレートチェーンを使用して分析を実行し、結果テーブルを返します。

重要

  • 差分プライバシー が有効な場合、このテンプレートの予算上限に達しているとクエリが失敗することがあります。

  • テンプレートがis_obfuscated 引数を適用することによって 不明瞭化 されている場合、Snowflake Enterprise Edition 以上を使用しなければテンプレートを実行できません。

引数:

  • cleanroom_name (文字列) - 分析を実行するクリーンルームの名前。

  • template_name(文字列) - クリーンルームで実行するテンプレートまたはテンプレートチェーンの名前。このテンプレートはプロバイダーまたはコンシューマーによってクリーンルームに追加されている必要があります。

  • consumer_tables(文字列の配列) - 完全修飾されたコンシューマーテーブル名の配列。これらは my_table テンプレート変数に割り当てられます。これらのテーブルはすでにクリーンルームにリンクされている必要があります。consumer.view_consumer_datasets を呼び出して利用可能なテーブルを参照してください。

  • provider_tables(文字列の配列) - 完全修飾されたプロバイダーテーブル名の配列。これらは source_table テンプレート変数に割り当てられます。これらのテーブルはクリーンルームにリンクされている必要があります。consumer.view_provider_datasets を呼び出して利用可能なテーブルを参照してください。

  • analysis_arguments(オブジェクト) - テンプレートに渡されるキーと値のペアのオブジェクト。テンプレートはキー名で変数にアクセスできます。{'age':20}を渡すと、テンプレートは{{age}}として値にアクセスします。値が必要ない場合は、空のオブジェクトを渡します。どの値が必要かを確認するには、consumer.view_template_definitionを呼び出して、問題のテンプレートを調べます。テンプレートを調べて、使用されている列名を完全に修飾する必要があるかどうかを判断します。テンプレートのエイリアスがp または cである場合、小文字のp および c のテーブルエイリアスを列名に使用してください。

    このオブジェクトには、オプションで1つの予約値があります。

    • epsilon (浮動、オプション) - このクリーンルームで差分プライバシーが有効になっている場合、[差分プライバシーのepsilon値](https://www.google.com/search?q=differential+privacy+epsilon&oq=differential+privacy+epsilon)を指定します。デフォルトは0.1です。

  • use_cache(ブール、オプション) - 同じクエリに対してキャッシュされた結果を使用するかどうか。デフォルトは FALSE です。

戻り値: (テーブル) クエリ結果。

例:

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

アクティベーション

次のプロシージャは アクティベーション、またはコンシューマーやプロバイダーのSnowflakeアカウントに結果を保存する処理について管理します。APIを使用してサードパーティアカウントにデータをアクティブ化することはできません。

view_external_activation_history

スキーマ:

LIBRARY

説明: 現在のアカウントのアクティベーションリクエスト履歴を表示します。

引数: なし

戻り値: アクティベーションリクエストの詳細とステータスのテーブル。

例:

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.LIBRARY.view_external_activation_history();
Copy

set_activation_policy

スキーマ:

CONSUMER

説明: アクティベーションテンプレート内で使用できる列を定義します。これにより、コンシューマーが承認した列のみが、アクティベーションテンプレートで使用できるようになります。アクティベーションポリシーを定義しない場合は、データの列をアクティブ化できません。アクティベーションポリシーを設定すると、アカウントの既存のアクティベーションポリシーが上書きされます。

引数:

  • cleanroom_name (文字列) - アクティベーションポリシーを設定するクリーンルームの名前。

  • 列(配列) - template name:database name.schema name.table name:column_nameの形式でアクティブ化できる独自のデータ列の名前。

戻り値: (String) 成功メッセージ。

例:

CALL samooha_by_snowflake_local_db.consumer.set_activation_policy(
  $cleanroom_name,
  [
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE_NAME.DEMO.CUSTOMERS:HASHED_EMAIL',
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE_NAME.DEMO.CUSTOMERS:REGION_CODE' ]);
Copy

run_activation

スキーマ:

CONSUMER

説明: コンシューマーまたはプロバイダーのSnowflakeアカウントに結果をプッシュバックするテンプレートを実行します。consumer_direct_activation 引数は、これがコンシューマーのアクティベーションかプロバイダーのアクティベーションかを決定します。

引数:

  • cleanroom_name (文字列) - アクティベーションを実行するクリーンルームの名前。

  • segment_name(文字列) - このアクティベーション実行によって生成された行のラベルに使用される任意の文字列。アクティベーションを実行するたびに、既存の結果テーブルに新しい行が追加されます。このプロシージャを呼び出すたびに、このフィールドに一意の文字列を入力すると、特定の実行結果にフィルタリングできます。

  • template_name (文字列) - 呼び出すアクティベーションテンプレートの名前。

  • consumer_tables(文字列の配列) - テンプレートに渡す完全修飾されたコンシューマーテーブル名の配列。

  • provider_tables(文字列の配列) - テンプレートに渡す完全修飾されたプロバイダーテーブル名の配列。

  • activation_arguments (オブジェクト) - テンプレートに渡す引数のキーと値のセット。

  • consumer_direct_activation(ブール、オプション) - 結果をコンシューマーアカウントにプッシュバックする場合はTRUE 、プロバイダーに結果を送信する場合はFALSEです。デフォルトは FALSE です。

戻り値: (String) 成功メッセージ。

例:

-- 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);
Copy

dcr_health.provider_run_provider_activation_history

説明: 指定されたクリーンルームのプロバイダーアクティベーションリクエストの履歴を返します。プロバイダーとコンシューマーの両方によって開始されたプロバイダーのアクティベーションリクエストが表示されます。このプロシージャは、プロバイダーのアクティベーションに関する問題のデバッグに役立つ追加情報を提供します。

引数:

  • cleanroom_name(文字列) -アクティベーションがリクエストされたクリーンルームの名前。このクリーンルームのプロバイダーまたはコンシューマーである必要があります。

戻り値: (テーブル) -テンプレートとセグメント名、ステータス、コンシューマーのアカウントロケーター、リクエストによって返されるエラーメッセージなど、各情報を持つアクティベーションリクエストのリスト。

例:

CALL samooha_by_snowflake_local_db.dcr_health.provider_run_provider_activation_history(
  $cleanroom_name);
Copy

コンシューマー定義のテンプレート

以下の APIs を使用すると、クリーンルームにコンシューマー定義のテンプレートを追加することができます。詳細については、コンシューマー向けテンプレートをご参照ください。

create_template_request

スキーマ:

CONSUMER

説明:クリーンルームのプロバイダーにリクエストを送信し、クリーンルームに追加できるようにカスタムテンプレートの承認を求めます。詳細は コンシューマー記述のカスタムテンプレートをご参照ください。

引数:

  • cleanroom_name *(文字列)- テンプレートが追加されるクリーンルームの名前。

  • template_name(文字列) - 追加するテンプレートの名前。すべて小文字、数字、スペース、またはアンダースコアでなければなりません。アクティベーションのテンプレート名は「アクティベーション」で始める必要があります。

  • template_definition(文字列) - JinjaSQL テンプレート。テンプレート構文の詳細はこちら

戻り値: (String) 成功メッセージ。

例:

CALL samooha_by_snowflake_local_db.consumer.create_template_request(
  $cleanroom_name,
  $template_name,
  $$
  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 %};
  $$);
Copy

get_sql_jinja

スキーマ:

CONSUMER

説明: SQL ステートメントに対するJinjaSQLテンプレートを評価します。このプロシージャは、カスタムテンプレートを開発するときに使用され、与えられたパラメーターセットで処理した後にテンプレートがどのようにレンダリングされるかを確認します。

このプロシージャは、標準 JinjaSQL ステートメントのみ処理できます。join_policycolumn_policyなどJinjaSQLへのクリーンルームの拡張機能は処理できません。

引数:

  • template_string(文字列) - 処理するJinjaSQL コード。標準JinjaSQL のみサポートされます。

  • 引数(オブジェクト) - フィールド名がテンプレートで使用される変数に対応するオブジェクト。

戻り値: (文字列) 発信されたテンプレートにより、指定した変数値で生成される 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'));
Copy

応答:

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');
Copy

generate_python_request_template

スキーマ:

CONSUMER

説明: カスタムPythonコードを含むコンシューマー向けクリーンルームテンプレートを生成します。生成されたテンプレートにはPythonコードと JinjaSQL テンプレートのプレースホルダーが含まれます。最終的なテンプレートをconsumer.create_template_request に渡します。

コンシューマーが定義するテンプレートについて詳細は、コンシューマー記述のカスタムテンプレートをご参照ください。

引数:

  • function_name(文字列) - 関数を呼び出すためにテンプレートで使用される関数名。

  • 引数(文字列ペアの配列) - 関数 function_nameが必要とする引数の配列。各要素はスペースで区切られたペアであり、引数名とそのSnowflakeSQL データ型を指定します。例:['size INT', 'start_date DATE']

  • パッケージ(文字列の配列) - Pythonコードに必要なパッケージ名の配列。ない場合は、空の配列を指定します。 サポートされているパッケージの完全なリストをご参照ください。。例えば、 ['pandas','numpy'] などです。

  • imports - [サポート対象外:使用しないでください]

  • 戻り値のタイプ(string) - 関数のSnowflake SQL 戻り値のタイプ。例: INTEGER、VARCHAR。

  • ハンドラー(string) - Pythonコード内のメインハンドラー関数の名前。通常、これは 'main' です。

  • コード(string) - Pythonコードの実装。インポートを含み、指定したハンドラーがインポート内で定義されている場合、これは空の文字列になります。

戻り値: (文字列) PythonUDFをJinjaSQL テンプレートのプレースホルダーと一緒に返します。テンプレート文字列を consumer.create_template_request に渡す前に、ネストされた$$または一重引用符(')を正しくエスケープする必要があります。コンシューマー送信コードをご参照ください。

例:

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.
  [],                                -- Reserved.
  'INTEGER',                         -- SQL return type.
  'main',                            -- Standard main handler.
  $$
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)
    $$
);
Copy

次の例は、生成されたコードを示しています。<INSERT SQL TEMPLATE HERE>をJinjaSQL コードのテンプレートに置き換えます。

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 run the SQL query
LET SQL_TEXT varchar := $$<INSERT SQL TEMPLATE HERE>$$;

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

END;  

list_template_requests

スキーマ:

CONSUMER

説明: コンシューマーがクリーンルームにテンプレートを追加するために行ったすべてのリクエストを表示します。

引数:

  • cleanroom_name (文字列) - テンプレートのリクエストをリストするクリーンルーム。

戻り値: 以下の列を持つテーブル。

  • request_id- クリーンルームシステムによって生成されたリクエストのID。

  • provider_identifier - プロバイダーのアカウントロケーター。

  • template_name - コンシューマーがリクエストで提供したテンプレート名。

  • template_definition - コンシューマーがクリーンルームに追加するよう依頼したテンプレートのソースコード。

  • request_status - リクエストのステータス: PENDING、APPROVED、またはREJECTED。

  • reason - リクエストのステータスが REJECTEDの場合、プロバイダーはここで却下する理由を示す必要があります。

例:

CALL samooha_by_snowflake_local_db.consumer.list_template_requests($cleanroom_name);
Copy

クリーンルームのメタデータゲッターメソッド

以下の方法は、クリーンルームの関連特性を示しています。

describe_cleanroom

スキーマ:

CONSUMER

説明: テンプレート、データセット、ポリシーを含む指定されたクリーンルームに関する主要な情報の概要を提供します。テンプレートがis_obfuscated引数の適用によって 不明瞭の場合、テンプレート名を確認するには、Snowflake Enterprise Edition(またはそれ以上)を使用する必要があります。

引数:

  • cleanroom_name (文字列) - 説明するクリーンルームの名前。

戻り値: (文字列) クリーンルームの説明。

例:

CALL samooha_by_snowflake_local_db.consumer.describe_cleanroom($cleanroom_name);
Copy

view_provider_datasets

スキーマ:

CONSUMER

**説明:**プロバイダーがクリーンルームに追加したすべてのデータセットをリストします。

引数:

戻り値: (テーブル) プロバイダーによって追加されたデータセットのテーブル。ここで返されたテーブル名をクエリで使用してください。

例:

CALL samooha_by_snowflake_local_db.consumer.view_provider_datasets($cleanroom_name);
Copy

view_added_templates

スキーマ:

CONSUMER

説明: クリーンルームのすべてのテンプレートをリストします。テンプレートがis_obfuscated引数の適用によって 不明瞭の場合、テンプレート名を表示するには、Snowflake Enterprise Edition(またはそれ以上)を使用する必要があります。

引数:

戻り値: このクリーンルームのテンプレートのリスト、およびそれぞれのソースコード(プロバイダーによってテンプレート不明瞭な場合を除く)。

例:

CALL samooha_by_snowflake_local_db.consumer.view_added_templates($cleanroom_name);
Copy

is_consumer_run_enabled

スキーマ:

LIBRARY

説明: 指定されたクリーンルームでコンシューマーが実行する分析を有効にしているかどうかを確認します。これはデフォルトで有効になっていますが、クリーンルームのプロバイダーは無効にすることができます。

引数:

戻り値:(文字列)* コンシューマーが実行する分析をこのクリーンルームが許可しているかどうか。

例:

CALL samooha_by_snowflake_local_db.library.is_consumer_run_enabled($cleanroom_name);
Copy

view_cleanrooms

スキーマ:

CONSUMER

説明: このアカウントで参加済み(インストール済み)または参加可能なすべてのクリーンルームを一覧表示します。インストールされたクリーンルームのみを表示するには、 consumer.view_installed_cleanroomsを実行します。このアカウントで作成されたクリーンルームを見るには、provider.view_cleanroomsを呼び出します。

引数: なし

戻り値: (テーブル) このアカウントにインストールまたは招待されているすべてのclean room。

例:

CALL samooha_by_snowflake_local_db.consumer.view_cleanrooms();
Copy

view_installed_cleanrooms

スキーマ:

CONSUMER

説明: このアカウントにインストール済み(参加済み)のすべてのクリーンルームを一覧表示します。結合済みおよび未結合のクリーンルームの両方を確認するには、consumer.view_cleanroomsを呼び出します。このアカウントで作成されたすべのクリーンルームを見るには、provider.view_cleanroomsを呼び出します。

引数: なし

戻り値: (テーブル) このアカウントにインストールされているclean room。

例:

CALL samooha_by_snowflake_local_db.consumer.view_installed_cleanrooms();
Copy

差分プライバシー

これらのプロシージャは、クリーンルーム内の 差分プライバシーを制御します。また、consumer.enable_templates_for_provider_runを呼び出す際に、テンプレートレベルで差分プライバシーを指定することもできます。

is_dp_enabled

スキーマ:

CONSUMER

説明: クリーンルームで差分プライバシーが有効になっているかどうかを確認します。この値を確認するには、クリーンルームがインストールされている必要があります。

引数:

戻り値: (ブール値) クリーンルームで差分プライバシーが有効になっているかどうか。

例:

CALL samooha_by_snowflake_local_db.consumer.is_dp_enabled($cleanroom_name);
Copy

view_remaining_privacy_budget

スキーマ:

CONSUMER

説明: クリーンルームのクエリの作成に使用できるプライバシー予算の残りを表示します。予算を使い果たした後、予算がリセットされるまで、run_analysis はそれ以上呼び出すことができません。予算は毎日リセットされます。

引数:

  • cleanroom_name (文字列) クリーンルームの名前。このプロシージャを成功させるには、クリーンルームをインストールする必要があります。

戻り値:(浮動小数点数)* 残りのプライバシー予算。

例:

CALL samooha_by_snowflake_local_db.consumer.view_remaining_privacy_budget($cleanroom_name);
Copy

set_privacy_settings

スキーマ:

CONSUMER

**説明:**カスタムテンプレートを使用するプロバイダー実行の分析(アクティベーションを含む)のプライバシー設定をセットします。以前に設定したすべての値を上書きします。このメソッドを呼び出すたびに、以前のすべての構成設定が消去されます。

引数:

  • cleanroom_name (文字列) - これらの設定が適用されるクリーンルームの名前。

  • 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 }
    }')
  );
Copy

戻り値: (String) 成功メッセージ。

Snowpark Container Servicesプロシージャ

クリーンルームでSnowpark Container Servicesを使用する方法についてご覧ください。

start_or_update_service

スキーマ:

CONSUMER

説明: このクリーンルームのプロバイダーによって定義されたSnowpark Container Servicesの最新バージョンを作成し、開始します。プロバイダーがprovider.load_service_into_cleanroomを呼び出すたびに、コンテナを作成または更新します。コンシューマーは、サービスを更新するためにconsumer.start_or_update_service を呼び出す必要があります。

コンシューマーは、このプロシージャを呼び出す前にプールを定義し、開始する必要があります。

引数:

  • cleanroom_name *(文字列)- コンテナをロードするクリーンルームの名前。

  • compute_pool_name(文字列) - このクリーンルームのコンシューマーによって定義されるコンピューティングプールの名前。プールはすでに作成されている必要があり、クリーンルームにはプールへのアクセス権限が必要です。

  • service_options (オブジェクト、オプション) - このサービスのパラメーターを指定するオブジェクト。以下のプロパティを指定できます:

    • query_warehouse -(文字列、オプション)このサービスに使用するウェアハウスの名前。クリーンルームを実行しているウェアハウスと同じウェアハウスである必要はありません。

    • 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'
));
Copy

環境管理

一般的なクリーンルームの機能性を支援するために、以下の方法を使用してください。

set_cleanroom_ui_accessibility

スキーマ:

CONSUMER

説明: 現在のアカウントのコンシューマーのために、クリーンルームUIでクリーンルームを表示または非表示にします。

引数:

  • cleanroom_name (文字列) クリーンルームの名前。

  • visibility_status(文字列) - 以下の大文字と小文字を区別する値のいずれか。

    • HIDDEN - 現在のコンシューマーアカウントの全ユーザーから、クリーンルームUIで指定されたクリーンルームを非表示にします。クリーンルームへは、引き続きAPIを呼び出しでアクセスできます。

    • EDITABLE - クリーンルームをクリーンルーム UI で見えるようにします。

戻り値: (String) 成功メッセージ。

例:

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

manage_datastats_task_on_account

スキーマ:

CONSUMER

説明: クリーンルームの統計を計算するバックグラウンドタスクを有効または無効にします。タスクはデフォルトで実行されていますが、コストを削減するために無効にすることができます。

重要

タスクを管理するには、 すべてのコラボレーターが 同じ値を持つこのプロシージャの適切なプロバイダー バージョンまたはコンシューマーバージョンを呼び出す必要があります。

引数:

  • enable(ブール値) - タスクを有効にする場合はTRUE 、タスクを無効にする場合は FALSE です。

戻り値: (String) 成功メッセージ。

例:

-- Disable the task in this account.
CALL samooha_by_snowflake_local_db.consumer.manage_datastats_task_on_account(FALSE);
Copy

enable_local_db_auto_upgrades

スキーマ:

LIBRARY

説明: 新しいプロシージャや機能がリリースされたときに、Snowflake Data Clean Rooms環境を自動的にアップグレードするタスクを有効にします(タスクは samooha_by_snowflake_local_db.admin.expected_version_task。)新しいリリースごとに library.apply_patch を呼び出すのではなく、このプロシージャを呼び出してアップグレードを自動化します。

このタスクを無効にすることでコストを削減できるかもしれませんが、システム上にクリーンルーム環境の最新バージョンが確実に存在するように、このタスクを実行したままにすることをお勧めします。

引数: なし

戻り値: (文字列) 成功または失敗のメッセージ。

例:

CALL samooha_by_snowflake_local_db.library.enable_local_db_auto_upgrades();
Copy

disable_local_db_auto_upgrades

スキーマ:

LIBRARY

説明: 新しいバージョンがリリースされたときに、Snowflake Data Clean Rooms環境を自動的にアップグレードするタスクを無効にします。自動アップグレードを無効にした場合は、新しいリリース ごとに library.apply_patch を呼び出す必要があります。

引数: なし

戻り値: (文字列) 成功または失敗のメッセージ。

例:

CALL samooha_by_snowflake_local_db.library.disable_local_db_auto_upgrades();
Copy

apply_patch

スキーマ:

LIBRARY

説明: クリーンルーム環境を更新し、環境の新機能と修正を可能にします。クリーンルーム環境の新しいバージョンがリリースされたときに、これを呼び出します。(これは通常、毎週発生します。最近の機能アップデートのクリーンルームエントリをご参照ください。)このプロシージャは SAMOOHA_BY_SNOWFLAKE_LOCAL_DBを更新します。

library.enable_local_db_auto_upgrades を呼び出すと、パッチの更新を自動化できます。自動更新を有効にすることをお勧めします。

引数: なし

戻り値: (String) 成功メッセージ。

例:

CALL samooha_by_snowflake_local_db.library.apply_patch();
Copy

patch_cleanroom

スキーマ:

CONSUMER

説明: 指定されたクリーンルームを最新バージョンに更新し、そのクリーンルームの新しい機能と修正を有効にします。通常は、Snowflakeサポートから呼び出しするように指示された場合にのみ呼び出します。

コンシューマーが library.patch_cleanroom を呼び出す前に、プロバイダーは library.patch_cleanroom を呼び出す必要があります。それ以外の場合は、適用するパッチはありません。

引数:

  • cleanroom_name(文字列) - パッチするクリーンルームの名前。

戻り値: (String) 成功メッセージ。

例:

CALL samooha_by_snowflake_local_db.consumer.patch_cleanroom($cleanroom_name);
Copy

dcr_health.dcr_tasks_health_check

説明: 実行中または最近停止したクリーンルームのタスクに関する情報を表示します。

引数: なし

戻り値: (テーブル) スケジュール、ウェアハウス名、ウェアハウスサイズなど、クリーンルームタスクに関する情報。

例:

CALL samooha_by_snowflake_local_db.dcr_health.dcr_tasks_health_check();
Copy

非推奨プロシージャ

以下のプロシージャは非推奨であり、ここでは念のためリストアップしています。交換プロシージャが示されている場合は、新しいプロシージャを使用してください。

register_table_or_view -- 非推奨

スキーマ:

LIBRARY

注意

このプロシージャは現在、非推奨です。 library.register_objectsを使用してください。

説明: あらゆるタイプのテーブルとビューを登録します。

引数: object_names(array)、is_view(boolean)、is_iceberg(boolean)、is_external(boolean)、is_under_managed_access_schema(boolean)

戻り値: (String) 成功メッセージ。

テーブルを登録するには:

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

Icebergテーブルを登録するには:

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

register_table -- 非推奨

スキーマ:

LIBRARY

注意

このプロシージャは現在、非推奨です。 library.register_objectsを使用してください。

説明: register_dbと似ていますが、テーブルレベルで操作します。完全修飾されたテーブル名を表す配列または文字列を渡すことができ、SAMOOHA_APP_ROLEロールへのグラント選択が行われ、ユーザーはテーブルをクリーンルームにリンクすることができます。

管理アクセススキーマ(つまり、 WITH MANAGED ACCESS パラメーターで作成されたスキーマ)にテーブルを登録したい場合は、代わりに library.register_managed_access_table を使用してください。

引数: table_name(array)

戻り値: (String) 成功メッセージ。

例:

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

register_managed_access_table -- 非推奨

スキーマ:

LIBRARY

注意

このプロシージャは現在、非推奨です。 library.register_objectsを使用してください。

説明: register_table と似ていますが、 WITH MANAGED ACCESS パラメーターで作成されたスキーマのテーブルを登録します。完全修飾されたテーブル名を表す配列または文字列を渡すことができ、SAMOOHA_APP_ROLEロールへのグラント選択が行われ、ユーザーはテーブルをクリーンルームにリンクすることができます。

引数: table_name(array)

戻り値: (String) 成功メッセージ。

例:

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

register_view -- 非推奨

スキーマ:

LIBRARY

注意

このプロシージャは現在、非推奨です。 library.register_objectsを使用してください。

説明: register_dbと似ていますが、ビューレベルで操作します。完全修飾されたビュー名を表す配列または文字列を渡すことができ、 SAMOOHA_APP_ROLE ロールへの付与選択が行われ、ユーザーはビューをクリーンルームにリンクすることができます。

管理アクセススキーマ(つまり、 WITH MANAGED ACCESS パラメーターで作成されたスキーマ)にビューを登録したい場合は、代わりに library.register_managed_access_view を使用してください。

引数: view_name(array)

戻り値: (String) 成功メッセージ。

例:

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

register_managed_access_view -- 非推奨

スキーマ:

LIBRARY

注意

このプロシージャは現在、非推奨です。 library.register_objectsを使用してください。

説明: register_view と似ていますが、 WITH MANAGED ACCESS パラメーターで作成されたスキーマのビューを登録します。完全修飾されたビュー名を表す配列または文字列を渡すことができ、 SAMOOHA_APP_ROLE ロールへの付与選択が行われ、ユーザーはビューをクリーンルームにリンクすることができます。

引数: view_name(array)

戻り値: (String) 成功メッセージ。

例:

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

unregister_table_or_view -- 非推奨

スキーマ:

LIBRARY

注意

このプロシージャは現在、非推奨です。 library.unregister_objectsを使用してください。

説明: すべてのタイプのテーブルとビューの登録を解除します。

引数: object_names(array)、is_view(boolean)、is_iceberg(boolean)、is_external(boolean)、is_under_managed_access_schema(boolean)

出力 (文字列) 成功メッセージ。

テーブルの登録を解除するには:

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

unregister_table -- 非推奨

スキーマ:

LIBRARY

注意

このプロシージャは現在、非推奨です。 library.unregister_objectsを使用してください

説明: unregister_db と似ていますが、テーブルレベルで操作します。テーブルの登録を解除するために、完全修飾テーブル名を表す配列または文字列を渡すことができます。ユーザーは、未登録のテーブルをクリーンルームにリンクすることはできません。

管理アクセススキーマ(つまり、 WITH MANAGED ACCESS パラメーターで作成されたスキーマ)内のテーブルの登録を解除したい場合は、代わりに library.unregister_managed_access_table を使用してください。

引数: table_name(array)

戻り値: (String) 成功メッセージ。

例:

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

unregister_managed_access_table -- 非推奨

スキーマ:

LIBRARY

注意

このプロシージャは現在、非推奨です。 library.unregister_objectsを使用してください

説明: unregister_table と似ていますが、マネージドアクセススキーマ(つまり、 WITH MANAGED ACCESS パラメーターで作成されたスキーマ)のテーブルを登録解除します。

引数: table_name(array)

戻り値: (String) 成功メッセージ。

例:

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

unregister_view -- 非推奨

スキーマ:

LIBRARY

注意

このプロシージャは現在、非推奨です。 library.unregister_objectsを使用してください

説明: unregister_db と似ていますが、ビューレベルで操作します。ビューの登録を解除するには、完全修飾したビュー名を表す配列あるいは文字列を渡します。ユーザーは、未登録のビューをクリーンルームにリンクすることはできません。

管理アクセススキーマ(つまり、 WITH MANAGED ACCESS パラメーターで作成されたスキーマ)内のビューの登録を解除したい場合は、代わりに library.unregister_managed_access_view を使用してください。

引数: view_name(array)

戻り値: (String) 成功メッセージ。

例:

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

unregister_managed_access_view -- 非推奨

スキーマ:

LIBRARY

注意

このプロシージャは現在、非推奨です。 library.unregister_objectsを使用してください

説明: unregister_view と似ていますが、マネージドアクセススキーマ(つまり、 WITH MANAGED ACCESS パラメーターで作成されたスキーマ)のビューを登録解除します。

引数: view_name(array)

戻り値: (String) 成功メッセージ。

例:

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