Ajouter des modèles personnalisés à une salle blanche¶

Both providers and consumers can add custom templates to a clean room. Custom templates are run the same way as Snowflake-provided templates. Custom templates are created using the API, and are run using the API or (if designed for it) the UI.

Un modèle de salle blanche est un modèle JinjaSQL valide. Il est recommandé de lire le guide de référence des salles blanches pour les modèles personnalisés avant d’essayer de créer vos propres modèles de salle blanche.

Modèles personnalisés rédigés par le fournisseur¶

Les fournisseurs peuvent ajouter un modèle personnalisé à une salle blanche sans l’accord du consommateur. Les consommateurs peuvent exécuter un modèle rédigé par un fournisseur sans autorisation. Les sections suivantes décrivent comment un fournisseur peut ajouter un modèle personnalisé et comment un consommateur peut exécuter ce modèle à l’aide de l’API.

Si le fournisseur souhaite concevoir un modèle que le consommateur peut exécuter dans l’UI des salles blanches, il doit :ref:` créer un formulaire d’entrée utilisateur <label-dcr_define_user_form>` pour le modèle.

Ajouter un modèle rédigé par le fournisseur¶

Les fournisseurs ajoutent des modèles personnalisés un par un en appelant provider.add_custom_sql_template, en transmettant le modèle JinjaSQL sous forme de chaîne. Les modèles personnalisés apparaissent dans la liste des modèles de la salle blanche et se comportent de la même manière que les modèles fournis par Snowflake. Une salle blanche peut contenir n’importe quelle combinaison de modèles personnalisés et fournis par Snowflake.

Vous pouvez également télécharger des UDFs Python personnalisées pour que votre modèle puisse l’appeler.

Astuce

Lorsque vous ajoutez un modèle personnalisé destiné à être utilisé par les consommateurs, vous devez fournir une documentation décrivant ce que fait le modèle, ainsi que les arguments obligatoires et facultatifs utilisés par le modèle.

The following SQL example shows how a provider adds a simple custom template to a clean room:

CALL samooha_by_snowflake_local_db.provider.add_custom_sql_template(
    $cleanroom_name,
    $basic_template_name,
    $$
    SELECT
      COUNT(*) AS total_count
    FROM IDENTIFIER({{ my_table[0] }}) AS c
      INNER JOIN IDENTIFIER({{ source_table[0] }}) AS p
      ON IDENTIFIER({{ consumer_id | join_policy }}) = IDENTIFIER({{ provider_id | join_policy }})
    {% if where_clause %}
    WHERE {{ where_clause | sqlsafe }}
    {% endif %};
  $$
);

Copy

This template takes four required parameters (my_table array, source_table array, consumer_id column name, and provider_id column name) and an optional where_clause parameter that specifies a WHERE clause.

In most templates, including the previous example, column names provided by the user must be fully qualified with the table name to avoid column name conflicts. This is because it is not easy to concatenate a table name prefix to a column name in the prefix and get a valid identifier (IDENTIFIER(p.{{ col_name | sqlsafe }}) is an error). Therefore, you might need the caller to provide a fully qualified table name rather than just a column name. Table names should use the approved lowercases p and c aliases.

Exécuter un modèle écrit par un fournisseur¶

Lorsqu’ils utilisent l’API des salles blanches, les consommateurs appellent consumer.run_analysis pour exécuter un modèle, et les fournisseurs appellent provider.submit_analysis_request pour les analyses exécutées par le fournisseur.

Si vous souhaitez qu’un modèle puisse être exécuté dans l’UIdes salles blanches, le fournisseur doit créer un formulaire d’entrée utilisateur pour le modèle. Seuls les modèles écrits par le fournisseur peuvent être exécutés dans l’UI des salles blanches.

Les collaborateurs de la salle blanche peuvent voir le JinjaSQL de n’importe quel modèle dans une salle blanche en appelant consumer.view_template_definition, sauf si le fournisseur a obscurci le modèle. Seuls les modèles rédigés par le fournisseur peuvent être obscurcis.

You can call consumer.get_arguments_from_template to parse and list the variables used in a template. However, for large or complex templates this procedure might not list all template variables, so be sure to provide helpful documentation for your template users.

