Benutzerdefinierte Clean Room-Vorlagen erstellen¶

Über Clean Room-Vorlagen¶

Clean Room-Vorlagen werden in JinjaSQL geschrieben. JinjaSQL ist eine Erweiterung der Jinja-Vorlagensprache, die eine SQL-Abfrage als Ausgabe erzeugt. JinjaSQL unterstützt logische Anweisungen und die Auflösung von Laufzeitvariablen, damit der Benutzer die Abfrage während der Laufzeit anpassen kann. Variablen werden in der Regel in einer Vorlage verwendet, damit ein Benutzer Tabellennamen, Tabellenspalten und benutzerdefinierte Werte für seine Abfrage angeben kann.

Snowflake bietet eine Auswahl an vorgefertigten Vorlagen für gängige Anwendungsfälle. Diese Standardvorlagen können nur in der Webanwendung verwendet werden. Sowohl Anbieter als auch Verbraucher können jedoch benutzerdefinierte Vorlagen für einen Clean Room erstellen. Benutzerdefinierte Vorlagen können nur im Code erstellt werden, können aber entweder im Code oder über die Webanwendung ausgeführt werden.

Es gibt zwei allgemeine Vorlagentypen:

• Analysevorlagen, die eine SELECT-Anweisung (oder eine Reihe von SELECT-Operationen) ergeben.

• Aktivierungsvorlagen, die eine SELECT-Anweisung ergeben, die in einer CREATE TABLE-Anweisung verschachtelt ist, und den Tabellennamen zurückgeben. Diese Vorlage generiert Daten, die in das Snowflake-Konto des Verbrauchers oder Anbieters oder an einen Dritten exportiert werden, je nachdem, wie der Clean Room konfiguriert ist. Eine Aktivierungsvorlage ist einer Analysevorlage sehr ähnlich, mit ein paar zusätzlichen Anforderungen.

In der Clean Room UI kann eine Analysevorlage mit einer Aktivierungsvorlage verknüpft werden, damit der Aufrufer eine Analyse durchführen und anschließend Daten an sich selbst oder einen Dritten senden kann. Die Aktivierungsvorlage muss nicht in dieselbe Abfrage wie die zugehörige Analysevorlage aufgelöst werden.

Benutzerdefinierte Vorlage erstellen und ausführen¶

Bei einem Clean Room mit Standardeinstellungen fügt der Anbieter eine Vorlage zu einem Clean Room hinzu und der Verbraucher kann diese auswählen, konfigurieren und ausführen:

1. Der Anbieter entwirft eine benutzerdefinierte Vorlage und fügt sie durch den Aufruf von provider.add_custom_sql_template zu einem Clean Room hinzu.

2. Der Verbraucher ruft consumer.run_analysis auf, um die Vorlage des Anbieters auszuführen, und übergibt dabei Werte für alle von der Vorlage benötigten Variablen.

Für diesen Ablauf sind keine Genehmigungen der anderen Partei erforderlich, außer dass der Verbraucher vom Anbieter in einen Clean Room eingeladen werden muss. Es gibt verschiedene Varianten dieses Prozesses, z. B. von Verbrauchern bereitgestellte Vorlagen und vom Anbieter ausgeführte Vorlagen, die an anderer Stelle behandelt werden.

