Kundenspezifische Vorlagen zu einem Clean Room hinzufügen

Both providers and consumers can add custom templates to a clean room. Custom templates are run the same way as Snowflake-provided templates. Custom templates are created using the API, and are run using the API or (if designed for it) the UI.

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.

The following SQL example shows how a provider adds a simple custom template to a clean room:

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

Diese Vorlage benötigt vier erforderliche Parameter (my_table-Array, source_table-Array, consumer_id-Spaltenname und provider_id-Spaltenname) und einen optionalen where_clause-Parameter, der eine WHERE-Klausel angibt.

In most templates, including the previous example, column names provided by the user must be fully qualified with the table name to avoid column name conflicts. This is because it is not easy to concatenate a table name prefix to a column name in the prefix and get a valid identifier (IDENTIFIER(p.{{ col_name | sqlsafe }}) is an error). Therefore, you might need the caller to provide a fully qualified table name rather than just a column name. Table names should use the approved lowercases p and c aliases.

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.

You can call consumer.get_arguments_from_template to parse and list the variables used in a template. However, for large or complex templates this procedure might not list all template variables, so be sure to provide helpful documentation for your template users.

The following example shows how a consumer runs the provider’s custom template shown previously:

 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',  -- Populates the consumer_id variable.
  'provider_id', 'p.hashed_email',  -- Populates the provider_id variable.
  'where_clause','c.status = $$MEMBER$$ AND c.age_band > 30' -- Populates the where_clause variable.
                                                             -- $$...$$ 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. The provider can approve (provider.approve_template_request) or reject (provider.reject_template_request) the consumer’s request to run their own template. (There are also bulk versions of these methods for approving or rejecting multiple requests.) If the provider approves the template, the template is added to the clean room immediately.

    • Bevor der Anbieter die Vorlage genehmigt, sollte der Anbieter zunächst alle erforderlichen Verknüpfungs- und Spaltenrichtlinien für seine Daten deklarieren.

  6. The consumer checks the status of their request by calling either consumer.list_template_requests (which shows the approval status) or consumer.view_added_templates (to see if their template was added to the clean room). A template is added to the clean room only after the provider approves it.

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

Here is a full code example showing how a consumer can submit and run a custom template. Upload the following worksheet files into your Snowflake account. You need two separate accounts with the clean rooms API installed to run the code; one account to act as the provider and the other to act as the consumer.

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.

  • Template changes made in the API propagate quickly and reliably to the UI, so you don’t need to create a new clean room for template changes. However, you should develop and test your template in the API before you reach the UI stage.

  • 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