Abläufe mit mehreren Schritten gestalten¶

Übersicht¶

Most clean room usage involves running a single SQL query against one or more tables in a clean room and displaying the results in the response. However, there are many use cases where you might want to break up your flow into several steps, which can be run sequentially or individually, and can involve calling Python code to process (or pre-process) data. Examples include a machine learning flow where the model is trained once against a data set and then run multiple times against varying input data, either singly or in batches.

Clean Rooms verfügen über mehrere Mechanismen, die diese erweiterten Szenarien ermöglichen:

• Vorlagenketten: Eine Vorlagenkette führt eine Reihe von Vorlagen in einer bestimmten Reihenfolge aus, wobei die Ausgabe jeder Vorlage als Eingabe für die nächste Vorlage verwendet wird. Die Eingabe für die erste Vorlage in der Kette wird vom Benutzer bereitgestellt; die Ausgabe der letzten Vorlage in der Kette wird an den Benutzer zurückgegeben.

• Internal tables: Your template or custom internal functions can create persistent tables within a clean room. These tables behave like linked tables in that they are accessible to templates or custom uploaded code. Internal tables are useful for maintaining state or data; in the machine learning example, the training data is saved in an internal table that is used by internal functions. Just as with linked tables, these tables can be accessed only by templates or uploaded code inside the clean room. Storing intermediary data in internal tables is more efficient than passing large blocks of information into and out of the clean room using templates.

• Benutzerdefinierte interne Funktionen: Sie können innerhalb eines Clean Rooms benutzerdefinierte Funktionen definieren, die von Vorlagen in diesem Clean Room aufgerufen werden können. Funktionen können in einem Clean Room entweder durch Hochladen von Python -UDFs oder UDTFs- in den Clean Room oder durch Erstellen eines Containerservice in Ihrem Clean Room, der Endpunkte bereitstellt, die Funktionen implementieren. Diese Funktionen können nur von Vorlagen innerhalb des Clean Rooms aufgerufen werden.

Interne Clean Room-Tabellen¶

You can create tables inside a clean room using SQL or Python to store intermediary results, or for persistent storage for the user or your internal functions (for example, to save training data that is used for multiple runs). These tables behave the same as linked tables, with the following notes:

• Internal tables are created using a clean room template or a UDF/UDTF, and have no linkage to outside tables.

• Internal tables are created in the cleanroom namespace.

• You can set row and column policies on internal tables after you create them.

• If the table name is dynamic, and the table is accessed by other templates or code, return the name of the table to the user so the user can pass the dynamic table name to any other templates that need to access that table.

Hier sind einige Beispiele für die Erstellung einer internen Tabelle:

CALL samooha_by_snowflake_local_db.provider.add_custom_sql_template(
  $cleanroom_name,
  $template_name,
  $$
  BEGIN
    CREATE OR REPLACE TABLE cleanroom.analysis_results AS
      SELECT count(*) 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;
  $$);

# Snippet of Python UDF to save results to an internal table.
table_name = f'cleanroom.results'

session.sql(f"""
CREATE OR REPLACE TABLE {table_name} AS (
  WITH joint_data AS (
    SELECT
        date,
        p.hashed_email AS hem,
        impression_id
    FROM {source_table} p
  )
  SELECT
    date,
    COUNT(DISTINCT hem) AS reach,
    COUNT(DISTINCT impression_id) AS num_impressions
  FROM joint_data
  GROUP BY date
  ORDER BY date
);
""").collect()

# Snippet of container services Python code to create an internal results table.
# 'cleanroom' table name prefix is added using the schema parameter when the table is created.
@app.post("/score")
def score():

... omitted content ...

df = pd.DataFrame({
    "ID": ids,
    "SCORE": scores
})
table = "LOOKALIKE_RESULTS"
session.write_pandas(df, table, schema="CLEANROOM", auto_create_table=True, overwrite=True)

end_time = time.perf_counter()
execution_time = end_time - start_time
response = make_json_response([[0, {"results_table": table, "size": len(ids), "execution_time": round(execution_time, 2)}]])
return response

Wenn Sie eine interne Tabelle generieren, auf die über eine Vorlage oder einen Code zugegriffen werden muss, können Sie entweder einen konstanten Tabellennamen verwenden oder die Tabelle dynamisch benennen und den Namen der Tabelle an den Benutzer zurückgeben, der den Tabellennamen dann an die Ergebnisfunktion weitergibt.