The following example shows how a consumer runs the provider’s custom template shown previously:

 CALL samooha_by_snowflake_local_db.consumer.run_analysis(
  $cleanroom_name,
  'basic_template',
  ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],  -- Populates the my_table array.
  ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],  -- Populates the source_table array.
  OBJECT_CONSTRUCT(
  'consumer_id', 'c.hashed_email',  -- Populates the consumer_id variable.
  'provider_id', 'p.hashed_email',  -- Populates the provider_id variable.
  'where_clause','c.status = $$MEMBER$$ AND c.age_band > 30' -- Populates the where_clause variable.
                                                             -- $$...$$ is used to stringify the column value.
  )
);

Copy

Exemple de code de modèle de fournisseur¶

Voici un exemple de code complet montrant comment un fournisseur ajoute un modèle personnalisé et comment le consommateur l’exécute. Vous avez besoin de deux comptes distincts avec l’API des salles blanches installée pour exécuter le code ; un compte pour agir en tant que fournisseur et l’autre compte pour agir en tant que consommateur.

Modèles personnalisés rédigés par le consommateur¶

Un consommateur peut ajouter un modèle personnalisé à la salle blanche si le fournisseur l’approuve. Une fois ajouté à la salle blanche, le modèle rédigé par le consommateur peut être exécuté de la même manière qu’un modèle rédigé par le fournisseur. Voici comment un consommateur ajoute un modèle personnalisé :

Le fournisseur crée, partage et publie une salle blanche de manière standard.
Le consommateur installe et configure la salle blanche de manière standard.
Le consommateur appelle consumer.create_template_request et transmet la chaîne du modèle personnalisé.
Le fournisseur appelle provider.list_pending_template_requests pour voir les demandes en attente.
The provider can approve (provider.approve_template_request) or reject (provider.reject_template_request) the consumer’s request to run their own template. (There are also bulk versions of these methods for approving or rejecting multiple requests.) If the provider approves the template, the template is added to the clean room immediately.
- Before the provider approves the template, the provider should first declare any necessary join and column policies on their data.
The consumer checks the status of their request by calling either consumer.list_template_requests (which shows the approval status) or consumer.view_added_templates (to see if their template was added to the clean room). A template is added to the clean room only after the provider approves it.
Le consommateur exécute le modèle en appelant consumer.run_analysis de manière standard.

Note

Un fournisseur peut exécuter un modèle ajouté par un consommateur si le consommateur accorde l’autorisation.

Exemple de modèle consommateur¶

Here is a full code example showing how a consumer can submit and run a custom template. Upload the following worksheet files into your Snowflake account. You need two separate accounts with the clean rooms API installed to run the code; one account to act as the provider and the other to act as the consumer.

Définir un formulaire d’entrée utilisateur pour un modèle personnalisé¶

Pour qu’un modèle personnalisé puisse être exécuté dans l’UI des salles blanches, le fournisseur doit définir un formulaire d’entrée pour le modèle. Cette exigence s’applique même si le modèle ne comporte aucun argument à définir par le consommateur. Les consommateurs ne peuvent pas définir de formulaire d’entrée utilisateur pour un modèle.

Important

Si vous avez utilisé provider.restrict_table_options_to_consumers ou provider.restrict_template_options_to_consumers pour restreindre les tables ou les modèles à des utilisateurs spécifiques, ces restrictions ne fonctionneront pas comme prévu dans l’UI des salles blanches . Il est déconseillé d’activer les modèles pour une utilisation UI dans les salles blanches avec ces restrictions.

Un formulaire de configuration permet aux utilisateurs de l’UI des salles blanches de transmettre des valeurs au modèle personnalisé, de la même manière que vous transmettez des valeurs à un modèle lorsque vous utilisez l’API.

L’exemple suivant montre un modèle personnalisé qui utilise trois variables, max_age, favorite_color et source_table :

CALL samooha_by_snowflake_local_db.provider.add_custom_sql_template(
  $cleanroom_name,
  'color_picker_template',
  $$
  SELECT p.hashed_email
    FROM source_table[0] AS p
    WHERE
      p.age <= {{ max_age }} AND
      UPPER(p.favorite_color) = UPPER({{ favorite_color }});
  $$);

Copy

L’exemple suivant montre comment transmettre les variables du modèle lorsque vous exécutez le modèle personnalisé précédent dans le code :

