Tutorial: Erste Schritte mit Snowflake Data Clean Rooms im Code¶

Einführung¶

Dieses Tutorial richtet sich an Entwickler, die Snowflake Data Clean Rooms im Code erstellen oder verwenden. Dieses Tutorial verwendet SQL-Code, aber Sie können die hier gezeigten Informationen anpassen, um Clean Rooms in jeder von Snowflake unterstützten Programmiersprache zu erstellen und zu verwenden.

Anbieter: Überblick¶

Hier sehen Sie eine Zusammenfassung der Schritte für das Erstellen eines Clean Rooms als Anbieter:

1. Erstellen Sie Testdaten zum Teilen in Ihrem Clean Room.

2. Erstellen Sie Ihren Clean Room.

3. Verschieben Sie die von Ihnen erstellten Daten in den Clean Room.

4. Legen Sie Verknüpfungsberechtigungen für Ihre Daten fest, um festzulegen, welche Spalten in Verbraucherabfragen verknüpft werden können.

5. Erstellen Sie eine Vorlage für Ihren Clean Room. Eine Clean Room-Vorlage wird in JinjaSQL geschrieben und ergibt zur Laufzeit eine SQL-Abfrage. Die meisten Vorlagen enthalten Variablen, die es den Teilnehmern ermöglichen, zur Laufzeit Tabellen- und Spaltennamen, Bedingungen für WHERE-Klauseln und mehr anzugeben. Ein Clean Room-Teilnehmer wählt eine Vorlage aus und führt sie in einem Clean Room aus.

6. Geben Sie die Standardversion des Clean Room an.

7. Fügen Sie Verbraucher hinzu, die Zugang zu Ihrem Clean Room haben. In diesem Tutorial müssen die Verbraucher Snowflake-Benutzer mit Konten sein, die von Ihrem Clean Room-Administrator genehmigt wurden.

8. Veröffentlichen Sie den Clean Room, um ihn für Ihre eingeladenen Verbraucher zugänglich zu machen.

Anbieter: Testdaten erstellen¶

Melden Sie sich bei Snowsight als Benutzer mit der Berechtigung SAMOOHA_APP_ROLE an. Wenn Sie diese Rolle nicht haben, bitten Sie Ihren Kontoadministrator, Ihnen diese Rolle zuzuweisen.

Erstellen Sie ein neues SQL-Arbeitsblatt in Snowsight, um Ihren Clean Room-Code zu speichern. Benennen Sie das Arbeitsblatt „API-Tutorial – Anbieter“.

Erstellen Sie eine Tabelle auf der Grundlage von 1.000 Zeilen Beispieltestdaten aus der SAMOOHA_SAMPLE_DATABASE.DEMO-.CUSTOMERS-Tabelle. Sie verwenden diese Tabelle als Anbieterdaten im Clean Room.

Verwenden Sie eine Rolle, die es Ihnen erlaubt, eine Datenbank zu erstellen. Das Beispiel hier verwendet ACCOUNTADMIN, aber Sie können jede Rolle verwenden, die das Erstellen einer Tabelle ermöglicht.

USE WAREHOUSE app_wh;
USE ROLE ACCOUNTADMIN;
-- Using ACCOUNTADMIN role because you need a role that allows you to create a database.
-- Feel free to use any other role that can create a database.

-- Generate a provider dataset based on the first 1,000 rows of sample data.
CREATE DATABASE IF NOT EXISTS cleanroom_tut_db;
CREATE SCHEMA IF NOT EXISTS cleanroom_tut_db.cleanroom_tut_sch;

-- Create a temporary table, in case you forget to delete it later.
CREATE TEMPORARY TABLE IF NOT EXISTS cleanroom_tut_db.cleanroom_tut_sch.demo_provider_table AS
  SELECT TOP 1000 * FROM SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS ORDER BY HASHED_EMAIL ASC;

DESCRIBE TABLE cleanroom_tut_db.cleanroom_tut_sch.demo_provider_table;

Anbieter: Clean Room erstellen¶

