Création de modèles de clean room personnalisés¶

À propos des modèles de clean rooms¶

Les modèles Clean room sont rédigés en JinjaSQL. JinjaSQL est une extension de la langue de création de modèles Jinja qui génère une requête SQL en sortie. JinjaSQL prend en charge les instructions logiques et la résolution des variables au moment de l’exécution pour permettre à l’utilisateur de personnaliser la requête au moment de l’exécution. Les variables sont généralement utilisées dans un modèle pour permettre à l’utilisateur de spécifier les noms des tables, les colonnes des tables et les valeurs personnalisées à utiliser dans sa requête.

Snowflake fournit une sélection de modèles préconçus pour les cas d’utilisation courants. Ces modèles de stock ne peuvent être utilisés que dans l’application web. Toutefois, les fournisseurs et les consommateurs peuvent créer des modèles personnalisés de clean room. Les modèles personnalisés ne peuvent être créés que dans le code, mais peuvent être exécutés soit dans le code, soit par l’intermédiaire de l’application web.

Il existe deux types généraux de modèles :

• Modèles d’analyse, qui évaluent une instruction SELECT (ou un ensemble d’opérations SELECT).

• Modèles d’activation, qui évaluent une instruction SELECT imbriquée dans une instruction CREATE TABLE et renvoient le nom de la table. Ce modèle génère des données qui sont exportées vers le compte Snowflake du consommateur ou du fournisseur ou vers un tiers, en fonction de la configuration de la clean room. Un modèle d’activation est très similaire à un modèle d’analyse avec quelques exigences supplémentaires.

Dans les UI de clean rooms, un modèle d’analyse peut être associé à un modèle d’activation pour permettre à l’appelant d’effectuer une analyse, puis d’envoyer des données à lui-même ou à un tiers. Le modèle d’activation ne doit pas nécessairement se résoudre à la même requête que le modèle d’analyse associé.

Création et exécution d’un modèle personnalisé¶

Dans une clean room avec paramètres par défaut, le fournisseur ajoute un modèle à une clean room et le consommateur peut le choisir, le configurer et l’exécuter :

1. Le fournisseur conçoit un modèle personnalisé et l’ajoute à une clean room en appelant provider.add_custom_sql_template.

2. Le consommateur appelle consumer.run_analysis pour exécuter le modèle du fournisseur, en lui transmettant les valeurs de toutes les variables nécessaires au modèle.

Ce flux ne nécessite pas d’autorisations de la part de l’autre partie, si ce n’est que le consommateur doit être invité dans une clean room par le fournisseur. Il existe des variantes de ce processus, telles que les modèles fournis par les consommateurs et les modèles gérés par les fournisseurs, qui sont couverts par.

SELECT COUNT(*), city FROM consumer_table
  INNER JOIN provider_table
  ON consumer_table.hashed_email = provider_table.hashed_email
  GROUP BY city;

SELECT COUNT(*), IDENTIFIER({{ group_by_col | column_policy }})
  FROM IDENTIFIER({{ my_table[0] }}) AS C
  INNER JOIN IDENTIFIER({{ source_table[0] }}) AS P
  ON IDENTIFIER({{ consumer_join_col | join_policy }}) = IDENTIFIER({{ provider_join_col | join_policy }})
  GROUP BY IDENTIFIER({{ group_by_col | column_policy }});

CALL SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.CONSUMER.RUN_ANALYSIS(
  $cleanroom_name,
  $template_name,
  ['my_db.my_sch.consumer_table],       -- Populates the my_table variable
  ['my_db.my_sch.provider_table'],      -- Populates the source_table variable
  OBJECT_CONSTRUCT(                     -- Populates custom named variables
    'consumer_join_col','c.age_band',
    'provider_join_col','p.age_band',
    'group_by_col','p.device_type'
  )
);

Syntaxe des modèles personnalisés¶

Snowflake Data Clean Rooms prend en charge la version 3 du site JinjaSQL, avec quelques extensions comme indiqué.

Cette section comprend les rubriques suivantes :

• Règles de dénomination des modèles

• Variables de modèles

• Alias de table requis

• Filtres Template]

• Exécution de code Python personnalisé

SELECT income FROM my_db.my_sch.customers WHERE income < {{ max_income }};

SELECT col1 FROM IDENTIFIER({{ source_table[0] }}) AS P;

JOIN IDENTIFIER({{ source_table[0] }}) AS p
  ON {{ c_join_col | sqlsafe | join_policy }} = {{ p_join_col | sqlsafe }}

-- Provider uploads a Python function that takes two numbers and returns the sum.
call samooha_by_snowflake_local_db.provider.load_python_into_cleanroom(
  $cleanroom_name,
  'simple_addition',                        -- Function name to use in the template
  ['someval integer', 'added_val integer'], -- Arguments
  [],                                       -- No packages needed
  'integer',                                -- Return type
  'main',                                   -- Handler for function name
  $$

def main(input, added_val):
  return input + int(added_val)
    $$
);

-- Template passes value from each row to the function, along with a
-- caller-supplied argument named 'increment'
call samooha_by_snowflake_local_db.provider.add_custom_sql_template(
    $cleanroom_name,
    'simple_python_example',
$$
    SELECT val, cleanroom.simple_addition(val, {{ increment | sqlsafe }})
    FROM VALUES (5),(8),(12),(39) AS P(val);
$$
);

Remarques relatives à la sécurité¶

Un modèle doit être évalué en une seule requête SELECT, qui est exécutée par l’application native de la clean room. Le modèle n’est pas exécuté avec l’identité de l’utilisateur actuel.

L’utilisateur n’a pas d’accès direct aux données de la clean room ; tout l’accès se fait par l’application native via les résultats du modèle.