CALL samooha_by_snowflake_local_db.consumer.run_analysis(
  $cleanroom_name,
  'color_picker_template',
  [],                                   -- Consumer tables, assigned to my_table array.
  ['MYDB.MYSCH.COLOR_PREFERENCES'],     -- Provider tables, assigned to source_table array.
  object_construct(
    'max_age', 30,                      -- Assign max_age.
    'favorite_color', 'blue'            -- Assign favorite_color.
  )
);

Copy

Pour exécuter ce modèle dans l’UI des salles blanches, vous devez définir un formulaire dans lequel le consommateur attribue ces variables de modèle. L’exemple suivant montre comment définir un formulaire simple dans lequel le consommateur peut attribuer des valeurs à max_age, favorite_color et source_table :

CALL samooha_by_snowflake_local_db.provider.add_ui_form_customizations(
    $cleanroom_name,
    'color_picker_template',
    {                                     -- Top-level template settings.
      'display_name': 'Color matcher',
      'description': 'See which users like the same color as you',
      'methodology': 'Choose a color and a max age',
      'render_table_dropdowns': {
        'render_consumer_table_dropdown': false,
        'render_provider_table_dropdown': true    -- Show a dropdown of provider tables.
      }                                           -- Chosen value is assigned to source_table.
    },
    { -- Form entry elements, one per template argument.
      'max_age': {
        'type': 'integer',
        'display_name': 'Maximum age',
        'description': 'Matching user must be less than or equal to this value.',
        'required': TRUE
      },
      'favorite_color': {
        'type': 'dropdown',
        'display_name': 'Favorite color',
        'description': 'Choose the favorite color to match.',
        'choices': ['Red', 'Blue', 'Green', 'Yellow'],
        'required': TRUE
      }
    },
    {} -- Output config not used in this example.
);

-- You must always call this procedure to propagate UI changes.
CALL samooha_by_snowflake_local_db.provider.create_or_update_cleanroom_listing(
  $cleanroom_name);

Copy

Le formulaire défini précédemment apparaît dans l’UI des salles blanches lorsque le consommateur exécute le modèle à l’étape Configure Analysis & Query. Le formulaire comprend un sélecteur de table pour source_table, intitulé Collaborator table, un élément de sélection d’entier pour max_age intitulé Maximum age et un menu déroulant de noms de couleurs pour favorite_color intitulé Favorite color, comme illustré dans cette image :

Formulaire d'entrée utilisateur rendu avec sélecteurs de table, d'âge et de couleur.

Vous pouvez également définir des menus déroulants préremplis avec des colonnes provenant, entre autres, des politiques de jointure, des politiques de colonnes et des tables du fournisseur ou du consommateur. Pour plus d’informations sur les types d’éléments de formulaire, veuillez consulter add_ui_form_customizations.

Remplir `source_table` et `my_table`¶

Les variables de modèle standard source_table et my_table peuvent être remplies comme suit :

Activer les menus déroulants de sélection de table par défaut : Ces menus déroulants sont à sélection unique. Vous pouvez les afficher ou les masquer à l’aide des paramètres render_provider_table_dropdown et render_consumer_table_dropdown. Les menus déroulants transmettent les noms de tableau complets aux variables de modèle source_table et my_table, respectivement.

Qualifier vos noms de colonne¶

La plupart des modèles exigent que tous les noms de colonne soient complets afin d’éviter toute ambiguïté.

Le modèle doit attribuer à toutes les tables l’alias p ou c, selon qu’il s’agit de tables fournisseur ou consommateur. Le modèle doit référencer toutes les colonnes à l’aide de leurs alias p ou c. En savoir plus sur les alias

Si vous créez un sélecteur de colonne déroulant, vous devez soit fournir explicitement l’alias de table p ou c dans un tableau choices du menu déroulant, soit ajouter l’alias dans votre modèle.

L’exemple suivant montre comment fournir l’alias de table dans un menu déroulant :

  'provider_join_col': {
    'display_name': 'Provider Join Column',
    'choices': ['p.HASHED_EMAIL', 'p.HASHED_SSN'],
    'type': 'dropdown',
    'description': 'Select the provider column to join users on.',
    'infoMessage': 'We recommend using HASHED_EMAIL.',
    'size': 'M',
    'group': 'Enable Provider Features'
}

