Utilisation des APIs du développeur pour exécuter les modèles de manière séquentielle¶

Des analyses complexes peuvent nécessiter l’exécution de plusieurs modèles dans un ordre spécifique, en utilisant parfois la sortie d’un modèle comme entrée d’un autre. Un fournisseur peut créer une chaîne de modèles pour définir une séquence de modèles à exécuter dans un ordre particulier. Lors de la définition de cette chaîne de modèles, le fournisseur peut spécifier si les résultats d’un modèle particulier seront disponibles pour les modèles suivants de la chaîne.

Un utilisateur de salle blanche exécute une chaîne de modèles pour effectuer une analyse qui exécute les modèles de la chaîne dans leur ordre prédéfini.

À propos des résultats intermédiaires¶

Si un fournisseur souhaite que les résultats d’un modèle soient disponibles pour les modèles suivants dans la chaîne de modèles, il peut créer un cache pour les résultats du modèle. Chaque modèle avec un cache dispose également d’un délai d’expiration pour ce cache.

Si un fournisseur spécifie qu’un modèle dispose d’un cache, la première fois qu’un utilisateur exécute la chaîne de modèles, les résultats de ce modèle sont stockés dans une table dans la salle blanche. Cette table sous-jacente n’est accessible qu’à la salle blanche elle-même. La prochaine fois qu’un utilisateur exécute la chaîne de modèles, Snowflake Data Clean Rooms vérifie si le cache a expiré avant d’exécuter le modèle. Le modèle avec les résultats mis en cache ne s’exécute pas à nouveau, sauf si le cache a expiré.

Les modèles suivants dans la chaîne de modèles peuvent utiliser le cache comme entrée en incluant le paramètre Jinja approprié dans le modèle.

Définir une chaîne de modèles¶

Un fournisseur utilise la commande provider.add_template_chain pour créer une chaîne de modèles. Les modèles que le fournisseur souhaite ajouter à la nouvelle chaîne de modèles doivent exister avant de créer la chaîne de modèles.

La commande provider.add_template_chain accepte les arguments suivants :

Nom d’une salle blanche (string).
Nom de la chaîne de modèles (string).
Modèles dans la chaîne de modèles (tableau d’objets JSON).

Pour un exemple d’utilisation de la commande provider.add_template_chain pour créer une chaîne de modèles, voir Exemple.

Ajout de modèles à la chaîne de modèles¶

Le fournisseur définit quels modèles font partie d’une chaîne de modèles en transmettant un tableau d’objets JSON dans provider.add_template_chain, où chaque objet JSON représente un modèle. L’ordre des objets JSON détermine l’ordre dans lequel les modèles sont exécutés.

L’objet JSON d’un modèle peut inclure les champs suivants :

template_name (string)

Spécifie le modèle ajouté à la chaîne de modèles. Le modèle doit déjà exister.

Ce champ est obligatoire.

cache_results (boolean)

Détermine si les résultats du modèle sont mis en cache afin que d’autres modèles de la chaîne de modèles puissent y accéder. Pour mettre en cache les résultats, spécifiez TRUE.

Ce champ est obligatoire. Si TRUE, les champs output_table_name et cache_expiration_hours sont également obligatoires.

output_table_name (string)

Quand cache_results = TRUE, spécifie le nom de la table Snowflake dans laquelle les résultats du modèle sont stockés.

Ce champ est obligatoire si cache_results = TRUE.

jinja_output_table_param (string)

Quand cache_results = TRUE, spécifie le nom du paramètre Jinja que les autres modèles doivent inclure pour accepter les résultats stockés dans output_table_name.

Ce champ est facultatif.

cache_expiration_hours (entier)

Quand cache_results = TRUE, spécifie le nombre d’heures avant que les résultats du cache ne soient supprimés. Lorsque le cache expire, la prochaine fois que la chaîne de modèles est exécutée, le cache est actualisé avec les résultats du modèle.

Ce champ est obligatoire si cache_results = TRUE.

Exemple¶

Dans cet exemple, le fournisseur souhaite :