Appliquez un filtre de politique chaque fois qu’une colonne est utilisée dans votre requête, même lorsque vous définissez un nom de colonne explicitement dans le modèle, ou lorsque la colonne ou la table est fournie par vous. Vous pouvez modifier vos politiques de jointure ou de colonne ultérieurement, ou changer la colonne, et oublier de mettre à jour le modèle. Pour toutes les colonnes fournies par l’utilisateur, vous devez appliquer un filtre join_policy, column_policy, join_and_column_policy, ou activation_policy.

Modèles d’activation¶

Un modèle peut également être utilisé pour enregistrer les résultats de la requête dans une table située à l’extérieur de la clean room ; il s’agit de l’activation. Actuellement, les seules formes d’activation supportées pour les modèles personnalisés sont l’activation du fournisseur et l’activation du consommateur (stockage des résultats sur le compte Snowflake du fournisseur ou du consommateur, respectivement). Découvrez comment mettre en œuvre l’activation.

Un modèle d’activation est un modèle d’analyse auquel s’ajoutent les exigences suivantes :

• Les modèles d’activation sont des instructions JinjaSQL qui évaluent un bloc de script SQL, contrairement aux modèles d’analyse, qui peuvent être de simples instructions SELECT.

• Le nom du modèle d’activation doit commencer par la chaîne activation (sauf pour les modèles d’activation des fournisseurs gérés par les consommateurs). Par exemple : activation_my_template.

• Le modèle d’activation doit créer une table dont le nom dépend du type d’activation qu’il permet :

  • Activation du fournisseur gérée par le fournisseur : Le nom de la table générée doit être cleanroom.temp_result_data.

  • Tous les autres types d’activité : Le nom de la table générée doit être préfixé par cleanroom.activation_data_, par exemple : cleanroom.activation_data_cross_activation_results. Le nom de la table doit être unique au sein de votre clean room.

  Cette table générée est une table intermédiaire ; vous ne devez pas essayer d’y accéder directement.

• Le bloc de script doit se terminer par une instruction RETURN qui renvoie le nom de la table générée, sans le préfixe cleanroom. ou cleanroom.activation_data_.

• Toute colonne activée doit être listée dans la politique d’activation du fournisseur ou du consommateur qui a lié les données, et le filtre activation_policy doit lui être appliqué. Notez qu’une colonne peut être à la fois une colonne d’activation et une colonne de jointure.

• Si le modèle doit être exécuté à partir des UI de clean rooms, vous devez fournir une forme web qui comprend les champs activation_template_name et enabled_activations. Les modèles à utiliser dans l’UI doivent avoir un modèle d’analyse et un modèle d’activation associé.

• Toutes les colonnes calculées doivent être explicitement aliasées, plutôt que d’avoir des noms déduits, parce qu’une table est générée. C’est-à-dire :

  SELECT COUNT(*), P.status from T AS P; FAILS car le nom de la colonne COUNT est déduit.

  SELECT COUNT(*) AS COUNT_OF_ITEMS, P.status from T AS P; SUCCEEDS parce qu’elle crée explicitement un alias pour la colonne COUNT.

Voici deux échantillons de modèles d’activation de base. L’une concerne l’activation du serveur géré par le fournisseur, l’autre les autres types d’activation. Elles se distinguent par les deux lignes surlignées, qui contiennent le nom de la table de résultats.

-- These are the required table name strings.
BEGIN
  CREATE OR REPLACE TABLE cleanroom.temp_result_data AS
    SELECT COUNT(c.status) AS ITEM_COUNT, c.status, c.age_band
      FROM IDENTIFIER({{ my_table[0] }}) AS c
    JOIN IDENTIFIER({{ source_table[0] }}) AS p
      ON {{ c_join_col | sqlsafe | activation_policy }} = {{ p_join_col | sqlsafe | activation_policy }}
    GROUP BY c.status, c.age_band
    ORDER BY c.age_band;
  RETURN 'temp_result_data';
END;

-- analysis_results can be whatever name you want.
BEGIN
  CREATE OR REPLACE TABLE cleanroom.activation_data_analysis_results AS
    SELECT COUNT(c.status) AS ITEM_COUNT, c.status, c.age_band
      FROM IDENTIFIER({{ my_table[0] }}) AS c
    JOIN IDENTIFIER({{ source_table[0] }}) AS p
      ON {{ c_join_col | sqlsafe | activation_policy }} = {{ p_join_col | sqlsafe | activation_policy }}
    GROUP BY c.status, c.age_band
    ORDER BY c.age_band;
  RETURN 'analysis_results';
END;

Prochaines étapes¶

Une fois que vous aurez maîtrisé le système de création de modèles, lisez les détails relatifs à la mise en place d’une clean room avec votre type de modèle :

• Les modèles du fournisseur sont des modèles rédigés par le fournisseur. Il s’agit du cas d’utilisation par défaut.

• Les modèles du consommateur sont des modèles rédigés par le consommateur. Dans certains cas, le créateur d’une clean room souhaite permettre au consommateur de créer, de télécharger et d’exécuter ses propres modèles dans la clean room.

• Les modèles d’activation créent une table de résultats après une exécution réussie. En fonction du modèle d’activation, la table des résultats peut être soit enregistrée sur le compte du fournisseur ou du consommateur en dehors de la clean room, soit envoyée à un fournisseur d’activation tiers répertorié dans le hub d’activation.

• Les modèles enchaînés vous permettent d’enchaîner plusieurs modèles où la sortie de chaque modèle est utilisée par le modèle suivant dans la chaîne.

Plus d’informations¶

• Documentation Jinja

• Documentation JinjaSQL