Kundenspezifische Vorlagen zu einem Clean Room hinzufügen

Sowohl Anbieter als auch Verbraucher können kundenspezifische Vorlagen zu einem Clean Room hinzufügen. Kundenspezifische Vorlagen werden auf die gleiche Weise ausgeführt wie die von Snowflake bereitgestellten Vorlagen.

Bemerkung

Eine Clean Room-Vorlage ist eine gültige JinjaSQL-Vorlage. Sie sollten das Clean Room-Referenzhandbuch für kundenspezifische Vorlagen lesen, bevor Sie versuchen, Ihre eigenen Clean Room-Vorlagen zu erstellen.

Vom Anbieter geschriebene kundenspezifische Vorlagen

Anbieter können eine kundenspezifische Vorlage zu einem Clean Room hinzufügen, ohne dass die Genehmigung des Verbrauchers erforderlich ist. Verbraucher können eine vom Anbieter geschriebene Vorlage ohne Genehmigung ausführen. Die nächsten Abschnitte beschreiben, wie ein Anbieter eine kundenspezifische Vorlage hinzufügen und ein Verbraucher diese Vorlage mithilfe der API ausführen kann.

Wenn der Anbieter eine Vorlage entwerfen möchte, die ein Verbraucher in der Clean Rooms UI ausführen kann, müssen sie ein Benutzereingabeformular für die Vorlage erstellen.

Vom Anbieter geschriebene Vorlage hinzufügen

Anbieter fügen kundenspezifische Vorlagen nacheinander hinzu, indem sie provider.add_custom_sql_template aufrufen und die Vorlage JinjaSQL als Zeichenfolge übergeben. Kundenspezifische Vorlagen werden in der Vorlagenliste des Clean Rooms angezeigt und verhalten sich genauso wie von Snowflake bereitgestellte Vorlagen. Ein Clean Room kann eine beliebige Mischung aus kundenspezifischen und von Snowflake bereitgestellten Vorlagen enthalten.

Sie können auch kundenspezifische Python-UDFs hochladen, die von Ihrer Vorlage aufgerufen werden.

Tipp

Wenn Sie eine kundenspezifische Vorlage für die Verbraucher hinzufügen, sollten Sie eine Dokumentation bereitstellen, in der beschrieben wird, wie die Vorlage agiert und welche erforderlichen und optionalen Argumente von der Vorlage verwendet werden.

Das folgende Beispiel zeigt, wie ein Anbieter eine kundenspezifische Vorlage zu einem Clean Room hinzufügt:

CALL samooha_by_snowflake_local_db.provider.add_custom_sql_template(
    $cleanroom_name,
    $basic_template_name,
    $$
    SELECT
      COUNT(*) AS total_count
    FROM IDENTIFIER({{ my_table[0] }}) AS c
      INNER JOIN IDENTIFIER({{ source_table[0] }}) AS p
      ON IDENTIFIER({{ consumer_id | join_policy }}) = IDENTIFIER({{ provider_id | join_policy }})
    {% if where_clause %}
    WHERE {{ where_clause | sqlsafe }}
    {% endif %};
  $$
);
Copy

In den meisten Vorlagen, einschließlich des vorherigen Beispiels, müssen die Spaltennamen vollständig mit dem Tabellennamen qualifiziert werden, um Konflikte mit Spaltennamen zu vermeiden. Das liegt daran, dass es nicht einfach ist, ein Tabellennamenpräfix mit einem Spaltennamen im Präfix zu verbinden und einen gültigen Bezeichner zu erhalten (IDENTIFIER(p.{{col_name | sqlsafe }}) ist ein Fehler). Daher muss der Aufrufer möglicherweise einen vollqualifizierten Tabellennamen und nicht nur einen Spaltennamen angeben. Tabellennamen sollten die genehmigten Aliasse p und c verwenden.

Vom Anbieter geschriebene Vorlage ausführen

Bei Verwendung der Clean Rooms API rufen Verbraucher consumer.run_analysis auf, um eine Vorlage auszuführen, und Anbieter rufen provider.submit_analysis_request für vom Anbieter durchgeführte Analysen auf.