Créer une chaîne de modèles insights_chain dans la salle blanche collab_clean_room.
Définir la chaîne de modèles afin que le modèle crosswalk s’exécute avant le modèle transaction_insights.
Mettre en cache les résultats du modèle crosswalk afin qu’ils puissent être utilisés comme entrée dans le modèle transaction_insights.

CALL samooha_by_snowflake_local_db.provider.add_template_chain(
  'collab_clean_room',
  'insights_chain',
  [
    {
      'template_name': 'crosswalk',
      'cache_results': True,
      'output_table_name': 'crosswalk',
      'jinja_output_table_param': 'crosswalk_table_name',
      'cache_expiration_hours': 2190
    },
    {
      'template_name': 'transaction_insights',
      'cache_results': False
    }
  ]
);

Copy

Pour plus d’informations sur chaque objet JSON objet, voir Ajout de modèles à la chaîne de modèles.

Exécuter une chaîne de modèles¶

Un utilisateur de salle blanche exécute la commande consumer.run_analysis pour exécuter une chaîne de modèles, qui est la même commande utilisée pour exécuter un seul modèle. L’exécution de la chaîne de modèles exécute chaque modèle de la chaîne dans leur ordre prédéfini pour obtenir le résultat final.

La commande consumer.run_analysis accepte les arguments qu’elle transmet aux modèles Jinja dans la chaîne de modèles. Vous pouvez déterminer quels arguments sont attendus par les modèles de la chaîne en exécutant la commande consumer.get_arguments_from_template_chain.

Les arguments transmis à consumer.run_analysis peuvent être spécifiques à un modèle particulier dans la chaîne ou peuvent être des arguments pour chaque modèle dans la chaîne.

Arguments universels

Si vous souhaitez transmettre un argument à chaque modèle de la chaîne de modèles, la syntaxe est la même que consumer.run_analysis pour exécuter un seul modèle. Par exemple, la commande suivante transmet la valeur de l’argument where_clause pour tous les modèles dans la chaîne de modèles :

CALL samooha_by_snowflake_local_db.consumer.run_analysis(
  'collab_clean_room',
  'insights_chain',
  ['MY_CONSUMER_DB.C_SCHEMA.CONVERSIONS'],
  ['PROVIDER_DB.P_SCHEMA.EXPOSURES'],
  object_construct(
    'where_clause', 'p.EMAIL=c.EMAIL'
  )
);

Copy

Arguments spécifiques au modèle

Si vous souhaitez passer un argument à un modèle spécifique, ajoutez un autre object_construct en tant qu’enfant object_construct de haut niveau avec le nom du modèle comme nom de champ. Par exemple, la commande suivante transmet la valeur de l’argument dimensions au modèle crosswalk_template uniquement :

CALL samooha_by_snowflake_local_db.consumer.run_analysis(
  'collab_clean_room',
  'insights_chain',
  ['MY_CONSUMER_DB.C_SCHEMA.CONVERSIONS'],
  ['PROVIDER_DB.P_SCHEMA.EXPOSURES'],
  object_construct(
    'where_clause', 'p.EMAIL=c.EMAIL',
    'crosswalk_template', object_construct(
      'dimensions', ['p.CAMPAIGN']
    )
  )
);

Copy

Commandes de chaîne de modèles¶

Vous pouvez utiliser les commandes suivantes pour travailler avec les chaînes de modèles :

Commande	Description
`provider.add_template_chain`	Crée une nouvelle chaîne de modèles.
`provider.view_added_template_chains` `consumer.view_added_template_chains`	Renvoie toutes les chaînes de modèles qui ont été ajoutées à la salle blanche.
`provider.view_template_chain_definition` `consumer.view_template_chain_definition`	Renvoie la définition d’une chaîne de modèles.
`provider.clear_template_chain`	Supprime une chaîne de modèles de la salle blanche.
`provider.clear_all_template_chains`	Supprime toutes les chaînes de modèles de la salle blanche.
`consumer.get_arguments_from_template_chain`	Renvoie les arguments attendus pour tous les modèles de la chaîne de modèles.

Pour plus d’informations sur ces commandes, consultez les éléments suivants :