Hier sehen Sie ein Beispiel für eine dynamisch benannte Tabelle, die zum Speichern von Ergebnissen verwendet wird. Der Benutzer macht zwei Aufrufe: einen, um die Daten zu generieren und den Tabellennamen zu erhalten, und einen zweiten, um die Ergebnisse zu sehen.

1. Die Anbietervorlage ruft die reach_impression_regression-UDF auf, um Daten zu verarbeiten (das Präfix cleanroom zeigt an, dass es sich um eine UDF handelt). Die UDF gibt den Namen des internen Tabellenpräfixes an die Vorlage zurück, die ihn an den Aufrufer zurückgibt.

   -- This template calls a UDF uploaded by a collaborator.
   -- The UDF takes two input tables as parameters.
   CALL samooha_by_snowflake_local_db.provider.add_custom_sql_template(
     $cleanroom_name,
     'prod_calculate_regression',
     $$
     CALL cleanroom.reach_impression_regression({{ source_table[0] }}, {{ my_table[0] | default('NONE') }});
     $$
   );
   

   Copy

2. The Python UDF generates the internal table and returns the generated table name to the template caller.

   def main(session, source_table, my_table):
     ...
     table = f'results_{suffix}'.upper()
     retval_df = session.write_pandas(regression_output, table,  schema = 'CLEANROOM', auto_create_table = True)
   
     return f'Done, results have been written to the following table: {table}'
   

   Copy

3. The provider template accepts a table name passed in and displays the contents of that table. Note how the table is always accessed from the cleanroom namespace.

   CALL samooha_by_snowflake_local_db.provider.add_custom_sql_template(
           $cleanroom_name,
           'prod_get_results',
           $$
             SELECT * FROM cleanroom.{{ results_table | sqlsafe }};
           $$
   );
   

   Copy

4. The consumer calls the template, passing in the table name.

   CALL samooha_by_snowflake_local_db.consumer.run_analysis(
     $cleanroom_name,
     'prod_get_results',
     [],
     [],
     object_construct(
         'results_table', $table_name
     )
   );
   

   Copy

Benutzerdefinierte Funktionen auslösen¶

Benutzerdefinierte Funktionen können entweder über Vorlagen oder über Code (UDFs, UDTFs oder Container-Dienstendpunkte) im Clean Room aufgerufen werden. Auf Funktionen, die von einem beliebigen Teilnehmer hochgeladen wurden, kann von jedem anderen Teilnehmer über Vorlagen oder Code zugegriffen werden.

Clean Room-Funktionen sollten immer in dem entsprechenden Namespace aufgerufen werden:

• cleanroom.function_name beim Aufruf einer benutzerdefinierten UDF/UDTF-Funktion

• service_functions.function_name, wenn Sie eine Funktion aufrufen, die als eingebettete Funktion des Snowpark Container Service angezeigt wird.

Hier finden Sie Beispiele für den Aufruf einer benutzerdefinierten UDF und eines benutzerdefinierten Container-Dienstendpunkts aus einer Vorlage:

-- Template to generate results. Calls the UDF 'my_function', which
-- generates a results table inside the clean room called 'results'.
CALL samooha_by_snowflake_local_db.provider.add_custom_sql_template(
  $cleanroom_name,
  'generate_results_template',
  $$
  CALL cleanroom.my_function({{ source_table[0] }}, {{ my_table[0] | default('NONE') }});
  $$
);

-- Template to trigger training data generation.
CALL samooha_by_snowflake_local_db.provider.add_custom_sql_template(
  $cleanroom_name,
  'lal_train',
  $$
  SELECT service_functions.my_func(
            {{ source_table[0] }},
            {{ provider_join_col }},
            {{ my_table[0] }},
            {{ consumer_join_col }},
            {{ dimensions | sqlsafe }},
            {{ filter_clause }}
          ) AS train_result;
$$

Häufige Muster für Abläufe mit mehreren Schritten¶

Das Snowpark-API-Beispiel verarbeitet Daten, generiert Zwischentabellen und dann eine Ergebnistabelle mit einem Vorlagenaufruf und gibt die Ergebnisse dann direkt über einen zweiten Vorlagenaufruf aus.

Das Snowpark Container Services-Beispiel erstellt Trainingsdaten mit einem Vorlagenaufruf und speichert die Trainingsdaten in einer internen Tabelle. Eine zweite Vorlage analysiert die Eingaben des Benutzers anhand der gespeicherten Trainingsdaten.