Wenn Sie möchten, dass eine Vorlage in der Clean Rooms-UI ausgeführt werden kann, muss der Anbieter ein Benutzereingabeformular für die Vorlage erstellen. In den der Clean Rooms-UI können nur vom Anbieter geschriebene Vorlagen ausgeführt werden.

Clean Room-Teilnehmer können JinjaSQL für jede Vorlage in einem Clean Room sehen, indem Sie consumer.view_template_definition aufrufen, es sei denn, der Anbieter hat die Vorlage verborgen. Nur vom Anbieter geschriebene Vorlagen können verborgen werden.

Sie können consumer.get_arguments_from_template aufrufen, um die in einer Vorlage verwendeten Variablen zu analysieren und aufzulisten. Bei großen oder komplexen Vorlagen listet dieser Prozess jedoch möglicherweise nicht alle Vorlagenvariablen auf. Stellen Sie daher sicher, dass Sie eine hilfreiche Dokumentation für die Benutzer Ihrer Vorlagen bereitstellen.

Das folgende Beispiel zeigt, wie ein Verbraucher die zuvor gezeigte kundenspezifische Vorlage des Anbieters ausführt:

 CALL samooha_by_snowflake_local_db.consumer.run_analysis(
  $cleanroom_name,
  'basic_template',
  ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],  -- Populates the my_table array.
  ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],  -- Populates the source_table array.
  OBJECT_CONSTRUCT(
  'consumer_id', 'c.hashed_email',  -- hashed_email column from the consumer's table.
  'provider_id', 'p.hashed_email',  -- hashed_email column from the provider's table.
  'where_clause','c.status = $$MEMBER$$ AND c.age_band > 30' -- $$...$$ is used to stringify the column value.
  )
);
Copy

Beispielcode für Anbietervorlage

Hier ist ein vollständiges Codebeispiel, das zeigt, wie ein Anbieter eine kundenspezifische Vorlage hinzufügt und wie der Verbraucher sie ausführt. Sie benötigen zwei separate Konten mit einer installierten Clean Rooms-API, um den Code auszuführen; ein Konto fungiert als Anbieter und das andere Konto als Verbraucher.

Von Verbrauchern geschriebene kundenspezifische Vorlagen

Ein Verbraucher kann dem Clean Room eine kundenspezifische Vorlage hinzufügen, wenn der Anbieter zustimmt. Sobald sie dem Clean Room hinzugefügt wurden, kann die vom Verbraucher geschriebene Vorlage genauso ausgeführt werden wie eine vom Anbieter geschriebene Vorlage. So fügt ein Verbraucher eine kundenspezifische Vorlage hinzu:

  1. Der Anbieter erstellt, teilt und veröffentlicht einen Clean Room auf die standardmäßige Weise.

  2. Der Verbraucher installiert und konfiguriert den Clean Room auf die standardmäßige Weise.

  3. Der Verbraucher ruft consumer.create_template_request auf und übergibt die kundenspezifische Zeichenfolge der Vorlage.

  4. Der Anbieter ruft provider.list_pending_template_requests auf, um ausstehende Anfragen anzuzeigen.

  5. Der Anbieter kann die Anfrage des Verbrauchers, seine eigene Vorlage zu erstellen, genehmigen (provider.approve_template_request) oder ablehnen (provider.reject_template_request). (Es gibt auch Massenversionen dieser Methoden, um mehrere Anfragen zu genehmigen oder abzulehnen.) Wenn der Anbieter zustimmt, wird die Vorlage sofort in den Clean Room aufgenommen.

    • Wenn der Anbieter die Vorlage genehmigt, sollte er alle erforderlichen Verknüpfungs- und Spaltenrichtlinien für diese Vorlage und deren Daten hinzufügen. Wenn der Anbieter keine Verknüpfungs- oder Spaltenrichtlinie im Clean Room hat, ist die Standardeinstellung, dass alle Spalten des Anbieters verknüpf- und projiziert werden können.

  6. Der Verbraucher überprüft den Status seiner Anfrage, indem er entweder consumer.list_template_requests (zeigt den Status, einschließlich des Ablehnungsstatus mit einer Erklärung) oder consumer.view_added_templates (um zu sehen, ob ihre Vorlage zum Clean Room hinzugefügt wurde) aufruft.

  7. Der Verbraucher fügt optional Spaltenrichtlinien für die Vorlage hinzu.

  8. Der Verbraucher führt die Vorlage aus, indem er consumer.run_analysis mit der Standardmethode aufruft.

