Snowflake Data Clean Rooms API de collaboration

Introduction

Il s’agit de la page de référence de l’API de collaboration Snowflake Data Clean Rooms. Cette API utilise les espaces de noms COLLABORATION et REGISTRY, et non les espaces de noms PROVIDER ou CONSUMER utilisés par les APIs fournisseur et consommateur.

Note

Vous devez désactiver les rôles secondaires dans votre environnement lorsque vous utilisez l’API de collaboration :

USE SECONDARY ROLES NONE;
Copy

Gérer l’accès à l’API de collaboration DCR

Les collaborateurs peuvent utiliser le rôle SAMOOHA_APP_ROLE de haut niveau pour appeler toutes les procédures d’API de collaboration DCR.

Toutefois, nous recommandons aux administrateurs d’accorder un accès plus granulaire à des collaborations spécifiques ou à des rôles spécifiques, en fonction de leurs besoins. Vous pouvez trouver les privilèges plus granulaires documentés dans Procédures de gestion des accès.

Pour accorder des privilèges d’API granulaires à un utilisateur, procédez comme suit :

  1. Créez un rôle.

  2. Accordez l’utilisation sur l’entrepôt utilisé au rôle.

  3. Appelez GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE si nécessaire pour accorder des privilèges appropriés sur une collaboration spécifique à un rôle.

  4. Appelez GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE si nécessaire pour accorder des privilèges de haut niveau appropriés sur toutes les collaborations du compte au rôle.

  5. Attribuez le rôle à l’utilisateur, qui peut désormais appeler des procédures de collaboration pour participer à la collaboration.

Exemple

Voici un exemple de création de deux rôle d’API de collaboration : un rôle qui peut créer et joindre des collaborations, et un autre rôle qui peut visualiser les ressources d’une collaboration et exécuter des analyses dans une collaboration (mais pas joindre ou modifier une collaboration).

-- Create a role that can create and join collaborations.
USE ROLE ACCOUNTADMIN;
CREATE ROLE COLLABORATION_CREATOR_ROLE;
GRANT USAGE ON WAREHOUSE APP_WH TO COLLABORATION_CREATOR_ROLE;
GRANT APPLY ROW ACCESS POLICY ON ACCOUNT TO ROLE COLLABORATION_CREATOR_ROLE;
GRANT CREATE APPLICATION ON ACCOUNT TO ROLE COLLABORATION_CREATOR_ROLE;
GRANT CREATE DATABASE ON ACCOUNT TO ROLE COLLABORATION_CREATOR_ROLE;
GRANT CREATE LISTING ON ACCOUNT TO ROLE COLLABORATION_CREATOR_ROLE;
GRANT CREATE SHARE ON ACCOUNT TO ROLE COLLABORATION_CREATOR_ROLE;
GRANT IMPORT SHARE ON ACCOUNT TO ROLE COLLABORATION_CREATOR_ROLE;
GRANT MANAGE SHARE TARGET ON ACCOUNT TO ROLE COLLABORATION_CREATOR_ROLE;
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.ADMIN.GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'COLLABORATION_CREATOR_ROLE');
GRANT ROLE COLLABORATION_CREATOR_ROLE TO USER george_washington;

-- Create a role that can run analyses on a specific collaboration.
USE ROLE COLLABORATION_CREATOR_ROLE;
CREATE ROLE ANALYST_ROLE;

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.ADMIN.GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE(
  'RUN',
  'COLLABORATION',
  $collaboration_name,
  'ANALYST_ROLE'
);

-- Also grant READ, which gives permission to read the resources available to use in a collaboration.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.ADMIN.GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE(
  'READ',
  'COLLABORATION',
  $collaboration_name,
  'ANALYST_ROLE'
);

GRANT ROLE ANALYST_ROLE to USER alexander_hamilton;
Copy

Aide-mémoire en matière de métadonnées

Voici comment trouver des informations fréquemment demandées sur une collaboration :

Pour apprendre cela…

Appeler cette

Quelles collaborations puis-je rejoindre ?

VIEW_COLLABORATIONS. Rechercher des collaborations où la colonne COLLABORATION_NAME est NULL.

Quelles collaborations ai-je rejointes ?

VIEW_COLLABORATIONS. Rechercher des collaborations où la colonne COLLABORATION_NAME n’est pas NULL, qui peut signifier que vous avez créé ou rejoint la collaboration.

Quelles collaborations puis-je posséder ?

VIEW_COLLABORATIONS. Regarder dans la colonne OWNER_ACCOUNT.

Quel est le statut de tous les collaborateurs d’une collaboration ?

GET_STATUS

Quel est mon statut de jointure ou de création dans une collaboration ?

GET_STATUS ou VIEW_COLLABORATIONS

Qui possède une collaboration donnée ?

GET_STATUS. Chercher OWNER dans la colonne ROLES.

Quel est mon rôle dans une collaboration donnée ?

GET_STATUS. Regarder dans la colonne ROLES.

Quels rôles sont attribués dans une collaboration donnée ?

GET_STATUS. Regarder dans la colonne ROLES.

Quelles sont les spécifications dans une collaboration donnée ?

VIEW_COLLABORATIONS. Regarder dans la colonne COLLABORATION_SPEC.

Les spécifications sont-elles à jour ?

Il n’y a aucun moyen de savoir si les spécifications données ont des modifications en cours, mais vous pouvez appeler VIEW_COLLABORATIONS pour savoir quand les dernières mises à jour ont été appliquées.

Quelles sont les demandes de mise à jour en attente ?

VIEW_UPDATE_REQUESTS. Rechercher des lignes où STATUS = PENDING.

Afficher les spécifications d’une collaboration donnée

review_collaboration renvoie les spécifications de collaboration. Si vous avez déjà appelé review_collaboration ou rejoint la collaboration, appelez la commande SQL suivante avec le nom de votre collaboration comme indiqué :

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_COLLABORATIONS() ->>
  SELECT "COLLABORATION_SPEC" FROM $1
    WHERE "SOURCE_NAME" = <collaboration name>;
Copy

Procédures de modèle

REGISTER_TEMPLATE

Schéma:

REGISTRY

Enregistre un modèle pour lui permettre d’être utilisé dans une collaboration. Chaque modèle enregistré doit disposer d’un nom et d’une version uniques pour tous les modèles dans tous les registres de votre compte.

Syntaxe

REGISTER_TEMPLATE( ['<registry_name>' ,] <template_spec> )
Copy

Arguments

registry_name (Facultatif)

Nom d’un registre personnalisé dans lequel enregistrer ce modèle. Si non spécifié, enregistre le modèle dans le registre de compte par défaut.

template_spec

Définition du modèle en format YAML, sous forme de chaîne.

Renvoie

Un ID de modèle à utiliser dans la spécification de collaboration.

Exemples

Enregistrer un modèle dans le registre par défaut :

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.REGISTRY.REGISTER_TEMPLATE(
  $$
  api_version: 2.0.0
  spec_type: template
  name: my_test_template
  version: 2026_01_12_V1
  type: sql_analysis
  description: A test template
  template:
    SELECT * FROM IDENTIFIER({{ source_table[0] }}) LIMIT 10;
$$);
Copy