Im folgenden -Ausschnitt wird ein Clean Room erstellt, der nur innerhalb der Organisation zugänglich ist (sodass er als INTERNAL gekennzeichnet ist). Die Freigabe eines Clean Rooms außerhalb einer Organisation erfordert zusätzliche Schritte, die in diesem Tutorial nicht behandelt werden. Wenn Sie einen Clean Room mit sich selbst teilen, muss er natürlich INTERNAL sein.

Sie müssen für die meisten Clean Room-Prozesse die SAMOOHA_APP_ROLE verwenden.

USE ROLE samooha_app_role;
SET cleanroom_name = 'Developer Tutorial';
CALL samooha_by_snowflake_local_db.provider.cleanroom_init($cleanroom_name, 'INTERNAL');

Anbieter: Daten in den Clean Room bringen¶

Als Nächstes bringen Sie Ihre Testdaten in den Clean Room. Es gibt zwei Schritte, um Daten in einen Clean Room zu bringen:

1. Registrieren Sie die Daten.

2. Importieren Sie (Link) die Daten in den Clean Room.

USE ROLE ACCOUNTADMIN;
CALL samooha_by_snowflake_local_db.provider.register_db('cleanroom_tut_db');

-- Use samooha_app_role until you need to clean things up at the end.
USE ROLE samooha_app_role;

CALL samooha_by_snowflake_local_db.provider.link_datasets($cleanroom_name,
  ['cleanroom_tut_db.cleanroom_tut_sch.demo_provider_table']);

CALL samooha_by_snowflake_local_db.provider.view_provider_datasets($cleanroom_name);

Anbieter: Verknüpfungsrichtlinien für die Daten festlegen¶

Sowohl Anbieter als auch Verbraucher können Verknüpfungsrichtlinien für ihre eigenen Daten festlegen. Eine Clean Room-Verknüpfungsrichtlinie legt fest, welche Spalten in einer Tabelle durch die Abfragen Ihrer Teilnehmer in diesem Clean Room verknüpft werden können. Dies bietet eine zusätzliche Stufe der Kontrolle darüber, wie andere Ihre Daten im Clean Room nutzen. Ihre eigenen Richtlinien werden bei Ihren eigenen Abfragen nicht erzwungen – das heißt, Verknüpfungsrichtlinien, die Sie für Ihre eigenen Daten festgelegt haben, werden ignoriert, wenn Sie eine Abfrage ausführen; Ihre Richtlinien werden nur bei Abfragen durchgesetzt, die von anderen Benutzern ausgeführt werden.

Clean Room-Verknüpfungsrichtlinien werden für die Tabelle festgelegt und gelten für alle Clean Rooms, in denen die Tabelle verwendet wird. Spalten, die hier nicht aufgeführt sind, können nicht mit INNER JOIN oder OUTER JOIN-Anweisungen im Clean Room verknüpft werden. Wenn Sie keine Verknüpfungsrichtlinie angeben, sind alle Spalten verknüpfbar.

Beachten Sie, dass Clean Room-Verknüpfungsrichtlinien nicht dasselbe sind wie Snowflake-Verknüpfungsrichtlinien. Clean Room-Richtlinien geben an, welche Spalten verbunden werden können; Snowflake-Verknüpfungsrichtlinien geben an, welche Spalten nicht verbunden werden können.

Geben Sie verknüpfbare Spalten für eine Tabelle mit dem Format database_name.schema_name.table_or_view_name:column_name für jede Spalte an. Im folgenden Beispiel können drei Spalten von Anbieterdaten verknüpft werden:

-- Limit joinable columns in this table to age_band, region_code, and device_type
CALL samooha_by_snowflake_local_db.provider.set_join_policy($cleanroom_name,
  ['cleanroom_tut_db.cleanroom_tut_sch.demo_provider_table:AGE_BAND',
   'cleanroom_tut_db.cleanroom_tut_sch.demo_provider_table:REGION_CODE',
   'cleanroom_tut_db.cleanroom_tut_sch.demo_provider_table:DEVICE_TYPE']);

CALL samooha_by_snowflake_local_db.provider.view_join_policy($cleanroom_name);

Anbieter: Vorlage hinzufügen¶

Eine Clean Room-Vorlage ist eine JinjaSQL-Vorlage, die eine SELECT-Abfrage ergibt. Diese Abfrage hat Zugriff auf alle mit dem Clean Room verknüpften Datensätze, vorbehaltlich der Verknüpfungs- und Spaltenrichtlinien.