Bemerkung

Ein Anbieter kann eine von einem Verbraucher hinzugefügte Vorlage ausführen, wenn der Verbraucher die Berechtigung erteilt.

Beispiel für eine Verbrauchervorlage

Hier ist ein vollständiges Codebeispiel, das zeigt, wie ein Verbraucher eine kundenspezifische Vorlage übermitteln und ausführen kann. Laden Sie die folgenden Arbeitsmappendateien in Ihr Snowflake-Konto hoch. Sie benötigen zwei separate Konten mit installierter Clean Rooms-API, um den Code auszuführen; ein Konto fungiert als Anbieter und das andere als Verbraucher.

Definieren Sie ein Benutzereingabeformular für eine kundenspezifische Vorlage

Damit eine kundenspezifische Vorlage in der Clean Rooms-UI ausgeführt werden kann, muss der Anbieter ein Eingabeformular für die Vorlage definieren. Diese Anforderung gilt auch dann, wenn die Vorlage keine Argumente enthält, die der Verbraucher einstellen kann. Verbraucher können für eine Vorlage kein Benutzereingabeformular definieren.

Wichtig

Wenn Sie provider.restrict_table_options_to_consumers oder provider.restrict_template_options_to_consumers verwendet haben, um Tabellen oder Vorlagen auf bestimmte Benutzer zu beschränken, funktionieren diese Einschränkungen in der Clean Rooms-UI nicht wie erwartet. Sie sollten keine Vorlagen für die UI-Nutzung in Clean Rooms mit diesen Einschränkungen aktivieren.

Ein Konfigurationsformular ermöglicht es Benutzern in der Clean Rooms-UI, Werte an die kundenspezifische Vorlage zu übergeben, ähnlich wie Sie bei Verwendung der API Werte übergeben.

Das folgende Beispiel zeigt eine kundenspezifische Vorlage, die drei Variablen verwendet: max_age, favorite_color``und ``source_table:

CALL samooha_by_snowflake_local_db.provider.add_custom_sql_template(
  $cleanroom_name,
  'color_picker_template',
  $$
  SELECT p.hashed_email
    FROM source_table[0] AS p
    WHERE
      p.age <= {{ max_age }} AND
      UPPER(p.favorite_color) = UPPER({{ favorite_color }});
  $$);
Copy

Das folgende Beispiel zeigt, wie Sie die Variablen der Vorlage übergeben, wenn Sie die vorherige kundenspezifische Vorlage im Code ausführen:

CALL samooha_by_snowflake_local_db.consumer.run_analysis(
  $cleanroom_name,
  'color_picker_template',
  [],                                   -- Consumer tables, assigned to my_table array.
  ['MYDB.MYSCH.COLOR_PREFERENCES'],     -- Provider tables, assigned to source_table array.
  object_construct(
    'max_age', 30,                      -- Assign max_age.
    'favorite_color', 'blue'            -- Assign favorite_color.
  )
);
Copy

So führen Sie diese Vorlage in der Clean Rooms-UI aus. Sie müssen ein Formular definieren, dem der Verbraucher diese Vorlagenvariablen zuweist. Das folgende Beispiel zeigt, wie Sie ein einfaches Formular definieren, dem der Verbraucher Werte zuweisen kann max_age, favorite_color``und ``source_table:

CALL samooha_by_snowflake_local_db.provider.add_ui_form_customizations(
    $cleanroom_name,
    'color_picker_template',
    {                                     -- Top-level template settings.
      'display_name': 'Color matcher',
      'description': 'See which users like the same color as you',
      'methodology': 'Choose a color and a max age',
      'render_table_dropdowns': {
        'render_consumer_table_dropdown': false,
        'render_provider_table_dropdown': true    -- Show a dropdown of provider tables.
      }                                           -- Chosen value is assigned to source_table.
    },
    { -- Form entry elements, one per template argument.
      'max_age': {
        'type': 'integer',
        'display_name': 'Maximum age',
        'description': 'Matching user must be less than or equal to this value.',
        'required': TRUE
      },
      'favorite_color': {
        'type': 'dropdown',
        'display_name': 'Favorite color',
        'description': 'Choose the favorite color to match.',
        'choices': ['Red', 'Blue', 'Green', 'Yellow'],
        'required': TRUE
      }
    },
    {} -- Output config not used in this example.
);

-- You must always call this procedure to propagate UI changes.
CALL samooha_by_snowflake_local_db.provider.create_or_update_cleanroom_listing(
  $cleanroom_name);
Copy

Das zuvor definierte Formular wird in der Clean Rooms-UI angezeigt, wenn der Verbraucher die Vorlage im Schritt:ui:Configure Analysis & Query ausführt. Das Formular enthält eine Tabellenauswahl für source_table, beschriftet mit Collaborator table, ein Ganzzahl-Auswahlelement für max_age beschriftet mit Maximum age`und ein Dropdown-Menü mit Farbnamen für ``favorite_color` beschriftet mit Favorite color, wie in dieser Abbildung gezeigt:

Rendern des Benutzereingabeformulars mit Tabellen-, Alters- und Farbauswahl.

Sie können auch Dropdown-Menüs definieren, die bereits mit Spalten aus den Verknüpfungsrichtlinien des Anbieters oder Verbrauchers, Spaltenrichtlinien, Tabellen und mehr gefüllt sind. Weitere Informationen zu Formularelementtypen finden Sie unter add_ui_form_customizations.

source_table und my_table ausfüllen

Die Standardvariable source_table und die Vorlagenvariable my_table können wie folgt gefüllt werden:

  • Aktivieren Sie die Standard-Dropdown-Menüs für die Tabellenauswahl: Diese Dropdown-Menüs sind Einzelauswahl-Menüs. Sie können sie mit den Einstellungen render_provider_table_dropdown und render_consumer_table_dropdown``ein- oder ausblenden. Die Dropdown-Menüs übergeben vollqualifizierte Tabellennamen an die Vorlagenvariablen ``source_table und my_table.

Spaltennamen qualifizieren

Bei den meisten Vorlagen müssen alle Spaltennamen vollqualifiziert sein, um eine Mehrdeutigkeit der Spaltennamen zu vermeiden.

Die Vorlage muss für alle Tabellen den Alias p oder c verwenden, je nachdem, ob es sich um Anbieter- oder Verbrauchertabellen handelt. Die Vorlage sollte alle Spalten mit den Aliassen p oder c angeben. Erfahren Sie mehr über Aliasing.

Wenn Sie einen Dropdown-Spaltenselektor erstellen, müssen Sie entweder den Tabellenalias p oder c explizit in einem choices-Array des Dropdown-Menüs angeben, oder Sie müssen den Alias zu Ihrer Vorlage hinzufügen.

Das folgende Beispiel zeigt, wie Sie den Tabellenalias in einem Dropdown-Menü angeben:

  'provider_join_col': {
    'display_name': 'Provider Join Column',
    'choices': ['p.HASHED_EMAIL', 'p.HASHED_SSN'],
    'type': 'dropdown',
    'description': 'Select the provider column to join users on.',
    'infoMessage': 'We recommend using HASHED_EMAIL.',
    'size': 'M',
    'group': 'Enable Provider Features'
}
Copy

Diese Methode ist jedoch einschränkend, da Sie alle Spaltennamen im Voraus kennen müssen.

Alternativ können Sie ein Dropdown-Menü für Spalten dynamisch füllen, indem Sie eine references-Eigenschaft angeben. Ein solcher Selektor gibt jedoch leere Spaltennamen zurück – zum Beispiel hashed_email – anstelle von vollqualifizierten Spaltennamen – zum Beispiel p.hasht_email. Wenn leere Spaltennamen zurückgegeben werden, müssen Sie die Spalte in Ihrer Vorlage explizit auf die Tabelle beschränken. Der folgende Code erstellt zum Beispiel ein Dropdown-Menü, in dem ein Benutzer eine Spalte aus der Verknüpfungsrichtlinie des Anbieters auswählen kann:

'p_join_col': {
  'type': 'dropdown',
  'references': ['PROVIDER_JOIN_POLICY']
}
Copy

Um den Spaltennamen in einer Vorlage zu verwenden, muss die Vorlage den Tabellenalias vor dem Spaltennamen fest kodieren, wie im folgenden Beispiel gezeigt:

SELECT p.{{ p_join_col | sqlsafe }} FROM table_col AS p;
Copy

Empfehlungen für die Entwicklung einer Vorlage, die in der Clean Rooms-UI ausgeführt werden kann

Die folgenden Schritte zeigen einen empfohlenen Workflow für die Entwicklung einer Vorlage, die in der Clean Rooms-UI ausgeführt werden kann:

1. Entwickeln der Vorlage

Entwickeln Sie zunächst Ihre -Vorlage und ggf Skripte, die es aufruft, indem nur die Clean Rooms-API sowohl in Anbieter- als auch in Verbraucherkonten verwendet wird. Das Testen der Vorlage in der API ist viel schneller und weniger fehleranfällig als die Verwendung der UI.

Testen Sie Ihre Vorlage gründlich in der API sowohl auf Anbieter- als auch auf Verbraucherseite, um sicherzustellen, dass die Vorlage genau das tut, was sie tun soll. Das Testen über die API ist sehr schnell, und Änderungen werden sofort an das Konto des Verbrauchers weitergegeben.

Nachdem Sie Ihre Vorlage getestet haben und sie genau so ausgeführt wurde, wie Sie es möchten, können Sie mit dem Entwerfen des Eingabeformulars fortfahren.

2. Entwickeln des Eingabeformulars

Wenn die Vorlage und alle hochgeladenen Skripte wie vorgesehen funktionieren, dann beginnen Sie mit der Arbeit am Eingabeformular. In dieser Phase verwenden Sie die API im Anbieterkonto, aber die UI im Verbraucherkonto.

Wenn Sie Änderungen mit der API vornehmen, werden einige Werte in der UI sofort aktualisiert, einige werden aktualisiert, wenn der Benutzer auf Refresh klickt. Einige werden nur alle 10 Minuten aktualisiert. Wenn Sie also am Eingabeformular arbeiten, erstellen und aktualisieren Sie das Formular auf der Anbieterseite mit der API. Den Clean Room installieren und konfigurieren Sie im Verbraucherkonto unter Verwendung der Clean Rooms-UI, nicht der API. Dadurch wird sichergestellt, dass Sie aktuelle Daten in der Clean Room-UI verwenden.

Jedes Mal, wenn Sie Änderungen am Eingabeformular in der API vornehmen, erstellen Sie einen neuen Clean Room, um sicherzustellen, dass Sie die neuesten Clean Room-Daten verwenden. Verwenden Sie im Namen eine aufsteigende Zahl. zum Beispiel „Mein Clean Room 1“, „Mein Clean Room 2“ und so weiter. Installieren Sie dann den Clean Room im Client, indem Sie die UI verwenden. Löschen Sie schließlich die alten Clean Rooms, da die Anzahl der Clean Rooms, die ein Konto enthalten kann, begrenzt ist.

Ein Eingabeformular muss an eine Vorlage angehängt werden, da sonst der Clean Room und das Formular in der Clean Rooms-UI nicht ausführen kann. Wenn Sie Ihr Formular entwickeln, sollten Sie eine Vorlage verwenden, die einfach alle im Formular ausgewählten Werte spiegelt, sodass Sie überprüfen können, welche Werte an die Vorlage gesendet werden.

Nehmen wir zum Beispiel an, dass Ihre Produktionsvorlage wie die folgende Vorlage aussieht:

SELECT {{ col1 | sqlsafe | column_policy }}, {{ col2 | sqlsafe | column_policy }}
  FROM IDENTIFIER({{ source_table[0] }}) AS p
  JOIN IDENTIFIER({{ my_table[0] }}) AS c
Copy

Sie könnten die folgende Vorlage erstellen, die alle Werte dieser Produktionsvorlage widerspiegelt:

