Guide du développeur Snowflake Data Clean Rooms

Cette page fournit quelques lignes directrices aux utilisateurs qui souhaitent créer ou gérer des clean rooms ou des modèles dans Snowflake de manière programmatique.

Snowflake expose des procédures stockées qui vous permettent de développer des applications pour créer ou contrôler des clean rooms. Ces procédures stockées peuvent être exécutées dans n’importe quelle interface ayant accès au compte Snowflake associé à votre environnement de clean room, y compris les carnets ou feuilles de calcul Snowsight ainsi que le site Snowflake CLI. Ces procédures peuvent être appelées à l’adresse SQL ou dans n’importe quelle langue prise en charge par les interfaces Snowflake.

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.

  • Les UI de clean rooms : Utilisez les UI de clean rooms pour configurer, gérer ou créer des clean rooms. La plupart des analystes de clean rooms utilisent le l’UI plutôt qu’un code. Il peut donc être utile de voir et de tester l’expérience de vos clean rooms dans l’UI. En outre, il existe quelques fonctions qui ne sont disponibles que dans les UI de clean rooms.

  • Snowsight est utile pour explorer des bases de données et d’autres objets et pour rechercher des objets.

Configuration du codage

Rôle et entrepôt requis

Les API clean rooms nécessitent le rôle SAMOOHA_APP_ROLE pour un accès complet à l’API. Demandez à l’administrateur de votre clean room de vous l’accès complet à l’API.

Clean rooms permet également de créer des rôles donnant accès à un sous-ensemble de procédures d’API.

Vous devez utiliser les API de clean rooms dans un entrepôt que SAMOOHA_APP_ROLE peut utiliser. La fonctionnalité Clean rooms fournit à l’entrepôt APP_WH l’accès à l’API clean rooms.

-- 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 expose un ensemble de procédures stockées qui permettent à un fournisseur de créer, configurer et partager une clean room. Ces procédures sont accessibles par tout environnement de ligne de commande qui supporte les procédures Snowflake, y compris les notebooks, les workbooks et le CLI Snowflake. Vous pouvez utiliser les API de clean rooms dans n’importe quelle langue prenant en charge les procédures stockées. La documentation présente l’utilisation de SQL, mais vous pouvez également utiliser Python ou toute autre langue supportée.

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 - Procédures générales appelées par le créateur de la salle blanche (fournisseur) ou par un collaborateur de la salle blanche (consommateur). (Ces éléments sont documentés dans les pages de référence du fournisseur et du consommateur)

Certaines procédures comportent une version pour le fournisseur et une version pour le consommateur. Les résultats sont adaptés au schéma : par exemple, provider.view_cleanrooms annonce toutes les clean rooms du compte courant pour lequel vous êtes fournisseur, et consumer.view_cleanrooms annonce toutes les clean rooms du compte courant pour lequel vous êtes consommateur.

À 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 de la clean room si une clean room a été créée à l’aide de l’API.

  • Utilisez l’ ID de la clean room si la clean room a été créée à l’aide de l’UI de clean room.

Vous pouvez voir le nom et l’ID de la clean roomen appelant describe_cleanroom.

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

Techniquement, vous n’avez pas besoin d’utiliser l’UI pour développer des clean rooms : la plupart des fonctionnalités des clean rooms sont disponibles à l’aide de procédures stockées. Toutefois, certaines fonctions ne sont disponibles que dans l’UI, et certaines sont plus rapides à réaliser dans l’UI. Et comme de nombreux utilisateurs utilisent exclusivement l’UI, il est important de voir comment votre clean room se comporte dans l’UI, surtout si vous créez une forme web de configuration utilisateur pour une clean room que vous avez créée. Par conséquent, vous devez demander à un administrateur de clean room de vous ajouter en tant que gestionnaire de clean room ou à un niveau supérieur dans les comptes de clean room appropriés.

Nous recommandons au minimum d’avoir des comptes Snowflake séparés pour le fournisseur et le consommateur afin de tester les deux côtés d’une clean room. En fonction de votre cas d’utilisation, vous pourriez également vouloir configurer un compte Snowflake Region supplémentaire dans différentes régions d’hébergement web pour tester le comportement inter-Cloud.

Nommez vos comptes Snowflake de test de manière significative pour indiquer leur utilisation typique : par exemple, compte consommateur, compte fournisseur et compte inter-Cloud. Cela peut s’avérer utile lorsque vous avez plusieurs comptes de test et que vous devez savoir à quel compte vous connecter.

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 n’a pas de raccourci pour ouvrir les UI de clean rooms pour le même compte, ou l’inverse, vous devez donc vous assurer que les UI de clean rooms et Snowsight sont ouvertes dans le même compte.

Noms Clean room vs ID des clean rooms

Lorsque vous utilisez l’API, pour les procédures qui nécessitent un argument cleanroom_name, déterminez s’il faut utiliser le nom ou l’ID de la clean room comme suit :

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

  • Si la clean room a été créée dans l’application web, utilisez l’ID de la clean room. Vous pouvez voir le nom et l’ID de la clean room en appelant provider.view_cleanrooms ou provider.describe_cleanroom.

Mettez à jour votre clean room chaque fois que vous effectuez des changements