In diesem Tutorial werden wir nicht auf die Einzelheiten der Gestaltung einer JinjaSQL-Vorlage eingehen, aber hier ist die SQL-Abfrage, die Sie implementieren möchten:

SELECT
  COUNT(*),
  group_by_col
FROM Consumer_Table AS C
  INNER JOIN Provider_Table AS P
    ON C.join_col = P.join_col
GROUP BY group_col;

Die Abfrage verknüpft einfach eine Anbieter- und eine Verbrauchertabelle über eine angegebene Verknüpfungsspalte, gruppiert nach einer angegebenen Gruppierungsspalte und projiziert den Gruppenwert und die Anzahl jeder Gruppe. Dies ist die Abfrage, die im Clean Room ausgeführt wird, wenn der Benutzer die Vorlage ausführt.

Hier ist die JinjaSQL-Vorlage für dieselbe Abfrage, mit hinzugefügten Variablen, in denen der Verbraucher Tabellen oder Spalten angeben kann. Nachdem der Verbraucher die Variablen angegeben hat, ergibt sich eine SQL-Abfrage, die der obigen Abfrage ähnelt, jedoch mit den vom Verbraucher angegebenen Tabellen- und Spaltennamen.

SELECT
  COUNT(*),
  IDENTIFIER({{group_by_col | column_policy}})
FROM IDENTIFIER({{my_table[0]}}) AS C
INNER JOIN
  IDENTIFIER({{source_table[0]}}) AS P
    ON IDENTIFIER({{consumer_join_col | join_policy}}) = IDENTIFIER({{provider_join_col | join_policy}})
GROUP BY IDENTIFIER({{group_by_col | column_policy}});

Ein paar Anmerkungen zur Vorlage:

• Inhalte, die von {{brackets}} umgeben sind, sind benannte Variablen, die vom Verbraucher beim Ausführen der Vorlage übergeben werden. Die folgenden Variablen werden vom Verbraucher übergeben: group_by_col, consumer_join_col, provider_join_col

• Die Arrays my_table und source_table sind vom System erstellte globale Variablen, die mit den vom Aufrufer übergebenen Namen der Verbraucher- und Anbietertabellen aufgefüllt werden. Diese Tabellen müssen vom Verbraucher und Anbieter mit dem Clean Room verknüpft werden.

• Alle Anbietertabellen müssen in der Abfrage dem Alias p zugeordnet werden. Alle Verbrauchertabellen müssen dem Alias c zugeordnet werden. Wenn Sie mehrere Tabellen verwenden, geben Sie ihnen ein auf 1 basierendes Suffix als Alias, also: p, p1, p2, p3 und so weiter für Anbietertabellen, und c, c1, c2, c3 und so weiter für Verbrauchertabellen. (p und p0 sind gleichwertig.)

• Snowflake Data Clean Rooms unterstützt einige benutzerdefinierte JinjaSQL-Filter, die auf Variablen angewendet werden. Die Filter column_policy und row_policy überprüfen, ob die Spalten, auf die sie angewendet werden, mit den Spalten- und Zeilenrichtlinien in diesem Clean Room übereinstimmen. Andernfalls schlägt die Anfrage zur Ausführung der Vorlage fehl. {{ consumer_join_col | join_policy }} prüft also, ob der an consumer_join_col übergebene Wert mit den Verknüpfungsrichtlinien übereinstimmt, die der Anbieter und der Verbraucher in diesem Clean Room festgelegt haben.

• Als Bezeichner verwendete Variablen müssen von der Funktion IDENTIFIER verarbeitet werden, bevor sie in SQL verwendet werden können.

Fügen Sie die Vorlage dem Clean Room hinzu:

-- Add the template
SET template_name = 'overlap_template';
CALL samooha_by_snowflake_local_db.provider.add_custom_sql_template(
    $cleanroom_name,
    $template_name,
    $$
    SELECT
      COUNT(*),
      IDENTIFIER({{group_by_col | column_policy}})
    FROM IDENTIFIER({{my_table[0]}}) AS C
    INNER JOIN
      IDENTIFIER({{source_table[0]}}) AS P
      ON IDENTIFIER({{consumer_join_col | join_policy}}) = IDENTIFIER({{provider_join_col | join_policy}})
    GROUP BY IDENTIFIER({{group_by_col | column_policy}});
    $$);