SELECT
  {{ col1 | default('Undefined')}},
  {{ col2 | default('Undefined') }},
  {{ source_table[0] | default('Undefined') }},
  {{ my_table[0] | default('Undefined') }},
  {{ provider_join_col | default('Undefined') }},
  {{ consumer_join_col | default('Undefined') }}
;
Copy

Entwerfen Sie dann ein Formular, das diese sechs Variablenwerte festlegt, und hängen Sie das Formular an die Spiegelvorlage und nicht an die Produktionsvorlage an.

Allgemeine Tipps zur Entwicklung des Eingabeformulars

Die folgende Liste enthält detaillierte Tipps, die Ihnen bei der Entwicklung eines effektiven Eingabeformulars helfen:

  • Wenn Sie bei der Installation, Konfiguration oder Ausführung eines Clean Rooms in der UI die allgemeine Meldung „Installation fehlgeschlagen“ oder „Es ist ein Fehler aufgetreten“ sehen, könnte die Meldung bedeuten, dass ein Fehler im UI-Formular oder einer zugehörigen Vorlage vorliegt, der nicht erfasst wurde, als Sie das Formular oder die Vorlage hinzugefügt haben.

  • Wenn ein Feld von einem anderen Feld abhängt – z. B. bei einem Dropdown-Menü für eine Spalte, das auf dem von einem Dropdown-Menü für eine Tabelle ausgewählten Wert basiert –, setzen Sie das übergeordnete Feld an die erste Stelle, möglicherweise direkt über dem untergeordneten Feld, damit Benutzer das übergeordnete Feld vor dem untergeordneten Feld ausfüllen. Bei abhängigen Feldern ist das Dropdown-Menü untergeordneter Felder leer, bis ein Wert für das übergeordnete Feld ausgewählt wurde.

  • Wenn Sie keinen order- oder group-Wert angeben, werden die Elemente in der Reihenfolge gerendert, in der sie definiert sind.

  • Fügen Sie informativen``infoMessage``- und description-Text hinzu und zeigen Sie Beispielwerte an, die ein Benutzer eingeben könnte.

  • Wählen Sie den genauen Elementtyp für den Variablen-Datentyp aus. Wählen Sie für eine Ganzzahl beispielsweise integer anstelle eines Freiform-Textfeldes aus. Ihre Vorlage kann Werte mithilfe von Jinja-Filtern umwandeln. Zum Beispiel: SELECT {{ max_age | int }};.

  • Wenn Sie nicht eine minimale Konfigurationsform für eine kundenspezifische Vorlage definieren, kann die Vorlage nicht in der Clean Room-UI ausgeführt werden.

  • Wenn Sie in der Vorlage kein Formularelement für eine Variable definieren, wird im Benutzerformular ein einfaches Textfeld für diese Variable gerendert. Dies ist wahrscheinlich nicht das, was Sie wollen, da das Textfeld mit dem Namen der Vorlagenvariable beschriftet ist und keine Beschreibung oder Vorschläge enthält.

  • Formularelemente, die in``add_ui_form_customizations`` angegeben sind, werden nicht gerendert, es sei denn, es gibt eine passende Vorlagenvariable mit demselben Namen wie das Element.

  • Änderungen an der Vorlage in der API werden schnell und zuverlässig an die UI weitergegeben, sodass Sie keinen neuen Clean Room für Änderungen an Vorlagen erstellen müssen. Sie sollten Ihre Vorlage jedoch in der API :emph: testen, bevor Sie den UI-Stagingbereich erreichen.

  • Sie können ein Dropdown-Menü nicht automatisch mit Spaltenwerten aus einer bestimmten Tabelle füllen. Sie können Werte in einem Dropdown-Menü fest codieren, aber Sie können zur Laufzeit keine Werte aus einer Tabelle anzeigen.

3. Verbinden des Eingabeformulars mit der Produktionsvorlage

Nachdem das Formular genau so aussieht, wie Sie es möchten, und das Formular alle Variablen der Vorlage für den Benutzer zugänglich macht, weisen Sie Ihre Arbeitsvorlage dem Eingabeformular zu, indem Sie provider.add_ui_form_customizations aufrufen.

Sprache: Deutsch