Verwenden der Entwickler-APIs zum sequenziellen Ausführen von Vorlagen¶

Für komplexe Analysen kann es erforderlich sein, dass mehrere Vorlagen in einer bestimmten Reihenfolge ausgeführt werden, wobei manchmal die Ausgabe einer Vorlage als Eingabe für eine andere verwendet wird. Ein Anbieter kann eine Vorlagenkette erstellen, um eine Sequenz von Vorlagen zu definieren, die in einer bestimmten Reihenfolge ausgeführt werden sollen. Bei der Definition dieser Vorlagenkette kann der Anbieter angeben, ob die Ergebnisse einer bestimmten Vorlage für nachfolgende Vorlagen in der Kette verfügbar sein sollen.

Ein Reinraumbenutzer führt eine Vorlagenkette aus, um eine Analyse durchzuführen, bei der die Vorlagen in der Kette in ihrer vordefinierten Reihenfolge ausgeführt werden.

Über Zwischenergebnisse¶

Wenn ein Anbieter möchte, dass die Ergebnisse einer Vorlage auch den nachfolgenden Vorlagen in der Vorlagenkette zur Verfügung stehen, kann er einen Cache für die Ergebnisse der Vorlage erstellen. Jede Vorlage mit einem Cache hat auch eine Verfallszeit für diesen Cache.

Wenn ein Anbieter angibt, dass eine Vorlage über einen Cache verfügt, werden bei der ersten Ausführung der Vorlagenkette durch einen Benutzer die Ergebnisse dieser Vorlage in einer Tabelle im Reinraum gespeichert. Diese zugrunde liegende Tabelle ist nur für den Reinraum selbst zugänglich. Wenn ein Benutzer die Vorlagenkette das nächste Mal ausführt, prüft Snowflake Data Clean Rooms, ob der Cache abgelaufen ist, bevor die Vorlage ausgeführt wird. Die Vorlage mit den im Cache gespeicherten Ergebnissen wird erst dann wieder ausgeführt, wenn der Cache abgelaufen ist.

Nachfolgende Vorlagen in der Vorlagenkette können den Cache als Eingabe verwenden, indem Sie den entsprechenden Jinja-Parameter in die Vorlage aufnehmen.

Vorlagenkette definieren¶

Ein Anbieter verwendet den Befehl provider.add_template_chain, um eine Vorlagenkette zu erstellen. Die Vorlagen, die der Anbieter der neuen Vorlagenkette hinzufügen möchte, müssen bereits vorhanden sein, bevor er die Vorlagenkette erstellt.

Der Befehl provider.add_template_chain akzeptiert die folgenden Argumente:

Name eines Reinraums (string).
Name der Vorlagenkette (string)
Vorlagen in der Vorlagenette (Array von JSON-Objekten).

Ein Beispiel für die Verwendung des Befehls provider.add_template_chain zur Erstellung einer Vorlagenkette finden Sie unter Beispiel.

Hinzufügen von Vorlagen zur Vorlagenkette¶

Der Anbieter definiert, welche Vorlagen Teil einer Vorlagenkette sind, indem er ein Array von JSON-Objekten an provider.add_template_chain übergibt, wobei jedes JSON-Objekt eine Vorlage darstellt. Die Reihenfolge der JSON-Objekte bestimmt die Reihenfolge, in der die Vorlagen ausgeführt werden.

Das JSON-Objekt für eine Vorlage kann die folgenden Felder enthalten:

template_name (string)

Gibt die Vorlage an, die der Vorlagenkette hinzugefügt wird. Die Vorlage muss bereits vorhanden sein.

Dieses Feld ist erforderlich.

cache_results (boolean)

Legt fest, ob die Ergebnisse der Vorlage zwischengespeichert werden, sodass andere Vorlagen in der Vorlagenkette darauf zugreifen können. Um Ergebnisse zwischenzuspeichern, geben Sie TRUE an.

Dieses Feld ist erforderlich. Falls TRUE, sind auch die Felder output_table_name und cache_expiration_hours erforderlich.

output_table_name (string)

Wenn Sie cache_results = TRUE wählen, geben Sie den Namen der Snowflake-Tabelle an, in der die Vorlagenergebnisse gespeichert werden.

