Verwenden von Snowflake Collaboration Data Clean Rooms

Dieses Thema bietet eine allgemeine Anleitung zur Verwendung von Collaboration Data Clean Rooms. Außerdem finden Sie Einzelheiten zu allen wichtigen Schritten, die erforderlich sind, um eine Zusammenarbeit zu erstellen oder an dieser zu teilnehmen.

Anforderungen

Grundlegender Workflow für die Zusammenarbeit im Clean Room

Hier ist ein einfaches Szenario für die Zusammenarbeit im Clean Room:

  1. Der Eigentümer der Zusammenarbeit kann optional alle Vorlagen oder Datenangebote registrieren, die in der anfänglichen Konfiguration der Zusammenarbeit vorhanden sein sollen.

  2. Der Eigentümer bittet optional alle vorgesehenen Teilnehmenden, Vorlagen oder Datenangebote zu registrieren, die in der Erstkonfiguration der Zusammenarbeit angezeigt werden sollen. Die Mitarbeiter geben dann die Ressourcen-IDs von allen Elementen an, die sie registriert haben.

  3. Der Eigentümer erstellt dann eine Zusammenarbeit. Die Zusammenarbeit wird durch eine Zusammenarbeits-YAML-Spezifikation definiert, die die Teilnehmenden, deren Rollen und alle Ressourcen auflistet, die in der ersten Version der Zusammenarbeit vorhanden sein sollen.

    • Wenn eine Zusammenarbeit erstellt wird, ist die Menge der Teilnehmenden und ihrer Rollen festgelegt: Nur Teilnehmende mit einer Rolle in der Definition der Zusammenarbeit werden zum Beitritt eingeladen. Ebenso ist der Satz der Analyseausführenden festgelegt. Jeder Teilnehmende kann jedoch auch ein Datenanbieter werden, indem er neue Daten mit der Zusammenarbeit verknüpft.

    • Wenn Ihre Zusammenarbeit Benutzende in anderen Cloudhosting-Regionen umfasst, müssen diese die Cloud-übergreifende automatische Ausführung für ihr Konto aktivieren, bevor sie die Zusammenarbeit überprüfen und ihr beitreten können.

  4. Der Eigentümer tritt der von ihm erstellten Zusammenarbeit bei, wodurch die Zusammenarbeit aktiv wird. Die Zusammenarbeit ist jetzt für jeden Teilnehmenden in der Spezifikation sichtbar und zum Beitreten verfügbar.

  5. Teilnehmende überprüfen die Zusammenarbeit und treten ihr bei.

  6. Teilnehmende können dann optional Ressourcen zur Zusammenarbeit hinzufügen, wie z. B. Vorlagen, und, auch wenn es sich um einen Datenanbieter handelt, Datenangebote.

  7. Analyseausführende können dann alle Vorlagen ausführen, die ihnen in der Zusammenarbeit zugewiesen sind, wobei sie alle Daten verwenden können, die ihnen in der Zusammenarbeit zur Verfügung stehen (sowie optional nicht freigegebene lokale Daten). Der Analyseausführende trägt die Kosten der Analyse. Vorlagen können die Abfrageergebnisse entweder in der Antwort zurückgeben oder Ergebnisse für den Aufrufenden oder einen anderen Teilnehmenden aktivieren.

In den folgenden Abschnitten werden die Details zu jedem dieser Schritte beschrieben.

Erstellen einer Zusammenarbeit

Um eine Zusammenarbeit zu erstellen, entwerfen Sie eine Zusammenarbeitsspezifikation, die alle Teilnehmenden und deren Rollen definiert. Optional registriert der Eigentümer der Zusammenarbeit sie und verknüpft alle anderen Ressourcen, die im Rahmen der anfänglichen Zusammenarbeit zur Verfügung gestellt werden sollen, und er schließt die Ressourcen in die Zusammenarbeitsspezifikation ein. Wenn der Eigentümer erwartet, dass Ressourcen von Teilnehmenden verwendet werden, kann der Eigentümer diese Benutzenden auch auffordern, ihre Ressourcen zu registrieren und dem Eigentümer die Ressourcen-IDs zu nennen, die in die Zusammenarbeitsspezifikation aufgenommen werden sollen.

Der Eigentümer ruft dann INITIALIZE auf, um mit der Erstellung der Zusammenarbeit zu beginnen. Standardmäßig verbindet INITIALIZE auch automatisch den Eigentümer mit der Zusammenarbeit. Dies ist ein asynchroner Prozess, daher muss GET_STATUS so lange aufgerufen werden, bis der Status JOINED lautet. Wenn der Status der Zusammenarbeit JOINED lautet, ist die Zusammenarbeit aktiv, und alle Teilnehmenden können die Zusammenarbeit sehen und ihr beitreten.

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.INITIALIZE(
$$
api_version: 2.0.0
spec_type: collaboration
name: my_first_collaboration
owner: alice
collaborator_identifier_aliases:
  alice: example_com.acct_abc
  bob: another_example.acct_xyz
analysis_runners:
  bob:
    data_providers:
      alice:
        data_offerings: []
      bob:
        data_offerings: []
  alice:
    data_providers:
      alice:
        data_offerings: []
      bob:
        data_offerings: []
    templates: []
$$,
'APP_WH'
);
SET collaboration_name = '<collaboration_name>';

-- INITIALIZE automatically joins the owner. Check status until JOINED.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.GET_STATUS($collaboration_name);

-- Collaboration is visible here when it's joined.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_COLLABORATIONS();

Ressourcen zu einer Zusammenarbeit hinzufügen

Jeder Teilnehmende kann Ressourcen zu einer Zusammenarbeit hinzufügen oder Ressourcen entfernen, die er der Zusammenarbeit hinzugefügt hat. Es gibt zwei Schritte, um eine Ressource zu einer Zusammenarbeit hinzuzufügen:

  1. Der Ressourceneigentümer erstellt eine Ressourcendefinitionsspezifikation für die Ressource und verwendet sie, um die Ressource in seinem Konto zu registrieren. Sie können die Ressource in der Standard-Registry Ihres Kontos registrieren, oder Sie können eine benutzerdefinierte Registry verwenden.

  2. Ein Teilnehmender verknüpft die Ressource mit einer Zusammenarbeit. Nachdem die Ressource mit verknüpft wurde, kann sie von den angegebenen Teilnehmenden verwendet werden. Einige Ressourcentypen, wie z. B. Vorlagen, können von jedem Teilnehmenden eingebunden werden. Andere Ressourcen, wie z. B. Datenangebote, können nur von Benutzenden mit einer Datenanbieterrolle verknüpft werden. Ressourcen stehen in der Regel nur bestimmten Teilnehmenden zur Verfügung, die in der Zusammenarbeitsspezifikation und der Ressourcenfreigabe definiert sind.

Ressourcen können einer Zusammenarbeit entweder vor oder nach dem Erstellen einer Zusammenarbeit hinzugefügt werden.

Ressourcen unterstützen die Versionierung. Das Erstellen einer neuen Ressource mit einer neuen Version entfernt jedoch nicht die vorherige Version aus der Zusammenarbeit.

Ressourcen werden eindeutig benannt, indem der vom Benutzenden angegebene Name und die Version (und Alias bei Datenangeboten) kombiniert werden.

Sie können die folgenden Ressourcen zu einer Zusammenarbeit hinzufügen:

Vorlagen

Vorlagen sind JinjaSQL-Clean Room-Vorlagen, die von festgelegten Teilnehmenden ausgeführt werden können. Jeder Teilnehmende kann eine Vorlage registrieren und zu einer Zusammenarbeit hinzufügen, solange alle betroffenen Teilnehmenden die Anfrage genehmigen, wie in den folgenden Schritten beschrieben. Sie können nur Vorlagen hinzufügen oder entfernen, die in Ihrem Konto registriert sind.

So fügen Sie eine Vorlage zu einer Zusammenarbeit hinzu:

  1. Entwerfen Sie eine Vorlage für die Zusammenarbeit, und betten Sie sie in eine Vorlagenspezifikation ein.

  2. Registrieren Sie die Vorlage, indem Sie REGISTRY.REGISTER_TEMPLATE aufrufen. Dadurch wird eine Vorlagen-ID zurückgegeben.

  3. Verknüpfen Sie die Vorlage. Der Prozess hängt davon ab, ob die Zusammenarbeit bereits vorhanden ist:

    • Um eine Vorlage vor dem Erstellen der Zusammenarbeit hinzuzufügen, geben Sie die Vorlagen-ID an den Eigentümer der Zusammenarbeit weiter, der sie zur Zusammenarbeitsspezifikation hinzufügt und definiert, wer sie ausführen kann.

       alice:
   data_providers:
     bob:
       data_offerings: []
   templates:
   - id: bob_template_v1 # Alice can run this template, seemingly registered by bob.

    • Um eine Vorlage zu einer vorhandenen Zusammenarbeit hinzuzufügen, müssen Sie bei allen von der Vorlage betroffenen Teilnehmenden die Berechtigung anfragen. Führen Sie die folgenden Schritte aus, um eine Vorlage zu einer vorhandenen Zusammenarbeit hinzuzufügen:

      1. Rufen Sie REGISTER_TEMPLATE auf, um die Vorlage in Ihrem Konto zu registrieren, damit sie zu Zusammenarbeiten hinzugefügt werden kann.

      2. Rufen Sie ADD_TEMPLATE_REQUEST mit der Vorlagen-ID auf, um den Genehmigungsablauf zu starten und die Vorlage zu einer bestimmten Zusammenarbeit für bestimmte Benutzende hinzuzufügen.

        Alle von der Ressource betroffenen Teilnehmenden sehen die Anfrage, wenn sie VIEW_UPDATE_REQUESTS aufrufen.

      3. Teilnehmende, denen die Anfrage mit dem Status PENDING angezeigt wird, sollten APPROVE_UPDATE_REQUEST oder REJECT_UPDATE_REQUEST aufrufen.

        • Wenn ein Teilnehmender die Anfrage ablehnt, wird die Aktualisierungsanfrage abgelehnt.

        • Mitarbeitende können später eine Genehmigung nicht in eine Ablehnung oder eine Ablehnung in eine Genehmigung ändern.

        Wenn der Status der Anfrage APPROVED ist, steht die Vorlage den in der Anfrage zum Hinzufügen einer Vorlage angegebenen Benutzenden zur Verfügung. Wenn die Anforderung REJECTED ist, ist jeder von der ablehnenden Seite angegebene Grund im Anfragebericht sichtbar. Nachdem eine Vorlage von allen Benutzenden genehmigt wurde, kann es eine kurze Verzögerung geben, bevor die Vorlage verfügbar ist. Rufen Sie view_templates auf, wenn Sie sicherstellen möchten, dass die Vorlage für die Verwendung verfügbar ist.

Tipp

Um zu sehen, welche Vorlagen Sie registriert haben, rufen Sie REGISTRY.VIEW_REGISTERED_TEMPLATES auf.

Vorlagenentwurf für eine Zusammenarbeit

Zusammenarbeitsvorlagen gleichen Clean Room-Vorlagen, wobei es einige Besonderheiten zu beachten gibt:

  • Freigegebene Tabellen, die in der Zusammenarbeit aufgeführt sind, werden verwendet, um die source_table-Variable der Vorlage auszufüllen.

  • my_table wird nur verwendet, wenn ein Analyseausführender lokale, nicht freigegebene Daten verwenden möchte. Wenn Sie die my_table-Variable in einer Vorlage verwenden, müssen Sie beachten, dass Tabellen, die dieser Variablen zugewiesen sind, nicht für die Zusammenarbeit freigegeben werden.

  • Spalten aus den Datenquellen haben möglicherweise neue Namen, wenn sie für die Vorlage oder den Benutzenden zugänglich sind. Unter Umbenennen der Quellspalte erfahren Sie mehr darüber, wie und wann Quellspalten umbenannt werden. Vorlagen und vom Benutzenden bereitgestellte Argumente (z. B. der Name einer Verknüpfungsspalte) sollten den endgültigen Namen und nicht den ursprünglichen Namen verwenden, wenn die Spalte umbenannt wird.

  • Aktivierungsvorlagen in einer Zusammenarbeit müssen nicht activation_template_name benannt werden. Alle anderen Anforderungen an die Aktivierungsvorlage gelten weiterhin.

Informationen zur Syntax benutzerdefinierter Vorlagen in Snowflake Data Clean Rooms finden Sie unter Referenz für benutzerdefinierte Clean Room-Vorlagen.

Datenangebote

Ein Datenangebot ist ein Satz von einer oder mehreren Datenansichten, die für in einer Zusammenarbeit für bestimmte Analyseausführende freigegeben werden. Datenangebote können von allen in einer Zusammenarbeit aufgeführten Datenanbietern hinzugefügt werden. Datenangebote werden in einem Bereichsformat als data offering ID.alias angezeigt, wobei der Alias eine bestimmte Ansicht im Datenangebot ist. Sie können Datenangebote nur dann für bestimmte Teilnehmende freigeben, wenn Sie in als Datenanbieter für diesen Analyseausführenden in den Zusammenarbeitsspezifikationen aufgeführt sind.

Ein Datenangebot ist eine Live-Ansicht der Daten und kein Snapshot der Daten zum Zeitpunkt der Erstellung oder Registrierung des Datenangebots. Alle Snowflake-Richtlinien, die auf die Quelldaten angewendet werden, sind in der Zusammenarbeit aktiv.

Wenn Sie ein Datenangebot registrieren, erstellt Snowflake eine Ansicht für jede in der Spezifikation des Datenangebots aufgeführte Datenquelle. Die Ansicht enthält nur die Spalten, die in der Spezifikation des Datenangebots aufgeführt sind. Wenn Sie ein Datenangebot mit einer Zusammenarbeit verknüpfen, erstellt Snowflake eine Kopie dieser Ansicht, die mit geschütztem Zugriff für alle Analyseausführenden versehen ist, die auf dieses Datenangebot zugreifen können, gemäß der Zusammenarbeitsspezifikation. Wenn Sie die zugrunde liegenden Tabellen verschieben, umbenennen oder die Zugriffsberechtigungen für die Tabellen ändern, wird das Datenangebot über alle zuvor registrierten Links nicht mehr verwendbar.

Wenn Sie die Snowflake Standard Edition verwenden, können Sie keine Datenangebote gemeinsam mit anderen Teilnehmenden verwenden. Aber Sie können Ihre eigenen Daten in einer Abfrage verwenden.

Anforderungen:

Datenangebote werden mit den folgenden Schritten zu einer Zusammenarbeit hinzugefügt:

  1. Erstellen Sie eine Datenangebotsspezifikation für Ihre Daten.

  2. Registriert das Datenangebot, indem REGISTRY.REGISTER_DATA_OFFERING aufgerufen wird, wodurch eine Datenangebots-ID zurückgegeben wird.

    Durch diesen Schritt wird das Datenangebot verfügbar, um mit jeder Zusammenarbeit verknüpft zu werden, auf die Sie zugreifen können. Sie können dieselbe Datenangebots-ID zur Freigabe eines Datenangebots für mehrere Kooperationen verwenden.

  3. Der nächste Schritt hängt davon ab, ob die Zusammenarbeit erstellt wurde oder nicht:

    • Wenn die Zusammenarbeit noch nicht erstellt wurde, gibt der Datenanbieter die Datenangebots-ID an den Ersteller der Zusammenarbeit, damit sie zur Zusammenarbeitsdefinition hinzugefügt wird. Wenn ein Datenangebot zur Definition der Zusammenarbeit hinzugefügt wird, ist das Datenangebot für jeden in der Zusammenarbeit sichtbar, nachdem der Datenanbieter der Zusammenarbeit beigetreten ist.

    • Wenn die Zusammenarbeit bereits erstellt wurde, tritt der Datenanbieter der Zusammenarbeit bei und ruft COLLABORATION.LINK_DATA_OFFERING mit der Datenangebots-ID, dem Namen der Zusammenarbeit und den Personen, für die die Daten freigegeben werden können, auf. Nachdem ein Datenangebot von allen Benutzenden genehmigt wurde, kann es eine kurze Verzögerung geben, bevor das Datenangebot zur Nutzung zur Verfügung steht. Rufen Sie view_data_offerings auf, wenn Sie sicherstellen möchten, dass die Daten für die Nutzung verfügbar sind.

    Sie können Datenressourcen aus einer Zusammenarbeit entfernen, indem Sie unlink_data_offering aufrufen.

Jedes Datenangebot besteht aus einer oder mehreren Tabellen oder Ansichten. Der Zugriff auf einzelne Tabellen erfolgt mit der Syntax collaborator alias.data offering ID.dataset alias, wo die Datenangebots-ID eine Kombination aus dem vom Benutzenden bereitgestellten Namen und den Versionswerten ist. Der Alias ist eine einzelne Tabelle im Angebot. Betrachten Sie den Namen, die Version und den Alias als Bereichssystem, wenn Sie Ihre Datenangebote registrieren.

Sie könnten zum Beispiel das folgende Datenangebot mit Verkaufsdaten registrieren, wobei jede Tabelle spezifisch für einen US-Bundesstaat ist:

api_version: 2.0.0
spec_type: data_offering
version: v0
name: examplecorp_sales_by_state
datasets:
 - alias: AL
   data_object_fqn: mydb.mysch.al_data
 - alias: NY
   data_object_fqn: mydb.mysch.ny_data
 - alias: CA
   data_object_fqn: mydb.mysch.ca_data

Der Analyseausführende würde diese Tabellen dann als data offering id.AL, data offering id.NY`oder :samp:`data offering id.CA referenzieren.

Datenangebote sind in einer Zusammenarbeit erst sichtbar, wenn der Benutzende, der das Datenangebot registriert hat, der Zusammenarbeit beitritt.

Tipp

Wenn Sie nicht die OWNERSHIP für Daten haben, die Sie freigeben, erhalten Sie eine Fehlermeldung, wenn Sie versuchen, der Zusammenarbeit beizutreten oder Ihr Datenangebot zu verknüpfen. Die Fehlermeldung enthält Informationen zu einem SQL-Befehl, der von einem ACCOUNTADMIN ausgeführt werden muss, um den Datenzugriff auf die Zusammenarbeit zu gewähren. Nachdem der ACCOUNTADMIN den Befehl ausgeführt hat, können Sie der Zusammenarbeit beitreten. Weitere Informationen dazu finden Sie unter.

Wenn Sie eine Abfrage ausführen, übergeben die Analyseausführenden die Datenangebote nach ID an den source_tables-Parameter von COLLABORATION.RUN.

Um Ihre registrierten Datenangebote anzuzeigen, rufen Sie VIEW_REGISTERED_DATA_OFFERINGS auf.

Anwenden von Nutzungsrichtlinien auf Ihre Daten

Es gibt zwei Möglichkeiten, eine Snowflake-Spaltenrichtlinie, z. B. eine Verknüpfungs- oder Aggregationsrichtlinie, auf Ihre freigegebenen Daten anzuwenden:

  • Wenden Sie die Richtlinie auf die Quelldaten an. Alle Richtlinien, die auf die Quelldaten angewendet werden, werden in den Datasets durchgesetzt, die im Rahmen einer Zusammenarbeit offengelegt wurden. Stellen Sie sicher, dass Sie dem Benutzenden Ihre Richtlinie mitteilen.

  • Wenden Sie die Richtlinie auf das Datenangebot an, wenn Sie es in Freiform-Abfragen verwenden. Wenn Sie Freiform-Abfragen für Ihre Datenangebote zulassen, können Sie Spaltenrichtlinien angeben, um Freiform-Abfragen für Ihre Daten durchzusetzen. Geben Sie Spaltenrichtlinien für Freiform-Abfragen in der Spezifikation des Datenangebots an. Diese Richtlinien werden zusätzlich zu allen vorhandenen Snowflake-Richtlinien für Ihre Quelltabellen angewendet.

Anwenden der Richtlinie auf Ihre Quelldaten

Alle Snowflake-Richtlinien, die auf die Quelldaten angewendet werden, gelten auch für die Datenangebotsansicht in der Zusammenarbeit.

Wenn Sie Snowflake-Richtlinien auf Ihre Quelldaten anwenden, müssen Sie Ihre Teilnehmenden über diese Richtlinien informieren, damit sie nicht unwissentlich versuchen, eine Abfrage auszuführen, die für eine nicht verknüpfbare Spalte eine Verknüpfung vornimmt oder die Gruppierung nicht dort vornimmt, wo dies geschehen sollte. Sie können alle Snowflake-Richtlinien im description-Feld Ihres Datenangebots angeben.

Anwenden der Richtlinie auf das Datenangebot an (nur Nutzung von Freiform-Abfragen)

Sie können Snowflake-Richtlinien auf Freiformabfragen in Ihren freigegebenen Daten anwenden, ohne sie auf die Quelldaten anzuwenden. Diese Richtlinien werden auf Ihre Daten angewendet, wenn Sie zusätzlich zu den Snowflake-Richtlinien, die direkt auf die Quelltabelle angewendet werden, auf Ihre Daten zugreifen.

So fügen Sie Ihren Daten Freiform-SQL-Richtlinien zu:

  1. Erstellen Sie einen Richtlinientyp, der von Collaboration Data Clean Rooms unterstützt wird.

  2. Fügen Sie die folgenden Informationen zu Ihrer Datenangebotsdefinition hinzu:

    • Setzen Sie allowed_analyses: template_and_freeform_sql.

    • Fügen Sie den Abschnitt freeform_sql_policies zur Definition des Datasets hinzu.

    • Fügen Sie unter freeform_sql_policies die entsprechenden Abschnitte für Richtlinientypen hinzu, wobei Sie die von Ihnen erstellten Snowflake-Richtlinien auflisten und angeben, auf welche Zusammenarbeitsspalten diese Richtlinien angewendet werden sollen.

Teilnehmende sehen die auf die Daten angewendeten Richtlinientypen, wenn sie COLLABORATION.VIEW_DATA_OFFERINGS aufrufen.

Sie können eine Richtlinie für mehrere Spalten in mehreren Tabellen wiederverwenden.

Beispiel:

CREATE OR REPLACE AGGREGATION POLICY my_db.public.my_agg_policy AS ()
  RETURNS AGGREGATION_CONSTRAINT ->
    AGGREGATION_CONSTRAINT(MIN_GROUP_SIZE => 5);

Umbenennen der Quellspalte

Die Spaltennamen, die der Vorlage oder dem Freiform-SQL-Aufrufenden angezeigt werden, werden durch die Werte category und column_type festgelegt, die die Spalte in der Datenangebotsdefinition beschreiben. Das Umbenennen von Spalten erfolgt entsprechend dieser Rubrik:

  • Wenn category für die Spalte join_custom oder passthrough lautet, wird der ursprüngliche Spaltenname angezeigt.

  • Wenn category den Wert join_standard hat, wird die Spalte als column_type-Wert umbenannt.

  • Wenn category den Wert timestamp hat, wird die Spalte im Datenangebot in timestamp umbenannt.

Beispiel: Wenn die Spalte in der Quelltabelle den Namen user_email_address hat, hängt die Offenlegung der Spalte in der Vorlage oder in Freiform-SQL davon ab, wie sie in der Definition des Datenangebots definiert ist:

  • Wenn die Spaltenkategorie join_standard lautet und column_type vorhanden ist:

    ... Snippet from data offering yaml ...
schema_and_template_policies:
     user_email_address:
       category: join_standard
       column_type: hashed_email_sha256

    Dann wird der Wert column_type in Abfragen und Vorlagen verwendet:

    SELECT HASHED_EMAIL_SHA256 FROM source_table[0];

  • Wenn die Spaltenkategorie join_custom lautet:

    ... Snippet from data offering yaml ...
schema_and_template_policies:
     user_email_address:
       category: join_custom
       column_type: hashed_email_sha256

    Dann wird der ursprüngliche Quellspaltenname in Abfragen und Vorlagen verwendet:

    -- column_type is ignored for join_custom columns.
SELECT user_email_address FROM source_table[0];

Einer Zusammenarbeit beitreten

Sie müssen einer Zusammenarbeit beitreten, damit alle Ressourcen, die Sie zu einer Zusammenarbeit beigesteuert haben, in der Zusammenarbeit verfügbar sind, oder um eine Analyse in der Zusammenarbeit ausführen zu können.

  • Der Ersteller wird beim Aufrufen von INITIALIZE automatisch verknüpft (es sei denn,``auto_join_warehouse`` wird bereitgestellt). Wenn die automatische Verknüpfung deaktiviert ist, ruft der Ersteller JOIN separat auf.

  • Nicht Erstellende rufen REVIEW und dann JOIN auf.

    Wichtig

    Wenn sich Ihr Konto in einer anderen Cloud-Hosting-Region befindet als die des Eigentümers der Zusammenarbeit:

Das Verknüpfen ist ein asynchroner Prozess. Rufen Sie GET_STATUS auf, um zu sehen, wann der Status als JOINED aufgeführt ist.

Analyse ausführen

Sie können Analysen entweder durchführen, indem Sie eine Vorlage in der Abfrage ausführen oder indem Sie eine Freiform-SQL-Abfrage für die Zusammenarbeitsdaten ausführen. Sie müssen ein benannter Analyseausführender in einer Zusammenarbeit sein, um eine Analyse durchführen zu können. Die Zusammenarbeitsspezifikation bestimmt, ob Sie eine Vorlage ausführen, Ergebnisse aktivieren oder Freiform-SQL-Abfragen ausführen können. Ihre Möglichkeiten sowie die Daten und Vorlagen, die Sie verwenden können, sind in der Spezifikation für die Zusammenarbeit beschrieben.

Der Analyseausführende trägt die Kosten für die Durchführung einer Analyse.

Ausführen einer Analyse aus einer Vorlage

Um eine Analyse aus einer Vorlage auszuführen, zeigen Sie die Liste der Vorlagen am, die Sie ausführen können, zeigen Sie die Liste der Datenangebote an, die Sie verwenden können, und rufen Sie dann COLLABORATION.RUN mit Ihren Werten auf, entweder als einzelne Parameter oder als Analysespezifikation im YAML-Format:

-- See which data offerings are available.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_DATA_OFFERINGS($collaboration_name);

-- See which templates you can run.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_TEMPLATES($collaboration_name);

-- Pass in the arguments in analysis YAML format.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.RUN(
  $collaboration_name,
  $$
    api_version: 2.0.0
    spec_type: analysis
    name: My_analysis
    description: Sales results Q2 2025
    template: sales_join_template

    template_configuration:
      view_mappings:
        source_tables:
          -  user1_alias.data_offering_v1.table1
          -  user2_alias.another_data_offering_v1.table_2
      arguments:
         conv_purchase_id: PURCHASE_ID
         conv_purchase_amount: PURCHASE_AMOUNT
         publisher_impression_id: IMPRESSION_ID
         publisher_campaign_name: CAMPAIGN_NAME
         publisher_device_type: DEVICE_TYPE
  $$ );

Aktivieren und Ausführen von Freiform-SQL-Abfragen für Ihre Daten

Ein Datenanbieter kann ermöglichen, dass Analyseausführende SQL-Abfragen für die Datenangebote der Zusammenarbeit ausführen können. Sie müssen Mitglied einer Zusammenarbeit sein und über die Rolle des Analyseausführenden mit SQL-Freiformberechtigung für ein Datenangebot verfügen, um SQL-Freiformabfragen für diese Daten durchzuführen.

Datenanbieterschritte

Damit Teilnehmende ein Dataset von der Befehlszeile aus abfragen können, legen Sie allowed_analyses: template_and_freeform_sql in Ihrer Dataset-Beschreibung fest. Benutzende, die der Zusammenarbeit beitreten, können Freiform-SQL-Abfragen für die Datasets ausführen, auf die sie zugreifen können.

Die folgenden YAML definiert ein Dataset, das Freiformabfragen erlaubt:

api_version: 2.0.0
version: 1
name: my_favorite_dataset
datasets:
  - alias: test_freeform_restricted_agg
    data_object_fqn: samooha_provider_sample_database.audience_overlap.customers
    object_class: custom
    allowed_analyses: template_and_freeform_sql
...

Schritte des Analyseausführenden

  1. Um zu sehen, welche Datasets Freiformabfragen unterstützen, führt der Analyseausführende nach dem Beitritt zu einer Zusammenarbeit COLLABORATION.VIEW_DATA_OFFERINGS aus. Die Spalte FREEFORM_SQL_VIEW_NAME in den Ergebnissen zeigt an, auf welche Tabellen mit Freiform-SQL zugegriffen werden kann, und welcher Tabellenname in der SQL-Abfrage verwendet wird.

    CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_DATA_OFFERINGS($collaboration_name);

    +-------------------------------+------------------------+------------------------------+------------------------------+---------------------------------------+
|   template_view_name          | template_join_columns  | analysis_allowed_columns     | activation_allowed_columns   |      freeform_sql_view_name           |
+-------------------------------+------------------------+------------------------------+------------------------------+---------------------------------------+
| useralias.data_offering_alias |     ip_address         | email, name, age             |             SSN              | alias_name.test_data_offering_v0.customers|
+-------------------------------+------------------------+------------------------------+------------------------------+---------------------------------------+

  2. Der Teilnehmende kann dann die in der Spalte FREEFORM_SQL_VIEW_NAME aufgeführte Tabelle mit Freiform-SQL-Abfragen abfragen:

    SELECT * FROM alias_name.test_data_offering_v0.customers;

Alle auf die Tabelle angewendeten Richtlinien werden durchgesetzt.

Ausführen einer Analyse mit Ihren eigenen Daten, wenn Sie die Standard Edition verwenden

Wenn Sie die Standard Edition verwenden, können Sie eine Analyse mit der Standardmethode ausführen. Sie können Ihre Daten jedoch nicht zur Beschreibung der Zusammenarbeit hinzufügen und sie für andere Benutzende freigeben.

So verwenden Sie als Benutzender der Standard Edition Ihre eigenen Daten in einer Zusammenarbeit:

  1. Um Ihr Datenangebot zu registrieren, rufen Sie REGISTRY.REGISTER_DATA_OFFERING auf. Sie müssen Spaltennamen angeben.

  2. Rufen Sie COLLABORATION.LINK_LOCAL_DATA_OFFERING auf.

    Nur Sie können Ihr Angebot sehen, wenn Sie COLLABORATION.VIEW_DATA_OFFERINGS aufrufen. Für andere Teilnehmende wird Ihre Datenquelle nicht aufgelistet.

  3. Verwenden Sie die ID des Datenangebots, wenn Sie COLLABORATION.RUN aufrufen, entweder im Parameter local_template_view_names oder im Feld local_view_mappings.my_tables, wenn Sie eine Analyse-YAML übergeben. local_template_view_names und local_view_mappings.my_tables füllen den Parameter my_table in der Vorlage aus.

Das folgende Beispiel zeigt, wie Sie eine Vorlage unter Verwendung der Ausführungsprozedurversion mit dem YAML-Format ausführen. Dieses Beispiel schließt das Feld my_tables ein, das durch Aufrufen von LINK_LOCAL_DATA_OFFERING ausgefüllt wird.

-- See what data offerings are available. Your own local data will be listed here as well.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_DATA_OFFERINGS($collaboration_name);

-- Pass in the arguments in analysis YAML format.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.RUN(
  $collaboration_name,
  $$
    api_version: 2.0.0
    spec_type: analysis
    name: my_analysis
    description: Cross-purchase results for Q4 2025
    template: mytemplate_v1

    template_configuration:
      view_mappings:
        source_tables:
          - ADVERTISER1.ADVERTISER_DATA_V1.CUSTOMERS
          - PUBLISHER.ADVERTISER_DATA_V1.CUSTOMERS
      local_view_mappings:
        my_tables:
          - PARTNER.MY_DATA_V1.MY_CUSTOMERS # Populate my_table array with my own table.
      arguments:  # Template arguments, as name: value pairs
         conv_purchase_id: PURCHASE_ID
         conv_purchase_amount: PURCHASE_AMOUNT
         publisher_impression_id: IMPRESSION_ID
         publisher_campaign_name: CAMPAIGN_NAME
         publisher_device_type: DEVICE_TYPE
  $$ );

Abfrageergebnisse aktivieren

Bemerkung

Wenn Sie die Rolle SAMOOHA_APP_ROLE nicht verwenden, d. h. Sie verwenden eine Rolle, die von Zugriffsverwaltungsverfahren verwaltet wird, müssen Sie über die Berechtigung REGISTER DATA OFFERING verfügen, um einer Zusammenarbeit beizutreten, bei der Sie Analyseausführender sind, und bei der die Zusammenarbeitsspezifikation das Feld activation_destinations beinhaltet.

So aktivieren Sie die Ergebnisse einer Abfrage:

  1. Stellen Sie sicher, dass für alle Aktivierungsspalten die folgenden Eigenschaften in der entsprechenden Spezifikation festgelegt sind:

    Die Datenangebotsspezifikation für die Tabelle mit der aktivierten Spalte muss activation_allowed: TRUE für diese Spalte festlegen:

     api_version: 2.0.0
 spec_type: data_offering
 name: 2025_orders
 version: 2025_01_01_v1
 description: Activating Cleveland sales results for 2025

 datasets:
  - alias: customers
    data_object_fqn: db1.schema1.orders
    allowed_analyses: template_only
    object_class: custom
    schema_and_template_policies:
      email:
        category: join_standard
        column_type: hashed_email_sha256
        activation_allowed: TRUE
      purchase_amount:
        category: passthrough
        activation_allowed: TRUE

    Bemerkung

    Für jede Spalte, die in der Vorlage mit angewendetem activation_policy-Filter verwendet wird, muss der activation_allowed-Wert in der Datenangebotsspezifikation auf TRUE festgelegt sein. Das folgende Beispiel zeigt eine Vorlage, bei der die Aktivierungsrichtlinie auf zwei Spalten angewendet wird, die vom Analyseausführenden bereitgestellt werden:

    BEGIN
  CREATE OR REPLACE TABLE cleanroom.activation_data_analysis_results AS
    SELECT count(*) AS ITEM_COUNT, c.status, c.age_band
    FROM IDENTIFIER({{ my_table[0] }}) AS c
    JOIN IDENTIFIER({{ source_table[0] }}) AS p
    ON {{ c_join_col | sqlsafe | activation_policy }} = {{ p_join_col | sqlsafe | activation_policy }}
    GROUP BY c.status, c.age_band
    ORDER BY c.age_band;
  RETURN 'analysis_results';
END;

  2. Der Analyseausführende ruft RUN auf, um die Analyse auszuführen.

    • Wenn Sie die Aktivierung für sich selbst vornehmen, sind die Ergebnisse sofort im Konto des Aufrufenden in der Tabelle consumers_database.ACTIVATION_RESULTS.CONSUMER_DIRECT_ACTIVATION_SUMMARY verfügbar. Wie Sie die Abfrageergebnisse anzeigen können, erfahren Sie im letzten Schritt.

    • Bei Aktivierung für einen anderen Teilnehmenden:

      1. Der Teilnehmende ruft VIEW_ACTIVATIONS auf, bis der Status SHARED zurückgegeben wird. Die Aktivierung für ein anderes Konto kann bei großen Resultsets einige Zeit in Anspruch nehmen, da die Daten an das Konto des Teilnehmenden übertragen und entschlüsselt werden müssen.

      2. Wenn der Status der Aktivierung SHARED lautet, ruft der Teilnehmende PROCESS_ACTIVATION auf, um die Ergebnisse an sein Konto zu senden. Die Antwort auf PROCESS_ACTIVATION schließt die Tabellen- und Segmentnamen mit ein. Hierdurch wird der Aktivierungsstatus auf PROCESSED festgelegt.

  3. Um Abfrageergebnisse abzurufen, führen Sie den folgenden SQL-Befehl aus, und geben Sie den Namen Ihrer Ergebnistabelle und optional einen Segmentnamen zum Filtern der Ergebnisse an:

    SELECT *
  FROM <results_table_name>
    [WHERE segment = <segment_name>];

Zusammenarbeit verlassen oder löschen

  • Nicht-Eigentümer verlassen eine Zusammenarbeit, indem sie COLLABORATION.LEAVE aufrufen. Alle von ihnen bereitgestellten Datenangebote werden aus der Zusammenarbeit entfernt. Sie können einer Zusammenarbeit nicht wieder beitreten, nachdem Sie sie verlassen haben.

  • Zusammenarbeitseigentümer können eine Zusammenarbeit nicht verlassen. Die Eigentümerschaft kann nicht übertragen werden. Ein Eigentümer einer Zusammenarbeit kann eine Zusammenarbeit für alle Teilnehmenden löschen, indem er COLLABORATION.TEARDOWN aufruft.

Beide Prozesse sind asynchron. Sie müssen GET_STATUS aufrufen, um den Status zu überwachen, und LEAVE oder TEARDOWN erneut aufrufen, wenn GET_STATUS den Status als LOCAL_DROP_PENDING anzeigt.

Cloud-übergreifende automatische Ausführung aktivieren

Wenn Sie sich nicht in der gleichen Cloud-Host-Region befinden wie der Eigentümer der Zusammenarbeit, muss die Cloud-übergreifende automatische Ausführung (LAF) für Ihr Konto aktiviert sein, damit Sie der Zusammenarbeit beitreten können. Wenn Sie versuchen, eine Zusammenarbeit in einer anderen Cloud-Region zu überprüfen und LAF nicht für Ihr Konto aktiviert ist oder Sie nicht über die richtigen Berechtigungen verfügen, erhalten Sie beim Aufruf von REVIEW für die Zusammenarbeit eine Fehlermeldung.

Bemerkung

Wenn die Cloud-übergreifende automatische Ausführung in einer Zusammenarbeit verwendet wird:

  • Die Daten werden im Konto jedes Teilnehmenden repliziert, der auf diese Daten zugreifen kann.

  • Die Daten werden auch in die Region des Eigentümers repliziert, unabhängig davon, ob dieser auf das Datenangebot zugreifen kann oder nicht. Dessen Möglichkeit, auf die Daten zuzugreifen, wird jedoch durch die Freigaberegeln des Datenangebots bestimmt.

Sie können Ihre Cloud-Hosting-Region ermitteln, indem Sie SELECT CURRENT_REGION(); ausführen.

So aktivieren Sie die Cloud-übergreifende automatische Ausführung für Ihr Konto:

  1. Ein Organisationsadministrator muss LAF für Ihr Konto aktivieren, indem er SYSTEM$ENABLE_GLOBAL_DATA_SHARING_FOR_ACCOUNT aufruft. Weitere Informationen dazu finden Sie unter Berechtigungen für automatische Ausführung verwalten.

  2. Damit Sie die richtigen Berechtigungen zum Ansehen einer LAF-Zusammenarbeit haben oder um ihr beitreten zu können, verwenden Sie die SAMOOHA_APP_ROLE oder eine Rolle, die über die Berechtigung MANAGE LISTING AUTO FULFILLMENT auf Kontoebene verfügt.

Teilnehmende, die sich in einer anderen Cloud-Hosting-Region befinden, erfahren zusätzliche Datenverzögerung aufgrund der Replikationshäufigkeit. Die Replikationshäufigkeit ist in einem Collaboration Data Clean Room noch nicht konfigurierbar.

Beispiel: Zusammenarbeit zwischen zwei Parteien

Das folgende Beispiel zeigt eine Zusammenarbeit mit zwei Parteien, wobei eine Partei (namens „alice“) die Erstellende der Zusammenarbeit, ein Datenanbieter für sich selbst und „bob“ sowie eine Analyseausführende ist. Die andere Partei (mit dem Namen „bob“) ist ein Datenanbieter für sich selbst und „alice“ sowie ein Analyseausführender.

Das Beispiel veranschaulicht die folgenden Aktionen:

  • Erstellen einer Zusammenarbeit

  • Registrieren von Vorlagen und Datenangeboten

  • Hinzufügen einer Vorlage und eines Datenangebots zum Zeitpunkt der Erstellung der Zusammenarbeit

  • Beitreten zu einer Zusammenarbeit

  • Hinzufügen von Vorlagen und Ressourcen zu einer vorhandenen Zusammenarbeit

  • Ausführen einer Analyse

Um dieses Beispiel auszuführen, müssen Sie über zwei separate Konten mit installierten Snowflake Data Clean Rooms verfügen.

Sie können die Dateien entweder herunterladen und in Ihr Snowflake-Konto hochladen oder den Beispielcode kopieren und in die Arbeitsblätter von zwei separaten Konten einfügen, indem Sie die Snowsight verwenden.

Laden Sie die SQL-Quelldateien herunter, und laden Sie diese dann in zwei separate Konten hoch, für die Snowflake Data Clean Rooms installiert sind: