Snowflake Data Clean Rooms 開発者ガイド¶
このページでは、Snowflakeでclean roomやテンプレートを作成または管理するプログラムを作成する必要のあるユーザー向けのガイドラインを示します。
Snowflakeは、clean roomを作成または制御するアプリケーションの開発を可能にするストアドプロシージャを公開しています。これらのストアドプロシージャは、Snowsightノートブックやワークシート、 Snowflake CLI など、clean room環境に関連付けられたSnowflakeアカウントへのアクセスが可能なインターフェイスで実行されます。これらのプロシージャは、 SQL、またはSnowflakeインターフェイスがサポートする任意の言語で呼び出すことができます。
環境のセットアップ¶
開発ツール¶
clean room用の主な開発ツールを以下に示します:
コーディング環境: Snowflakeアカウントでストアドプロシージャを実行できる環境であれば、どのようなコーディング環境でもかまいません。ほとんどの開発者は、Snowsight(ブラウザベースのツール)または Snowflake CLI を使用しています。
clean room UI: clean room UI を使用して、clean roomの構成、管理、作成を行います。ほとんどのclean roomアナリストは、コードではなく UI を使用しています。したがって、 UI でclean roomの使用感を確認し、テストすることをお勧めします。また、 clean room UI でのみ使用できる機能 もいくつかあります。
Snowsight は、データベースやその他のオブジェクトを探索したり、検索したりするのに便利です。
コーディング設定¶
必要なロールとウェアハウス¶
clean room API には、 API にフルにアクセスするための SAMOOHA_APP_ROLE ロールが必要です。clean room管理者に、 API へのフルアクセスを許可するよう依頼してください。
Clean roomは、 API プロシージャのサブセットへのアクセスを持つロールの作成 もサポートしています。
SAMOOHA_APP_ROLE による使用が許可されたclean room API を、ウェアハウスで使用する必要があります。Clean roomはウェアハウスの APP_WH に、clean room API へのアクセスを提供します。
-- Set up environment.
USE ROLE samooha_app_role;
USE WAREHOUSE app_wh;
-- Call your clean rooms API functions.
...
他のウェアハウスを使用する場合は、必ずそのウェアハウスに SAMOOHA_APP_ROLE の使用を許可してください:
GRANT USAGE ON WAREHOUSE <your warehouse> TO SAMOOHA_APP_ROLE;`
clean room API について¶
Snowflake Data Clean Rooms は、プロバイダーによるclean roomの作成、構成、共有を可能にするストアドプロシージャのセットを公開します。これらのプロシージャには、ノートブック、ワークブック、Snowflake CLI など、Snowflake プロシージャをサポートするすべてのコマンドライン環境からアクセスできます。ストアドプロシージャをサポートしていれば、どの言語でもclean room API を使用できます。このドキュメントでは SQL を使用しますが、Pythonおよび その他のサポート対象言語 も使用できます。
プロシージャは以下のスキーマ内に存在します。
samooha_by_snowflake_local_db.provider
- プロバイダー固有のプロシージャ.これらのプロシージャは、現在のアカウントによって作成されたclean roomに対してのみ呼び出すことができます。samooha_by_snowflake_local_db.consumer
- コンシューマー固有のプロシージャ.これらのプロシージャは、現在のアカウントがコンシューマーとして招待されたクリーンルームに対してのみ呼び出すことができます。samooha_by_snowflake_local_db.library
- クリーンルーム作成者(プロバイダー)またはクリーンルームコラボレーター(コンシューマー)のどちらかによって呼び出される一般的なプロシージャ。(これらについて、プロバイダーとコンシューマーの両方のリファレンスページに記載されています)。
プロバイダーとコンシューマーの両方のバージョンを持つプロシージャもあります。スキーマごとに適切な結果が生成され、たとえば、 provider.view_cleanrooms
であれば、プロバイダーとしての現在のアカウントのすべてのclean roomの一覧が生成され、 consumer.view_cleanrooms
であれば、コンシューマーとしての現在のアカウントのすべてのclean roomの一覧が生成されます。・
API プロシージャのclean roomの名称について¶
clean room API プロシージャの多くは cleanroom_name
引数を取ります。
APIを使用してclean roomを作成 した場合は、clean roomの 名前 を使用します。
clean room UIを使用してclean roomを作成 した場合は、clean roomの ID を使用してください。
clean roomの名前と ID を確認するには、 describe_cleanroom
を呼び出します。
アカウント、ユーザー、ロールのセットアップ¶
技術的には、clean room UI を使用しなくてもclean roomを開発できます。clean roomのほとんどの機能は、ストアドプロシージャで使用できます。しかし、 UI でしか利用できない 機能や、 UI で実行した方が高速な機能もいくつかあります。また、多くのユーザーが UI を排他的に使用しているため、 UI でclean roomの動作を確認することは、作成したclean roomにユーザー構成用のウェブフォームを作成する場合などに特に重要です。そのため、clean room管理者に依頼して、clean roomのアカウントにclean roomの管理者またはそれ以上の権限を追加してもらう必要があります。
少なくともプロバイダーとコンシューマーのSnowflakeアカウントを別々に持ち、双方をclean roomでテストすることをお勧めします。場合によっては、複数のウェブホスティングリージョンに追加のSnowflakeアカウントを設定し、 クロスクラウドの動作 をテストしてもよいでしょう。
テスト用のSnowflakeアカウントには、"コンシューマーアカウント"、"プロバイダーアカウント"、"クロスクラウドアカウント"など、目的をわかりやすく示す名前を付けてください。そうすれば、複数のテストアカウントがある場合に、どのアカウントにサインインすればよいかがすぐにわかります。
ガイドラインと推奨事項¶
clean room UI とコードで同じアカウントを使用していることを確認する¶
同じSnowflakeアカウントでコーディング環境とclean room UI を開くことも少なくありません(たとえば、コードでclean roomを作成し、その表示をclean room UI で確認する場合など)。その場合は、同じSnowflakeアカウントをそれぞれに使用しているかを確認することが重要です。
Snowsightには、同じアカウントでclean room UI を開くためのメニューはなく、その逆も同様であるため、clean room UI とSnowsightが同じアカウントで開いていることを確認する必要があります。
Clean roomの名前とclean roomの ID¶
API を使用する場合、プロシージャに cleanroom_name
引数を使用し、clean roomの名前と ID のどちらを使用するかを定義する必要があります:
API を使用してclean roomを作成した場合は、clean roomの 名前 を使用します。
clean roomをウェブアプリで作成した場合は、clean roomの ID を使用します。clean roomの名前と ID の両方を確認するには、
provider.view_cleanrooms
またはprovider.describe_cleanroom
を呼び出します。
clean roomの変更時に更新する¶
clean roomの設定(テンプレート、権限、ポリシーなど)を変更し、それを有効にするには、 provider.create_or_update_cleanroom_listing
を呼び出します。場合によっては、このプロシージャを呼び出さなくても、変更されたように見える場合がありますが、 provider.create_or_update_cleanroom_listing
を呼び出すまで変更が正しく適用されません。
コードまたは UI で作成されたclean roomの相互運用性¶
API でclean roomを作成すると、一部の機能をclean room UI で変更できなくなります。例えば、 UIで作成したclean roomのコードにテンプレートを追加することは(Snowflakeのストックテンプレートであっても)できません。また、差分プライバシー設定も変更できません。
clean roomのオブジェクトについて¶
Snowflake Data Clean Rooms をインストールすると、多数のローカルデータベースが作成されます。これよりも便利なオブジェクトをいくつか示します:
SAMOOHA_CLEANROOM_cleanroom_id
このアカウントで作成されたclean roomごとに固有の情報を含みます。以下の項目が含まれます:
Admin: 暗号キー、プライバシーバジェット、リクエストログ、プロバイダー分析リクエストなど。
Shared_schema: 結合ポリシー、 LAF ステータス、リンクテーブル、バージョン。
Templates: このclean roomのアクティベーションテンプレート、カスタムテンプレート、テンプレートチェーンのリスト。
SAMOOHA_CLEANROOM_REQUESTS_cleanroom_id
マルチプロバイダーリクエスト、テンプレートリクエスト、クエリリクエストなどのリクエスト履歴を含みます。
- SAMOOHA_BY_SNOWFLAKE_LOCAL_DB:
Provider.procedures: プロバイダーのすべての API プロシージャの定義
Consumer.procedures: コンシューマーのすべての API プロシージャの定義。
Library.procedures: プロバイダーとコンシューマーのすべての API プロシージャの定義。
Public.consumer_activation_summary: コンシューマーのアクティベーション結果。
Public.provider_activation_summary: プロバイダーのアクティベーション結果。
- SAMOOHA_BY_SNOWFLAKE.TEMPLATES.TEMPLATES:
このアカウントのclean roomで利用可能なSnowflakeのすべてのストックテンプレートのリストと定義を保持します。
(コンシューマー) 結合されたclean roomで、結合ポリシーのセットやその他の基本的なアクションを実行できない¶
clean roomが適切なロール (SAMOOHA_APP_ROLE) でインストールされたことを確認してください。clean roomをインストールする際に SAMOOHA_APP_ROLE を使用していない場合、アクセス許可のエラーをはじめとする多くの問題が発生します。そのの場合は consumer.uninstall_cleanroom
までもがエラーになり、clean roomをアンインストールしてから正しいロールで再インストールするという面倒な手間が必要になります。
-- Who owns the clean room?
SHOW SHARES LIKE 'SAMOOHA_CLEANROOM_REQUESTS_<cleanroom_name>';
-- If the owner role is not SAMOOHA_APP_ROLE, you must drop the share, then
-- uninstall the clean room.
DROP SHARE SAMOOHA_CLEANROOM_REQUESTS_<cleanroom_name>;
CALL samooha_by_snowflake_local_db.consumer.uninstall_cleanroom($cleanroom_name);
USE ROLE samooha_app_role;
CALL samooha_by_snowflake_local_db.consumer.install_cleanroom($cleanroom_name, '<provider_locator>');
一般的な予想外の結果¶
プロシージャのバージョン( consumer
または provider
)を正しく判断して呼び出してください。多くのプロシージャには、プロバイダーとコンシューマーの両方のバージョンがあります。
自分で作ったclean roomが見つからない¶
アカウントでclean roomを作成したのに、コラボレーターのアカウントで表示されない場合、以下の理由が考えられます:
clean roomが別のクラウドホスティングリージョンで作成され、 クロスクラウド自動フルフィルメント を有効にしていない。
provider.create_or_update_cleanroom_listing
を呼び出してclean roomを公開していない。provider.view_cleanrooms()
ではなく、consumer.view_cleanrooms()
を呼び出している(またはその逆)。clean roomを共有していないか、間違ったアカウントでclean roomを共有しているか、またはSnowsight/Clean roomの UI/CLI を間違ったコラボレーターアカウントで開いている。clean roomが表示されるアカウントが、clean roomを共有したアカウントであり、その共有アカウントでサインインしたことを確認してください。
clean roomを公開した後、それがコラボレーターに表示されるまで多少時間がかかります。
不明な関数¶
プロシージャを呼び出した際に、次のエラーが発生した場合: ... code-block:: sqlexample
不明なユーザー定義関数 SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.CONSUMER.<プロシージャ名>
SAMOOHA_APP_ROLE がないか、関数名を間違って入力したかのどちらかです。
また、アクセスが制限された実行ロールが付与されていて、呼び出している関数がそのロールで許可されていない場合もあります。この原因を調べるには、 consumer.grant_run_on_cleanrooms_to_role
で許可されているプロシージャをいずれか実行します。プロシージャが成功した場合は、実行アクセスが制限されたロールを使用している可能性があります。失敗した場合、このアカウントでclean room API を実行する権限がない可能性があります。
SAMOOHA_APP_ROLE があるかどうかを確認するには、以下のコマンドを実行します:
SELECT IS_ROLE_IN_SESSION( 'SAMOOHA_APP_ROLE' );
以下のエラーが発生した場合:
Database <cleanroom name> does not exist or not authorized. in RUN_ANALYSIS_STRING
一時的な実行ロールを付与されており、それが取り消されています。clean roomの管理者に新しい実行ロール、または SAMOOHA_APP_ROLE のフルアクセスを依頼してください。
クエリ履歴の確認¶
実行したクエリの履歴を、 UI またはコードで確認できます。これらの履歴は別々に保存され、チェックされます。
UI のクエリ履歴¶
clean room UI の場合は、このアカウントに対する過去のクエリと結果のリストが Analyses & Queries ページに表示されます。表示されるのは、 UI で実行されたクエリの結果のみです。
API のクエリ履歴¶
API を使用して実行されたクエリのアカウント履歴を確認するには、以下の手順を実行します:
Snowsightにサインインします 。
Monitoring » Query History を選択します。
フィルターを使用して、分析に関連するクエリを見つけ、クエリ ID をコピーします。
ワークシートを開き、クエリのクエリ ID に基づいて結果を取得するクエリを実行します。例えば、クエリ ID が
ABC123
の場合、以下のように実行します:SELECT * FROM TABLE(result_scan(ABC123));
API 分析を実行してから、このクエリを使用して結果を取得するまでの間に、ウェアハウスが中断された場合、結果を取得できない可能性があります。
拡張例¶
clean roomのドキュメントにある Use cases セクションの例を参照し、開発者 APIs の様々な機能の使い方を理解するために役立ててください。