Grundlegende Datenanalyse durch Verbraucher¶

Umgebung einrichten¶

To use the API, you must use a warehouse that SAMOOHA_APP_ROLE has privileges in. app_wh is one of a number of warehouses with access to the API. Choose the warehouse that is appropriate for your needs. (You can also use your own warehouse, if you choose.)

The SAMOOHA_APP_ROLE role is required to access the API.

USE WAREHOUSE app_wh;
USE ROLE SAMOOHA_APP_ROLE;

Reinraum erstellen¶

The next step is to create a new clean room. This is done with a single API call that specifies whether the clean room is for internal or external use. Internal clean rooms can be accessed only by consumers within the same organization; external clean rooms can be used by consumers outside the organization. For both clean room types, consumers must be invited to use the clean room to be able to access it.

Externe Clean Rooms lösen zusätzliche Sicherheitsprüfungen aus, wenn bestimmte Aktionen durchgeführt werden. Wenn dies geschieht, müssen Sie provider.view_cleanroom_scan_status aufrufen, um zu sehen, wann der Sicherheitsscan abgeschlossen ist. Dann können Sie mit der nächsten Aktion fortfahren.

Im folgenden Beispiel wird ein interner Clean Room erstellt:

CALL samooha_by_snowflake_local_db.provider.cleanroom_init($cleanroom_name, 'INTERNAL');

Daten mit dem Clean Room verknüpfen¶

Both the provider and consumer can link (import) tables, views, and other supported data objects into a clean room. When you link data, the API creates a hidden, secure view inside the clean room that is based on the linked source object. You reference the linked object by its source name, not its internal view name, in all clean room procedures.

Data linked into the clean room can’t be accessed directly by any clean room collaborators. Linked data is accessed using a template imported into the clean room (unless you enable free-form SQL queries on your data).

Before an object can be linked into a clean room, the object must be registered. Registering an object grants proper access privileges to the SAMOOHA_APP_ROLE on the object. You can either register an object directly, or register a parent object (such as a database or schema) to access child objects. You can register an object in either the UI or the API.

Objekte werden auf Kontoebene registriert, nicht auf Clean Room-Ebene; Sie müssen ein Objekt nur einmal pro Konto registrieren und es kann mit jedem Clean Room im Konto verknüpft werden. (Sie können nur Objekte verknüpfen, die in Ihrem eigenen Konto registriert sind.) Nachdem Sie ein Objekt registriert haben, steht das Objekt für die Verknüpfung mit jedem Clean Room des Kontos zur Verfügung. Erfahren Sie mehr über die Registrierung.

Das folgenden Beispiel verknüpft die CUSTOMERS-Tabelle aus der Beispieldatenbank SAMOOHA_SAMPLE_DATABASE. Diese Datenbank wird automatisch registriert, wenn Sie die Clean Room-Umgebung in einem Konto installieren, sodass Sie sie nicht registrieren müssen. Sie können Objekte jederzeit in einem Clean Room verknüpfen oder entkoppeln. Die Ergebnisse werden schnell an alle Teilnehmer weitergegeben.

CALL samooha_by_snowflake_local_db.provider.link_datasets(
  $cleanroom_name,
  ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);

Verknüpfungsrichtlinie festlegen¶

If you add a template to the clean room that allows the consumer to join on your data, you should set a clean room join policy on your data. A clean room join policy specifies which columns can be joined on in queries run by collaborators. Your own join policies don’t constrain your own queries.

Clean rooms support a few types of data policies that you can set on linked data. These policies are similar to, but not the same as, the equivalent Snowflake policies, and are applied only on the internal view, not on the source data. Any Snowflake policies that are set on the source data are propagated to the views linked into a clean room. Clean room policies are set on the linked data only, not on the source data.

Sie können Richtlinien nur für die Daten festlegen, die Sie verknüpfen. Sie können keine Richtlinien für die Daten einer anderen Partei festlegen.

Das folgende Beispiel zeigt, wie Sie eine Verknüpfungsrichtlinie festlegen, die es ermöglicht, zwei Spalten aus der verknüpften Tabelle miteinander zu verknüpfen.

CALL samooha_by_snowflake_local_db.provider.set_join_policy(
  $cleanroom_name,
  ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:HASHED_EMAIL',
   'SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:HASHED_PHONE']);

Erfahren Sie mehr über Verknüpfungsrichtlinien.

Vorlagen zum Clean Room hinzufügen¶

A clean room template is a valid JinjaSQL template that typically evaluates to a SQL query. A template, sometimes called an analysis, can be passed arguments by the caller, and can access any data linked into the clean room. Both providers and consumers can add templates into a clean room and run them.

Snowflake provides a few standard templates, but you will probably write your own custom templates.

Alle Clean Room-Richtlinien, die Sie festlegen, werden nur durchgesetzt, wenn die Vorlage Richtlinienfilter in der Vorlage enthält. Stellen Sie also sicher, dass die Vorlagen, die Sie einem Clean Room hinzufügen, diese Filter enthalten. Weitere Informationen zu Richtlinien finden Sie unter Richtlinien für Clean Room-Tabellen.

Standardmäßig können Vorlagen nur von Verbrauchern ausgeführt werden. Wenn ein Anbieter eine Vorlage ausführen möchte, müssen sie den Verbraucher um eine Berechtigung bitten. Außerdem gilt: Wenn ein Verbraucher eine Vorlage hochladen möchte, muss er den Anbieter um Erlaubnis bitten.

Weitere Informationen zum Erstellen einer kundenspezifischen Vorlage finden Sie unter Kundenspezifische Vorlagen zu einem Clean Room hinzufügen und Referenz für benutzerdefinierte Clean Room-Vorlagen.

Das folgende Beispiel zeigt, wie Sie eine von Snowflake bereitgestellte Vorlage zum Clean Room hinzufügen:

CALL samooha_by_snowflake_local_db.provider.add_templates(
  $cleanroom_name,
  ['prod_overlap_analysis']);

Spaltenrichtlinien festlegen¶

Clean Room-Spaltenrichtlinien legen fest, welche Spalten aus Ihren Tabellen in Abfragen von Teilnehmern projiziert werden können. Eine Spaltenrichtlinie ist sowohl an eine Spalte als auch an eine Vorlage gebunden, sodass verschiedene Spalten mit verschiedenen Vorlagen als projiziert definiert werden können. Eine Vorlage muss in einem Clean Room vorhanden sein, bevor Sie Spaltenrichtlinien für diese Vorlage festlegen können.

Column policies, like all policies, are overwrite-only; this means that setting column policies completely overwrites any existing column policies set by that account. Both the provider and the consumer can set column policies on their data. Learn more about column policies.

Das folgende Beispiel zeigt, wie Sie die Projektion von vier Spalten aus der zuvor verknüpften Beispieldatenbank für Clean Rooms ermöglichen:

CALL samooha_by_snowflake_local_db.provider.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',
  'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:REGION_CODE']);

Freigabe für Verbraucher¶

Nur vom Anbietenden eingeladene Verbrauchende haben Zugriff auf den Clean Room. Verbraucher können einen Clean Room nicht mit anderen Verbrauchern teilen. Bestimmte Verbraucher können erst nach der Veröffentlichung auf den Clean Room zugreifen. Einladungen zum Beitritt zu einem Clean Room erfolgen auf Kontoebene, nicht auf Benutzerebene.

Das folgende Beispiel zeigt, wie Sie einen Clean Room für zwei Verbraucher freigeben. Die Prozedur benötigt zwei parallele, durch Kommas getrennte Listen von Verbraucherkonto-Locator und Data Sharing-Konto-IDs für Verbraucher.

CALL samooha_by_snowflake_local_db.provider.add_consumers(
  $cleanroom_name,
  'CONSUMER_LOCATOR1,CONSUMER_LOCATOR2',
  'CONSUMER_DATA_SHARING_ACCOUNT_ID1,CONSUMER_DATA_SHARING_ACCOUNT_ID2');

Standardversion verwenden¶

Clean Rooms sind versionierte native Anwendungen. Bestimmte Aktionen, wie das Hinzufügen von Code zu einem Clean Room, erzeugen eine neue Patchversion der Anwendung. Verbraucher müssen den Clean Room in ihrem Konto installieren. Die Version, die installiert wird, basiert auf der von Ihnen angegebenen Standardversionsnummer. Wenn Sie später eine neue Version des Clean Rooms veröffentlichen und die Standardversionsnummer erhöhen, werden alle von Verbrauchern installierten Versionen automatisch aktualisiert. Neue Installationen werden standardmäßig auf die neue Version umgestellt. Erfahren Sie mehr über die Versionierung von Clean Rooms.

Das folgende Beispiel zeigt, wie Sie die Standardversion eines Clean Rooms auf V1.0.0 einstellen. Das ist die erste Version eines Clean Rooms, wenn Sie keinen Code hochgeladen haben:

CALL samooha_by_snowflake_local_db.provider.set_default_release_directive(
  $cleanroom_name,
  'V1_0',          -- Version number: Never changes.
  '0'              -- Patch number: Can change.
  );

Clean Room veröffentlichen¶

Im folgenden Beispiel sehen Sie, wie Sie einen Clean Room veröffentlichen oder erneut veröffentlichen. Befolgen Sie diese Anweisung. Wenn dieser Prozess zum ersten Mal aufgerufen wird, macht er den Clean Room für alle Verbraucher, für die Sie ihn freigegeben haben, sichtbar und installierbar. Sie sollten diesen Prozess immer dann aufrufen, wenn Sie erhebliche Änderungen vornehmen, z. B. wenn Sie die Standardversion aktualisieren oder Änderungen speziell für die Clean Room UI vornehmen.

CALL samooha_By_snowflake_local_db.provider.create_or_update_cleanroom_listing(
  $cleanroom_name);

Jetzt kann der Verbraucher den Clean Room installieren, Daten verknüpfen, Richtlinien festlegen und Vorlagen ausführen, wie nachfolgend beschrieben.

