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 finden Sie eine Zusammenfassung der Schritte, die Sie unternehmen müssen, um einen Clean Room zu erstellen:

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 zu bestimmen, welche Spalten bei der Abfrage durch Verbraucher 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¶

Beginnen Sie mit der Arbeit in Ihrem Anbieterkonto-Notebook.

Zunächst erstellen Sie eine Tabelle auf der Grundlage von 1.000 Zeilen mit Testdaten aus der Tabelle SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS. Sie werden diese Tabelle als Anbieterdaten im Clean Room verwenden.

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 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¶

Ein Clean Room beginnt ohne Daten, ohne Benutzer und nur mit Standardeigenschaften.

Der folgende Ausschnitt erstellt einen Clean Room, der nur innerhalb der Organisation zugänglich ist (daher ist er als INTERNAL gekennzeichnet). Die Freigabe eines Clean Room außerhalb einer Organisation erfordert zusätzliche Schritte, die in diesem Tutorial nicht behandelt werden.

Sie müssen die SAMOOHA_APP_ROLE für fast alle Aktionen im Clean Room 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¶

Lassen Sie uns Ihre Testdaten in den Clean Room verschieben.

Es gibt zwei Schritte, um Daten in den Clean Room zu verschieben:

1. Registrierung der Daten

2. Importieren der Daten in den Clean Room

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

-- Back to 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 angeben. Eine Clean Room-Verknüpfungsrichtlinie legt fest, welche Spalten in einer Tabelle durch Abfragen in diesem Clean Room verbunden werden können. Damit haben Sie eine zusätzliche Kontrolle darüber, wie andere Ihre Daten im Clean Room nutzen können.

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.

Stellen Sie dem Clean Room eine Liste der verknüpfbaren Spalten zur Verfügung. Alle Spalten, die hier nicht aufgeführt sind, können im Clean Room nicht mit den Anweisungen INNER JOIN oder OUTER JOIN verbunden werden. Geben Sie verknüpfbare Spalten für eine Tabelle an und verwenden Sie das Format database_name.schema_name.table_or_view_name:column_name für jede Spalte.

-- 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 einschränken, welche Spalten die anderen Parteien in den Ergebnissen anzeigen können, indem sie eine column_policy setzt. Eine Spaltenrichtlinie in einem Clean Room listet alle Spalten auf, die projiziert werden können; keine anderen Spalten können projiziert werden. Der Anbieter legt die Spaltenrichtlinien für seine Tabellen fest; der Verbraucher legt die Spaltenrichtlinien für seine Tabellen fest.

Eine Spaltenrichtlinie ist an eine bestimmte Tabelle und Vorlage in einem Clean Room gebunden. Sie können zulassen, dass verschiedene Spalten in verschiedenen Vorlagen angezeigt werden. Dieselbe Spalte kann nicht sowohl in einer Verknüpfungs- 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. Wenn Sie keine Spaltenrichtlinie angeben, bedeutet dies, dass alle Ihre Spalten projiziert werden können; ebenso bedeutet die Nichtangabe einer Verknüpfungsrichtlinie, dass alle Ihre Spalten verknüpft werden können.

Hier sehen 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:AGE_BAND',
   $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, die sich aus Haupt-, Neben- und Patch-Werten zusammensetzt. Sie müssen angeben, welche Version des Clean Room einem Verbraucher bereitgestellt 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, wenn Sie Code in den Clean Room hochladen, eine neue Version des Clean Room. Wenn Sie möchten, dass die Benutzer die neueste Version erhalten, müssen Sie diese Prozedur erneut mit der neuen Version aufrufen. Da Sie keinen Code hochladen werden, brauchen Sie diesen Befehl nicht erneut aufzurufen.

Anbieter: Verbraucher hinzufügen¶

Legen Sie nun fest, welche Konten Ihren Clean Room als Verbraucher nutzen können. Ein paar Anforderungen für die gemeinsame Nutzung eines Clean Room:

• Benutzer müssen über ein Snowflake-Konto verfügen, auf dem die Clean Room-Umgebung installiert ist. Es ist möglich, einen Clean Room mit einem Konto zu teilen, das nicht zu Snowflake gehört, aber das wird hier nicht behandelt.

• Das Verbraucherkonto muss sich in derselben Cloudregion befinden wie das Anbieterkonto. Die Freigabe ist regionsübergreifend möglich, aber das erfordert eine zusätzliche Konfiguration, die hier nicht behandelt wird.

• Das Verbraucherkonto muss auf der Seite Collaborators im Konto des Anbieters hinzugefügt werden. Nur Konten, die zur Liste der Teilnehmer eines Kontos hinzugefügt wurden, können eine Einladung zu einem Clean Room erhalten, der mit diesem Konto erstellt wurde.

• Den Konto-Locator erhalten Sie, indem Sie in Ihrem Verbraucherkonto die folgende Prozedur ausführen: SELECT CURRENT_ACCOUNT();.

• Der Name des Kontos hat das Format org_name.account_name. Sie erhalten diese Werte, indem Sie die folgenden Prozeduren in Ihrem Verbraucherkonto ausführen:

  • SELECT CURRENT_ORGANIZATION_NAME();

  • SELECT CURRENT_ACCOUNT_NAME();

CALL samooha_by_snowflake_local_db.provider.add_consumers(
  $cleanroom_name,
  <CONSUMER_LOCATOR>,
  <ORG_NAME>.<ACCOUNT_NAME>);

CALL samooha_by_snowflake_local_db.provider.view_consumers($cleanroom_name);

Anbieter: Clean Room veröffentlichen¶

Schließlich können Sie den Clean Room veröffentlichen. Dadurch wird der Clean Room für die Verbraucher, die Sie oben hinzugefügt haben, verfügbar. Die Prozedur dauert eine Minute oder länger.

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

Wenn die Prozedur abgeschlossen ist, sollte der Clean Room auf der Registerkarte Created der Web-App für Clean Rooms Ihres Anbieterkontos und auf der Registerkarte Invited der Web-App Ihres Verbraucherkontos mit der Bezeichnung „Powered by Dev Edition“ aufgeführt sein. Das Verbraucherkonto erhält eine Einladungs-E-Mail, und der Clean Room sollte auf der Registerkarte Invited in der Web-App des Verbraucherkontos erscheinen.

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

Wechseln Sie nun zum Verbraucherkonto, um den Clean Room zu nutzen.

Verbraucher: Clean Room installieren (verknüpfen)¶

Wechseln Sie zum Verbraucherkonto in Snowsight. Sie können eine zweite Registerkarte in Ihrem Browser öffnen oder den Konto-Switcher verwenden.

Nachdem Sie sich mit Ihrem Verbraucherkonto angemeldet haben, richten Sie Ihre Umgebung in Ihrem Verbraucher-Notebook ein:

USE WAREHOUSE app_wh;
USE ROLE samooha_app_role;

Installieren Sie den Clean Room, den Sie gerade veröffentlicht und freigegeben haben.

Um einen Clean Room zu installieren, müssen Sie sowohl den Namen des Clean Room als auch den Konto-Locator des Anbieters angeben, der den Clean Room für Sie freigegeben hat. Die Angabe des Namens des Clean Room und des Konto-Locators hilft, mehrere Einladungen zu Clean Rooms eindeutig zu identifizieren. Sie können SELECT CURRENT_ACCOUNT(); im Anbieterkonto ausführen, um den Anbieter-Locator abzurufen.

Die Installation kann ein paar Minuten dauern.

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

Verbraucher: Ihre Daten erstellen und verknüpfen¶

Erstellen Sie nun in diesem Clean Room einen Datensatz, der dem Datensatz des Anbieters ähnelt, aber die unteren 1.000 Zeilen der Beispieldaten verwendet.

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

CREATE 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 sie registrieren und mit dem Clean Room verknüpfen, genau 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: Verknüpfungsrichtlinien für Ihre Daten festlegen¶

Sie können jetzt für Ihre Daten Verknüpfungsrichtlinien festlegen, genau wie beim Konto des Anbieters. Die Festlegung von Verbraucher-Verknüpfungsrichtlinien ist in diesem Beispiel überflüssig, da nur Verbraucher eine Vorlage in diesem Clean Room ausführen können. Und da Sie die Vorlage selbst ausführen, wissen Sie, welche Ihrer Spalten verknüpfbar sein sollten. In der Praxis ist es jedoch sinnvoll, Verknüpfungsrichtlinien für Ihre Daten festzulegen, wenn der Clean Room dem Anbieter die Ausführung einer Vorlage erlaubt.

-- Allow same three columns in your data to be joined.
CALL samooha_by_snowflake_local_db.consumer.set_join_policy($cleanroom_name,
  ['cleanroom_tut_db.cleanroom_tut_sch.demo_consumer_table:age_band',
  'cleanroom_tut_db.cleanroom_tut_sch.demo_consumer_table:region_code',
  'cleanroom_tut_db.cleanroom_tut_sch.demo_consumer_table:device_type']);

Verbraucher: Ihre Abfrage vorbereiten¶

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

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

• Die Namen der Tabellen, die Sie der Vorlage zur Verfügung stellen möchten.

• Die Namen der Tabellen des Anbieters, die für die Vorlage verfügbar gemacht werden sollen.

• Jede andere Name/Wert-Variable, die Sie übergeben möchten. In unserer Vorlage müssen wir die Namen der Verknüpfungsspalten aus den Tabellen der Anbieter und Verbraucher übergeben.

-- List templates in the clean room, then examine the template details
CALL samooha_by_snowflake_local_db.consumer.view_added_templates($cleanroom_name);

SET template_name = 'overlap_template';
CALL samooha_by_snowflake_local_db.consumer.view_template_definition($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'],
  ['cleanroom_tut_db.cleanroom_tut_sch.demo_provider_table'],
  OBJECT_CONSTRUCT(
    'consumer_join_col','c.age_band',
    'provider_join_col','p.age_band',
    'group_by_col','p.status'
  ),
  FALSE
);

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;