Guide du développeur Snowflake Data Clean Rooms

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.

Paramétrage de votre environnement

Outils de développement

Voici les principaux outils de développement pour les clean rooms :

  • Environnement de codage : Tout environnement de codage capable d’exécuter des procédures stockées dans votre compte Snowflake fonctionnera. La plupart des développeurs utilisent des feuilles de calcul dans Snowsight (l’outil basé sur le navigateur) ou sur le site 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 est utile pour explorer des bases de données et d’autres objets et pour rechercher des objets.

  • Clean rooms API: API documentation is divided into provider and consumer topic pages.

Configuration du codage

Rôle et entrepôt requis

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.

Vous devez utiliser l’API des salles blanches dans un entrepôt que SAMOOHA_APP_ROLE peut utiliser. app_wh est l’un des entrepôts avec accès à l’API. Choisissez l’entrepôt approprié à vos besoins.

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

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

Si vous utilisez un autre entrepôt, veillez à autoriser l’utilisation de SAMOOHA_APP_ROLE sur cet entrepôt :

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

A propos de l’API des clean rooms

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.

Les procédures existent dans les schémas suivants :

  • samooha_by_snowflake_local_db.provider - Procédures spécifiques aux fournisseurs. Ces procédures ne peuvent être appelées que sur les clean rooms qui ont été créées dans le compte courant.

  • samooha_by_snowflake_local_db.consumer - Procédures spécifiques aux consommateurs. Ces procédures ne peuvent être appelées que dans les salles blanches où le compte courant a été invité en tant que consommateur.

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

À propos des noms de clean room dans les procédures d’API

De nombreuses procédures d’API de clean room s’appuient sur un argument cleanroom_name.

  • Utilisez le nom d’une salle blanche, si cette salle blanche a été créée à l’aide de l’API. Si le nom est utilisé comme partie du nom d’un package, remplacez les espaces par des traits de soulignement :

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

  • Utilisez l’ID de la salle blanche, si cette salle blanche a été créée en utilisant l’UI des salles blanches.

Vous pouvez voir le nom et l’ID de la salle blanche en appelant describe_cleanroom ou view_cleanrooms.

Clean rooms created using the API are labeled in the clean rooms UI as Supported with Developer APIs.

Paramétrage des comptes, des utilisateurs et des rôles

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.

En fonction de votre cas d’utilisation, vous pouvez également configurer un compte Snowflake supplémentaire dans différentes régions d’hébergement Web pour tester le comportement inter-Cloud.

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.

Salles blanches de tests internes

You can test a clean room during development by sharing the clean room with yourself. Such a clean room is called an internal testing clean room. Using a single account for both provider and consumer is convenient for quick feature testing.

To create an internal testing clean room, simply pass the provider account information to provider.add_consumers as the sole consumer.

Internal testing clean rooms have the following restrictions:

  • An internal testing clean room cannot later be shared with other accounts. An internal testing clean room always is an internal testing clean room.

  • Les fonctions suivantes ne sont pas prises en charge dans les salles blanches de tests internes :

    • Activation du fournisseur

    • Analyses menées par les fournisseurs

    • Monter ou voir les journaux de requêtes (provider.mount_request_logs_for_all_consumers ou provider.view_request_logs)

    • Modèles définis par le consommateur

    • Analyses multi-fournisseurs

    • Confidentialité différentielle

    Si vous souhaitez tester des fonctionnalités qui ne sont pas prises en charge dans une salle blanche de test interne, vous devez configurer des comptes Snowflake distincts du fournisseur et du consommateur pour tester les deux côtés d’une salle blanche.

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

Voir ce qui est installé avec l’environnement des salles blanches

Snowflake Data Clean Rooms crée de nombreuses bases de données locales lors de l’installation. Vous pouvez trouver des détails sur les tâches et les objets qui sont exécutés ou installés avec un paquet de salle blanche dans Snowflake Data Clean Rooms : objets installés.

Données d’échantillon

L’environnement des salles blanches installe quelques ensembles de données d’échantillon que vous pouvez utiliser.

Vous pouvez également générer des données de test synthétiques avec Snowflake

Lignes directrices et recommandations

Confirmez que vous utilisez le même compte dans les UI de clean rooms et dans le code

Vous devez souvent ouvrir un environnement de codage et les UI de clean rooms pour le même compte Snowflake, par exemple, lorsque vous créez une clean room dans le code, puis que vous vérifiez son apparence dans les UI de clean rooms. Il est important de confirmer que vous utilisez le même compte Snowflake dans chaque cas.

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.

Noms Clean room vs ID des clean rooms

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:

  • Si la clean room a été créée à l’aide de l’API, utilisez le nom de la clean room.

  • Si la salle blanche a été créée dans l’UI des salles blanches, utilisez l’ID de la salle blanche. Vous pouvez voir à la fois le nom de la salle blanche et l’ID en appelant provider.view_cleanrooms ou provider.describe_cleanroom.

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.

