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
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;
Vergeben Sie einen Namen für den Reinraum, den der Anbieter für Sie freigegeben hat:
set cleanroom_name = 'Test Cleanroom 1';
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>');
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);
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);
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)
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)
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 Sieconsumer.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);
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');
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']);
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']);
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']);
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);
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);
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']);
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']);
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']);
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']);
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');
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']);
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']);
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']);
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);
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']);
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']);
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']);
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']);
Verknüpfung und Aufhebung der Verknüpfung von Datensätzen¶
Sobald ein Datensatz registriert wurde, können Sie Tabellen oder Ansichten aus diesem Datensatz mit einem bestimmten Reinraum verknüpfen. Sie können auch die Verknüpfung einer Tabelle oder Ansicht mit einem bestimmten Reinraum aufheben, um den Zugriff auf diese Daten aus dem Reinraum zu entfernen.
consumer.link_datasets¶
Beschreibung: Verknüpfen Sie eine Tabelle oder eine Ansicht mit dem Reinraum, sodass Vorlagen in diesem Reinraum Zugriff auf die Tabelle haben, und zwar gemäß den von Ihnen festgelegten Join- und Spaltenrichtlinien.
Argumente:
cleanroom_name (string) – Name des Reinraums, zu dem Zugang gewährt werden soll
tables_list (array of strings) – Liste der Namen der vollqualifizierten Tabellen oder Ansichten, die für den Reinraum freigegeben werden sollen. Diese Objekte müssen zunächst mit der entsprechenden Registrierungsmethode registriert (für die Reinraumumgebung verfügbar gemacht) werden.
Rückgabe: Erfolgsmeldung (string)
Beispiel:
call samooha_by_snowflake_local_db.consumer.link_datasets($cleanroom_name, ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS', 'SAMOOHA_SAMPLE_DATABASE.DEMO.EXPOSURES']);
consumer.unlink_datasets¶
Beschreibung: Entfernt den Zugriff auf die angegebenen Tabellen oder Ansichten im angegebenen Reinraum für alle Benutzer. Dies funktioniert nur für vom Verbraucher bereitgestellte Daten.
Argumente:
cleanroom_name (string) – Name des Reinraums, für den der Zugang entfernt werden soll.
tables_list (array of strings) – Liste der Namen der vollqualifizierten Tabellen oder Ansichten, für die der Zugriff gesperrt werden soll.
Rückgabe: Erfolgsmeldung (string)
Beispiel:
call samooha_by_snowflake_local_db.consumer.unlink_datasets($cleanroom_name, ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS', 'SAMOOHA_SAMPLE_DATABASE.DEMO.EXPOSURES']);
consumer.view_consumer_datasets¶
Beschreibung: Zeigt alle Tabellen und Ansichten an, die von einem beliebigen Verbraucher in diesem Konto mit dem angegebenen Reinraum verknüpft sind.
Argumente:
cleanroom_name (string) – Der Name des Reinraums.
Rückgabe: Tabelle der Objekte, die mit dem angegebenen Reinraum verknüpft sind, zusammen mit dem Namen der internen Ansicht des Reinraums für jedes Objekt.
Beispiel:
call samooha_by_snowflake_local_db.consumer.view_consumer_datasets($cleanroom_name);
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']);
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']);
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');
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');
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);
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');
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');
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 Sieconsumer.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 Sieconsumer.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 Sieconsumer.view_template_definition
aufrufen. Dieses Objekt hat einen optionalen reservierten Wert:epsilon
(Float, optional) – Gibt den Epsilon-Wert für differentielle Privatsphäre an, wenn die differentielle Privatsphäre für diesen Reinraum aktiviert ist. Der Standardwert ist 0.1.
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
)
);
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' ]);
consumer.approve_provider_activation_consent¶
Beschreibung: Genehmigt die Anfrage des Anbieters, die Anbieteraktivierung zuzulassen, d. h. die Möglichkeit, Ergebnisse an das Snowflake-Konto des Anbieters zu senden. Geht davon aus, dass der Anbieter bereits provider.request_provider_activation_consent
aufgerufen hat, um eine Berechtigung anzufragen.
Eingabe: cleanroom_name (string), activation_template_name (string)
Ausgabe: Erfolgsmeldung
Beispiel:
call consumer.approve_provider_activation_consent('my_cleanroom', 'activation_my_template');
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'
));
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 %};
$$);
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)
$$
);
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;
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');
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);
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);
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);
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);
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);
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);
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);
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;
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);
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);
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');
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();
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();