SELECT COUNT(*), city FROM consumer_table
  INNER JOIN provider_table
  ON consumer_table.hashed_email = provider_table.hashed_email
  GROUP BY city;

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.CONSUMER.RUN_ANALYSIS(
  $cleanroom_name,
  $template_name,
  ['my_db.my_sch.consumer_table],       -- Populates the my_table variable
  ['my_db.my_sch.provider_table'],      -- Populates the source_table variable
  OBJECT_CONSTRUCT(                     -- Populates custom named variables
    'consumer_join_col','c.age_band',
    'provider_join_col','p.age_band',
    'group_by_col','p.device_type'
  )
);

Syntax einer benutzerdefinierten Vorlage¶

Snowflake Data Clean Rooms unterstützt V3 JinjaSQL, mit einigen Erweiterungen (wie angegeben).

Dieser Abschnitt enthält die folgenden Themen:

• Regeln für die Benennung von Vorlagen

• Vorlagenvariablen

• Erforderliche Tabellen-Aliasse

• Vorlagenfilter

• Benutzerdefinierten Python-Code ausführen

SELECT income FROM my_db.my_sch.customers WHERE income < {{ max_income }};

SELECT col1 FROM IDENTIFIER({{ source_table[0] }}) AS P;

JOIN IDENTIFIER({{ source_table[0] }}) AS p
  ON {{ c_join_col | sqlsafe | join_policy }} = {{ p_join_col | sqlsafe }}

-- Provider uploads a Python function that takes two numbers and returns the sum.
call samooha_by_snowflake_local_db.provider.load_python_into_cleanroom(
  $cleanroom_name,
  'simple_addition',                        -- Function name to use in the template
  ['someval integer', 'added_val integer'], -- Arguments
  [],                                       -- No packages needed
  'integer',                                -- Return type
  'main',                                   -- Handler for function name
  $$

def main(input, added_val):
  return input + int(added_val)
    $$
);

-- Template passes value from each row to the function, along with a
-- caller-supplied argument named 'increment'
call samooha_by_snowflake_local_db.provider.add_custom_sql_template(
    $cleanroom_name,
    'simple_python_example',
$$
    SELECT val, cleanroom.simple_addition(val, {{ increment | sqlsafe }})
    FROM VALUES (5),(8),(12),(39) AS P(val);
$$
);

Sicherheitshinweise¶

Eine Vorlage muss eine einzige SELECT-Abfrage ergeben, die von der nativen Clean Room-Anwendung ausgeführt wird. Die Vorlage wird nicht mit der Identität des aktuellen Benutzers ausgeführt.

Der Benutzer hat keinen direkten Zugriff auf die Daten im Clean Room. Der Zugriff erfolgt ausschließlich über die native Anwendung anhand der Vorlagenergebnisse.

Wenden Sie jedes Mal einen Richtlinienfilter an, wenn eine Spalte in Ihrer Abfrage verwendet wird, auch wenn Sie einen Spaltennamen explizit in der Vorlage definieren oder wenn die Spalte oder Tabelle von Ihnen bereitgestellt wird. Vielleicht ändern Sie später Ihre Verknüpfungs- oder Spaltenrichtlinien oder ändern die Spalte und vergessen, die Vorlage zu aktualisieren. Für alle vom Benutzer angegebenen Spalten sollten Sie einen join_policy-, column_policy-, join_and_column_policy- oder activation_policy-Filter anwenden.

Aktivierungsvorlagen¶

Eine Vorlage kann auch verwendet werden, um Abfrageergebnisse in einer Tabelle außerhalb des Clean Room zu speichern; dies wird Aktivierung genannt. Derzeit werden für benutzerdefinierte Vorlagen nur die Anbieteraktivierung und die Verbraucheraktivierung (Speicherung der Ergebnisse im Snowflake-Konto des Anbieters bzw. Verbrauchers) unterstützt. Erfahren Sie, wie Sie die Aktivierung implementieren.

Eine Aktivierungsvorlage ist eine Analysevorlage mit den folgenden zusätzlichen Anforderungen:

• Aktivierungsvorlagen sind JinjaSQL-Anweisungen, die einen SQL-Skriptblock ergeben, im Gegensatz zu Analysevorlagen, die einfache SELECT-Anweisungen sein können.

• Der Name der Aktivierungsvorlage muss mit der Zeichenfolge activation beginnen (außer bei Anbieteraktivierungsvorlagen, die von Verbrauchern ausgeführt werden). Beispiel: activation_my_template.

• Die Aktivierungsvorlage muss eine Tabelle mit einem Namen erstellen, der von der Art der Aktivierung abhängt, die sie ermöglicht:

  • Vom Anbieter durchgeführte Anbieteraktivierung: Der generierte Tabellenname muss cleanroom.temp_result_data lauten.

  • Alle anderen Aktivierungstypen: Dem generierten Tabellennamen muss das Präfix cleanroom.activation_data_ vorangestellt werden, zum Beispiel: cleanroom.activation_data_cross_activation_results. Der Tabellenname sollte innerhalb Ihres Clean Room eindeutig sein.

  Diese generierte Tabelle ist eine Zwischentabelle; Sie sollten nicht versuchen, direkt auf sie zuzugreifen.

• Der Skriptblock sollte mit der Anweisung RETURN enden, die den Namen der generierten Tabelle abzüglich der Präfixe cleanroom. oder cleanroom.activation_data_ zurückgibt.

• Alle Spalten, die aktiviert werden, müssen in der Aktivierungsrichtlinie des Anbieters oder Verbrauchers, der die Daten verknüpft hat, aufgelistet sein. Zudem sollte der activation_policy-Filter darauf angewendet worden sein. Beachten Sie, dass eine Spalte sowohl eine Aktivierungs- als auch eine Verknüpfungsspalte sein kann.

• Wenn die Vorlage über die Clean Room UI ausgeführt werden soll, sollten Sie ein Webformular bereitstellen, das die Felder activation_template_name und enabled_activations enthält. Vorlagen zur Verwendung in der UI müssen sowohl eine Analysevorlage als auch eine zugehörige Aktivierungsvorlage haben.

• Alle berechneten Spalten müssen explizit mit einem Alias versehen werden und dürfen keine abgeleiteten Namen haben, da eine Tabelle erzeugt wird. Das heißt:

  SELECT COUNT(*), P.status from T AS P; FAILS, da der Name der Spalte COUNT abgeleitet wird.

  SELECT COUNT(*) AS COUNT_OF_ITEMS, P.status from T AS P; SUCCEEDS, da dies explizit ein Alias der Spalte COUNT ist.

Hier finden Sie zwei Beispiele für grundlegende Aktivierungsvorlagen. Eine ist für die vom Anbieter durchgeführte Serveraktivierung, die andere für andere Aktivierungstypen. Sie unterscheiden sich durch die beiden hervorgehobenen Zeilen, die den Namen der Ergebnistabelle enthalten.

-- These are the required table name strings.
BEGIN
  CREATE OR REPLACE TABLE cleanroom.temp_result_data AS
    SELECT COUNT(c.status) 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 'temp_result_data';
END;

-- analysis_results can be whatever name you want.
BEGIN
  CREATE OR REPLACE TABLE cleanroom.activation_data_analysis_results AS
    SELECT COUNT(c.status) 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;

Nächste Schritte¶

Nachdem Sie das Vorlagensystem gemeistert haben, lesen Sie sich die Einzelheiten zur Implementierung eines Clean Room mit Ihrem Vorlagentyp durch:

• Anbietervorlagen sind Vorlagen, die vom Anbieter geschrieben wurden. Dies ist der Standardanwendungsfall.

• Verbrauchervorlagen sind Vorlagen, die vom Verbraucher geschrieben wurden. In manchen Fällen möchte der Ersteller eines Clean Room dem Verbraucher die Möglichkeit geben, eigene Vorlagen zu erstellen, hochzuladen und im Clean Room auszuführen.

• Aktivierungsvorlagen erstellen nach einer erfolgreichen Ausführung eine Ergebnistabelle. Je nach Aktivierungsvorlage kann die Ergebnistabelle entweder im Konto des Anbieters oder des Verbrauchers außerhalb des Clean Room gespeichert oder an einen Drittanbieter gesendet werden, der im Activation Hub aufgeführt ist.

• Verkettete Vorlagen ermöglichen es Ihnen, mehrere Vorlagen miteinander zu verketten, wobei die Ausgabe jeder Vorlage von der nächsten Vorlage in der Kette verwendet wird.

Weitere Informationen¶

• Jinja-Dokumentation

• JinjaSQL-Dokumentation