Snowflake Data Clean Rooms: Verbraucher-API-Referenzhandbuch

Der folgende Inhalt beschreibt alle Entwickler-APIs, die von Snowflake Data Clean Rooms für Verbraucher bereitgestellt werden. Alle Funktionen befinden sich innerhalb des folgenden Schemas:

samooha_by_snowflake_local_db.consumer
Copy

Umgebung einrichten

Führen Sie die folgenden Befehle aus, um die Snowflake-Umgebung einzurichten, bevor Sie Entwickler-APIs für die Arbeit mit einem Snowflake Data Clean Room verwenden. Wenn Sie nicht über die Rolle SAMOOHA_APP_ROLE verfügen, wenden Sie sich an Ihren Kontoadministrator.

use role samooha_app_role;
use warehouse app_wh;
Copy

Vergeben Sie einen Namen für den Reinraum, den der Anbieter für Sie freigegeben hat:

set cleanroom_name = 'Test Cleanroom 1';
Copy

Reinraum installieren

Installieren Sie den Reinraum, den der Anbieter freigegeben hat, mit den folgenden Befehlen:

consumer.install_cleanroom

Beschreibung: Installiert den Reinraum auf dem Verbraucherkonto mit dem zugehörigen Anbieter und dem ausgewählten Reinraum.

Argumente: cleanroom_name (string), provider_account_locator (string)

Rückgabe: Erfolgsmeldung (string)

Beispiel:

call samooha_by_snowflake_local_db.consumer.install_cleanroom($cleanroom_name, '<PROVIDER_ACCOUNT_LOCATOR>');
Copy

consumer.is_enabled

Beschreibung: Sobald der Reinraum installiert ist, dauert es etwa 1 Minute, bis der Anbieter die Einrichtung abgeschlossen hat und ihn auf seiner Seite aktivieren kann. Mit dieser Funktion kann der Benutzer den Status des Reinraums überprüfen und sehen, ob er aktiviert ist oder nicht. Das Flag wechselt in der Regel etwa eine Minute nach der Installation des Reinraums auf „True“.

Argumente: cleanroom_name (string)

Liefert: ist aktiviert (boolean)

Beispiel:

call samooha_by_snowflake_local_db.consumer.is_enabled($cleanroom_name);
Copy

consumer.uninstall_cleanroom

Beschreibung: Deinstalliert den Reinraum auf dem Verbraucherkonto. Dadurch werden alle mit dem Reinraum verbundenen Datenbanken entfernt, einschließlich der freigegebenen Reinraum-Datenbank. Beachten Sie, dass der Reinraum jederzeit mit consumer.install_cleanroom erneut installiert werden kann.

Argumente: cleanroom_name (string)

Rückgabe: Erfolgsmeldung (string)

Beispiel:

call samooha_by_snowflake_local_db.consumer.uninstall_cleanroom($cleanroom_name);
Copy

Provider Run Analysis einrichten

library.is_provider_run_enabled

Beschreibung: Prüft, ob in diesem Reinraum Provider Run Analysis aktiviert ist. Hinweis: Die explizite Genehmigung muss noch erteilt werden, indem Sie consumer.enable_templates_for_provider_run aufrufen (siehe unten).

Argumente: cleanroom_name (string)

Rückgabe: aktiviert Nachricht (string)

Beispiel:

call samooha_by_snowflake_local_db.library.is_provider_run_enabled($cleanroom_name)
Copy

library.is_consumer_run_enabled

Beschreibung: Prüft, ob in diesem Reinraum die Consumer Run Analysis aktiviert ist. Dieses Flag bestimmt, ob der Reinraum-Verbraucher (Installierer) Analysen ausführen oder als Datenlieferant für die Zusammenarbeit fungieren kann.

Argumente: cleanroom_name (string)

Rückgabe: aktiviert Nachricht (string)

Beispiel:

call samooha_by_snowflake_local_db.library.is_consumer_run_enabled($cleanroom_name)
Copy

consumer.enable_templates_for_provider_run

Beschreibung: Wenn in einem Reinraum die Provider Run Analysis aktiviert ist (d. h. der Anbieter des Reinraums hat den Reinraum so markiert, dass Anbieter Analysen ausführen können), muss diese Prozedur vom Verbraucher aufgerufen werden, um sie zu aktivieren. Dieses Verfahren wird benötigt, um Anbietern, die eine Analyse ausführen möchten, eine explizite Genehmigung für jede einzelne Vorlage zu erteilen.

Der letzte boolesche Parameter ermöglicht es dem Verbraucher, die differentielle Privatsphäre für die Analysen des Anbieters zu aktivieren, wenn er auf TRUE gesetzt ist.

Argumente:

  • cleanroom_name (string) – Der Name des Reinraums.

  • template_names (array of strings) – Ein Array mit einer oder mehreren Vorlagen im Reinraum, die für die Anbieteranalyse aktiviert werden sollen

  • enable_differential_privacy (boolean) – Wenn TRUE, aktivieren Sie die differentielle Privatsphäre für alle in template_names aufgeführten Vorlagen. Die differentielle Privatsphäre kann für diese Vorlagen nur aktiviert werden, wenn die differentielle Privatsphäre für den Reinraum selbst aktiviert ist. Sie können den differentiellen Privatsphärenstatus für einen Reinraum überprüfen, indem Sie consumer.is_dp_enabled aufrufen.

Rückgabe: Erfolgsmeldung (string)

Beispiel:

call samooha_by_snowflake_local_db.consumer.enable_templates_for_provider_run($cleanroom_name, ['prod_overlap_analysis'], FALSE);
Copy