Dieses Feld ist erforderlich, wenn cache_results = TRUE.

jinja_output_table_param (string)

Wenn cache_results = TRUE verwendet wird, gibt es den Namen des Jinja-Parameters an, den andere Vorlagen enthalten müssen, um die in output_table_name gespeicherten Ergebnisse zu akzeptieren.

Dieses Feld ist optional.

cache_expiration_hours (Ganzzahl)

Wenn Sie cache_results = TRUE wählen, geben Sie die Anzahl der Stunden an, bevor die Ergebnisse im Cache gelöscht werden. Wenn der Cache abläuft, wird bei der nächsten Ausführung der Vorlagenkette der Cache mit den Ergebnissen der Vorlage aktualisiert.

Dieses Feld ist erforderlich, wenn cache_results = TRUE.

Beispiel¶

In diesem Beispiel möchte der Anbieter:

Erstellen Sie eine Vorlagenkette insights_chain im Reinraum collab_clean_room.
Definieren Sie die Vorlagenkette so, dass die Vorlage crosswalk vor der Vorlage transaction_insights ausgeführt wird.
Speichern Sie die Ergebnisse der Vorlage crosswalk, damit sie als Eingabe für die Vorlage transaction_insights verwendet werden können.

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

Weitere Informationen zu den einzelnen JSON-Objekten finden Sie unter Hinzufügen von Vorlagen zur Vorlagenkette.

Eine Vorlagenkette ausführen¶

Ein Reinraumbenutzer führt den Befehl consumer.run_analysis aus, um eine Vorlagenkette auszuführen. Dies ist derselbe Befehl, der auch für die Ausführung einer einzelnen Vorlage verwendet wird. Bei der Ausführung der Vorlagenkette werden die einzelnen Vorlagen in der Kette in ihrer vordefinierten Reihenfolge ausgeführt, um das Endergebnis zu erhalten.

Der Befehl consumer.run_analysis akzeptiert Argumente, die er an die Jinja-Vorlagen in der Vorlagenkette weitergibt. Sie können feststellen, welche Argumente von den Vorlagen in der Kette erwartet werden, indem Sie den Befehl consumer.get_arguments_from_template_chain ausführen.

Die an consumer.run_analysis übergebenen Argumente können für eine bestimmte Vorlage in der Kette spezifisch sein oder für jede Vorlage in der Kette gelten.

Universelle Argumente

Wenn Sie ein Argument an jede Vorlage in der Vorlagenkette übergeben möchten, ist die Syntax dieselbe wie bei der Verwendung von consumer.run_analysis zur Ausführung einer einzelnen Vorlage. Der folgende Befehl übergibt zum Beispiel den Wert des Arguments where_clause an alle Vorlagen in der Vorlagenkette:

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

Vorlagenspezifische Argumente

Wenn Sie ein Argument an eine bestimmte Vorlage übergeben möchten, fügen Sie ein weiteres object_construct als untergeordnetes Element der obersten Ebene object_construct mit dem Namen der Vorlage als Feldnamen hinzu. Der folgende Befehl übergibt beispielsweise den Wert des Arguments dimensions nur an die Vorlage crosswalk_template:

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

Befehle der Vorlagenkette¶

Sie können die folgenden Befehle verwenden, um mit Vorlagenketten zu arbeiten:

Befehl	Beschreibung
`provider.add_template_chain`	Erzeugt eine neue Vorlagenkette.
`provider.view_added_template_chains` `consumer.view_added_template_chains`	Liefert alle Vorlagenketten, die dem Reinraum hinzugefügt wurden.
`provider.view_template_chain_definition` `consumer.view_template_chain_definition`	Gibt die Definition einer Vorlagenkette zurück.
`provider.clear_template_chain`	Löscht eine Vorlagenkette aus dem Reinraum.
`provider.clear_all_template_chains`	Löscht alle Vorlagenketten aus dem Reinraum fallen.
`consumer.get_arguments_from_template_chain`	Gibt die erwarteten Argumente für alle Vorlagen in der Vorlagenkette zurück.

Weitere Informationen zu diesen Befehlen finden Sie im Folgenden: