Snowflake Data Clean Rooms-Entwicklerhandbuch

Unter diesem Thema finden Sie Richtlinien für Benutzende, die Snowflake Data Clean Rooms programmgesteuert erstellen oder verwalten möchten.

Snowflake stellt eine API von gespeicherten Prozeduren zur Erstellung und Steuerung von Clean Rooms zur Verfügung. Diese gespeicherten Prozeduren können über jede Schnittstelle ausgeführt werden, die auf das mit Ihrer Clean Room-Umgebung verbundene Snowflake-Konto zugreifen kann, einschließlich Snowsight-Notebooks und -Arbeitsblätter sowie Snowflake CLI.. Diese Prozeduren können in SQL oder in einer beliebigen Sprache aufgerufen werden, die von Ihrer Snowflake-Umgebung unterstützt wird.

Einrichten Ihrer Umgebung

Im Folgenden finden Sie einige Tipps, wie Sie Ihre Coding-Umgebung für eine effektive Nutzung der Clean Rooms-API einrichten können.

Entwicklungs-Tools

Hier sind die wichtigsten Entwickler-Tools für Clean Rooms:

  • Codierungsumgebung: Jede Codierungsumgebung, die gespeicherte Prozeduren in Ihrem Snowflake-Konto ausführen kann, funktioniert. Die meisten Entwickler verwenden Arbeitsblätter in Snowsight (dem browserbasierten Tool) oder das Snowflake CLI.

  • Die Clean Rooms-UI: Verwenden Sie die Clean Rooms-UI zum Konfigurieren, Verwalten oder Erstellen von Clean Rooms. Die meisten Clean Room-Analysten verwenden die UI statt Code, daher ist es wichtig, dass Sie das Verhalten Ihrer Clean Rooms in der UI sehen und testen. Außerdem gibt es eine Reihe von -Features, die nur in der Clean Rooms-UI verfügbar sind.

  • Snowsight ist nützlich, um Datenbanken und andere Objekte zu erkunden und nach Objekten zu suchen.

  • Clean Rooms-API: Die API-Dokumentation ist in Themenseiten für Anbietende und Verbrauchende unterteilt.

Codierung einrichten

So richten Sie Ihre Coding-Umgebung für Clean Rooms ein:

Erforderliche Rolle und Warehouse

Die Clean Rooms-API erfordert die SAMOOHA_APP_ROLE-Rolle für den vollständige API-Zugriff. Bitten Sie Ihren Clean Rooms-Administrator, Ihnen vollen API-Zugriff zu gewähren. Clean Rooms unterstützt auch das Erstellen von Rollen mit Zugriff auf eine Teilmenge von API-Prozeduren.

Sie müssen die Clean Room-API in einem Warehouse verwenden, das SAMOOHA_APP_ROLE verwenden kann. app_wh ist eines von mehreren Warehouses mit Zugriff auf die API. Wählen Sie das für Ihre Anforderungen geeignete Warehouse aus.

Wir empfehlen Ihnen, ein XS-Warehouse für allgemeine Befehle zum Bearbeiten, Erstellen oder Löschen von Clean Rooms zu verwenden. Ziehen Sie die Verwendung größerer Warehouses oder Snowpark-optimierter Warehouses in Betracht, wenn Sie große Analysen durchführen, wie z. B. Machine Learning-Workloads.

-- Set up environment.
USE ROLE SAMOOHA_APP_ROLE;
USE WAREHOUSE app_wh;

-- Call your clean rooms API functions.
...
Copy

Wenn Sie ein anderes Warehouse verwenden, stellen Sie sicher, dass Sie SAMOOHA_APP_ROLE die Nutzung dieses Warehouse gestatten:

GRANT USAGE ON WAREHOUSE <your_warehouse> TO SAMOOHA_APP_ROLE;`
Copy

Allgemeine Informationen zur Clean Room API

Snowflake Data Clean Rooms stellt eine Reihe von gespeicherten Prozeduren zur Verfügung, mit denen ein Anbietender einen Clean Room erstellen, konfigurieren und freigeben kann. Diese Prozeduren können in jeder Befehlszeilenumgebung aufgerufen werden, die Snowflake-Prozeduren, einschließlich Notebooks, Arbeitsblätter und die Snowflake CLI, unterstützt. Die Dokumentation hier zeigt die Nutzung von SQL, aber Sie können auch Python oder jede andere von Snowflake unterstützte Sprache verwenden.

Prozeduren existieren innerhalb der folgenden Schemata:

  • samooha_by_snowflake_local_db.provider - Anbieterspezifische Prozeduren. Diese Prozeduren können nur für Clean Rooms aufgerufen werden, die auf dem aktuellen Konto erstellt wurden.

  • samooha_by_snowflake_local_db.consumer - Verbraucherspezifische Prozeduren. Diese Prozeduren können nur für Reinräume aufgerufen werden, zu denen das aktuelle Konto als Verbraucher eingeladen wurde.

  • samooha_by_snowflake_local_db.library – Allgemeine Prozeduren, die entweder vom Ersteller des Reinraums (Anbieter) oder von einem Teilnehmer des Reinraums (Verbraucher) aufgerufen werden. Diese Prozeduren sind sowohl auf der Anbieter- als auch auf der Verbraucherreferenzseite dokumentiert.

Einige Prozeduren haben sowohl Anbieter- als auch Verbraucherversionen. Die Ergebnisse sind für das Schema geeignet: provider.view_cleanrooms listet beispielsweise alle Clean Rooms im aktuellen Konto auf, für die Sie ein Anbieter sind, und consumer.view_cleanrooms listet alle Clean Rooms im aktuellen Konto auf, für die Sie ein Verbraucher sind. Achten Sie darauf, dass Sie die Prozedur in dem Namespace aufrufen, den Sie benötigen.

Allgemeine Informationen zu Clean Room-Namen in API-Prozeduren

Viele Clean Room API-Prozeduren nutzen ein cleanroom_name-Argument.

  • Verwenden Sie den Clean Room-Namen, wenn ein Clean Room unter Verwendung der API erstellt wurde. Bei Verwendung als Teil eines Paketnamens ersetzen Sie Leerzeichen durch Unterstriche:

    -- Spaces work here:
CALL samooha_by_snowflake_local_db.provider.describe_cleanroom('my code created clean room');

-- Underscores required here:
SHOW VERSIONS IN APPLICATION PACKAGE SAMOOHA_CLEANROOM_my_code_created_clean_room;
    Copy

  • Verwenden Sie die Clean Room-ID, wenn der Clean Room unter Verwendung der Clean Rooms-UI erstellt wurde.

Sie können den Namen des Clean Rooms und die ID anzeigen, indem Sie describe_cleanroom oder view_cleanrooms aufrufen.

Clean Rooms, die mit der API erstellt wurden, sind in der Clean Rooms-UI als Supported with Developer APIs gekennzeichnet.

Konten, Benutzer und Rollen einrichten

Sie müssen nicht die Clean Rooms-UI zum Entwickeln von Clean Rooms verwenden: Die meisten Clean Room-Funktionen sind durch Aufrufen der API verfügbar. Einige Funktionen sind jedoch nur in der UI verfügbar und einige werden in der UI schneller ausgeführt. Und weil viele Benutzende ausschließlich die UI verwenden, ist es wichtig zu sehen, wie sich Ihr Clean Room in der UI verhält. Daher sollten Sie einen Clean Room-Administrator bitten, Sie in den entsprechenden Clean Room-Konten als Clean Room-Manager oder höher hinzuzufügen.

Abhängig von Ihrem Anwendungsfall sollten Sie möglicherweise in verschiedenen Webhosting-Regionen ein zusätzliches Snowflake-Konto einrichten, um Cloud-übergreifendes Verhalten zu testen.

Benennen Sie Ihre Snowflake-Testkonten aussagekräftig, um ihre typische Nutzung anzugeben: z. B. „Verbraucherkonto“, „Anbieterkonto“ und „Cloudübergreifendes Konto“. Dies kann hilfreich sein, wenn Sie mehrere Testkonten haben und ein Konto auf der Anmeldeseite des Clean Rooms auswählen müssen.

Interne Test-Clean Rooms

Sie können einen Clean Room während der Entwicklung testen, indem Sie diesen für sich selbst freigeben. Ein solcher Clean Room wird als interner Test-Clean Room bezeichnet. Die Verwendung eines einzigen Kontos für Anbietende und Verbrauchende ist praktisch, um Funktionen schnell zu testen.

Um einen internen Test-Clean Room zu erstellen, übergeben Sie einfach die Informationen des Anbieterkonto an provider.add_consumers als einzigen Verbrauchenden.

Interne Test-Clean Rooms unterliegen den folgenden Einschränkungen:

  • Ein interner Test-Clean Room kann später nicht für andere Konten freigegeben werden. Ein interner Test-Clean Room ist immer ein interner Test-Clean Room.

  • Die folgenden Features werden in internen Test-Clean Rooms nicht unterstützt:

    • Anbieter-Aktivierung

    • Vom Anbieter durchgeführte Analysen

    • Einbinden oder Anzeigen von Anforderungsprotokollen (provider.mount_request_logs_for_all_consumers oder provider.view_request_logs)

    • Verbraucherdefinierte Vorlagen

    • Multi-Anbieter-Analysen

    • Differential Privacy

    Wenn Sie Features testen möchten, die in einem internen Testraum nicht unterstützt werden, müssen Sie separate Snowflake-Konten für Anbieter und Verbraucher einrichten, um beide Seiten eines Clean Rooms zu testen.

Laden Sie ein Beispiel-Arbeitsblatt herunter, das die Verwendung eines Clean Rooms in einem einzigen Konto sowohl für Anbieter als auch für Verbraucher demonstriert.

Sehen Sie, was mit der Clean Rooms-Umgebung installiert wird

Snowflake Data Clean Rooms erstellt bei der Installation viele lokale Datenbanken. Details zu Aufgaben und Objekten, die mit einem Clean Room-Paket ausgeführt oder installiert werden, finden Sie in Snowflake Data Clean Rooms: Installierte Objekte.

Beispieldaten

Die Clean Room-Umgebung installiert einige Beispiel-Datensets, die Sie verwenden können.

Sie können auch synthetische Testdaten mit Snowflake generieren.

Richtlinien und Empfehlungen

Hier finden Sie einige Richtlinien, um Probleme bei der Arbeit mit Clean Rooms zu vermeiden:

Sicherstellen, dass Sie das gleiche Konto in der Clean Room UI und im Code verwenden

Häufig müssen Sie eine Codingumgebung und die Clean Room UI für dasselbe Snowflake-Konto öffnen, z. B. wenn Sie einen Clean Room im Code erstellen und dann sein Aussehen in der Clean Room UI überprüfen. Es ist wichtig, dass Sie sich vergewissern, dass Sie in beiden Konten das gleiche Snowflake-Konto verwenden.

Snowsight hat kein Tastaturkürzel zum Öffnen der Clean Rooms-UI für dasselbe Konto (oder umgekehrt). Daher müssen Sie sicherstellen, dass Sie sich in jeder Umgebung bei demselben Konto anmelden.

Clean Room-Namen vs. Clean Room-ID

Bei Verwendung der APIbestimmen Sie für Prozeduren, die ein name-Argument für den Clean Room verwenden, wie folgt, ob Sie den Clean Room-Namen oder die Clean Room ID verwenden möchten:

  • Wenn der Clean Room mit der API erstellt wurde, verwenden Sie den Namen des Clean Room.

  • Wenn der Clean Room in der Clean Room-ID erstellt wurde, verwenden Sie die Clean Room-ID. Sie können sowohl den Namen des Clean Rooms als auch die ID sehen, indem Sie provider.describe_cleanroom oder provider.describe_cleanroom aufrufen.

Aktualisieren von Clean Rooms bei jeder Änderung an der UI

Wenn Sie Eigenschaften eines Clean Rooms ändern, die sich auf die UI auswirken, rufen Sie provider.create_or_update_cleanroom_listing, um die Änderungen zu übernehmen.

Interoperabilität zwischen Clean Rooms, die mit Code oder der UI erstellt wurden

Wenn Sie einen Clean Room mit der API erstellen, können einige Features in der Clean Rooms-UI nicht geändert werden. Beispielsweise können Sie im Code für einen in der UI erstellten Clean Room keine zusätzlichen Vorlagen hinzufügen, auch nicht die Bestandsvorlagen von Snowflake. Sie können auch die Einstellungen der differentiellen Privatsphäre nicht ändern.

Problembehandlung

Im Folgenden finden Sie einige allgemeine Tipps zur Problembehandlung:

Der Verbraucher kann keine Verknüpfungsrichtlinien festlegen oder andere grundlegende Aktionen für einen verknüpften Clean Room durchführen

Stellen Sie sicher, dass Sie Ihren Clean Room mit der richtigen Rolle installiert haben (SAMOOHA_APP_ROLE). Wenn Sie bei der Installation des Clean Room SAMOOHA_APP_ROLE nicht verwendet haben, werden Sie auf viele Probleme stoßen, typischerweise Berechtigungsfehler. Wenn dies der Fall ist, schlägt auch consumer.uninstall_cleanroom fehl und Sie müssen zusätzliche Schritte unternehmen, um den Clean Room zu deinstallieren und dann mit der richtigen Rolle neu zu installieren.

-- Who owns the clean room?
SHOW SHARES LIKE 'SAMOOHA_CLEANROOM_REQUESTS_<cleanroom_name>';

-- If the owner role is not SAMOOHA_APP_ROLE, you must drop the share, then
-- uninstall the clean room.
DROP SHARE SAMOOHA_CLEANROOM_REQUESTS_<cleanroom_name>;
CALL samooha_by_snowflake_local_db.consumer.uninstall_cleanroom($cleanroom_name);
USE ROLE SAMOOHA_APP_ROLE;
CALL samooha_by_snowflake_local_db.consumer.install_cleanroom($cleanroom_name, '<provider_locator>');
Copy

Sie können keinen Clean Room finden, den Sie erstellt haben

Wenn Sie einen Clean Room in einem Konto erstellt haben, ihn aber im Konto des Teilnehmers nicht sehen können, kommen diese Gründe infrage:

  • Der Clean Room wurde in einer anderen Cloud-Hosting-Region erstellt, und Sie haben die Cloud-übergreifende automatische Ausführung nicht aktiviert.

  • Sie haben Ihren Clean Room nicht veröffentlicht, indem Sie provider.create_or_update_cleanroom_listing aufgerufen haben.

  • Sie rufen consumer.view_cleanrooms() anstelle von provider.view_cleanrooms() auf (oder umgekehrt).

  • Sie haben den Clean Room nicht freigegeben, Sie haben den Clean Room mit dem falschen Konto freigegeben oder Sie haben in der Snowsight/Clean Room UI/CLI das falsche Teilnehmerkonto geöffnet. Vergewissern Sie sich, dass das Konto, in dem Sie Ihren Clean Room sehen möchten, das Konto ist, mit dem Sie den Clean Room geteilt haben, und dass Sie in diesem gemeinsamen Konto angemeldet sind.

  • Es gibt eine kleine Verzögerung zwischen der Veröffentlichung eines Clean Room und dem Zeitpunkt, an dem er für den Teilnehmer sichtbar wird.

Unbekannte Funktion

Wenn Sie eine Prozedur aufrufen und einen Fehler wie den folgenden Ausschnitt erhalten:

Unknown user-defined function SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.CONSUMER.<procedure name>

Hier sind einige mögliche Ursachen:

Sie haben den falschen Namespace eingegeben.

Stellen Sie sicher, dass Sie die richtige consumer- oder provider-Version Ihrer Prozedur aufrufen. Für viele Prozeduren gibt es sowohl Anbieter- als auch Verbraucherversionen.

Sie haben den Namen der Funktion falsch eingegeben.

Suchen Sie im Referenzhandbuch nach der richtigen Benennung.

Ihnen wurde eine eingeschränkte Ausführungsrolle zugewiesen und die Funktion, die Sie aufgerufen haben, wird von Ihrer Rolle nicht zugelassen.

Testen Sie dies, indem Sie den folgenden SQL-Code ausführen:

USE DATABASE samooha_by_snowflake_local_db;
CALL IS_DATABASE_ROLE_IN_SESSION('samooha_run_role');
Copy

Wenn der Codeausschnitt TRUE zurückgibt, haben Sie nur begrenzten Zugriff run-role-Berechtigungen für die Clean Room-API. Wenn Sie umfangreicheren Zugriff benötigen, bitten Sie einen Clean Room-Administrator um vollen Zugriff. Die Liste der zulässigen Ausführungsrollenprozeduren finden Sie in der consumer.grant_run_on_cleanrooms_to_role-Dokumentation.

Sie haben SAMOOHA_APP_ROLE nicht

Um zu sehen, ob Sie die SAMOOHA_APP_ROLE verwenden können, führen Sie den folgenden Befehl aus:

-- Get current user name.
SELECT current_user();

-- Add current user name in place as indicated.
SHOW GRANTS TO USER <current_user_name> ->> select * from $1 where "role" = 'SAMOOHA_APP_ROLE';
Copy

Wenn Sie keine Ergebnisse erhalten, bitten Sie einen Administrator, Ihnen API-Zugriff auf den Clean Room zur Verfügung zu stellen.

Sehen Sie, ob ein Benutzer einen Clean Room installiert hat

Sie können überprüfen, ob ein bestimmter Benutzer einen bestimmten Clean Room installiert hat, indem Sie den folgenden SQL-Code ausführen. Ersetzen Sie $consumer_locator und $cleanroom_name mit dem Verbraucher-Locator und dem Namen des Clean Rooms.

SELECT * FROM snowflake.data_sharing_usage.application_state
  WHERE consumer_account_locator = $consumer_locator
    AND CONTAINS(package_name, UPPER(REPLACE($cleanroom_name, ' ', '_')));
Copy

Den Verlauf Ihrer Abfrage oder Analyse prüfen

Sie können Ihren Abfrageverlauf für Analysen einsehen, die in der UI oder im Code durchgeführt wurden. Diese Verläufe werden separat gespeichert und geprüft.

UI-Analyseverlauf

Die Clean Rooms-UI zeigt eine Liste aller vorherigen Analysen für dieses Konto auf der Seite Analyses & Queries an. Diese Ergebnisse beziehen sich nur auf Abfragen, die in der UI ausgeführt wurden.

Wenn Sie einen Clean Room ändern oder löschen, werden die Analyseberichte in der UI für diesen Clean Room gelöscht, es sei denn, der Bericht verwendet eine der folgenden Vorlagen:

  • Audience Overlap & Segmentation

  • SQL Query

  • Eine benutzerdefinierte Vorlage.

Der Abfrageverlauf für die oben aufgeführten Vorlagen bleibt erhalten, auch wenn ein Clean Room geändert oder gelöscht wird.

API-Abfrageverlauf

Um den Kontoverlauf aller Aufrufe anzuzeigen, die über die API ausgeführt werden, einschließlich Vorlagenanalysen, tun Sie Folgendes:

  1. Melden Sie sich bei Snowsight an.

  2. Wählen Sie im Navigationsmenü die Option Monitoring » Query History aus.

  3. Verwenden Sie die Filter, um die mit der Analyse verbundene Abfrage zu finden, und wählen Sie dann die Abfrage oder Analyse aus.

Erweiterte Beispiele

Damit Sie verstehen, wie Sie die verschiedenen Features von Entwickler-APIs nutzen, können Sie sich an den Beispielen in den Abschnitten Use cases und Features in der Clean Rooms-Dokumentation orientieren.