Copy

Cependant, cette méthode est limitée, car vous devez connaître tous les noms de colonnes à l’avance.

Vous pouvez également remplir dynamiquement un menu déroulant de colonnes en fournissant une propriété references. Cependant, un tel sélecteur renvoie des noms de colonnes bruts, par exemple hashed_email, plutôt que des noms de colonnes complets, par exemple p.hashed_email. Si des noms de colonnes bruts sont renvoyés, vous devez explicitement définir la colonne dans la table dans votre modèle. Par exemple, le code suivant crée un menu déroulant dans lequel l’utilisateur peut sélectionner une colonne à partir de la politique de jointure du fournisseur :

'p_join_col': {
  'type': 'dropdown',
  'references': ['PROVIDER_JOIN_POLICY']
}

Copy

Pour utiliser le nom de la colonne dans un modèle, celui-ci doit coder en dur l’alias de la table devant le nom de la colonne, comme indiqué dans l’exemple suivant :

SELECT p.{{ p_join_col | sqlsafe }} FROM table_col AS p;

Copy

Recommandations pour le développement d’un modèle pouvant être exécuté dans l’UI des salles blanches¶

Les étapes suivantes présentent un workflow recommandé pour le développement d’un modèle pouvant être exécuté dans l’UI des salles blanches :

1. Développez le modèle¶

Commencez par développer votre modèle et tous les :doc:`scripts </user-guide/cleanrooms/demo-flows/custom-code> ` qu’il appelle en utilisant uniquement l’API des salles blanches dans les comptes du fournisseur et du consommateur. Tester le modèle dans les API est beaucoup plus rapide et moins sujet aux erreurs que de consommer l’UI.

Testez votre modèle de manière approfondie dans l’API, tant du côté du fournisseur que du consommateur, afin de vous assurer que le modèle fait exactement ce que vous souhaitez. Les tests dans l’API sont très rapides et les modifications sont immédiatement répercutées sur le compte consommateur.

Une fois que vous avez testé votre modèle et qu’il fonctionne exactement comme vous le souhaitez, passez à la conception du formulaire d’entrée.

2. Développez le formulaire d’entrée¶

Lorsque le modèle et les scripts téléchargés fonctionnent comme prévu, commencez à travailler sur le formulaire d’entrée. À ce stade, vous utilisez l’API dans le compte fournisseur, mais l’UI dans le compte consommateur.

Lorsque vous apportez des modifications à l’aide de l’API, certaines valeurs de l’UI sont actualisées immédiatement, d’autres sont actualisées lorsque l’utilisateur clique sur Refresh, et d’autres encore ne sont actualisées que toutes les 10 minutes. Par conséquent, lorsque vous travaillez sur le formulaire d’entrée, créez et mettez à jour le formulaire côté fournisseur à l’aide de l’API, mais installez et configurez la salle blanche dans le compte consommateur à l’aide de l’UI des salles blanches, :emph:` et non de l’API`. Cela garantit que vous utilisez des données récentes dans l’UI de la salle blanche.

De plus, chaque fois que vous apportez des modifications au formulaire d’entrée dans l’API, créez une nouvelle salle blanche pour vous assurer que vous utilisez les dernières données de la salle blanche. Utilisez un numéro incrément dans le nom, par exemple « Ma salle blanche 1 », « Ma salle blanche 2 », etc. Ensuite, installez la salle blanche dans le client à l’aide de l’UI. Enfin, supprimez les anciennes salles blanches, car le nombre de salles blanches qu’un compte peut contenir est limité.

Un formulaire d’entrée doit être joint à un modèle, sinon la salle blanche et l’entrée ne pourront pas être exécutées dans l’UI des salles blanches. Lorsque vous développez votre entrée, envisagez d’utiliser un modèle qui reflète simplement toutes les valeurs sélectionnées dans l’entrée afin de pouvoir vérifier quelles valeurs sont envoyées au modèle.

Par exemple, supposons que votre modèle de production ressemble au modèle suivant :

SELECT {{ col1 | sqlsafe | column_policy }}, {{ col2 | sqlsafe | column_policy }}
  FROM IDENTIFIER({{ source_table[0] }}) AS p
  JOIN IDENTIFIER({{ my_table[0] }}) AS c

Copy

Vous pouvez créer le modèle suivant qui reflète toutes les valeurs de ce modèle de production :

SELECT
  {{ col1 | default('Undefined')}},
  {{ col2 | default('Undefined') }},
  {{ source_table[0] | default('Undefined') }},
  {{ my_table[0] | default('Undefined') }},
  {{ provider_join_col | default('Undefined') }},
  {{ consumer_join_col | default('Undefined') }}
;

Copy

Concevez ensuite un formulaire qui définit ces six valeurs variables et joignez le formulaire au modèle miroir plutôt qu’au modèle de production.

Conseils généraux pour le développement du formulaire d’entrée

La liste suivante fournit des conseils détaillés pour vous aider à développer un formulaire d’entrée efficace :

Si vous rencontrez un message générique « Échec de l’installation » ou « Une erreur s’est produite » lors de l’installation, de configurer ou de l’exécution d’une salle blanche dans l’UI, cela peut signifier qu’il y a une erreur dans le formulaire UI ou le modèle associé qui n’a pas été détectée lorsque vous avez ajouté le formulaire ou le modèle.
Lorsqu’un champ dépend d’un autre champ, par exemple un menu déroulant de colonne basé sur la valeur choisie dans un menu déroulant de tableau, placez le champ parent en premier, si possible juste au-dessus du champ enfant, afin que les utilisateurs remplissent le champ parent avant de remplir le champ enfant. Avec les champs dépendants, le menu déroulant enfant reste vide jusqu’à ce qu’une valeur soit choisie pour le champ parent.
Si vous ne spécifiez pas de valeur order ou group, les éléments sont affichés dans l’ordre dans lequel ils sont définis.
Incluez du texte informatif infoMessage et description et affichez des exemples de valeurs qu’un utilisateur pourrait saisir.
Choisissez le type d’élément précis pour le type de données variable. Par exemple, pour un entier, choisissez integer plutôt qu’une zone de texte libre. Votre modèle peut convertir des valeurs à l’aide de filtres Jinja ; par exemple : SELECT {{ max_age | int }};.
Si vous ne définissez pas de formulaire de configuration minimale pour un modèle personnalisé, le modèle ne peut pas être exécuté dans l’UI des salles blanches.
Si vous ne définissez pas d’élément de formulaire pour une variable dans le modèle, une zone de texte simple est affichée pour cette variable dans le formulaire utilisateur. Ce n’est probablement pas ce que vous souhaitez, car la zone de texte est étiquetée avec le nom de la variable du modèle et ne comporte aucune description ni suggestion.
Les éléments de formulaire spécifiés dans add_ui_form_customizations ne sont pas affichés, sauf s’il existe une variable de modèle correspondante portant le même nom que l’élément.
Template changes made in the API propagate quickly and reliably to the UI, so you don’t need to create a new clean room for template changes. However, you should develop and test your template in the API before you reach the UI stage.
Vous ne pouvez pas remplir automatiquement un menu déroulant avec les valeurs des colonnes d’un tableau donné. Vous pouvez coder en dur des valeurs dans un menu déroulant, mais vous ne pouvez pas afficher les valeurs d’une table lors de l’exécution.

3. Connectez le formulaire d’entrée au modèle de production¶

Une fois que le formulaire correspond exactement à ce que vous souhaitez et qu’il rend toutes les variables du modèle accessibles à l’utilisateur, attribuez votre modèle de travail au formulaire d’entrée dans votre appel à provider.add_ui_form_customizations.

Ajouter des modèles personnalisés à une salle blanche¶

Modèles personnalisés rédigés par le fournisseur¶

Ajouter un modèle rédigé par le fournisseur¶

Exécuter un modèle écrit par un fournisseur¶

Exemple de code de modèle de fournisseur¶

Modèles personnalisés rédigés par le consommateur¶

Exemple de modèle consommateur¶

Définir un formulaire d’entrée utilisateur pour un modèle personnalisé¶

Remplir source_table et my_table¶

Qualifier vos noms de colonne¶

Recommandations pour le développement d’un modèle pouvant être exécuté dans l’UI des salles blanches¶

1. Développez le modèle¶

2. Développez le formulaire d’entrée¶

3. Connectez le formulaire d’entrée au modèle de production¶

Remplir `source_table` et `my_table`¶