Umgebung einrichten¶

Like the provider, the consumer must use a warehouse that SAMOOHA_APP_ROLE can access. However, unlike the provider, the consumer can either use the SAMOOHA_APP_ROLE role directly for full API access, or a clean room administrator in that account can grant a more limited role that gives privileges to run a subset of the API for consumers. This limited role, sometimes generically called a „run role,“ is granted by a user with full clean room privileges. Learn how to grant limited API access.

Mit einer Ausführungsrolle können Sie keinen Clean Room installieren, also müssen Sie SAMOOHA_APP_ROLE, wie im folgenden Beispiel gezeigt, verwenden:

USE WAREHOUSE app_wh;
USE ROLE SAMOOHA_APP_ROLE;

Reinraum installieren¶

Der folgende Ausschnitt zeigt, wie Sie alle installierten Clean Rooms auflisten, zu deren Installation Sie eingeladen wurden:

-- See all clean rooms, installed and not.
CALL samooha_by_snowflake_local_db.consumer.view_cleanrooms();

-- See only clean rooms that aren't installed.
CALL samooha_by_snowflake_local_db.consumer.view_cleanrooms() ->>
  SELECT * FROM $1
    WHERE IS_ALREADY_INSTALLED = false;

Installieren Sie den Clean Room, den der Anbieter für Sie freigegeben hat, wie im folgenden Beispiel gezeigt. Sie müssen den Konto-Locator des Anbieters angeben, wenn Sie einen Clean Room installieren.

CALL samooha_by_snowflake_local_db.consumer.install_cleanroom(
  $cleanroom_name,
  '<PROVIDER_ACCOUNT_LOCATOR>');

Daten hinzufügen und Richtlinien festlegen¶

If the clean room templates allow the consumer to include their own data in a query, the consumer registers data, links data, and sets policies like the provider does. Be sure to use the consumer versions of the procedures, as shown in the following example:

-- You must use a role with MANAGE GRANTS privilege on an object to register it.
USE ROLE ACCOUNTADMIN;
CALL samooha_by_snowflake_local_db.consumer.register_db('MY_DATABASE');

-- Link some tables.
CALL samooha_by_snowflake_local_db.consumer.link_datasets(
  $cleanroom_name,
  [
    'SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS',
    'MY_DATABASE.PUBLIC.EXPOSURES'
  ]);

Die Verknüpfungsrichtlinie des Anbieters zeigt, welche Anbieterspalten verknüpft werden können. Dieses Beispiel zeigt, wie Sie überprüfen, mit welchen Anbieterspalten Sie verknüpfen können:

CALL samooha_by_snowflake_local_db.consumer.view_provider_join_policy($cleanroom_name);

A provider needs the consumer’s approval to run a template in the clean room. As a result, most consumers don’t bother setting policies on the tables that they link in. Nevertheless, we recommend that you consider adding policies in case a provider asks to run a template later, because you might forget to add appropriate policies at that time.

Wenn Sie Richtlinien festlegen, werden diese nur durchgesetzt, wenn die Vorlage einen join_policy- oder column_policy-Filter für die Spalte in der Vorlage enthält. Stellen Sie also sicher, dass die Vorlagen, die Sie einem Clean Room hinzufügen, diese Filter enthalten, um Ihre Richtlinien durchzusetzen. Um die Vorlagen in einem Clean Room zu untersuchen, rufen Sie consumer.view_added_templates auf. Weitere Informationen zu Richtlinien finden Sie unter Richtlinien für Clean Room-Tabellen.

Analyse ausführen¶

Bevor Sie eine Vorlage ausführen, untersuchen Sie diese in der Regel, um festzustellen, was sie tut und welche Variablen sie akzeptiert. Anschließend prüfen Sie, welche Anbietertabellen im Clean Room verfügbar sind.

-- View the list of templates available in this clean room,
-- and the source code for each template.
CALL samooha_by_snowflake_local_db.consumer.view_added_templates($cleanroom_name);

-- Show which variables can be passed in when running the specified template.
CALL samooha_by_snowflake_local_db.consumer.get_arguments_from_template(
  $cleanroom_name,
  $template_name
);

-- See which datasets you have linked into the clean room.
CALL samooha_by_snowflake_local_db.consumer.view_consumer_datasets($cleanroom_name);

-- See which datasets the provider has linked into the clean room.
CALL samooha_by_snowflake_local_db.consumer.view_provider_datasets($cleanroom_name);

CALL samooha_by_snowflake_local_db.consumer.run_analysis(
$cleanroom_name,
$template_name,
[],                                              -- This template doesn't accept consumer tables.
['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],      -- Provider tables.
object_construct(                                -- Template-specific arguments.
  'dimensions', ['p.STATUS'],                    -- Template takes a variable named 'dimensions'.
  'where_clause', 'p.REGION_CODE=$$REGION_10$$'  -- Template allows you to pass in a WHERE clause.
                                                 -- $$ is used to wrap string literals
  )
);