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

Les fournisseurs et les consommateurs peuvent ajouter des modèles personnalisés à une salle blanche. Les modèles personnalisés s’exécutent de la même manière que les modèles fournis par Snowflake.

Note

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.

L’exemple suivant montre comment un fournisseur ajoute un modèle personnalisé à une salle blanche :

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

Dans la plupart des modèles, y compris l’exemple précédent, les noms de colonnes doivent être entièrement qualifiés avec le nom du tableau afin d’éviter les conflits de noms de colonnes. En effet, il n’est pas facile de concaténer un préfixe de nom de tableau à un nom de colonne dans le préfixe et d’obtenir un identifiant valide (IDENTIFIER(p.{{col_name | sqlsafe }}) est une erreur). Par conséquent, vous pouvez demander à l’appelant de fournir un nom de tableau entièrement qualifié plutôt qu’un simple nom de colonne. Les noms de tableau doivent utiliser les alias approuvés p et c.

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.

Vous pouvez appeler consumer.get_arguments_from_template pour analyser et répertorier les variables utilisées dans un modèle. Cependant, pour les modèles volumineux ou complexes, cette procédure peut ne pas répertorier toutes les variables du modèle. Veuillez donc vous assurer de fournir une documentation utile aux utilisateurs de votre modèle.

L’exemple suivant montre comment un consommateur exécute le modèle personnalisé du fournisseur présenté précédemment :

 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',  -- hashed_email column from the consumer's table.
  'provider_id', 'p.hashed_email',  -- hashed_email column from the provider's table.
  'where_clause','c.status = $$MEMBER$$ AND c.age_band > 30' -- $$...$$ 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é :

  1. Le fournisseur crée, partage et publie une salle blanche de manière standard.

  2. Le consommateur installe et configure la salle blanche de manière standard.

  3. Le consommateur appelle consumer.create_template_request et transmet la chaîne du modèle personnalisé.

  4. Le fournisseur appelle provider.list_pending_template_requests pour voir les demandes en attente.

  5. Le fournisseur peut approuver (provider.approve_template_request) ou rejeter (provider.reject_template_request) la demande du consommateur d’exécuter son propre modèle. (Il existe également des versions groupées de ces méthodes pour approuver ou rejeter plusieurs demandes.) Si le fournisseur donne son approbation, le modèle est immédiatement ajouté à la salle blanche.

    • Si le fournisseur approuve le modèle, il doit ajouter toutes les politiques de jointure et de colonne nécessaires pour ce modèle et ses données. Si le fournisseur ne dispose pas d’une politique de jointure ou de colonne dans la salle blanche, par défaut, toutes les colonnes du fournisseur sont jointables et projetables.

  6. Le consommateur vérifie l’état de sa demande en appelant soit consumer.list_template_requests (qui affiche l’état, y compris celui de rejet avec une explication), soit consumer.view_added_templates (pour voir si son modèle a été ajouté à la salle blanche).

  7. Le consommateur ajoute éventuellement des stratégies de colonne pour le modèle.

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

Voici un exemple de code complet montrant comment un consommateur peut soumettre et exécuter un modèle personnalisé. Téléchargez les fichiers du classeur suivant dans votre compte Snowflake. Vous avez besoin de deux comptes distincts avec l’API des salles blanches pour exécuter le code : un compte pour agir en tant que fournisseur et l’autre pour agir en tant que consommateur.

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.

  • Les modifications apportées au modèle dans l’API se propagent rapidement et de manière fiable vers l’UI, vous n’avez donc pas besoin de créer une nouvelle salle blanche pour les modifications du modèle. Cependant, vous devez développer et effectuer un test sur votre modèle dans l’API :emph: avant d’atteindre la zone de préparation UI.

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

Langage: Français