Enregistrer un modèle dans un registre personnalisé :

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.REGISTRY.REGISTER_TEMPLATE(
  'my_custom_registry',
  $$
  api_version: 2.0.0
  spec_type: template
  name: my_test_template
  version: 2026_01_12_V1
  type: sql_analysis
  description: A test template
  template:
    SELECT * FROM IDENTIFIER({{ source_table[0] }}) LIMIT 10;
$$);
Copy

Exigences d’accès

Si vous n’utilisez pas le rôle SAMOOHA_APP_ROLE, vous devez utiliser un rôle qui s’est vu accorder des privilèges en appelant la procédure suivante :

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('REGISTER TEMPLATE', 'role name')

VIEW_REGISTERED_TEMPLATES

Schéma:

REGISTRY

Répertorie tous les modèles que vous avez enregistrés. Pour enregistrer un modèle, appelez REGISTRY.REGISTER_TEMPLATE.

Syntaxe

VIEW_REGISTERED_TEMPLATES( [ '<registry_name>' ] )
Copy

Arguments

registry_name (Facultatif)

Nom d’un registre personnalisé dans lequel enregistrer ce modèle. Si non spécifié, enregistre le modèle dans le registre de compte par défaut.

Renvoie

Une table qui répertorie les détails de tous les modèles que vous avez enregistrés dans ce compte.

Exemple

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.REGISTRY.VIEW_REGISTERED_TEMPLATES();
Copy

Exigences d’accès

