Snowflake Data Clean Rooms-Entwicklerhandbuch

This topic provides guidelines for users who want to create or manage Snowflake Data Clean Rooms programmatically.

Snowflake exposes an API of stored procedures for creating and controlling clean rooms. These stored procedures can be run in any interface that can access the Snowflake account associated with your clean room environment, including Snowsight notebooks and worksheets, as well as the Snowflake CLI. These procedures can be called in SQL or in any language supported by your Snowflake environment.

Einrichten Ihrer Umgebung

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.

  • The clean rooms UI: Use the clean rooms UI to configure, manage, or create clean rooms. Most clean room analysts use the UI rather than code, so it’s important to see and test the experience of your clean rooms in the UI. Additionally, there are a handful of features that are available only in the clean rooms UI.

  • 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

Erforderliche Rolle und Warehouse

The clean rooms API requires the SAMOOHA_APP_ROLE role for full API access. Ask your clean rooms administrator to grant you full API access. Clean rooms also supports creating roles with access to a subset of API procedures.

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.

-- 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 exposes a set of stored procedures that let a provider create, configure, and share a clean room. These procedures can be called in any command-line environment that supports Snowflake procedures, including notebooks, worksheets, and the Snowflake CLI. The documentation here shows SQL usage, but you can also use Python or any other supported Snowflake language.

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 - General procedures called by either the clean room creator (provider) or a clean room collaborator (consumer). These procedures are documented in both the provider and consumer reference pages.

Some procedures have both provider and consumer versions. The results are appropriate to the schema: for example, provider.view_cleanrooms lists all clean rooms in the current account for which you are a provider, and consumer.view_cleanrooms lists all clean rooms in the current account for which you are a consumer. Be sure to call the procedure in the namespace that you need.

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 created using the API are labeled in the clean rooms UI as Supported with Developer APIs.

Konten, Benutzer und Rollen einrichten

You aren’t required to use the clean rooms UI to develop clean rooms: most clean room functionality is available by calling the API. However, a few features are available only in the UI, and some are faster to perform in the UI. And because many users use the UI exclusively, it’s important to see how your clean room behaves in the UI. Therefore, you should ask a clean room administrator to add you as a clean room manager or higher in the appropriate clean room accounts.

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.

Name your test Snowflake accounts meaningfully to indicate their typical usage: for example, „Consumer account,“ „Provider account,“ and „Cross-cloud account.“ This can help when you have multiple test accounts and must choose an account on the clean rooms login page.

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.

Internal testing clean rooms have the following restrictions:

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

Download a sample worksheet that demonstrates using a clean room in a single account for both provider and consumer.

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

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 does not have a shortcut to open the clean rooms UI for the same account, or the reverse, so you must be sure to log in to the same account in each environment.

Clean Room-Namen vs. Clean Room-ID

When using the API, for procedures that take a clean room name argument, determine whether to use the clean room name or the clean room ID as follows:

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

Update your clean room whenever you make UI changes

When you change any clean room properties that affect the UI, call provider.create_or_update_cleanroom_listing to propagate the changes.

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

When you create a clean room using the API, some features are not modifiable in the clean rooms UI. For example, you cannot add additional templates, even stock Snowflake templates, in code for a UI-created clean room. You also cannot change the differential privacy settings.

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

To help you understand how to use various features of the Developer APIs, you can refer to the examples in the Use cases and Features sections of the clean rooms documentation.

Sprache: Deutsch