Pour modifier l’ensemble des paramètres de la clean room, y compris les modèles, les autorisations ou les politiques, appelez provider.create_or_update_cleanroom_listing pour activer les modifications. Dans certains cas, les modifications peuvent être visibles avant l’appel de cette procédure, mais elles ne s’appliqueront correctement qu’après l’appel de provider.create_or_update_cleanroom_listing.

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

Lorsque vous créez une clean room dans l’API, certaines fonctions ne sont pas modifiables dans l’UI de clean rooms. Par exemple, vous ne pouvez pas ajouter de modèles supplémentaires, même des modèles Snowflake en stock, dans le code d’une clean room créée dans l’UI. Vous ne pouvez pas non plus modifier les paramètres de confidentialité différentielle.

Description des objets de la clean room

Snowflake Data Clean Rooms crée de nombreuses bases de données locales lors de l’installation. Voici quelques-uns des objets les plus utiles :

SAMOOHA_CLEANROOM_cleanroom_id

Contient des informations spécifiques à chaque clean room créée dans ce compte. Comprend les éléments suivants :

  • Admin : Clés cryptographiques, budget de confidentialité, journaux des requêtes, demandes d’analyses des fournisseurs, etc.

  • Schéma partagé : Politique de jointure, statut LAF, tables liées, versions.

  • Modèles : Liste des modèles d’activation, des modèles personnalisés et des chaînes de modèles dans cette clean room.

SAMOOHA_CLEANROOM_REQUESTS_cleanroom_id

Contient l’historique des requêtes, telles que les requêtes multi-fournisseurs, les requêtes de modèles et les requêtes.

SAMOOHA_BY_SNOWFLAKE_LOCAL_DB:
  • Provider.procedures : Définitions de toutes les procédures d’API du fournisseur

  • Consumer.procedures : Définitions de toutes les procédures d’API du consommateur.

  • Library.procedures : Définitions de toutes les procédures d’API pour les fournisseurs et les consommateurs.

  • Public.consumer_activation_summary : Résultats de l’activation du consommateur.

  • Public.provider_activation_summary : Résultats de l’activation du fournisseur.

SAMOOHA_BY_SNOWFLAKE.TEMPLATES.TEMPLATES:

Contient la liste et la définition de tous les modèles Snowflake en stock disponibles pour les clean rooms dans ce compte.


(Consommateur) Impossible d’établir des politiques de jonction ou d’effectuer d’autres actions de base sur une clean room jonctionnée

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

Résultats généraux inattendus

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.

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 que vous obtenez une erreur du type : … code-block: : sqlexample

Fonction définie par l’utilisateur inconnue SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.CONSUMER. <Nom de la procédure>

Soit vous n’avez pas le site SAMOOHA_APP_ROLE, soit vous avez mal saisi le nom de la fonction.

Cela peut également signifier que vous avez reçu un rôle d’exécution à accès limité et que la fonction que vous appelez n’est pas autorisée par votre rôle. Vous pouvez le vérifier en essayant d’exécuter l’une des procédures autorisées à l’adresse consumer.grant_run_on_cleanrooms_to_role. Si la procédure réussit, il se peut que vous utilisiez un rôle limité. En cas d’échec, il est probable que vous n’ayez pas l’autorisation d’exécuter les API de clean rooms dans ce compte.

Pour savoir si vous disposez de SAMOOHA_APP_ROLE, exécutez la commande suivante :

SELECT IS_ROLE_IN_SESSION( 'SAMOOHA_APP_ROLE' );
Copy

Si vous obtenez l’erreur suivante :

Database <cleanroom name> does not exist or not authorized. in RUN_ANALYSIS_STRING
Copy

Vous avez reçu un rôle d’exécution temporaire qui a été révoqué. Demandez à un administrateur de clean rooms un nouveau rôle d’exécution ou un accès complet à SAMOOHA_APP_ROLE.

Consultez l’historique de vos requêtes

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

Historique des requêtes de l’UI

L’UI clean rooms affiche une liste de toutes les requêtes et de tous les résultats antérieurs pour ce compte dans la page Analyses & Queries. Ces résultats ne concernent que les requêtes effectuées dans l’UI.

Historique des requêtes de l’API

Pour consulter l’historique des comptes des requêtes exécutées à l’aide de l’ API, procédez comme suit :

  1. Connectez-vous à Snowsight .

  2. Sélectionnez Monitoring » Query History.

  3. Utilisez les filtres pour trouver la requête associée à l’analyse, puis copiez l’ID de la requête.

  4. Ouvrez une feuille de calcul et exécutez une requête qui récupère les résultats en fonction de l’ID de la requête. Par exemple, si l’ID de requête est ABC123, exécutez ce qui suit :

    SELECT * FROM TABLE(result_scan(ABC123));
    
    Copy

    Si l’entrepôt est suspendu entre l’exécution de l’analyse de l’API et l’utilisation de cette requête pour récupérer les résultats, il se peut que vous ne puissiez pas obtenir les résultats.

Exemples étendus

Pour vous aider à comprendre comment utiliser les différentes fonctions des APIs de développeur, vous pouvez vous référer aux exemples de la section Use cases de la documentation sur les clean rooms.