Daten registrieren und abmelden

Verwenden Sie den folgenden Befehl, um Datenbanken, Schemas und Objekte zu registrieren und die Registrierung aufzuheben. Tabellen und Ansichten müssen registriert werden, bevor sie mit dem Reinraum verknüpft werden können. Wenn Sie eine Datenbank oder ein Schema registrieren, werden alle Objekte in dieser Datenbank oder diesem Schema registriert.

consumer.register_db

Beschreibung: Indem Sie eine Datenbank in den Reinraum einbinden, können Sie jedes Datenset aus der Datenbank verknüpfen. Wenn diese Funktion nicht aufgerufen wird, müssen Sie „samooha_app_role“ Berechtigungen einzeln zugwiesen werden.

Argumente: db_name (string)

Rückgabe: Erfolgsmeldung (string)

Beispiel:

call samooha_by_snowflake_local_db.consumer.register_db('SAMOOHA_SAMPLE_DATABASE');
Copy

library.register_schema

Beschreibung: Ähnlich wie register_db, arbeitet jedoch auf Schemaebene. Ein Array oder eine Zeichenfolge, die den vollständig qualifizierten Schemanamen repräsentiert, kann übergeben werden, und es werden SELECT-Zuweisungen für die Rolle SAMOOHA_APP_ROLE vorgenommen, sodass der Benutzer die Objekte im Schema mit dem Reinraum verknüpfen kann.

Wenn Sie ein verwaltetes Zugriffsschema registrieren möchten (d. h. ein Schema, das mit dem Parameter WITH MANAGED ACCESS erstellt wurde), verwenden Sie stattdessen library.register_managed_access_schema.

Argumente: schema_name (array)

Rückgabe: Erfolgsmeldung (string)

Beispiel:

call samooha_by_snowflake_local_db.library.register_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);
Copy

library.register_managed_access_schema

Beschreibung: Ähnlich wie register_schema, registriert jedoch ein Schema, das mit dem Parameter WITH MANAGED ACCESS erstellt wurde. Ein Array oder eine Zeichenfolge, die den vollständig qualifizierten Schemanamen repräsentiert, kann übergeben werden, und es werden SELECT-Zuweisungen für die Rolle SAMOOHA_APP_ROLE vorgenommen, sodass der Benutzer die Objekte im Schema mit dem Reinraum verknüpfen kann.

Argumente: schema_name (array)

Rückgabe: Erfolgsmeldung (string)

Beispiel:

call samooha_by_snowflake_local_db.library.register_managed_access_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);
Copy

library.register_objects

Beschreibung: Gewährt dem Reinraum Zugriff auf Tabellen und Ansichten aller Arten, sodass sie durch den Aufruf von consumer.link_datasets mit dem Reinraum verknüpft werden können. Sie können breitere Gruppen von Objekten registrieren, indem Sie library.register_schema, library.register_managed_access_schema oder consumer.register_db aufrufen.

Argumente:

  • object_names (array) – Array mit vollständig qualifizierten Objektnamen. Diese Objekte können dann mit dem Reinraum verknüpft werden.

Rückgabe: Erfolgsmeldung (string)

Beispiele

So registrieren Sie eine Tabelle und eine Ansicht:

call samooha_by_snowflake_local_db.library.register_objects(
    ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS','SAMOOHA_SAMPLE_DATABASE.INFORMATION_SCHEMA.FIELDS']);
Copy

library.register_table_or_view – Veraltet

Achtung

Dieser Befehl ist jetzt veraltet. Bitte verwenden Sie library.register_objects.

Beschreibung: Registriert Tabellen und Ansichten aller Art.

Argumente: object_names (array), is_view (boolean), is_iceberg (boolean), is_external (boolean), is_under_managed_access_schema (boolean)

Ausgabe Erfolgsmeldung (string)

Beispiele

Um eine Tabelle zu registrieren:

call samooha_by_snowflake_local_db.library.register_table_or_view(
    ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],
    false,
    false,
    false,
    false);
Copy

Um eine Iceberg-Tabelle zu registrieren:

call samooha_by_snowflake_local_db.library.register_table_or_view(
        ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'], 
        false, 
        true,
        false,
        false);
Copy

library.register_table – Veraltet

Achtung

Dieser Befehl ist jetzt veraltet. Bitte verwenden Sie library.register_objects.

Beschreibung: Ähnlich wie register_db, operiert aber auf Tabellenebene. Ein Array oder eine Zeichenfolge, die den vollqualifizierten Tabellennamen repräsentiert, kann übergeben werden, und SELECT-Zuweisungen für die Rolle SAMOOHA_APP_ROLE werden ausgeführt, sodass der Benutzer die Tabelle mit dem Reinraum verknüpfen kann.

Wenn Sie Tabellen in einem verwalteten Zugriffsschema (d. h. ein Schema, das mit dem Parameter WITH MANAGED ACCESS erstellt wurde) registrieren möchten, verwenden Sie stattdessen library.register_managed_access_table.

Argumente: table_name (array)

Rückgabe: Erfolgsmeldung (string)

Beispiel:

call samooha_by_snowflake_local_db.library.register_table(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
Copy

library.register_managed_access_table – Veraltet

Achtung

Dieser Befehl ist jetzt veraltet. Bitte verwenden Sie library.register_objects.

Beschreibung: Ähnlich wie register_table, registriert aber Tabellen in einem Schema, das mit dem Parameter WITH MANAGED ACCESS erstellt wurde. Ein Array oder eine Zeichenfolge, die den vollqualifizierten Tabellennamen repräsentiert, kann übergeben werden, und SELECT-Zuweisungen für die Rolle SAMOOHA_APP_ROLE werden ausgeführt, sodass der Benutzer die Tabelle mit dem Reinraum verknüpfen kann.

Argumente: table_name (array)

Rückgabe: Erfolgsmeldung (string)

Beispiel:

call samooha_by_snowflake_local_db.library.register_managed_access_table(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
Copy

library.register_view – Veraltet

Achtung

Dieser Befehl ist jetzt veraltet. Bitte verwenden Sie library.register_objects.

Beschreibung: Ähnlich wie register_db, arbeitet aber auf der Ansichtsebene. Ein Array oder eine Zeichenfolge, die den vollqualifizierten Ansichtsnamen repräsentiert, kann übergeben werden, und SELECT-Zuweisungen für die Rolle SAMOOHA_APP_ROLE werden ausgeführt, sodass der Benutzer die Ansicht mit dem Reinraum verknüpfen kann.

Wenn Sie Ansichten in einem verwalteten Zugriffsschema (d. h. ein Schema, das mit dem Parameter WITH MANAGED ACCESS erstellt wurde) registrieren möchten, verwenden Sie stattdessen library.register_managed_access_view.

Argumente: view_name (array)

Rückgabe: Erfolgsmeldung (string)

Beispiel:

call samooha_by_snowflake_local_db.library.register_view(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
Copy

library.register_managed_access_view – Veraltet

Achtung

Dieser Befehl ist jetzt veraltet. Bitte verwenden Sie library.register_objects.

Beschreibung: Ähnlich wie register_view, registriert aber die Ansichten in einem Schema, das mit dem Parameter WITH MANAGED ACCESS erstellt wurde. Ein Array oder eine Zeichenfolge, die den vollqualifizierten Ansichtsnamen repräsentiert, kann übergeben werden, und SELECT-Zuweisungen für die Rolle SAMOOHA_APP_ROLE werden ausgeführt, sodass der Benutzer die Ansicht mit dem Reinraum verknüpfen kann.

Argumente: view_name (array)

Rückgabe: Erfolgsmeldung (string)

Beispiel:

call samooha_by_snowflake_local_db.library.register_managed_access_view(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
Copy

library.unregister_db

Beschreibung: Macht die Prozedur register_db rückgängig und entfernt die Berechtigungen auf Datenbankebene, die der Rolle SAMOOHA_APP_ROLE und der nativen Snowflake Data Clean Room-Anwendung erteilt wurden. Dadurch wird auch jede Datenbank aus dem UI-Dropdown-Element entfernt.

Argumente: db_name (string)

Rückgabe: Erfolgsmeldung (string)

Beispiel:

call samooha_by_snowflake_local_db.library.unregister_db('SAMOOHA_SAMPLE_DATABASE');
Copy

library.unregister_schema

Beschreibung: Hebt die Registrierung eines Schemas auf, was Benutzer daran hindert, dessen Tabellen und Ansichten mit dem Clean Room zu verknüpfen.

Wenn Sie die Registrierung eines verwalteten Zugriffsschemas (d. h. eines Schemas, das mit dem Parameter WITH MANAGED ACCESS erstellt wurde) aufheben möchten, verwenden Sie stattdessen library.unregister_managed_access_schema.

Argumente: schema_name (array)

Rückgabe: Erfolgsmeldung (string)

Beispiel:

call samooha_by_snowflake_local_db.library.unregister_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);
Copy

library.unregister_managed_access_schema

Beschreibung: Ähnlich wie unregister_schema, hebt jedoch die Registrierung eines Schemas auf, das mit dem Parameter WITH MANAGED ACCESS erstellt wurde.

Argumente: schema_name (array)

Rückgabe: Erfolgsmeldung (string)

Beispiel:

call samooha_by_snowflake_local_db.library.unregister_managed_access_schema(['SAMOOHA_SAMPLE_DATABASE.DEMO']);
Copy

library.unregister_objects

Beschreibung: Widerruft den Reinraum-Zugriff auf Tabellen und Ansichten aller Art. Die Objekte sind für Benutzer in allen von diesem Konto verwalteten Reinräumen nicht mehr verfügbar.

Argumente:

  • object_names (array) – Array der vollqualifizierten Objektnamen, für die der Zugriff widerrufen werden soll.

Rückgabe: Erfolgsmeldung (string)

Beispiele

So heben Sie die Registrierung einer Tabelle und einer Ansicht auf:

call samooha_by_snowflake_local_db.library.unregister_objects(
    ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS','SAMOOHA_SAMPLE_DATABASE.INFORMATION_SCHEMA.FIELDS']);
Copy

library.unregister_table_or_view – Veraltet

Achtung

Dieser Befehl ist jetzt veraltet. Bitte verwenden Sie library.unregister_objects.

Beschreibung: Hebt die Registrierung von Tabellen und Ansichten aller Art auf.

Argumente: object_names (array), is_view (boolean), is_iceberg (boolean), is_external (boolean), is_under_managed_access_schema (boolean)

Ausgabe Erfolgsmeldung (string)

Beispiele

So heben Sie die Registrierung einer Tabelle auf:

call samooha_by_snowflake_local_db.library.unregister_table_or_view(
    ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],
    false,
    false,
    false,
    false);
Copy

library.unregister_table – Veraltet

Achtung

Dieser Befehl ist jetzt veraltet. Bitte verwenden Sie library.unregister_objects

Beschreibung: Ähnlich wie unregister_db, arbeitet jedoch auf Tabellenebene. Ein Array oder eine Zeichenfolge, die den vollqualifizierten Tabellennamen repräsentiert, kann übergeben werden, um die Registrierung der Tabellen aufzuheben. Benutzer können keine nicht registrierten Tabellen mit einem Reinraum verknüpfen.

Wenn Sie die Registrierung von Tabellen in einem verwalteten Zugriffsschema (d. h. ein Schema, das mit dem Parameter WITH MANAGED ACCESS erstellt wurde) aufheben möchten, verwenden Sie stattdessen library.unregister_managed_access_table.

Argumente: table_name (array)

Rückgabe: Erfolgsmeldung (string)

Beispiel:

call samooha_by_snowflake_local_db.library.unregister_table(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
Copy

library.unregister_managed_access_table – Veraltet

Achtung

Dieser Befehl ist jetzt veraltet. Bitte verwenden Sie library.unregister_objects

Beschreibung: Ähnlich wie unregister_table, hebt jedoch die Registrierung von Tabellen in einem verwaltetem Zugriffsschema auf (d. h. ein Schema, das mit dem Parameter WITH MANAGED ACCESS erstellt wurde).

Argumente: table_name (array)

Rückgabe: Erfolgsmeldung (string)

Beispiel:

call samooha_by_snowflake_local_db.library.unregister_managed_access_table(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
Copy

library.unregister_view – Veraltet

Achtung

Dieser Befehl ist jetzt veraltet. Bitte verwenden Sie library.unregister_objects

Beschreibung: Ähnlich wie unregister_db, arbeitet jedoch auf Ansichtsebene. Ein Array oder eine Zeichenfolge, die den vollständig qualifizierten Namen der Ansicht repräsentiert, kann übergeben werden, um die Registrierung der Ansichten aufzuheben. Benutzer können keine nicht registrierten Ansichten mit einem Reinraum verknüpfen.

Wenn Sie die Registrierung von Ansichten in einem verwaltetem Zugriffsschema (d. h. einem Schema, das mit dem Parameter WITH MANAGED ACCESS erstellt wurde) aufheben möchten, verwenden Sie stattdessen library.unregister_managed_access_view.

Argumente: view_name (array)

Rückgabe: Erfolgsmeldung (string)

Beispiel:

call samooha_by_snowflake_local_db.library.unregister_view(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
Copy

library.unregister_managed_access_view – Veraltet

Achtung

Dieser Befehl ist jetzt veraltet. Bitte verwenden Sie library.unregister_objects

Beschreibung: Ähnlich wie unregister_view, hebt jedoch die Registrierung von Ansichten in einem verwaltetem Zugriffsschema auf (d. h. ein Schema, das mit dem Parameter WITH MANAGED ACCESS erstellt wurde).

Argumente: view_name (array)

Rückgabe: Erfolgsmeldung (string)

Beispiel:

call samooha_by_snowflake_local_db.library.unregister_managed_access_view(['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);
Copy

Vom Anbieter durchgeführte Analyse

consumer.set_join_policy

Beschreibung: Gibt an, auf welchen Spalten der Anbieter eine Verknüpfung ausführen darf, wenn er Vorlagen im Reinraum ausführt bei Verwendung von Provider Run Analysis. Beachten Sie, dass die Spaltenrichtlinie nur ersetzt wird. Wenn die Funktion also erneut aufgerufen wird, wird die zuvor festgelegte Spaltenrichtlinie vollständig durch die aktuelle ersetzt.

Beachten Sie, dass die Prüfungen ausgeführt werden, indem die SQL-Abfrage, die auf den Daten ausgeführt werden soll, auf nicht autorisierte Spalten analysiert wird. Abfragen mit Platzhaltern werden von diesen Prüfungen möglicherweise nicht erfasst, und Sie sollten bei der Entwicklung der Analysemaske trotzdem Vorsicht walten lassen.

Argumente: cleanroom_name(string), table_and_col_names (array)

Rückgabe: Erfolgsmeldung (string)

Beispiel:

call samooha_by_snowflake_local_db.consumer.set_join_policy($cleanroom_name, ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:EMAIL', 'SAMOOHA_SAMPLE_DATABASE.DEMO.EXPOSURES:EMAIL']);
Copy

consumer.set_column_policy

Beschreibung: Legt fest, mit welchen Spalten in den Daten der Anbieter Operationen ausführen kann. Dies sollte erst nach dem Hinzufügen der Vorlage aufgerufen werden. Dies ist ebenfalls eine Funktion der Vorlage, sodass die Eingaben im Format „template_name:full_table_name:column_name“ erfolgen müssen. Beachten Sie, dass die Spaltenrichtlinie nur ersetzt wird. Wenn die Funktion erneut aufgerufen wird, wird die zuvor festgelegte Spaltenrichtlinie vollständig durch die aktuelle ersetzt.

Spaltenrichtlinie sollte nicht für Identitätsspalten wie E-Mail aufgerufen werden. Sie sollte nur für Aggregate und die Gruppierung nach Spalten verwendet werden.

Beachten Sie, dass die Prüfungen ausgeführt werden, indem die SQL-Abfrage, die auf den Daten ausgeführt werden soll, auf nicht autorisierte Spalten analysiert wird. Abfragen mit Platzhaltern werden von diesen Prüfungen möglicherweise nicht erfasst, und Sie sollten bei der Entwicklung der Analysemaske trotzdem Vorsicht walten lassen.

Prüfungen werden für SQL Jinja-Argumente namens dimensions oder measure_columns ausgeführt. Stellen Sie sicher, dass Sie diese Tags verwenden, um diese Prüfung zu aktivieren.

Argumente: cleanroom_name (string), analysis_and_table_and_columns (array)

Rückgabe: Erfolgsmeldung (string)

Beispiel:

call samooha_by_snowflake_local_db.consumer.set_column_policy($cleanroom_name,
['prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:STATUS',
 'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:AGE_BAND',
 'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:DAYS_ACTIVE',
 'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.EXPOSURES:CAMPAIGN']);
Copy

Vorlagen

Mit den folgenden Befehlen können Benutzer mit Vorlagen im Reinraum verfügbaren Vorlagen arbeiten.

consumer.view_template_definition

Beschreibung: Die Reinraum-Vorlagendefinitionen sind verfügbar, um zu bestimmen, welche Parameter an die Vorlage übergeben werden müssen.

Bemerkung

Beachten Sie, dass alle Samooha-Prozeduren verschlüsselt und standardmäßig nicht anzeigbar sind. Alle benutzerdefinierten Vorlagen, die Sie hinzufügen, werden jedoch für Sie sichtbar sein.

Argumente: cleanroom_name (string), template_name (string)

Rückgabe: Die Definition der Vorlage (string)

Beispiel:

call samooha_by_snowflake_local_db.consumer.view_template_definition($cleanroom_name, 'prod_overlap_analysis');
Copy

consumer.get_arguments_from_template

Beschreibung: Legt fest, wie die Daten organisiert werden sollen und welche Daten für jede Vorlage erforderlich sind, um sicherzustellen, dass die Ausgabe gut lesbar ist.

Argumente: cleanroom_name (string), template_name (string)

Rückgabe: Argumentenliste und Spezifikation (Tabelle)

Beispiel:

call samooha_by_snowflake_local_db.consumer.get_arguments_from_template($cleanroom_name, 'prod_overlap_analysis');
Copy

Vorlagenketten

Mit den folgenden Befehlen können Benutzer mit den im Reinraum verfügbaren Vorlagenketten arbeiten. Allgemeine Informationen zur Verwendung von Vorlagenketten finden Sie unter Verwendung der Entwickler-APIs zur sequenziellen Ausführung von Vorlagen.

consumer.view_added_template_chains

Beschreibung: Zeigt die derzeit im Reinraum aktiven Vorlagenketten an.

Argumente: cleanroom_name (string)

Rückgabe: Die hinzugefügten Vorlagenketten (Tabelle)

Beispiel:

call samooha_by_snowflake_local_db.consumer.view_added_template_chains($cleanroom_name);
Copy

consumer.view_template_chain_definition

Beschreibung: Gibt die Attribute einer Vorlagenkette zurück.

Argumente: cleanroom_name (string), template_chain_name (string)

Rückgabe: Die Definition der Vorlagenkette (string)

Beispiel:

call samooha_by_snowflake_local_db.consumer.view_template_chain_definition($cleanroom_name, 'insights_chain');
Copy

consumer.get_arguments_from_template_chain

Beschreibung: Gibt die erwarteten Argumente für alle Vorlagen in der Vorlagenkette zurück.

Argumente: cleanroom_name (string), template__chain_name (string)

Rückgabe: Argumentenliste und Spezifikation (Tabelle)

Beispiel:

call samooha_by_snowflake_local_db.consumer.get_arguments_from_template_chain($cleanroom_name, 'insights_chain');
Copy

Analysen durchführen

Die folgenden Befehle führen eine bestimmte Analyse oder Aktivität auf der Grundlage der angegebenen Vorlage aus.

consumer.run_analysis

Beschreibung: Führt eine Analyse anhand einer Vorlage oder Vorlagenkette aus und gibt die Ergebnistabelle zurück.

Wenn die differentielle Privatsphäre aktiviert ist, kann die Abfrage fehlschlagen, wenn Sie Ihr Budgetlimit für diese Vorlage erreicht haben.

Argumente:

  • cleanroom_name (string) – Name des Reinraums, in dem die Vorlage ausgeführt werden soll.

  • template_name (string) – Name der Vorlage oder Vorlagenkette, die im Reinraum ausgeführt werden soll.

  • consumer_tables (array of string) – Array mit den Namen der vollständig qualifizierten Verbrauchertabellen. Diese werden der Vorlagenvariable my_table zugewiesen. Diese Tabellen müssen bereits mit dem Reinraum verknüpft sein. Zeigen Sie die verfügbaren Tabellen an, indem Sie consumer.view_consumer_datasets aufrufen. Wenn Sie zum Beispiel [‚mytable1‘,‘mytable2‘,‘mytable3‘] übergeben, kann die Vorlage auf diese Werte als {{my_table[0]}}, {{my_table[1]}} bzw. {{my_table[2]}} zugreifen.

  • provider_tables (array of string) – Array mit den Namen der vollständig qualifizierten Anbietertabellen. Diese werden der Vorlagenvariable source_table zugewiesen. Diese Tabellen müssen bereits mit dem Reinraum verknüpft sein. Zeigen Sie die verfügbaren Tabellen an, indem Sie consumer.view_provider_datasets aufrufen. Wenn Sie zum Beispiel [‚sourcetable1‘,‘sourcetable2‘,‘sourcetable3‘] übergeben, kann die Vorlage auf diese Werte als {{source_table[0]}}, {{source_table[1]}} bzw. {{source_table[2]}} zugreifen.

  • analysis_arguments (object) – Ein Objekt mit Schlüssel/Wert-Paaren, das an die Vorlage übergeben wird. Die Vorlage kann über den Schlüsselnamen auf die Variable zugreifen. Wenn Sie {'age': 20} übergeben, greift die Vorlage auf den Wert als {{age}} zu. Geben Sie ein leeres Objekt ein, wenn keine Werte benötigt werden. Um zu sehen, welche Werte benötigt werden, untersuchen Sie die betreffende Vorlage, indem Sie consumer.view_template_definition aufrufen. Dieses Objekt hat einen optionalen reservierten Wert:

  • use_cache (Boolean, optional) – Ob zwischengespeicherte Ergebnisse für dieselbe Abfrage verwendet werden sollen oder nicht. Standardwert ist TRUE. Setzen Sie diese Option beim Testen und Bearbeiten einer Vorlage auf FALSE, um sicherzustellen, dass die Abfrage jedes Mal mit der neuesten Version der Vorlage ausgeführt wird.

Ergebnisse: (Tabelle) Abfrageergebnisse.

Beispiel:

call samooha_by_snowflake_local_db.consumer.run_analysis(
  $cleanroom_name,
  'prod_overlap_analysis',
  ['SAMOOHA_SAMPLE_DATABASE.MYDATA.CONVERSIONS'],  -- Consumer tables
  ['SAMOOHA_SAMPLE_DATABASE.DEMO.EXPOSURES'],      -- Provider tables
  object_construct(
    'max_age', 30
  )
);
Copy

Aktivierung

Weitere Informationen über die Aktivierung von Ergebnissen finden Sie unter Verwendung von Entwickler-APIs zum Senden von Ergebnissen an ein Snowflake-Konto zur Aktivierung.

consumer.set_activation_policy

Beschreibung: Legt fest, welche Spalten in Aktivierungsvorlagen verwendet werden können. Dadurch wird sichergestellt, dass nur die Spalten, die vom Verbraucher genehmigt wurden, mit der Aktivierungsvorlage verwendet werden können.

Eingabe: cleanroom_name (string), columns (array)

Das Argument columns wird im Format <template_name>:<fully_qualified_table_name>:<column_name> übergeben.

Ausgabe: Erfolgsmeldung

Beispiel:

call samooha_by_snowflake_local_db.consumer.set_activation_policy('my_cleanroom', [ 
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE_NAME.DEMO.CUSTOMERS:HASHED_EMAIL',  
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE_NAME.DEMO.CUSTOMERS:REGION_CODE' ]);
Copy

consumer.run_activation

Beschreibung: Führt eine Vorlage aus, die die Ergebnisse zur Aktivierung an ein Snowflake-Konto zurückschickt.

Argumente: cleanroom_name (string), segment_name (string), template_name (string), consumer_tables (array), provider_tables (array), activation_arguments (object), consumer_direct_activation (boolean), application_id (string)

Wenn der Verbraucher die Ergebnisse zur Aktivierung an sein eigenes Snowflake-Konto sendet, setzen Sie das Argument consumer_direct_activation auf TRUE.

Übergeben Sie eine leere Zeichenkette als Argument an application_id.

Rückgabe: Erfolgsmeldung

Beispiel:

call samooha_by_snowflake_local_db.consumer.run_activation(
  $cleanroom_name,
  'my_activation_segment',
  'activation_custom_template',
  ['consumer_source_table'], 
  ['provider_source_table'],
  object_construct(                 -- Custom arguments needed for the template
    'dimensions', ['p.CAMPAIGN'],   -- always use p. to refer to fields in provider tables, and c. to refer to fields in consumer tables. Use p2, p3, etc. for more than one provider table and c2, c3, etc. for more than one consumer table.
    'where_clause', 'p.EMAIL=c.EMAIL'
  ));
Copy

Verbraucherdefinierte Vorlagen

Mit den folgenden APIs können Sie verbraucherdefinierte Vorlagen zu einem Reinraum hinzufügen. Weitere Informationen finden Sie unter Mit der Entwickler-API verbraucherdefinierte Vorlagen hinzufügen.

consumer.create_template_request

Beschreibung: Sendet eine Anfrage an den Anbieter eines Reinraums mit der Bitte, eine benutzerdefinierte Vorlage zu genehmigen, damit sie dem Reinraum hinzugefügt werden kann.

Argumente: cleanroom_name (string), template_name (string), template_definition (string)

Rückgabe: Erfolgsmeldung (string)

Beispiel:

  CALL samooha_by_snowflake_local_db.consumer.create_template_request('dcr_cleanroom', 
  'my_analysis', 
  $$
  SELECT 
      identifier({{ dimensions[0] | column_policy }}) 
  FROM 
      identifier({{ my_table[0] }}) c 
    INNER JOIN
      identifier({{ source_table[0] }}) p 
        ON   
          c.identifier({{ consumer_id  }}) = identifier({{ provider_id | join_policy }}) 
        {% if where_clause %} where {{ where_clause | sqlsafe | join_and_column_policy }} {% endif %};
  $$);
Copy

consumer.generate_python_request_template

Beschreibung: Erzeugt eine Reinraumvorlage für Verbraucher, die benutzerdefinierten Python-Code enthält. Die generierte Vorlage enthält Ihren Python-Code und einen Platzhalter für Ihre JinjaSQL-Vorlage. Übergeben Sie Ihre endgültige Vorlage an consumer.list_template_requests.

Erfahren Sie mehr über verbraucherdefinierte Vorlagen

Argumente:

  • function_name (string) – Der Name der Python-Funktion, die Ihre SQL-Vorlage aufrufen soll, um Ihre Funktion auszuführen.

  • arguments (array of string) – Liste der Argumente für Ihre Python-Funktion, wobei jedes Argument ein durch Leerzeichen getrenntes Zeichenfolgenpaar im Format „<argument_name> <argument_type>“ ist. Zum Beispiel: ['data variant', 'scale integer'].

  • packages (array of string) – Array mit Paketnamen, die für Ihren Python-Code benötigt werden. Wenn nicht, geben Sie ein leeres Array an. Beispiel: ['pandas','numpy'].

  • imports (array of strings) – Alle benutzerdefinierten Python-Bibliotheken, die für den Python-Code benötigt werden. Sollte ein Array mit null oder mehr Stagingbereich-Adressen sein. Beispiel: ['@db.schema.stage/my_python_sproc.py']

  • rettype (string) – Der SQL-Rückgabetyp Ihrer Funktion. Beispiele: 'integer', 'varchar'.

  • handler (string) – Der Name der Haupthandlerfunktion in Ihrem Python-Code. In der Regel ist dies 'main'.

  • code (string) – Ihre Python-Code-Implementierung. Wenn Sie einen Import einschließen und Ihr designierter Handler innerhalb eines Imports definiert ist, kann dies eine leere Zeichenfolge sein.

Rückgabe: Erstellte Python-Vorlage (string). Ersetzen Sie den Platzhalter durch Ihren SQL-Code.

Beispiel:

Rufen Sie die Hilfsfunktion mit einem einfachen Python-Beispiel auf.

call SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.CONSUMER.GENERATE_PYTHON_REQUEST_TEMPLATE(
  'my_func',                         // SQL should use this name to call your function
  ['data variant', 'index integer'], // Arguments and types for the function
  ['pandas', 'numpy'],               // Standard libraries used
  [],                                // No custom libraries needed.
  'integer',                         // Return type integer
  'main',                            // Standard main handler
// Python implementation as UDF  
  $$
import pandas as pd
import numpy as np

def main(data, index):
    df = pd.DataFrame(data)  # you can do something with df but this is just an example
    return np.random.randint(1, 100)
    $$
);
Copy

Hier ist die Antwort auf den vorherigen Aufruf. Fügen Sie Ihr JinjaSQL wie am Platzhalter angegeben ein, und übergeben Sie es an consumer.create_template_request.

BEGIN

-- First define the Python UDF
CREATE OR REPLACE FUNCTION CLEANROOM.my_func(data variant, index integer)
RETURNS integer
LANGUAGE PYTHON
RUNTIME_VERSION = 3.10
PACKAGES = ('pandas', 'numpy')

HANDLER = 'main'
AS '
import pandas as pd
import numpy as np

def main(data, index):
    df = pd.DataFrame(data)  # you can do something with df but this is just an example
    return np.random.randint(1, 100)
    ';
        

-- Then define and execute the SQL query
LET SQL_TEXT varchar := '<INSERT SQL TEMPLATE HERE>';

-- Execute the query and return the result
LET RES resultset := (EXECUTE IMMEDIATE :SQL_TEXT);
RETURN TABLE(RES);

END;
Copy

consumer.list_template_requests

Beschreibung: Listet die Anfragen auf, die der Verbraucher gestellt hat, um eine Vorlage zu einem Reinraum hinzuzufügen.

Argumente: cleanroom_name (string)

Rückgabe: request_id (string), provider_identifier (string), template_name (string), template_definition (string), request_status (string), reason (string)

Beispiel:

CALL samooha_by_snowflake_local_db.consumer.list_template_requests('dcr_cleanroom');
Copy

Getter-Methoden für Reinraum-Metadaten

Die folgenden Methoden zeigen relevante Eigenschaften des Reinraums:

consumer.describe_cleanroom

Beschreibung: Erstellt eine Textzusammenfassung mit allen Informationen darüber, was dem Reinraum hinzugefügt wurde, einschließlich Vorlagen, Datensets, Richtlinien usw.

Argumente: cleanroom_name (string)

Rückgabe: Ausführliche Beschreibungszeichenfolge des Reinraums (Tabelle)

Beispiel:

call samooha_by_snowflake_local_db.consumer.describe_cleanroom($cleanroom_name);
Copy

consumer.view_provider_datasets

Beschreibung: Zeigt alle Datensets an, die vom Anbieter zum Reinraum hinzugefügt wurden.

Argumente: cleanroom_name (string)

Ergebnisse: Alle Namen der Anbieter-Datensätze im Reinraum (Tabelle)

Beispiel:

call samooha_by_snowflake_local_db.consumer.view_provider_datasets($cleanroom_name);
Copy

consumer.view_join_policy

Beschreibung: Legt fest, welche Spalten Benutzer in einem Reinraum sicher verknüpfen können. Dies wird vom Verbraucher für Verbraucher-Datensets festgelegt.

Argumente: cleanroom_name (string)

Rückgabe: Die Verknüpfungsrichtlinie (Tabelle)

Beispiel:

call samooha_by_snowflake_local_db.consumer.view_join_policy($cleanroom_name);
Copy

consumer.view_provider_join_policy

Beschreibung: Legt fest, welche Spalten Benutzer in einem Reinraum sicher verknüpfen können. Dies wird vom Anbieter für Anbieter-Datensets festgelegt.

Argumente: cleanroom_name (string)

Rückgabe: Die Verknüpfungsrichtlinie (Tabelle)

Beispiel:

call samooha_by_snowflake_local_db.consumer.view_provider_join_policy($cleanroom_name);
Copy

consumer.view_added_templates

Beschreibung: Zeigt alle aktiven Vorlagen im Reinraum an.

Argumente: cleanroom_name (string)

Rückgabe: Die hinzugefügten Vorlagen (Tabelle)

Beispiel:

call samooha_by_snowflake_local_db.consumer.view_added_templates($cleanroom_name);
Copy

consumer.view_column_policy

Beschreibung: Zeigt alle Spaltenrichtlinien an, die vom Verbraucher auf den Reinraum angewendet wurden.

Argumente: cleanroom_name (string)

Rückgabe: Die Spaltenrichtlinie (Tabelle)

Beispiel:

call samooha_by_snowflake_local_db.consumer.view_column_policy($cleanroom_name);
Copy

consumer.view_provider_column_policy

Beschreibung: Zeigt alle Spaltenrichtlinien an, die vom Anbieter auf den Reinraum angewendet wurden.

Argumente: cleanroom_name (string)

Rückgabe: Die Spaltenrichtlinie (Tabelle)

Beispiel:

call samooha_by_snowflake_local_db.consumer.view_provider_column_policy($cleanroom_name);
Copy

consumer.view_cleanrooms

Beschreibung: Zeigt alle Reinräume an, die mit diesem Konto verknüpft sind (installiert) oder verknüpft werden können. Gescheiterte Reinräume werden nicht angezeigt. In der Ergebnistabelle:

  • IS_ALREADY_INSTALLED: True, wenn der Reinraum verknüpft ist (Registerkarte Joined in der Web-App), False, wenn Sie eingeladen wurden, dem Reinraum beizutreten, ihm aber nicht beigetreten sind (Registerkarte Invited in der Web-App).

    Bekanntes Problem: – Bei dieser Methode werden nicht installierte Reinräume manchmal nicht angezeigt. Wenn Sie wissen, dass ein Reinraum mit Ihnen geteilt wurde, dieser aber nicht in der Liste erscheint, rufen Sie consumer.describe_cleanroom auf, um zu sehen, ob dieser Reinraum zum Beitritt verfügbar ist.

Argumente: Keine

Rückgabe: Alle vorhandenen Reinräume, geordnet nach Erstellungsdatum (Tabelle)

Beispiel:

call samooha_by_snowflake_local_db.consumer.view_cleanrooms();

-- Now filter out invitations that have not been accepted
SELECT cleanroom_name FROM TABLE(RESULT_SCAN(LAST_QUERY_ID())) WHERE is_already_installed = TRUE;
Copy

Differential Privacy

Diese Befehle steuern die differentielle Privatsphäre im Reinraum. Sie können auch eine differentielle Privatsphäre auf Vorlagenebene festlegen, wenn Sie consumer.enable_templates_for_provider_run aufrufen.

Erfahren Sie mehr über die Verwaltung der differentiellen Privatsphäre

consumer.is_dp_enabled

Beschreibung: Prüft, ob die differentielle Privatsphäre im Reinraum aktiviert wurde.

Argumente: cleanroom_name (string)

Rückgabe: Ob der Reinraum DP aktiviert hat (boolean)

Beispiel:

call samooha_by_snowflake_local_db.consumer.is_dp_enabled($cleanroom_name);
Copy

consumer.view_remaining_privacy_budget

Beschreibung: Zeigt das verbleibende Datenschutzbudget an, das für Abfragen aus dem Reinraum verwendet werden kann. Sobald das Budget erschöpft ist, sind weitere Aufrufe von „run_analysis“ erst wieder möglich, nachdem das Budget zurückgesetzt wurde. Das Budget wird täglich neu festgelegt.

SELECT cleanroom_name FROM TABLE(RESULT_SCAN(LAST_QUERY_ID())) WHERE is_already_installed = TRUE;

Argumente: cleanroom_name (string)

Rückgabe: Das verbleibende Budget für die Privatsphäre (Float)

Beispiel:

call samooha_by_snowflake_local_db.consumer.view_remaining_privacy_budget($cleanroom_name);
Copy

Allgemeine Hilfsmethoden

Verwenden Sie die folgenden Methoden, um die allgemeine Funktionalität des Reinraums zu unterstützen.

consumer.set_cleanroom_ui_accessibility

Beschreibung: Zeigt oder verbirgt Reinräume in der Web-App für Verbraucher im aktuellen Konto.

Argumente:

  • cleanroom_name (string) – Der Name des Reinraums.

  • visibility_status (string) – Einer der folgenden Werte (Groß- und Kleinschreibung beachten):

    • HIDDEN – Verbirgt den angegebenen Reinraum in der Web-App vor allen Benutzern des aktuellen Verbraucherkontos. Der Reinraum wird weiterhin über API erreichbar sein.

    • EDITABLE – Macht den Reinraum in der Web-App sichtbar.

Rückgabe: Erfolgsmeldung (string)

Beispiel:

call samooha_by_snowflake_local_db.consumer.set_cleanroom_ui_accessibility($cleanroom_name, 'HIDDEN');
Copy

library.enable_local_db_auto_upgrades

Beschreibung: Aktiviert die Aufgabe samooha_by_snowflake_local_db.admin.expected_version_task, die automatisch ein Upgrade der Snowflake Native App für Snowflake Data Clean Rooms durchführt, sobald neue Versionen veröffentlicht werden.

Argumente: Keine

Rückgabe: Erfolgsmeldung (string)

Beispiel:

CALL samooha_by_snowflake_local_db.library.enable_local_db_auto_upgrades();
Copy

library.disable_local_db_auto_upgrades

Beschreibung: Deaktiviert die Aufgabe samooha_by_snowflake_local_db.admin.expected_version_task, die automatisch ein Upgrade der Snowflake Native App für Snowflake Data Clean Rooms durchführt, wenn neue Versionen veröffentlicht werden.

Argumente: Keine

Rückgabe: Erfolgsmeldung (string)

Beispiel:

CALL samooha_by_snowflake_local_db.library.disable_local_db_auto_upgrades();
Copy