CALL samooha_by_snowflake_local_db.provider.view_added_templates($cleanroom_name);

Anbieter: Spaltenrichtlinien festlegen¶

Jede Partei im Clean Room kann eingrenzen, welche Spalten die anderen Parteien projizieren können, indem eine Spaltenrichtlinie festgelegt wird. Eine Spaltenrichtlinie in einem Clean Room listet alle Spalten Ihrer Daten auf, die projiziert werden können. Es können keine anderen Spalten projiziert werden. Wenn Sie keine Spaltenrichtlinie für Ihre Daten angeben, können alle Ihre Daten projiziert werden.

Eine Spaltenrichtlinie ist an eine bestimmte Tabelle und Vorlage in einem Clean Room gebunden. Sie können die Projektion verschiedener Spalten in verschiedenen Vorlagen erlauben. Dieselbe Spalte kann nicht sowohl in einer Verknüpfung als auch in einer Spaltenrichtlinie enthalten sein.

Beachten Sie, dass Spalten- und Verknüpfungsrichtlinien nur durchgesetzt werden, wenn die Vorlage die Filter column_policy und row_policy in der Vorlage verwendet.

Hier erfahren Sie, wie Sie die Projektion von drei Spalten Ihrer Daten in der soeben erstellten Vorlage ermöglichen. Die Spaltensyntax lautet template_name:table_name:column_name

-- Set column policies. Column policies are tied to a specific template and table, so we
-- needed to add the template first.
CALL samooha_by_snowflake_local_db.provider.set_column_policy($cleanroom_name,
  [$template_name || ':cleanroom_tut_db.cleanroom_tut_sch.demo_provider_table:STATUS',
   $template_name || ':cleanroom_tut_db.cleanroom_tut_sch.demo_provider_table:DAYS_ACTIVE']);

CALL samooha_by_snowflake_local_db.provider.view_column_policy($cleanroom_name);

Anbieter: Release-Richtlinie hinzufügen¶

Jeder Clean Room hat eine Versionsnummer, bestehend aus Haupt-, Neben- und Patch-Werten. Sie müssen angeben, welche Version des Clean Rooms den Verbrauchern zur Verfügung gestellt wird: Dies wird als Standard-Release-Richtlinie bezeichnet.

Dies ist die erste Version, daher lautet die Versionsnummer 1.0.0.

CALL samooha_by_snowflake_local_db.provider.set_default_release_directive(
  $cleanroom_name,
  'V1_0',
  '0');

Snowflake erstellt jedes Mal eine neue Version des Clean Rooms, wenn Sie Code in den Clean Room hochladen. Wenn Sie möchten, dass die Benutzer die neueste Version erhalten, müssen Sie eine neue Standard-Release-Richtlinie mit der neuesten Versionsnummer festlegen. Sie werden keinen Code hochladen, sodass Sie dies für dieses Tutorial nicht noch einmal aufrufen müssen.

Anbieter: Benennen von Verbrauchern¶

Jetzt geben Sie an, wer als Verbraucher Zugang zu Ihrem Clean Room hat. Für dieses Tutorial fügen Sie sich selbst als Verbraucher hinzu. Dadurch wird der Clean Room als interner Test-Clean Room gekennzeichnet, der nur für das Testen verwendet wird. Das schränkt einige Funktionen ein, aber es werden alle Features unterstützt, die für dieses Tutorial benötigt werden.

Der Prozess benötigt zwei Argumente, um jeden Verbraucher zu identifizieren:

• Konto-Locator des Verbrauchers. Rufen Sie Ihren Konto-Locator wie folgt ab:

  SELECT CURRENT_ACCOUNT();
  

  Copy

• Die Datenfreigabekonto-ID des Verbrauchers im Format: org_name.account_name. Rufen Sie die Datenfreigabekonto-ID für Verbraucher im richtigen Format ab:

  SELECT CURRENT_ORGANIZATION_NAME() || '.' || CURRENT_ACCOUNT_NAME();
  

  Copy

Geben Sie den Clean Room nun für sich selbst als Verbraucher frei, indem Sie Ihren Konto-Locator und Ihre Datenfreigabekonto-ID für Verbraucher wo erforderlich angeben:

CALL samooha_by_snowflake_local_db.provider.add_consumers(
  $cleanroom_name,
  '<CONSUMER_LOCATOR>',
  '<CONSUMER_DATA_SHARING_ACCOUNT_ID>');

CALL samooha_by_snowflake_local_db.provider.view_consumers($cleanroom_name);

Anbieter: Clean Room veröffentlichen¶

Veröffentlichen Sie schließlich den Clean Room. Damit steht der Clean Room dem oben hinzugefügten Verbraucher zur Verfügung. Der Prozess dauert nur etwa eine Minute oder etwas mehr.

-- Publish the clean room.
CALL samooha_by_snowflake_local_db.provider.create_or_update_cleanroom_listing(
  $cleanroom_name);

Wenn der Prozess beendet ist, sollten Sie den Clean Room in der Clean Rooms-UI auf der Registerkarte Created in Ihrem Anbieterkonto und auf der Registerkarte Invited im Verbraucherkonto mit der Bezeichnung „unterstützt von Dev Edition“ sehen. Das Verbraucherkonto erhält eine Einladungs-E-Mail. (Installieren Sie den Clean Room nicht über die Registerkarte Invited. Sie werden es ihn einem späteren Schritt im Code installieren).

Herzlichen Glückwunsch! Sie haben Ihren ersten Clean Room veröffentlicht!

Wechseln Sie jetzt Ihre Perspektive vom Anbieter zum Verbraucher.

Verbraucher: Clean Room installieren (verknüpfen)¶

Da Sie in diesem Tutorial dasselbe Konto für die Anbieter- und Verbraucherrollen verwenden, fügen Sie also ein neues SQL-Arbeitsblatt mit dem Namen „API Tutorial – Verbraucher“ in Snowsight im selben Konto hinzu.

Richten Sie die Sitzungsumgebung ein, ähnlich wie Sie es für den Anbieter getan haben:

USE WAREHOUSE app_wh;
USE ROLE samooha_app_role;

Als Nächstes installieren Sie den Clean Room, den Sie veröffentlicht und als Anbieter freigegeben haben. Um einen Clean Room zu installieren, müssen Sie sowohl den Namen des Clean Rooms als auch den Konto-Locator des Anbieters angeben, der den Clean Room für Sie freigegeben hat. Die Angabe des Clean Room-Namens und des Konto-Locators hilft, Clean Rooms mit identischen Namen zu unterscheiden. Führen Sie SELECT CURRENT_ACCOUNT(); aus, um Ihren Anbieter-Locator zu erhalten.

SET cleanroom_name = 'Developer Tutorial';
CALL samooha_by_snowflake_local_db.consumer.install_cleanroom(
  $cleanroom_name,
  <PROVIDER_LOCATOR>);

Die Installation kann ein paar Minuten dauern.

Verbraucher: Ihre Daten erstellen und verknüpfen¶

Erstellen Sie jetzt ein Datenset und fügen Sie es zu diesem Clean Room hinzu. Erstellen Sie eine Tabelle, die dem Datenset des Anbieters ähnelt, verwenden Sie jedoch die untersten 1.000 Zeilen der Beispieldaten.

USE ROLE ACCOUNTADMIN;
CREATE DATABASE IF NOT EXISTS cleanroom_tut_db;
CREATE SCHEMA IF NOT EXISTS cleanroom_tut_db.cleanroom_tut_sch;

CREATE TEMPORARY TABLE IF NOT EXISTS cleanroom_tut_db.cleanroom_tut_sch.demo_consumer_table AS
  SELECT
    TOP 1000 *
    FROM SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS
  ORDER BY HASHED_EMAIL DESC;

DESCRIBE TABLE cleanroom_tut_db.cleanroom_tut_sch.demo_consumer_table;

Nachdem Sie Ihre Quelldaten erstellt haben, müssen Sie diese registrieren und mit dem Clean Room verknüpfen, so wie Sie es als Anbieter getan haben:

-- You need to use a role that has ownership of the object to be registered, probably not samooha_app_role.
USE ROLE ACCOUNTADMIN;
CALL samooha_by_snowflake_local_db.library.register_objects(
  ['cleanroom_tut_db.cleanroom_tut_sch.demo_consumer_table']);

-- Drop back down to samooha_app_role for the other actions.
USE ROLE samooha_app_role;
CALL samooha_by_snowflake_local_db.consumer.link_datasets(
  $cleanroom_name,
  ['cleanroom_tut_db.cleanroom_tut_sch.demo_consumer_table']);

CALL samooha_by_snowflake_local_db.consumer.view_consumer_datasets($cleanroom_name);

Verbraucher: Es müssen keine Richtlinien festgelegt werden¶

Sie könnten Richtlinien für Ihre Daten festlegen, so wie der Anbieter es getan hat, aber diese Vorlage ist nur für die Ausführung durch den Verbraucher zugelassen. Warum sollten Sie sich also die eigenen Abfragen einschränken? In jedem Fall werden Ihre eigenen Zeilen- und Spaltenrichtlinien ignoriert, wenn Sie eine Abfrage ausführen.

Wenn Sie jedoch eine Anfrage eines Anbieters zur Ausführung dieser Vorlage genehmigen würden, würden Sie zunächst Join- und Spaltenrichtlinien für Ihre Daten festlegen, um zu steuern, was der Anbieter damit tun könnte.

Verbraucher: Führen Sie die Analyse aus¶

Um eine Abfrage auszuführen, benötigen Sie die folgenden Informationen:

• Den Namen der Vorlage, die Sie ausführen möchten.

• Die Namen Ihrer Tabellen, die in der Vorlage verwendet werden sollen.

• Die Namen der Tabellen des Anbieters, die in der Vorlage verwendet werden sollen.

• Alle anderen Name/Wert-Variablen, die übergeben werden sollen.

-- List templates in the clean room.
CALL samooha_by_snowflake_local_db.consumer.view_added_templates($cleanroom_name);

-- See the template code.
SET template_name = 'overlap_template';
CALL samooha_by_snowflake_local_db.consumer.view_template_definition(
  $cleanroom_name,
  $template_name);

-- See what arguments can be passed in to the template:
CALL samooha_by_snowflake_local_db.consumer.get_arguments_from_template(
  $cleanroom_name,
  $template_name
);

-- Table name to use is in the LINKED_TABLE column in the results.
CALL samooha_by_snowflake_local_db.consumer.view_provider_datasets($cleanroom_name);

-- See which provider columns can be joined on.
CALL samooha_by_snowflake_local_db.consumer.view_provider_join_policy($cleanroom_name);

-- See which provider columns can be projected.
CALL samooha_by_snowflake_local_db.consumer.view_provider_column_policy($cleanroom_name);

CALL samooha_by_snowflake_local_db.consumer.run_analysis(
  $cleanroom_name,
  $template_name,
  ['cleanroom_tut_db.cleanroom_tut_sch.demo_consumer_table'], -- Consumer table list.
  ['cleanroom_tut_db.cleanroom_tut_sch.demo_provider_table'], -- Provider table list.
  OBJECT_CONSTRUCT(                    -- Additional template arguments as name-value pairs.
    'consumer_join_col','c.age_band',
    'provider_join_col','p.age_band',
    'group_by_col','p.status'
  )
);

Beide Konten: Bereinigen¶

Lassen Sie uns nun alle von Ihnen erstellten Ressourcen bereinigen.

Beachten Sie, dass Sie zum Löschen Ihrer Quelltabellen dieselbe Rolle verwenden müssen, mit der Sie sie erstellt haben.

USE ROLE samooha_app_role;
CALL samooha_by_snowflake_local_db.provider.drop_cleanroom($cleanroom_name);

USE role ACCOUNTADMIN;
DROP TABLE cleanroom_tut_db.cleanroom_tut_sch.demo_provider_table;
DROP DATABASE cleanroom_tut_db;

USE ROLE samooha_app_role;
CALL samooha_by_snowflake_local_db.consumer.uninstall_cleanroom($cleanroom_name);

USE ROLE ACCOUNTADMIN;
DROP VIEW cleanroom_tut_db.cleanroom_tut_sch.demo_consumer_table;
DROP DATABASE cleanroom_tut_db;