Si vous n’utilisez pas le rôle SAMOOHA_APP_ROLE, vous devez utiliser un rôle auquel des privilèges ont été accordés en appelant l’une des procédures suivantes :

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('VIEW REGISTERED TEMPLATES', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

ADD_TEMPLATE_REQUEST

Schéma:

COLLABORATION

Envoie une requête pour ajouter un modèle à une collaboration existante. Si l’expéditeur est concerné par la requête, il approuve automatiquement la requête ; tous les autres collaborateurs concernés doivent approuver la demande d’application de la modification. Tous les collaborateurs doivent appeler cette procédure pour ajouter un modèle à une collaboration existante, même le propriétaire de la collaboration.

Pour ajouter des partages de modèles supplémentaires, vous pouvez rappeler cette procédure avec leurs alias. Chaque appel ajoute les utilisateurs répertoriés dans share_with

Pour voir le statut de la requête, appelez VIEW_UPDATE_REQUESTS.

Voir le flux d’ajout de modèles.

Syntaxe

ADD_TEMPLATE_REQUEST( <collaboration_name>, <template_id>, <share_with> )
Copy

Arguments

collaboration_name

Nom de la collaboration à laquelle ajouter le modèle.

template_id

ID du modèle à ajouter à la collaboration. Enregistrez le modèle pour obtenir cette valeur.

share_with

Tableau d’alias de gestionnaires d’analyses avec lesquels partager ce modèle. Les collaborateurs répertoriés ici seront ajoutés en plus des autres collaborateurs associés à ce modèle. Tous les collaborateurs répertoriés ici doivent être des gestionnaires d’analyses, sinon la procédure échouera sans partager ce modèle avec personne.

Renvoie

Une chaîne représentant un message de réussite.

Exemple

-- Ask to add the template only for Collaborator3 in this collaboration.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.ADD_TEMPLATE_REQUEST(
  $collaboration_name,
  $template_alias,
  ['Collaborator3']
);
Copy

Exigences d’accès

Si vous n’utilisez pas le rôle SAMOOHA_APP_ROLE, vous devez utiliser un rôle auquel des privilèges ont été accordés en appelant l’une des procédures suivantes :

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('UPDATE', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

REMOVE_TEMPLATE

Schéma:

COLLABORATION

Requête asynchrone pour supprimer un modèle d’une collaboration donnée pour des collaborateurs spécifiés. Seul le collaborateur qui a enregistré le modèle peut supprimer un modèle. Aucune approbation n’est nécessaire pour supprimer un modèle que vous avez enregistré. Lorsqu’un modèle est supprimé pour un collaborateur, ce collaborateur ne peut pas voir ou visualiser le modèle.

Syntaxe

REMOVE_TEMPLATE( <collaboration_name>, <template_id>, <remove_for> )
Copy

Arguments

collaboration_name

Nom de la collaboration à partir de laquelle le modèle doit être supprimé.

template_id

ID du modèle à supprimer de la collaboration.

remove_for

Tableau d’un ou plusieurs alias de gestionnaires d’analyses de cette collaboration qui ne devraient plus être en mesure de voir ou d’utiliser ce modèle.

Renvoie

Une chaîne représentant un message de réussite. Pour voir si un modèle a été supprimé pour un collaborateur, consultez les spécifications de la collaboration.

Exemple

-- Prevent collaborator_1234 from using the specified template
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.REMOVE_TEMPLATE(
  $collaboration_name,
  $template_id,
  ['collaborator_1234']
);
Copy

Exigences d’accès

Si vous n’utilisez pas le rôle SAMOOHA_APP_ROLE, vous devez utiliser un rôle auquel des privilèges ont été accordés en appelant l’une des procédures suivantes :

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('UPDATE', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

VIEW_TEMPLATES

Schéma:

COLLABORATION

Affiche tous les modèles que vous pouvez exécuter ou que vous avez soumis à la collaboration spécifiée.

Syntaxe

VIEW_TEMPLATES( <collaboration_name> )
Copy

Arguments

collaboration_name

Nom de la collaboration. Vous devez consulter ou rejoindre cette collaboration avant de pouvoir répertorier ses modèles.

Renvoie

Une table qui répertorie les informations sur les modèles que vous pouvez exécuter dans cette collaboration, y compris les modèles que vous avez enregistrés. Les informations comprennent l’ID du modèle (utilisé pour exécuter le modèle), le corps du modèle, les paramètres, qui l’a créé et qui peut l’exécuter.

Exemple

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_TEMPLATES(
  $collaboration_name
);
Copy

Exigences d’accès

Si vous n’utilisez pas le rôle SAMOOHA_APP_ROLE, vous devez utiliser un rôle auquel des privilèges ont été accordés en appelant l’une des procédures suivantes :

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('VIEW TEMPLATES', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('READ', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

ENABLE_TEMPLATE_AUTO_APPROVAL

Schéma:

COLLABORATION

Toutes les demandes de mise à jour des modèles envoyées par d’autres collaborateurs sont approuvées automatiquement. Les demandes apparaîtront toujours dans le journal des demandes. Cela concerne uniquement les demandes envoyées après l’activation de l’approbation automatique.

Syntaxe

ENABLE_TEMPLATE_AUTO_APPROVAL( <collaboration_name> )
Copy

Arguments

collaboration_name

Nom de la collaboration.

Renvoie

Une chaîne représentant un message de réussite.

Exemple

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.ENABLE_TEMPLATE_AUTO_APPROVAL(
  $collaboration_name
);
Copy

Exigences d’accès

Si vous n’utilisez pas le rôle SAMOOHA_APP_ROLE, vous devez utiliser un rôle auquel des privilèges ont été accordés en appelant l’une des procédures suivantes :

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('MANAGE TEMPLATE AUTO APPROVAL', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('UPDATE', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

DISABLE_TEMPLATE_AUTO_APPROVAL

Schéma:

COLLABORATION

Désactive l’approbation automatique des requêtes de modèles soulevées par d’autres collaborateurs. Toutes les requêtes futures doivent être approuvées manuellement en appelant APPROVE_UPDATE_REQUEST.

Syntaxe

DISABLE_TEMPLATE_AUTO_APPROVAL( <collaboration_name> )
Copy

Arguments

collaboration_name

Nom de la collaboration.

Renvoie

Une chaîne représentant un message de réussite.

Exemple

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.DISABLE_TEMPLATE_AUTO_APPROVAL(
  $collaboration_name
);
Copy

Exigences d’accès

Si vous n’utilisez pas le rôle SAMOOHA_APP_ROLE, vous devez utiliser un rôle auquel des privilèges ont été accordés en appelant l’une des procédures suivantes :

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('MANAGE TEMPLATE AUTO APPROVAL', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('UPDATE', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

Procédures relatives à l’offre de données

REGISTER_DATA_OFFERING

Schéma:

REGISTRY

Enregistre une offre de données afin qu’elle puisse être ajoutée à une définition de collaboration. Vous ne pouvez pas annuler l’enregistrement d’une offre de données enregistrée. Vous ne pouvez pas remplacer une offre de données existante, mais vous pouvez en enregistrer une nouvelle portant le même nom et affichant une nouvelle version. La création d’une nouvelle version d’une offre de données ne supprime pas les versions antérieures.

Chaque offre de données doit disposer d’un nom et d’une version uniques pour toutes les offres de données dans tous les registres de votre compte.

Si vous souhaitez partager cette table avec d’autres personnes au sein de la collaboration, ajoutez la table à la spécification de la collaboration avant que la collaboration ne soit créée.

Vous devez disposer du privilège OWNERSHIP sur toutes les données que vous partagez dans le cadre d’une collaboration. Si cela n’est pas le cas, vous obtiendrez une erreur de type « octroi d’utilisation de référence manquante » lorsque vous essayerez de rejoindre la collaboration ou d’enregistrer l’objet. Découvrez comment résoudre ce problème.

Syntaxe

REGISTER_DATA_OFFERING( ['<registry_name>' ,] <data_offering_spec> )
Copy

Arguments

registry_name (Facultatif)

Nom d’un registre personnalisé dans lequel enregistrer cette offre de données. Si non spécifié, enregistre l’offre de données dans le registre de comptes par défaut.

data_offering_spec

Une définition de l’offre de données en format YAML qui décrit cette offre de données.

Renvoie

L’ID d’offre de données à utiliser dans un champ data_offerings.id de collaboration.

Exemples

Enregistrer une offre de données dans le registre par défaut :

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.REGISTRY.REGISTER_DATA_OFFERING(
    $$
    api_version: 2.0.0
    spec_type: data_offering
    version: v1
    name: customers
    datasets:
     - alias: customers_1
       data_object_fqn: SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS
       allowed_analyses: template_only
       schema_and_template_policies:
         hashed_email:
           category: join_custom
         status:
           category: passthrough
    $$
  );
Copy

Enregistrer une offre de données dans un registre personnalisé :

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.REGISTRY.REGISTER_DATA_OFFERING(
    'my_custom_registry',
    $$
    api_version: 2.0.0
    spec_type: data_offering
    version: v1
    name: customers
    datasets:
     - alias: customers_1
       data_object_fqn: SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS
       allowed_analyses: template_only
       schema_and_template_policies:
         hashed_email:
           category: join_custom
         status:
           category: passthrough
    $$
  );
Copy

Exigences d’accès

Si vous n’utilisez pas le rôle SAMOOHA_APP_ROLE, vous devez utiliser un rôle qui s’est vu accorder des privilèges en appelant la procédure suivante :

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('REGISTER DATA OFFERING', 'role name')

VIEW_REGISTERED_DATA_OFFERINGS

Schéma:

REGISTRY

Répertorie toutes les offres de données que vous avez enregistrées. Pour voir les offres de données dans une collaboration ajoutée par d’autres personnes, appelez COLLABORATION.VIEW_DATA_OFFERINGS.

Syntaxe

VIEW_REGISTERED_DATA_OFFERINGS( [ '<registry_name>' ] )
Copy

Arguments

registry_name (Facultatif)

Nom d’un registre personnalisé dans lequel enregistrer cette offre de données. Si non spécifié, enregistre l’offre de données dans le registre de comptes par défaut.

Renvoie

Une table qui répertorie toutes les offres de données que vous avez enregistrées avec ce compte.

Exemple

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.REGISTRY.VIEW_REGISTERED_DATA_OFFERINGS();
Copy

Exigences d’accès

Si vous n’utilisez pas le rôle SAMOOHA_APP_ROLE, vous devez utiliser un rôle auquel des privilèges ont été accordés en appelant l’une des procédures suivantes :

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('VIEW REGISTERED DATA OFFERINGS', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

VIEW_DATA_OFFERINGS

Schéma:

COLLABORATION

Répertorie toutes les offres de données présentes dans une collaboration spécifiée auxquelles vous pouvez accéder en tant que gestionnaire d’analyses ou que vous avez ajoutées vous-même. Pour voir uniquement les offres de données que vous avez enregistrées, appelez REGISTRY.VIEW_REGISTERED_DATA_OFFERINGS.

Vous pouvez voir les offres de données du collaborateur X uniquement après que X a rejoint la collaboration.

Syntaxe

VIEW_DATA_OFFERINGS( <collaboration_name> )
Copy

Arguments

collaboration_name

Nom de la collaboration à explorer.

Renvoie

Informations sur toutes les offres de données de la collaboration spécifiée. Le tableau comprend les colonnes suivantes :

  • FREEFORM_SQL_COLUMN_POLICIES : Une représentation JSON de toutes les politiques de colonnes de forme libre dans cette collaboration, classées par type de politique.

  • FREEFORM_SQL_VIEW_NAME : Nom de table complet utilisé dans les requêtes SQL de forme libre, lorsque l’ensemble de données prend en charge les requêtes SQL de forme libre. Cette cellule est vide si l’ensemble de données ne propose pas de requêtes SQL de forme libre.

  • SHARE_WITH : Qui peut utiliser les données dans une analyse. Si cette valeur est LOCAL, il s’agit d’un ensemble de données local qui n’est partagé avec aucun collaborateur, à l’exception de la partie qui héberge les données.

  • TEMPLATE_VIEW_NAME : Le nom de table complet utilisé dans un modèle lors de l’appel de COLLABORATION.RUN.

Exemple

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_DATA_OFFERINGS(
  $collaboration_name
);
Copy

Exigences d’accès

Si vous n’utilisez pas le rôle SAMOOHA_APP_ROLE, vous devez utiliser un rôle auquel des privilèges ont été accordés en appelant l’une des procédures suivantes :

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('VIEW DATA OFFERINGS', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('READ', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

Mettre à jour les procédures de demande

Ces procédures sont utilisées pour gérer les demandes de mise à jour de la collaboration qui nécessitent une approbation, telles que le flux ajouter un modèle.

VIEW_UPDATE_REQUESTS

Schéma:

COLLABORATION

Consultez toutes les demandes de mise à jour que vous avez créées ou que vous pouvez approuver ou refuser, dans la collaboration spécifiée. L’enregistrement d’une demande de mise à jour peut prendre quelques secondes, de sorte que vous ne verrez peut-être pas une demande que vous venez d’envoyer il y a un moment.

Voir le flux d’ajout de modèles.

Syntaxe

VIEW_UPDATE_REQUESTS( <collaboration_name> )
Copy

Arguments

collaboration_name

Nom de la collaboration.

Renvoie

Une table des demandes de mise à jour envoyées dans cette collaboration. Informations comprises

  • ID : l’ID de la requête. Utilisez cette information pour approuver ou refuser une demande.

  • TYPE : Type de requête. Les valeurs suivantes sont prises en charge :

    • « Ajouter un modèle »

  • STATUS : Statut actuel de la demande. Les statuts suivants peuvent être signalés :

    • REJECTED : Un utilisateur de la collaboration a rejeté cette demande.

    • PENDING : La demande est en attente de votre approbation ou de votre rejet.

    • AWAITING_PARTNER_APPROVAL : Vous avez approuvé la demande, mais celle-ci doit encore être approuvée par un ou plusieurs autres collaborateurs.

    • APPROVED : Tous les approbateurs requis ont approuvé la requête et la modification a été appliquée à la collaboration.

  • APPROVAL_LOG : Journal de toutes les approbations et de tous les rejets de la demande. Si la demande est rejetée, la raison invoquée par la partie qui l’a rejetée est également fournie ici.

  • DETAILS : Détails spécifiques au type de demande, tels que le nom du modèle, sa description et les personnes avec lesquelles il est partagé pour une demande « Ajouter un modèle ».

  • SPEC : Les détails de la ressource en cours de mise à jour, comme la spécification du modèle pour une demande « Ajouter un modèle ».

  • UPDATED_ON : L’horodatage de la dernière action entreprise sur cette demande (par exemple, une approbation ou un rejet).

Exemple

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_UPDATE_REQUESTS(
  $collaboration_name
);
Copy

Exigences d’accès

Si vous n’utilisez pas le rôle SAMOOHA_APP_ROLE, vous devez utiliser un rôle auquel des privilèges ont été accordés en appelant l’une des procédures suivantes :

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('UPDATE', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('READ', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

APPROVE_UPDATE_REQUEST

Schéma:

COLLABORATION

Approuve une demande de mise à jour de la collaboration. Consultez la liste des demandes en attente en appelant VIEW_UPDATE_REQUESTS. Une fois que vous avez approuvé une demande, vous ne pouvez pas la rejeter ultérieurement.

Tous les collaborateurs concernés doivent approuver une demande avant que la modification ne soit effectivement appliquée à la collaboration.

Voir le flux d’ajout de modèles.

Syntaxe

APPROVE_UPDATE_REQUEST( <collaboration_name>, <request_id> )
Copy

Arguments

collaboration_name

Nom de la collaboration.

request_id

L’ID de la requête.

Renvoie

Une chaîne représentant un message de réussite.

Exemple

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.APPROVE_UPDATE_REQUEST(
  $collaboration_name,
  $request_id
);
Copy

Exigences d’accès

Si vous n’utilisez pas le rôle SAMOOHA_APP_ROLE, vous devez utiliser un rôle auquel des privilèges ont été accordés en appelant l’une des procédures suivantes :

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('MANAGE UPDATE REQUEST', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('UPDATE', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

REJECT_UPDATE_REQUEST

Schéma:

COLLABORATION

Rejette une demande de mise à jour de la collaboration. Un seul rejet empêche l’application de la modification à la collaboration. Vous ne pouvez pas approuver une demande après l’avoir rejetée.

Syntaxe

REJECT_UPDATE_REQUEST( <collaboration_name>, <request_id>, <reason> )
Copy

Arguments

collaboration_name

Nom de la collaboration.

request_id

L’ID de la requête.

reason

Une description compréhensible expliquant pourquoi la demande a été rejetée. L’argument est obligatoire, mais vous pouvez soumettre une chaîne vide.

Renvoie

Une chaîne représentant un message de réussite.

Exemple

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.REJECT_UPDATE_REQUEST(
  $collaboration_name,
  'request_1324f934457',
  'Needs more cowbell'
);
Copy

Exigences d’accès

Si vous n’utilisez pas le rôle SAMOOHA_APP_ROLE, vous devez utiliser un rôle auquel des privilèges ont été accordés en appelant l’une des procédures suivantes :

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('MANAGE UPDATE REQUEST', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('UPDATE', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

Procédures de gestion de la collaboration

INITIALIZE

Schéma:

COLLABORATION

Le propriétaire appelle cette clause pour créer une collaboration. Après avoir appelé INITIALIZE, vous devez appeler JOIN pour mettre la collaboration à la disposition d’autres collaborateurs. Vous devez utiliser le même rôle pour appeler INITIALIZE et JOIN.

Soumettre une définition de collaboration avec la même valeur name en tant que collaboration existante génère une erreur.

La création d’une collaboration prend un certain temps, vous devez donc appeler GET_STATUS pour savoir quand la collaboration a été créée.

Une fois la collaboration créée, tous les collaborateurs répertoriés peuvent la voir lorsqu’ils appellent VIEW_COLLABORATIONS, et peuvent l’examiner et la rejoindre.

Syntaxe

INITIALIZE( <collaboration_spec> )
Copy

Arguments

collaboration_spec

Définition de la collaboration en format YAML, sous forme de chaîne.

Renvoie

Une table avec les colonnes suivantes :

  • COLLABORATION_NAME : Nom de la collaboration. Utilisez cette clause dans toutes les procédures qui nécessitent la spécification d’une collaboration.

  • MESSAGE : Informations sur la demande d’initialisation.

Exemples

L’exemple suivant crée une collaboration dont Alice est la propriétaire et peut exécuter une analyse à l’aide des données fournies par Bob.

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.INITIALIZE(
  $$
  api_version: 2.0.0
  spec_type: collaboration
  name: basic_collaboration
  owner: alice
  collaborator_identifier_aliases:
    alice: corp_id.account_id
    bob: corp2_id.account2_id
  analysis_runners:
    alice:
      data_providers:
        bob:
          data_offerings:
          - id: bob_data_v1
      templates:
      - id: alice_test_template_2026_01_12_V1
  $$
);
Copy

Exigences d’accès

Si vous n’utilisez pas le rôle SAMOOHA_APP_ROLE, vous devez utiliser un rôle qui s’est vu accorder des privilèges en appelant la procédure suivante :

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

Voir GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE pour les autorisations de rôle supplémentaires requises.

TEARDOWN

Schéma:

COLLABORATION

Appelée par le propriétaire pour supprimer une collaboration pour toutes les parties.

Vous devez appeler cette procédure deux fois. Appelez-la une fois, puis appelez GET_STATUS jusqu’à ce qu’elle renvoie LOCAL_DROP_PENDING, puis appelez à nouveau cette procédure.

Note

Cette procédure ne peut être appelée que sur une collaboration que vous avez créée et rejointe. Si vous avez créé la collaboration, mais que vous ne l’avez pas encore rejointe, vous devez la rejoindre avant de pouvoir la supprimer.

Syntaxe

TEARDOWN( <collaboration_name> )
Copy

Arguments

collaboration_name

Nom de la collaboration à supprimer.

Renvoie

Une chaîne représentant un message de réussite.

Exemple

-- Start the process.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.TEARDOWN($collaboration_name);

-- Call until it returns LOCAL_DROP_PENDING.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.GET_STATUS($collaboration_name);

-- Final call.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.TEARDOWN($collaboration_name);
Copy

Exigences d’accès

Si vous n’utilisez pas le rôle SAMOOHA_APP_ROLE, vous devez utiliser un rôle auquel des privilèges ont été accordés en appelant l’une des procédures suivantes :

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

Voir GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE pour les autorisations de rôle supplémentaires requises.

GET_STATUS

Schéma:

COLLABORATION

Affiche des informations sur tous les collaborateurs d’une collaboration donnée.

Lors de l’exécution d’une opération asynchrone telle que la création ou la jointure d’une collaboration, vous devez vérifier le statut pour savoir quand la dernière opération a été terminée avant de pouvoir effectuer des actions supplémentaires sur cette collaboration, telles que l’exécution d’analyses. Cette procédure peut être appelée par tout collaborateur invité à une collaboration.

Syntaxe

GET_STATUS( <collaboration_name> )
Copy

Arguments

collaboration_name

Nom de la collaboration dont vous souhaitez consulter le statut. Vous pouvez afficher la liste de vos collaborations en appelant COLLABORATION.VIEW_COLLABORATIONS. Vous devez être invité à rejoindre une collaboration, ou l’avoir rejointe, avant de pouvoir appeler GET_STATUS.

Renvoie

Une table qui indique les détails de la dernière tentative de jointure pour tous les collaborateurs de la collaboration spécifiée. Le tableau comprend les colonnes suivantes :

  • UPDATED_ON : Horodatage lorsque le statut a été signalé par le système.

  • COLLABORATOR_ACCOUNT : ID de compte de partage de données de ce collaborateur.

  • COLLABORATOR_NAME : L’alias du collaborateur, tel que déclaré dans la spécification de la collaboration.

  • COLLABORATOR_ROLES : Les rôles réels et potentiels de ce collaborateur. Les valeurs incluent owner, data_provider, analysis_runner.

  • STATUS : Statut au moment de la mise à jour. Les valeurs suivantes sont prises en charge et indiquent le statut du collaborateur nommé dans la collaboration spécifiée.

    • CREATING : La création de la collaboration a commencé.

    • CREATE_FAILED : Échec de la création de la collaboration.

    • CREATED : La collaboration a été créée et est prête à fonctionner.

    • INVITED : Le participant a été invité.

    • REVIEWING : Examen en cours de la collaboration.

    • JOINING : Le processus de jointure a commencé.

    • JOIN_FAILED : Le processus de jointure a échoué.

    • JOINED : Vous avez bien joint la collaboration.

    • INVITE_STARTED : Le processus d’invitation a commencé.

    • INVITE_ACCEPTED : L’invitation a été acceptée.

    • LEAVING : Le processus de départ a commencé.

    • LEAVE_FAILED : Échec du processus de départ.

    • LEFT : A quitté la collaboration avec succès.

    • LOCAL_DROP_PENDING : Votre demande de quitter la collaboration a bien été enregistrée. Finalisez le processus en appelant TEARDOWN ou LEAVE à nouveau.

    • DROPPING : Le processus visant à quitter la collaboration a commencé.

    • DROPPED : Collaboration quittée avec succès.

    • DROP_FAILED : Échec du processus visant à quitter la collaboration.

Exemple

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.GET_STATUS(
  $collaboration_name
);
Copy

Exigences d’accès

Si vous n’utilisez pas le rôle SAMOOHA_APP_ROLE, vous devez utiliser un rôle auquel des privilèges ont été accordés en appelant l’une des procédures suivantes :

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('READ', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

ENABLE_EXTERNAL_TABLE_ANALYSIS_FOR_COLLABORATION

Schéma:

ADMIN

Active les tables externes et Apache Iceberg™ à utiliser pour exécuter une analyse de votre compte. Un gestionnaire d’analyse doit appeler cette clause avant d’exécuter une analyse qui inclut des tables externes ou Iceberg. Cette procédure est appelée une fois par collaboration, et non une fois par analyse.

Syntaxe

ENABLE_EXTERNAL_TABLE_ANALYSIS_FOR_COLLABORATION( <collaboration_name> )
Copy

Arguments

collaboration_name

Nom de la collaboration.

Renvoie

Une chaîne représentant un message de réussite.

Exemple

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.ADMIN.ENABLE_EXTERNAL_TABLE_ANALYSIS_FOR_COLLABORATION(
  $collaboration_name
);
Copy

Exigences d’accès

Si vous n’utilisez pas le rôle SAMOOHA_APP_ROLE, vous devez utiliser un rôle auquel le privilège MANAGE FIREWALL CONFIGURATION a été accordé pour appeler cette procédure.

VIEW_COLLABORATIONS

Schéma:

COLLABORATION

Affichez les informations relatives aux collaborations que vous avez créées, que vous pouvez consulter ou auxquelles vous avez participé.

Syntaxe

VIEW_COLLABORATIONS()
Copy

Arguments

Aucun

Renvoie

Une table qui répertorie les détails de toutes les collaborations auxquelles vous pouvez accéder. Le tableau comprend les colonnes suivantes :

  • SOURCE_NAME : Le nom de la collaboration, tel qu’indiqué par la valeur name dans la spécification de collaboration.

  • COLLABORATION_NAME : Nom de la collaboration installée. Valeur NULL jusqu’à ce que la collaboration soit installée en appelant JOIN (propriétaires) ou REVIEW (non-propriétaires).

  • OWNER_ACCOUNT : ID de partage de données du compte qui a créé la collaboration.

  • UPDATED_ON : Quand la collaboration a été mise à jour pour la dernière fois.

  • COLLABORATION_SPEC : La spécification de cette collaboration au format YAML. Affiche la dernière version de la collaboration, y compris toutes les ressources ajoutées ou supprimées après la création de la collaboration. Toutefois, il peut y avoir des demandes de mise à jour en cours qui seront bientôt ajoutées, telles que des modèles ou des offres de données nouveaux ou supprimés.

Exemples

Affichez toutes les collaborations :

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_COLLABORATIONS();
Copy

Affichez la spécification d’une collaboration donnée par son nom :

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_COLLABORATIONS() ->>
SELECT "COLLABORATION_SPEC" FROM $1 WHERE "SOURCE_NAME" = $collaboration_name;
Copy

Exigences d’accès

Si vous n’utilisez pas le rôle SAMOOHA_APP_ROLE, vous devez utiliser un rôle auquel des privilèges ont été accordés en appelant l’une des procédures suivantes :

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('READ', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('RUN', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('VIEW COLLABORATIONS', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

REVIEW

Schéma:

COLLABORATION

Fournit des détails sur une collaboration à laquelle vous avez été invité. Appelez COLLABORATION.VIEW_COLLABORATIONS pour voir les collaborations auxquelles vous avez été invité et que vous n’avez pas encore rejointe. Tous les collaborateurs, à l’exception du propriétaire, doivent appeler cette procédure avant d’appeler JOIN. Vous ne pouvez pas appeler cette procédure sur une collaboration que vous avez rejointe. Vous devez utiliser le même rôle pour appeler REVIEW et JOIN. Si votre compte se trouve au sein d’une région d’hébergement Cloud différente de celle du propriétaire, vous devrez peut-être appeler cette procédure plusieurs fois jusqu’à ce qu’elle renvoie une réponse réussie.

Cette procédure installe l’application sous-jacente dans votre compte.

Remarques importantes :

  • Les propriétaires ne peuvent pas appeler REVIEW sur leurs propres collaborations.

  • Tout le monde, sauf le propriétaire, doit appeler REVIEW avant d’appeler JOIN.

  • Après avoir rejoint une collaboration, vous ne pouvez pas appeler REVIEW à nouveau.

Syntaxe

REVIEW( <source_name>, <owner_account> )
Copy

Arguments

source_name

Nom de la collaboration à laquelle vous avez été invité à participer. Vous pouvez afficher la liste de vos collaborations en appelant COLLABORATION.VIEW_COLLABORATIONS.

owner_account

Identificateur du compte de partage de données du propriétaire. Vous pouvez le trouver dans la réponse à COLLABORATION.VIEW_COLLABORATIONS.

Renvoie

Table d’informations sur la collaboration, y compris l’ID de collaboration, le propriétaire et la spécification de collaboration.

Si votre compte se situe dans une région d’hébergement Cloud différente que celle du propriétaire de la collaboration, REVIEW peut renvoyer un message indiquant que des étapes de configuration supplémentaires sont encore en cours d’exécution. Si vous obtenez ce message, continuez d’appeler REVIEW jusqu’à ce que la table d’informations sur la collaboration soit renvoyée.

Exemple

-- View the collaboration for your own usage.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.REVIEW(
  $collaboration_name,
  'org1.account1234'
);
Copy

Exigences d’accès

Si vous n’utilisez pas le rôle SAMOOHA_APP_ROLE, vous devez utiliser un rôle auquel des privilèges ont été accordés en appelant l’une des procédures suivantes :

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

Voir GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE pour les autorisations de rôle supplémentaires requises.

JOIN

Schéma:

COLLABORATION

Méthode asynchrone pour rejoindre une collaboration spécifiée. Notez que vous ne pouvez accéder qu’aux ressources répertoriées dans la collaboration au moment de la jointure. L’exécution de cette procédure prend un certain temps.

Vous devez disposer du privilège de compte REGISTER DATA OFFERING pour rejoindre toute collaboration dans laquelle vous pouvez activer des données (c’est-à-dire que vous êtes un gestionnaire d’analyses et que la spécification de la collaboration inclut un champ activation_destinations). Voir le guide de référence de l’API de gestion des accès.

Vous ne pouvez pas avoir de rôle secondaire actif lorsque vous exécutez cette procédure. Exécutez le code SQL suivant pour désactiver tout rôle secondaire :

USE SECONDARY ROLES NONE;
Copy

Tout le monde, à l’exception du créateur de la collaboration, doit appeler COLLABORATION.REVIEW avant d’appeler cette procédure.

Cette procédure est asynchrone ; appelez GET_STATUS pour déterminer quand vous avez réussi à rejoindre la collaboration.

Toute personne qui soumet une ressource à la collaboration ou qui souhaite exécuter un modèle dans la collaboration (y compris le créateur de la collaboration) doit d’abord rejoindre la collaboration.

Syntaxe

JOIN( <collaboration_name> )
Copy

Arguments

collaboration_name

Nom de la collaboration à rejoindre. Vous pouvez afficher la liste de vos collaborations en appelant COLLABORATION.VIEW_COLLABORATIONS. Si vous avez été invité à rejoindre plusieurs collaborations portant le même nom, le système sélectionne par défaut la dernière sur laquelle vous avez appelé COLLABORATION.REVIEW.

Renvoie

Une chaîne représentant un message de réussite. Si vous obtenez une erreur concernant l’absence d’autorisation d’utilisation de référence, consultez le guide de dépannage.

Exemple

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.JOIN(
  $collaboration_name
);
Copy

Exigences d’accès

Si vous n’utilisez pas le rôle SAMOOHA_APP_ROLE, vous devez utiliser un rôle auquel des privilèges ont été accordés en appelant l’une des procédures suivantes :

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

Voir GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE pour les autorisations de rôle supplémentaires requises.

LEAVE

Schéma:

COLLABORATION

Quitte une collaboration que vous avez rejointe. Vous ne pouvez pas rejoindre à nouveau une collaboration après l’avoir quittée.

Vous devez appeler cette procédure deux fois. Appelez-la une fois, puis appelez GET_STATUS jusqu’à ce qu’elle renvoie LOCAL_DROP_PENDING, puis appelez à nouveau cette procédure.

Syntaxe

LEAVE( <collaboration_name> )
Copy

Arguments

collaboration_name

Nom de la collaboration à quitter.

Renvoie

Une chaîne représentant un message de réussite.

Exemple

-- Start the process.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.LEAVE($collaboration_name);

-- Call until it returns LOCAL_DROP_PENDING.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.GET_STATUS($collaboration_name);

-- Final call.
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.LEAVE($collaboration_name);
Copy

Exigences d’accès

Si vous n’utilisez pas le rôle SAMOOHA_APP_ROLE, vous devez utiliser un rôle auquel des privilèges ont été accordés en appelant l’une des procédures suivantes :

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

Voir GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE pour les autorisations de rôle supplémentaires requises.

Exécution d’analyses et d’activations

RUN

Schéma:

COLLABORATION

Effectue une analyse dans la salle blanche des données. Vous pouvez transmettre les détails de l’exécution soit sous forme de paramètres individuels, soit en transmettant une analyse de chaîne de spécifications YAML.

Lisez la référence consumer.run_analysis pour obtenir des informations générales sur l’exécution d’un modèle dans une salle blanche de données.

Il existe deux versions de cette procédure : l’une qui prend les arguments d’exécution comme une seule chaîne au format YAML, et une qui prend les arguments comme paramètres individuels.

Syntaxe d’argument YAML

RUN( <collaboration_name>, <analysis_spec> )
Copy
Arguments
collaboration_name

Nom de la collaboration dans laquelle cette analyse doit être exécutée.

analysis_spec

Définition de l’analyse au format YAML sous forme de chaîne, décrivant le modèle, les tables et les valeurs de modèle à utiliser dans cette analyse.

Syntaxe des paramètres explicites

RUN( <collaboration_name>, <template_id>, <template_view_names>, <local_template_view_names>, <arguments> )
Copy
Arguments
collaboration_name

Nom de la collaboration dans laquelle cette analyse doit être exécutée.

template_id

ID du modèle à exécuter.

template_view_names

Tableau de noms de chaînes des tables sources à utiliser dans l’analyse. Utilisez les noms de table renvoyés par VIEW_DATA_OFFERINGS dans la colonne TEMPLATE_VIEW_NAME. Le format pour chaque entrée est user_alias.data_offering_id.dataset_alias

local_template_view_names

Tableau des IDs de chaîne de vos propres tables à utiliser dans l’analyse. Vous devez d’abord associer ces tables en appelant LINK_LOCAL_DATA_OFFERING.

arguments

Objet JSON qui contient des arguments nommés utilisés par le modèle, où chaque clé est un nom d’argument du modèle, et la valeur est la valeur de cet argument.

Renvoie

Résultats de l’analyse au format de table.

Exemples

Exemple de transmission de paramètres :

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.RUN(
  $collaboration_name,
  $template_name,
  ['Provider.data_offering_1_2026_01_12_v0.test_dataset'], -- Tables to pass to source_tables variable.
  [],
  {} -- Template takes no parameters.
);
Copy

Exigences d’accès

Si vous n’utilisez pas le rôle SAMOOHA_APP_ROLE, vous devez utiliser un rôle auquel des privilèges ont été accordés en appelant l’une des procédures suivantes :

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('RUN', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

VIEW_ACTIVATIONS

Schéma:

COLLABORATION

Affiche le statut d’activation de toute exécution d’analyse que vous avez déclenchée pour envoyer à un collaborateur ou des activations qu’un collaborateur a déclenché pour vous envoyer. Les demandes d’activation pour vous envoyer des données ne sont pas répertoriées.

Pour en savoir plus sur l’activation, voir Activer les résultats de la requête.

Syntaxe

VIEW_ACTIVATIONS( <collaboration_name> )
Copy

Arguments

collaboration_name

Nom de la collaboration.

Renvoie

Une table contenant des détails pour chaque activation. Le tableau comprend les colonnes suivantes :

  • UPDATED_ON : Heure à laquelle le statut a été mis à jour pour la dernière fois.

  • SEGMENT_NAME : Chaîne arbitraire attribuée par le gestionnaire d’analyses pour identifier cette activation. Pour plus d’informations, voir Activating query results.

  • ACTIVATION_ID : ID de cette demande d’activation. Pour plus d’informations, voir Vue des résultats de l’activation des fournisseurs et des consommateurs.

  • TEMPLATE_ID : Modèle utilisé pour produire ces données d’activation.

  • SHARED_BY : Le collaborateur qui a exécuté l’analyse.

  • SHARED_WITH : Le collaborateur qui doit recevoir les données d’analyse.

  • STATUS : Statut de l’activation. Les valeurs suivantes sont prises en charge :

    • PENDING : L’activation a été demandée, mais est en attente de traitement.

    • SHARED : Les données d’activation sont prêtes à être traitées. Appelez PROCESS_ACTIVATION pour envoyer les résultats sur votre compte.

    • FAILED : Le traitement de l’activation a échoué. Voir les informations dans la colonne DETAILS.

    • PROCESSED : Les résultats de l’activation ont été envoyés au compte spécifié dans la demande d’activation.

  • DETAILS : Détails relatifs à l’échec, si l’activation a échoué.

Exemple

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.VIEW_ACTIVATIONS(
  $collaboration_name
);
Copy

Exigences d’accès

Si vous n’utilisez pas le rôle SAMOOHA_APP_ROLE, vous devez utiliser un rôle auquel des privilèges ont été accordés en appelant l’une des procédures suivantes :

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('VIEW ACTIVATIONS', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('RUN', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

PROCESS_ACTIVATION

Schéma:

COLLABORATION

Si le gestionnaire d’analyses envoie des données sur le compte d’un autre collaborateur, ce dernier doit appeler PROCESS_ACTIVATION pour importer les données d’activation dans leur compte. Le collaborateur doit appeler VIEW_ACTIVATIONS et attendre que la sortie indique que le statut d’activation d’un segment donné est SHARED avant d’appeler PROCESS_ACTIVATION.

Syntaxe

PROCESS_ACTIVATION( <collaboration_name>, <segment_name> )
Copy

Arguments

collaboration_name

Nom de la collaboration.

segment_name

Une chaîne arbitraire attribuée pour identifier cette activation dans la table de résultats. Le nom du segment est attribué dans la requête d’analyse, à l’aide de template_configuration.arguments.segment_name. Pour plus d’informations, voir Activating query results.

Renvoie

Nom de la table dans laquelle l’utilisateur peut récupérer les résultats, et nom du segment spécifié pour les résultats. Voir Activer les résultats de la requête pour découvrir comment lire les résultats.

Exemple

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.COLLABORATION.PROCESS_ACTIVATION(
  $collaboration_name,
  'q1_2025_segment'
);
Copy

Exigences d’accès

Si vous n’utilisez pas le rôle SAMOOHA_APP_ROLE, vous devez utiliser un rôle auquel des privilèges ont été accordés en appelant l’une des procédures suivantes :

  • GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE('PROCESS ACTIVATION', 'COLLABORATION', 'collaboration name', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE COLLABORATION', 'role name')

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('JOIN COLLABORATION', 'role name')

Procédures de gestion des registres

CREATE_REGISTRY

Schéma:

REGISTRY

Crée un registre personnalisé pour organiser les ressources telles que les modèles et les offres de données. Un registre personnalisé peut stocker des ressources d’un seul type, désignées lors de la création du registre.

Utilisez des registres personnalisés pour regrouper les ressources associées séparément du registre local par défaut. Ajoutez des ressources à ce registre en utilisant le paramètre facultatif de nom de registre.

Syntaxe

CREATE_REGISTRY( '<registry_name>', <registry_type> )
Copy

Arguments

registry_name

Nom du registre à créer. Doit être un nom unique parmi tous les registres du compte.

registry_type

Le type de ressources que ce registre contiendra. Valeurs prises en charge : TEMPLATE, DATA-OFFERING.

Renvoie

Une chaîne représentant un message de réussite.

Exemple

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.REGISTRY.CREATE_REGISTRY(
  'my_custom_registry',
  'TEMPLATE'
);
Copy

Exigences d’accès

Si vous n’utilisez pas le rôle SAMOOHA_APP_ROLE, vous devez utiliser un rôle qui s’est vu accorder des privilèges en appelant la procédure suivante :

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE REGISTRY', 'role name')

DROP_REGISTRY

Schéma:

REGISTRY

Supprime un registre personnalisé et annule l’enregistrement de tous les objets qu’il contient. Vous ne pouvez supprimer que les registres que vous avez créés.

Syntaxe

DROP_REGISTRY( '<registry_name>' )
Copy

Arguments

registry_name

Nom du registre à supprimer.

Renvoie

Une chaîne représentant un message de réussite.

Exemple

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.REGISTRY.DROP_REGISTRY(
  'my_custom_registry'
);
Copy

Exigences d’accès

Si vous n’utilisez pas le rôle SAMOOHA_APP_ROLE, vous devez utiliser un rôle qui s’est vu accorder des privilèges en appelant la procédure suivante :

  • GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE('CREATE REGISTRY', 'role name')

Procédures de gestion des accès

Le rôle SAMOOHA_APP_ROLE donne accès à toutes les procédures d’API de collaboration DCR. Toutefois, si un administrateur souhaite accorder des privilèges plus granulaires à des rôles spécifiques, vous pouvez créer un rôle et lui accorder des privilèges spécifiques à l’aide des procédures décrites dans cette section.

Pour en savoir plus sur l’octroi d’accès, consultez Gérer l’accès à l’API de collaboration DCR.

Les procédures suivantes sont utilisées pour gérer l’accès affiné à l’API de salle blanche de données Snowflake :

GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE

Schéma:

ADMIN

Accorde les droits pour appeler des procédures spécifiques sur un objet spécifique à un rôle spécifique. Le type d’objet est défini à l’aide de l’argument OBJECT_TYPE.

Vous pouvez appeler cette procédure plusieurs fois pour accorder plusieurs autorisations au même rôle. Exécutez cette procédure en utilisant le rôle qui possède l’objet.

Syntaxe

GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE(
  <privilege>,
  <object_type>,
  <object_name>,
  <account_role_name> )
Copy

Arguments

privilege

L’autorisation qui doit être accordée à ce rôle. Consultez le tableau ci-dessous pour savoir quels privilèges sont disponibles pour quels objets.

object_type

Le type d’objet pour lequel ce rôle se voit attribuer des autorisations. Valeurs prises en charge :

  • COLLABORATION

  • REGISTRY

object_name

L’ID de l’objet, tel que spécifié dans la spécification de l’objet.

account_role_name

Le rôle attribué.

Les combinaisons de privilèges et de types d’objets suivantes sont prises en charge :

Privilège

Type d’objet

Procédures activées

READ

COLLABORATION

VIEW_COLLABORATIONS, GET_STATUS, VIEW_DATA_OFFERINGS, VIEW_UPDATE_REQUESTS, VIEW_TEMPLATES

RUN

COLLABORATION

RUN, VIEW_ACTIVATIONS, VIEW_COLLABORATIONS

UPDATE

COLLABORATION

LINK_DATA_OFFERING, UNLINK_DATA_OFFERING, LINK_LOCAL_DATA_OFFERING, UNLINK_LOCAL_DATA_OFFERING, ADD_TEMPLATE_REQUEST, REMOVE_TEMPLATE, APPROVE_UPDATE_REQUEST, REJECT_UPDATE_REQUEST, ENABLE_TEMPLATE_AUTO_APPROVAL, DISABLE_TEMPLATE_AUTO_APPROVAL, VIEW_UPDATE_REQUESTS

READ

REGISTRY

Affichez les ressources enregistrées dans un registre personnalisé.

REGISTER

REGISTRY

Enregistrez des ressources telles que des modèles et des offres de données dans un registre personnalisé.

Renvoie

Une chaîne représentant un message de réussite.

Exemple

Cet exemple crée un rôle que les analystes peuvent utiliser pour exécuter des analyses dans une collaboration nommée my_collaboration et l’attribue à un utilisateur.

USE ROLE role_that_created_this_collaboration;

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.ADMIN.GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE(
  'RUN',
  'COLLABORATION',
  $collaboration_name,
  'collaborator_analyst_role'
);
GRANT ROLE collaborator_analyst_role to USER alexander_hamilton;
Copy

Exigences d’accès

Vous devez utiliser le même rôle que celui qui a créé l’objet pour appeler GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE sur cet objet.

GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE

Schéma:

ADMIN

Accorde des privilèges au niveau du compte à un rôle. Cette procédure permet à toute personne utilisant ce rôle d’appeler les procédures répertoriées pour ce privilège.

Syntaxe

GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE( <privilege>, <account_role_name> )
Copy

Arguments

privilege

Le privilège d’accorder ce rôle. Les valeurs de chaîne suivantes sont prises en charge :

  • JOIN COLLABORATION : Accorde l’autorisation d’exécuter COLLABORATION.JOIN ainsi que les procédures suivantes sur la collaboration jointe :

    • ADMIN.GRANT_PRIVILEGE_ON_OBJECT_TO_ROLE

    • COLLABORATION.ADD_TEMPLATE_REQUEST

    • COLLABORATION.APPROVE_UPDATE_REQUEST

    • COLLABORATION.ENABLE_TEMPLATE_AUTO_APPROVAL

    • COLLABORATION.DISABLE_TEMPLATE_AUTO_APPROVAL

    • COLLABORATION.REMOVE_TEMPLATE

    • COLLABORATION.GET_STATUS

    • COLLABORATION.LEAVE

    • COLLABORATION.LINK_DATA_OFFERING

    • COLLABORATION.LINK_LOCAL_DATA_OFFERING

    • COLLABORATION.PROCESS_ACTIVATION

    • COLLABORATION.REJECT_UPDATE_REQUEST

    • COLLABORATION.REVIEW

    • COLLABORATION.RUN

    • COLLABORATION.TEARDOWN

    • COLLABORATION.UNLINK_DATA_OFFERING

    • COLLABORATION.UNLINK_LOCAL_DATA_OFFERING

    • COLLABORATION.VIEW_ACTIVATIONS

    • COLLABORATION.VIEW_COLLABORATIONS

    • COLLABORATION.VIEW_DATA_OFFERINGS

    • COLLABORATION.VIEW_TEMPLATES

    • COLLABORATION.VIEW_UPDATE_REQUESTS

    • REGISTRY.VIEW_REGISTERED_DATA_OFFERINGS

    • REGISTRY.VIEW_REGISTERED_TEMPLATES

    Ce privilège nécessite que les privilèges de niveau compte suivants soient attribués manuellement au rôle :

    • APPLY ROW ACCESS POLICY

    • CREATE APPLICATION

    • CREATE DATABASE

    • CREATE LISTING

    • CREATE SHARE

    • IMPORT SHARE

    • MANAGE SHARE TARGET

  • CREATE COLLABORATION : Accorde l’autorisation d’exécuter COLLABORATION.INITIALIZE, ainsi que toutes les procédures autorisées par JOIN COLLABORATION pour la collaboration jointe. Exige que les privilèges suivants au niveau du compte soient attribués manuellement au rôle :

    • APPLY ROW ACCESS POLICY

    • CREATE APPLICATION

    • CREATE DATABASE

    • CREATE LISTING

    • CREATE SHARE

    • IMPORT SHARE

    • MANAGE SHARE TARGET

  • VIEW COLLABORATIONS : Accorde l’autorisation d’exécuter COLLABORATION.VIEW_COLLABORATIONS. Exige que les privilèges suivants soient attribués manuellement au rôle :

    • IMPORT SHARE

  • REGISTER DATA OFFERING : Accorde l’autorisation d’exécuter REGISTRY.REGISTER_DATA_OFFERING. Cette autorisation est nécessaire pour tout gestionnaire d’analyses pour rejoindre une collaboration qui met en œuvre l’activation.

  • VIEW REGISTERED DATA OFFERINGS : Accorde l’autorisation d’exécuter REGISTRY.VIEW_REGISTERED_DATA_OFFERINGS.

  • VIEW REGISTERED TEMPLATES : Accorde l’autorisation d’exécuter REGISTRY.VIEW_REGISTERED_TEMPLATES.

  • REGISTER TEMPLATE : Accorde l’autorisation d’exécuter REGISTRY.REGISTER_TEMPLATE.

  • CREATE REGISTRY : Accorde l’autorisation d’exécuter REGISTRY.CREATE_REGISTRY et REGISTRY.DROP_REGISTRY, ainsi que la possibilité de lire à partir de registres personnalisés.

  • MANAGE LISTING AUTO FULFILLMENT : Accorde l’autorisation à un collaborateur de rejoindre une collaboration dans une autre région d’hébergement Cloud. Pour plus d’informations, voir Activer l’exécution automatique inter-Cloud.

account_role_name

Le nom d’un rôle au niveau du compte.

Renvoie

Une chaîne représentant un message de réussite.

Exemple

USE ROLE ACCOUNTADMIN;
CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.ADMIN.GRANT_PRIVILEGE_ON_ACCOUNT_TO_ROLE(
  'REGISTER DATA OFFERING',
  'COLLABORATOR_ANALYST_ROLE'
);
Copy

Exigences d’accès

Vous devez disposer du rôle ACCOUNTADMIN pour exécuter cette procédure.