Interopérabilité entre les clean rooms créées en code ou dans l’UI

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.

Résolution des problèmes

Le consommateur ne peut pas définir de politiques de jointure ou effectuer d’autres actions de base sur une salle blanche jointe

Confirmez que vous avez installé votre clean room avec le rôle approprié (SAMOOHA_APP_ROLE). Si vous n’avez pas utilisé SAMOOHA_APP_ROLE lors de l’installation de la clean room, vous rencontrerez de nombreux problèmes, généralement des erreurs d’autorisation. Si c’est le cas, même consumer.uninstall_cleanroom échouera et vous devrez prendre des mesures supplémentaires pour désinstaller puis réinstaller la clean room avec le rôle correct.

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

Impossible de trouver une clean room que vous avez créée

Si vous avez créé une clean room dans un compte mais que vous ne la voyez pas dans le compte du collaborateur, voici quelques raisons possibles :

  • La clean room a été créée dans une région d’hébergement Cloud différente et vous n’avez pas activé l’exécution automatique inter-Cloud.

  • Vous n’avez pas publié votre clean room en appelant provider.create_or_update_cleanroom_listing.

  • Vous appelez consumer.view_cleanrooms() au lieu de provider.view_cleanrooms() (ou l’inverse).

  • Vous n’avez pas partagé la clean room, vous avez partagé la clean room avec le mauvais compte, ou vous avez ouvert le mauvais compte de collaborateur dans l’UI/CLI Clean rooms de Snowsight. Confirmez que le compte sur lequel vous pensez voir votre clean room est celui avec lequel vous avez partagé la clean room, et que vous êtes connecté à ce compte partagé.

  • Il y a un petit délai entre la publication d’une clean room et le moment où elle devient visible pour le collaborateur.

Fonction inconnue

Si vous appelez une procédure et obtenez une erreur comme l’extrait suivant :

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

Voici quelques causes possibles :

Vous avez saisi le mauvais espace de noms.

Veillez à appeler la version consumer ou provider appropriée de votre procédure. De nombreuses procédures comportent une version pour le fournisseur et une version pour le consommateur.

Vous avez mal saisi le nom de la fonction.

Consultez le guide de référence pour connaître le nom correct.

Un rôle d’exécution avec accès limité vous a été attribué et la fonction que vous avez appelée n’est pas autorisée par votre rôle.

Testez ceci en exécutant le code SQL suivant :

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

Si l’extrait de code renvoie TRUE, vous avez des autorisations de rôle d’exécution avec accès limité sur l’API de salle blanche. Si vous avez besoin d’un niveau accès plus élevé, demandez à un administrateur de salle blanche de vous accorder un accès complet. Voir la liste des procédures de rôle d’exécution autorisées dans la documentation de consumer.grant_run_on_cleanrooms_to_role.

Vous n’avez pas le rôle SAMOOHA_APP_ROLE

Pour savoir si vous pouvez utiliser le rôle SAMOOHA_APP_ROLE, exécutez la commande suivante :

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

Si vous n’obtenez aucun résultat, demandez à un administrateur de vous donner l’accès API à la salle blanche.

Voir si un utilisateur a installé une salle blanche

Vous pouvez vérifier si un utilisateur donné a installé une salle blanche donnée en exécutant le code SQL suivant. Remplacez $consumer_locator et $cleanroom_name avec le localisateur de consommateur et le nom de la salle blanche.

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

Vérifier les requêtes ou l’historique des analyses

Vous pouvez voir l’historique de vos requêtes pour les analyses exécutées dans l’UI ou dans le code. Les historiques sont stockés et vérifiés séparément.

Historique de l’analyse de l’UI

L’UI des salles blanches affiche une liste de toutes les analyses précédentes pour ce compte dans la page Analyses & Queries. Ces résultats ne concernent que les requêtes exécutées dans l’UI.

Si vous modifiez ou supprimez une salle blanche, les rapports d’analyse dans l’UI pour cette salle blanche seront supprimées à moins que le rapport n’utilise l’un des modèles suivants :

  • Audience Overlap & Segmentation

  • SQL Query

  • Un modèle personnalisé.

L’historique des requêtes pour les modèles répertoriés ci-dessus est conservé même si une salle blanche est modifiée ou supprimée.

Historique des requêtes de l’API

Pour afficher l’historique de tous les appels exécutés à l’aide de l’API pour un compte, y compris les analyses de modèles, procédez comme suit :

  1. Connectez-vous à Snowsight.

  2. Dans le menu de navigation, sélectionnez Monitoring » Query History.

  3. Utilisez les filtres pour trouver la requête associée à l’analyse, puis sélectionnez la requête ou l’analyse.

Exemples étendus

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.

Langage: Français